diff options
| author | Lennart Poettering <lennart@poettering.net> | 2024-09-12 14:13:22 +0200 |
|---|---|---|
| committer | Lennart Poettering <lennart@poettering.net> | 2024-09-12 16:18:07 +0200 |
| commit | 55184c4cfc6beb3e5e689194fb8331e3b9a4ab36 (patch) | |
| tree | f8b33974683817123aa5ad5942514d0036543e43 /man | |
| parent | update TODO (diff) | |
| download | systemd-55184c4cfc6beb3e5e689194fb8331e3b9a4ab36.tar.xz systemd-55184c4cfc6beb3e5e689194fb8331e3b9a4ab36.zip | |
man: document that sd_bus_process() only returns otherwise unhandled messages in *ret_message
Diffstat (limited to 'man')
| -rw-r--r-- | man/sd_bus_process.xml | 24 |
1 files changed, 18 insertions, 6 deletions
diff --git a/man/sd_bus_process.xml b/man/sd_bus_process.xml index d9b49bd79e..46e221c9f9 100644 --- a/man/sd_bus_process.xml +++ b/man/sd_bus_process.xml @@ -52,12 +52,24 @@ <citerefentry><refentrytitle>sd_bus_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>. </para> - <para><function>sd_bus_process()</function> processes at most one incoming message per call. If the parameter - <parameter>ret</parameter> is not <constant>NULL</constant> and the call processed a message, - <parameter>*ret</parameter> is set to this message. The caller owns a reference to this message and should call - <citerefentry><refentrytitle>sd_bus_message_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> when the - message is no longer needed. If <parameter>ret</parameter> is not <constant>NULL</constant>, progress was made, but no message was - processed, <parameter>*ret</parameter> is set to <constant>NULL</constant>.</para> + <para><function>sd_bus_process()</function> processes at most one incoming message per call. If the + parameter <parameter>ret</parameter> is not <constant>NULL</constant> and the call processed a message, + <parameter>*ret</parameter> is set to this message. The caller owns a reference to this message and + should call + <citerefentry><refentrytitle>sd_bus_message_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> + when the message is no longer needed. If <parameter>ret</parameter> is not <constant>NULL</constant> and + progress was made, but no message was processed, <parameter>*ret</parameter> is set to + <constant>NULL</constant>. Note that only messages not already handled by the various types of registered + message handlers (i.e. by filters registered via + <citerefentry><refentrytitle>sd_bus_add_filter</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + object handlers registered via + <citerefentry><refentrytitle>sd_bus_add_object</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + matches registered via + <citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + and related) will be returned through this parameter. Also note that if such a message handler returns a + zero return value (as opposed to some value > 0) an incoming message will not be considered handled, + and be passed to other suitable handlers (until one returns > > 0), or returned by + <function>sd_bus_process()</function> (in case none returns > 0).</para> <para>If the bus object is connected to an <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry> event loop (with |