Merge pull request #16483 from poettering/man-env-d-no-session

[thirdparty/systemd.git] / man / sd_bus_call.xml

diff --git a/man/sd_bus_call.xml b/man/sd_bus_call.xml
index f2d725a29f0bcd75cc554fd9e88ef97deb4b2ef4..f47f9c8526e57032e52594801860f6219c5c6896 100644 (file)
--- a/man/sd_bus_call.xml
+++ b/man/sd_bus_call.xml
@@ -27,6 +27,8 @@
     <funcsynopsis>
       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
 
+      <xi:include href="sd_bus_add_match.xml" xpointer="sd_bus_message_handler_t"/>
+
       <funcprototype>
         <funcdef>int <function>sd_bus_call</function></funcdef>
         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
@@ -52,34 +54,40 @@
     <title>Description</title>
 
     <para><function>sd_bus_call()</function> takes a complete bus message object and calls the
-    corresponding D-Bus method. The response is stored in <parameter>reply</parameter>.
+    corresponding D-Bus method. On success, the response is stored in <parameter>reply</parameter>.
     <parameter>usec</parameter> indicates the timeout in microseconds. If
     <parameter>ret_error</parameter> is not <constant>NULL</constant> and
-    <function>sd_bus_call()</function> returns an error, <parameter>ret_error</parameter> is
-    initialized to an instance of <structname>sd_bus_error</structname> describing the error.</para>
-
-    <para><function>sd_bus_call_async()</function> is like <function>sd_bus_call()</function> but
-    works asynchronously. The <parameter>callback</parameter> shall reference a function to call
-    when the event source is triggered. The <parameter>userdata</parameter> pointer will be passed
-    to the callback function, and may be chosen freely by the caller. If <parameter>slot</parameter>
-    is not <constant>NULL</constant> and <function>sd_bus_call_async()</function> succeeds,
-    <parameter>slot</parameter> is set to a slot object which can be used to cancel the method call
-    at a later time using
+    <function>sd_bus_call()</function> fails (either because of an internal error or because it
+    received a D-Bus error reply), <parameter>ret_error</parameter> is initialized to an instance of
+    <structname>sd_bus_error</structname> describing the error.</para>
+
+    <para><function>sd_bus_call_async()</function> is like <function>sd_bus_call()</function> but works
+    asynchronously. The <parameter>callback</parameter> indicates the function to call when the response
+    arrives. The <parameter>userdata</parameter> pointer will be passed to the callback function, and may be
+    chosen freely by the caller. If <parameter>slot</parameter> is not <constant>NULL</constant> and
+    <function>sd_bus_call_async()</function> succeeds, <parameter>slot</parameter> is set to a slot object
+    which can be used to cancel the method call at a later time using
     <citerefentry><refentrytitle>sd_bus_slot_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
-    If <parameter>slot</parameter> is <constant>NULL</constant>, the lifetime of the method call is
-    bound to the lifetime of the bus object itself, and it cannot be cancelled independently. See
+    If <parameter>slot</parameter> is <constant>NULL</constant>, the lifetime of the method call is bound to
+    the lifetime of the bus object itself, and it cannot be cancelled independently. See
     <citerefentry><refentrytitle>sd_bus_slot_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-    for details. The <parameter>callback</parameter> function is called when the response arrives
-    and receives the response, <parameter>userdata</parameter> and a
-    <structname>sd_bus_error</structname> object as its arguments. The
-    <structname>sd_bus_error</structname> object is unused here and should be ignored. If
-    <parameter>callback</parameter> returns a non-negative integer when called, a debug message is
-    logged along with details about the response.</para>
-
-    <para>To determine whether the method call succeeded, use
+    for details. <parameter>callback</parameter> is called when a reply arrives with the reply,
+    <parameter>userdata</parameter> and an <structname>sd_bus_error</structname> output parameter as its
+    arguments. Unlike <function>sd_bus_call()</function>, the <structname>sd_bus_error</structname> output
+    parameter passed to the callback will be empty. To determine whether the method call succeeded, use
     <citerefentry><refentrytitle>sd_bus_message_is_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-    on the reply object returned by <function>sd_bus_call()</function> or passed to the callback of
-    <function>sd_bus_call_async()</function>.</para>
+    on the reply message passed to the callback instead. If the callback returns zero and the
+    <structname>sd_bus_error</structname> output parameter is still empty when the callback finishes, other
+    handlers registered with functions such as
+    <citerefentry><refentrytitle>sd_bus_add_filter</refentrytitle><manvolnum>3</manvolnum></citerefentry> or
+    <citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry> are
+    given a chance to process the message. If the callback returns a non-zero value or the
+    <structname>sd_bus_error</structname> output parameter is not empty when the callback finishes, no
+    further processing of the message is done. Generally, you want to return zero from the callback to give
+    other registered handlers a chance to process the reply as well. (Note that the
+    <structname>sd_bus_error</structname> parameter is an output parameter of the callback function, not an
+    input parameter; it can be used to propagate errors from the callback handler, it will not receive any
+    error that was received as method reply.)</para>
 
     <para>If <parameter>usec</parameter> is zero, the default D-Bus method call timeout is used. See
     <citerefentry><refentrytitle>sd_bus_get_method_call_timeout</refentrytitle><manvolnum>3</manvolnum></citerefentry>.