From: Lennart Poettering <lennart@poettering.net>
Date: Thu, 12 Sep 2024 12:13:22 +0000 (+0200)
Subject: man: document that sd_bus_process() only returns otherwise unhandled messages in... 
X-Git-Tag: v257-rc1~458^2~1
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=55184c4cfc6beb3e5e689194fb8331e3b9a4ab36;p=thirdparty%2Fsystemd.git

man: document that sd_bus_process() only returns otherwise unhandled messages in *ret_message
---

diff --git a/man/sd_bus_process.xml b/man/sd_bus_process.xml
index d9b49bd79e6..46e221c9f9f 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 &gt; 0) an incoming message will not be considered handled,
+    and be passed to other suitable handlers (until one returns &gt; > 0), or returned by
+    <function>sd_bus_process()</function> (in case none returns &gt; 0).</para>
 
     <para>If the bus object is connected to an
     <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry> event loop (with