man: document fd ownership for sd-bus fd marshalling

Fixes: #8003

diff --git a/man/sd_bus_message_append.xml b/man/sd_bus_message_append.xml
index 5faadd603a123cfd915e7fe998307826b90e3407..7f9235954f47aba033efdc637019d69dbd06bef4 100644 (file)
--- a/man/sd_bus_message_append.xml
+++ b/man/sd_bus_message_append.xml
@@ -146,8 +146,10 @@
       </tgroup>
     </table>
 
-    <para>For types "s" and "g" (unicode string or signature), the pointer may be
-    <constant>NULL</constant>, which is equivalent to an empty string. See
+    <para>For types <literal>s</literal> and <literal>g</literal> (unicode string or signature), the pointer
+    may be <constant>NULL</constant>, which is equivalent to an empty string. For <literal>h</literal> (UNIX
+    file descriptor), the descriptor is duplicated by this call and the passed descriptor stays in possession
+    of the caller. See
     <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     for the precise interpretation of those and other types.</para>
   </refsect1>

diff --git a/man/sd_bus_message_read.xml b/man/sd_bus_message_read.xml
index 1b9f36cd84ed8f2a55672e5bacd1f6db1213af6b..2b5f1000be7c1d1ce8fac81ba56fd65f0a5e059e 100644 (file)
--- a/man/sd_bus_message_read.xml
+++ b/man/sd_bus_message_read.xml
@@ -73,7 +73,10 @@
     should be read. See the table below for a complete list of allowed arguments and their types. Note that,
     if the basic type is a pointer (e.g., <type>const char *</type> in the case of a string), the argument is
     a pointer to a pointer, and also the pointer value that is written is only borrowed and the contents must
-    be copied if they are to be used after the end of the messages lifetime.</para>
+    be copied if they are to be used after the end of the messages lifetime. If the type is
+    <literal>h</literal> (UNIX file descriptor), the descriptor is not duplicated by this call and the
+    returned descriptor remains in possession of the message object, and needs to be duplicated by the caller
+    in order to keep an open reference to it after the message object is freed.</para>
 
     <para>Each argument may also be <constant>NULL</constant>, in which case the value is read and ignored.
     </para>
@@ -228,6 +231,15 @@ const char *s, *t, *u;
 
 sd_bus_message_read(m, "a{is}", 3, &amp;i, &amp;s, &amp;j, &amp;t, &amp;k, &amp;u);
      </programlisting>
+
+     <para>Read a single file descriptor, and duplicate it in order to keep it open after the message is
+     freed.</para>
+
+     <programlisting>sd_bus_message *m;
+int fd, fd_copy;
+
+sd_bus_message_read(m, "h", &amp;fd);
+fd_copy = fcntl(fd, FD_DUPFD_CLOEXEC, 3);</programlisting>
   </refsect1>
 
   <refsect1>

diff --git a/man/sd_bus_message_read_basic.xml b/man/sd_bus_message_read_basic.xml
index e1e993434ac3f5a8b7dd2855b14a8a5c16314ec4..dc9f960618cf0788c83e2bbc1c0e7a62f651aa1e 100644 (file)
--- a/man/sd_bus_message_read_basic.xml
+++ b/man/sd_bus_message_read_basic.xml
@@ -52,17 +52,19 @@
     </para>
 
     <para>
-      If <parameter>p</parameter> is not <constant>NULL</constant>, it should contain
-      a pointer to an appropriate object. For example, if <parameter>type</parameter>
-      is <constant>'y'</constant>, the object passed in <parameter>p</parameter>
-      should have type <type>uint8_t *</type>. If <parameter>type</parameter> is
-      <constant>'s'</constant>, the object passed in <parameter>p</parameter> should
-      have type <type>const char **</type>. Note that, if the basic type is a pointer
-      (e.g., <type>const char *</type> in the case of a string), the pointer is only
-      borrowed and the contents must be copied if they are to be used after the end
-      of the messages lifetime. Similarly, during the lifetime of such a pointer, the
-      message must not be modified. See the table below for a complete list of allowed
-      types.
+      If <parameter>p</parameter> is not <constant>NULL</constant>, it should contain a pointer to an
+      appropriate object. For example, if <parameter>type</parameter> is <constant>'y'</constant>, the object
+      passed in <parameter>p</parameter> should have type <type>uint8_t *</type>. If
+      <parameter>type</parameter> is <constant>'s'</constant>, the object passed in <parameter>p</parameter>
+      should have type <type>const char **</type>. Note that, if the basic type is a pointer (e.g.,
+      <type>const char *</type> in the case of a string), the pointer is only borrowed and the contents must
+      be copied if they are to be used after the end of the messages lifetime. Similarly, during the lifetime
+      of such a pointer, the message must not be modified. If <parameter>type</parameter> is
+      <constant>'h'</constant> (UNIX file descriptor), the descriptor is not duplicated by this call and the
+      returned descriptor remains in possession of the message object, and needs to be duplicated by the caller
+      in order to keep an open reference to it after the message object is freed (for example by calling
+      <literal>fcntl(fd, FD_DUPFD_CLOEXEC, 3)</literal>). See the table below for a complete list of
+      allowed types.
     </para>
 
     <table id='format-specifiers'>