picnoir/Systemd
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

man: document that sd_bus_message_close_container() may only be called at end of container

Browse source 
Prompted-by: https://lists.freedesktop.org/archives/systemd-devel/2020-September/045264.html
This commit is contained in:
Lennart Poettering 2020-09-09 18:56:24 +02:00 committed by Zbigniew Jędrzejewski-Szmek
parent 2bb4d58eba
commit 8d29a1b9c5
1 changed files with 15 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

17
man/sd_bus_message_open_container.xml
View file

@ -80,7 +80,7 @@
<parameter>m</parameter> itself if there is no parent container.</para> <parameter>m</parameter> itself if there is no parent container.</para>
<para><function>sd_bus_message_enter_container()</function> enters the next container of the message <para><function>sd_bus_message_enter_container()</function> enters the next container of the message
<parameter>m</parameter>. It behaves mostly the same as <parameter>m</parameter> for reading. It behaves mostly the same as
<function>sd_bus_message_open_container()</function>. Entering a container allows reading its contents <function>sd_bus_message_open_container()</function>. Entering a container allows reading its contents
with with
<citerefentry><refentrytitle>sd_bus_message_read</refentrytitle><manvolnum>3</manvolnum></citerefentry> <citerefentry><refentrytitle>sd_bus_message_read</refentrytitle><manvolnum>3</manvolnum></citerefentry>
@ -89,7 +89,12 @@
<para><function>sd_bus_message_exit_container()</function> exits the scope of the last container entered <para><function>sd_bus_message_exit_container()</function> exits the scope of the last container entered
with <function>sd_bus_message_enter_container()</function>. It behaves mostly the same as with <function>sd_bus_message_enter_container()</function>. It behaves mostly the same as
<function>sd_bus_message_close_container()</function>.</para> <function>sd_bus_message_close_container()</function>. Note that
<function>sd_bus_message_exit_container()</function> may only be called after iterating through all
members of the container, i.e. reading or skipping them. Use
<citerefentry><refentrytitle>sd_bus_message_skip</refentrytitle><manvolnum>3</manvolnum></citerefentry>
to skip over felds of a container in order to be able to exit the container with
<function>sd_bus_message_exit_container()</function> without reading all members.</para>
</refsect1> </refsect1>
<refsect1> <refsect1>
@ -128,6 +133,13 @@
<listitem><para>Memory allocation failed.</para></listitem> <listitem><para>Memory allocation failed.</para></listitem>
</varlistentry> </varlistentry>
<varlistentry>
<term><constant>-EBUSY</constant></term>
<listitem><para><function>sd_bus_message_exit_container()</function> was called but there are
unread members left in the container.</para></listitem>
</varlistentry>
</variablelist> </variablelist>
</refsect2> </refsect2>
</refsect1> </refsect1>
@ -158,6 +170,7 @@
<citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_message_read</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_read</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_message_skip</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<ulink url="https://dbus.freedesktop.org/doc/dbus-specification.html">The D-Bus specification</ulink> <ulink url="https://dbus.freedesktop.org/doc/dbus-specification.html">The D-Bus specification</ulink>
</para> </para>
</refsect1> </refsect1>