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

man: document fd ownership for sd-bus fd marshalling 

Fixes: #8003
This commit is contained in:
Lennart Poettering 2020-08-28 21:18:14 +02:00 committed by Daan De Meyer
parent a667ddf132
commit e2b40db616
3 changed files with 30 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
man/sd_bus_message_append.xml
View File

@ -146,8 +146,10 @@
</tgroup> </tgroup>
</table> </table>
<para>For types "s" and "g" (unicode string or signature), the pointer may be <para>For types <literal>s</literal> and <literal>g</literal> (unicode string or signature), the pointer
<constant>NULL</constant>, which is equivalent to an empty string. See 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> <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>
for the precise interpretation of those and other types.</para> for the precise interpretation of those and other types.</para>
</refsect1> </refsect1>

14
man/sd_bus_message_read.xml
View File

@ -73,7 +73,10 @@
should be read. See the table below for a complete list of allowed arguments and their types. Note that, 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 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 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>Each argument may also be <constant>NULL</constant>, in which case the value is read and ignored.
</para> </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); sd_bus_message_read(m, "a{is}", 3, &amp;i, &amp;s, &amp;j, &amp;t, &amp;k, &amp;u);
</programlisting> </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>
<refsect1> <refsect1>

24
man/sd_bus_message_read_basic.xml
View File

@ -52,17 +52,19 @@
</para> </para>
<para> <para>
If <parameter>p</parameter> is not <constant>NULL</constant>, it should contain If <parameter>p</parameter> is not <constant>NULL</constant>, it should contain a pointer to an
a pointer to an appropriate object. For example, if <parameter>type</parameter> appropriate object. For example, if <parameter>type</parameter> is <constant>'y'</constant>, the object
is <constant>'y'</constant>, the object passed in <parameter>p</parameter> passed in <parameter>p</parameter> should have type <type>uint8_t *</type>. If
should have type <type>uint8_t *</type>. If <parameter>type</parameter> is <parameter>type</parameter> is <constant>'s'</constant>, the object passed in <parameter>p</parameter>
<constant>'s'</constant>, the object passed in <parameter>p</parameter> should should have type <type>const char **</type>. Note that, if the basic type is a pointer (e.g.,
have type <type>const char **</type>. Note that, if the basic type is a pointer <type>const char *</type> in the case of a string), the pointer is only borrowed and the contents must
(e.g., <type>const char *</type> in the case of a string), the pointer is only be copied if they are to be used after the end of the messages lifetime. Similarly, during the lifetime
borrowed and the contents must be copied if they are to be used after the end of such a pointer, the message must not be modified. If <parameter>type</parameter> is
of the messages lifetime. Similarly, during the lifetime of such a pointer, the <constant>'h'</constant> (UNIX file descriptor), the descriptor is not duplicated by this call and the
message must not be modified. See the table below for a complete list of allowed returned descriptor remains in possession of the message object, and needs to be duplicated by the caller
types. 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> </para>
<table id='format-specifiers'> <table id='format-specifiers'>