shaba/systemd-stable
1
1
Fork 0
mirror of https://github.com/systemd/systemd-stable.git synced 2024-10-26 08:55:18 +03:00
Code

sd-bus/man: document EBUSY error in bus_message_read (#21954)

Browse Source 
* sd-bus/man: document EBUSY error in bus_message_read

The EBUSY error can be returned from sd_bus_exit_container(), and, if
that happens, it will be propogated upwards towards bus_message_read. In
terms of documentation, this means that bus_message_read's man page
can't just include the error text for sd_bus_message_read_basic, as
reading basic types exclusively doesn't have the potential for this
error.

sd_bus_message_read_basic's error documentation isn't incorrect when
applied to sd_bus_message_read, it's just incomplete.  While EBUSY is
documented in sd_bus_message_open_container.xml,
it's explanation is unique to the sd_bus_message_exit_container function
and makes for poor documentation of the general read API.

(cherry picked from commit a1a03fa54b)
This commit is contained in:
lincoln auster 2022-01-11 03:47:31 -07:00 committed by Zbigniew Jędrzejewski-Szmek
parent e9a0404b76
commit 9a109a9a11
2 changed files with 20 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
man/sd_bus_message_read.xml
View File

@ -172,7 +172,23 @@
<para>On success, these functions return a non-negative integer. On failure, they return a negative
errno-style error code.</para>
<xi:include href="sd_bus_message_read_basic.xml" xpointer="errors" />
<refsect2 id='errors'>
<title>Errors</title>
<para>Returned errors may indicate the following problems:</para>
<variablelist>
<xi:include href="sd_bus_message_read_basic.xml" xpointer="errors-einval"/>
<xi:include href="sd_bus_message_read_basic.xml" xpointer="errors-enxio"/>
<xi:include href="sd_bus_message_read_basic.xml" xpointer="errors-ebadmsg"/>
<varlistentry>
<term><constant>-EBUSY</constant></term>
<listitem><para>When reading from a container, this error will be returned if unread elements
are left in the container.</para></listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />

6
man/sd_bus_message_read_basic.xml
View File

@ -199,21 +199,21 @@
<para>Returned errors may indicate the following problems:</para>
<variablelist>
<varlistentry>
<varlistentry id="errors-einval">
<term><constant>-EINVAL</constant></term>
<listitem><para>Specified type string is invalid or the message parameter is
<constant>NULL</constant>.</para></listitem>
</varlistentry>
<varlistentry>
<varlistentry id="errors-enxio">
<term><constant>-ENXIO</constant></term>
<listitem><para>The message does not contain the specified type at current position.
</para></listitem>
</varlistentry>
<varlistentry>
<varlistentry id="errors-ebadmsg">
<term><constant>-EBADMSG</constant></term>
<listitem><para>The message cannot be parsed.</para></listitem>