From: Daan De Meyer <daan.j.demeyer@gmail.com>
Date: Sun, 15 Mar 2020 20:10:37 +0000 (+0100)
Subject: sd-bus: Add sd_bus_set_fd documentation along with some cleanups.
X-Git-Tag: v246-rc1~750
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=aaf6c75061109e6e6a8049cef93703e079d6b4f3;p=thirdparty%2Fsystemd.git

sd-bus: Add sd_bus_set_fd documentation along with some cleanups.
---

diff --git a/man/sd_bus_get_fd.xml b/man/sd_bus_get_fd.xml
index 6a022b1a190..213d1390199 100644
--- a/man/sd_bus_get_fd.xml
+++ b/man/sd_bus_get_fd.xml
@@ -22,6 +22,7 @@
 
   <refnamediv>
     <refname>sd_bus_get_fd</refname>
+    <refname>sd_bus_set_fd</refname>
     <refname>sd_bus_get_events</refname>
     <refname>sd_bus_get_timeout</refname>
 
@@ -37,6 +38,13 @@
         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
       </funcprototype>
 
+      <funcprototype>
+        <funcdef>int <function>sd_bus_set_fd</function></funcdef>
+        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
+        <paramdef>int <parameter>input_fd</parameter></paramdef>
+        <paramdef>int <parameter>output_fd</parameter></paramdef>
+      </funcprototype>
+
       <funcprototype>
         <funcdef>int <function>sd_bus_get_events</function></funcdef>
         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
@@ -57,8 +65,13 @@
     object. This descriptor can be used with <citerefentry
     project='man-pages'><refentrytitle>poll</refentrytitle><manvolnum>3</manvolnum></citerefentry> or a similar
     function to wait for I/O events on the specified bus connection object. If the bus object was configured with the
-    <citerefentry><refentrytitle>sd_bus_set_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry> function, then
-    the <parameter>input_fd</parameter> file descriptor used in that call is returned.</para>
+    <function>sd_bus_set_fd()</function> function, then the <parameter>input_fd</parameter> file descriptor used in
+    that call is returned.</para>
+
+    <para><function>sd_bus_set_fd()</function> sets the file descriptors used to communicate from a message bus
+    object. Both <parameter>input_fd</parameter> and <parameter>output_fd</parameter> must be valid file descriptors.
+    The same file descriptor may be used as both the input and the output file descriptor. This function must be called
+    before the bus is started.</para>
 
     <para><function>sd_bus_get_events()</function> returns the I/O events to wait for, suitable for passing to
     <function>poll()</function> or a similar call. Returns a combination of <constant>POLLIN</constant>,
@@ -96,14 +109,17 @@
   <refsect1>
     <title>Return Value</title>
 
-    <para><function>sd_bus_get_fd()</function> returns the file descriptor used for communication, or a negative
-    <varname>errno</varname>-style error code on error.</para>
+    <para>On success, <function>sd_bus_get_fd()</function> returns the file descriptor used for communication. On failure,
+    it returns a negative errno-style error code.</para>
+
+    <para>On success, <function>sd_bus_set_fd()</function> returns a non-negative integer. On failure, it returns a
+    negative errno-style error code.</para>
 
-    <para><function>sd_bus_get_events()</function> returns the I/O event mask to use for I/O event watching, or a
-    negative <varname>errno</varname>-style error code on error.</para>
+    <para>On success, <function>sd_bus_get_events()</function> returns the I/O event mask to use for I/O event watching.
+    On failure, it returns a negative errno-style error code.</para>
 
-    <para><function>sd_bus_get_timeout()</function> returns zero or positive on success, or a negative
-    <varname>errno</varname>-style error code on error.</para>
+    <para>On success, <function>sd_bus_get_timeout()</function> returns a non-negative integer. On failure, it returns a
+    negative errno-style error code.</para>
 
     <refsect2>
       <title>Errors</title>
@@ -137,6 +153,19 @@
           <function>sd_bus_set_fd()</function>, which <function>sd_bus_get_fd()</function> cannot
           return.</para></listitem>
         </varlistentry>
+
+        <varlistentry>
+          <term><constant>-EBADF</constant></term>
+
+          <listitem><para>An invalid file descriptor was passed to <function>sd_bus_set_fd()</function>.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><constant>-ENOPKG</constant></term>
+
+          <listitem><para>The bus cannot be resolved.</para></listitem>
+        </varlistentry>
       </variablelist>
     </refsect2>
   </refsect1>
@@ -149,7 +178,6 @@
     <para>
       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>sd_bus_set_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd_bus_process</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd_bus_attach_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd_bus_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>,