diff --git a/man/sd_bus_call.xml b/man/sd_bus_call.xml
index f2d725a29f..93462f24b5 100644
--- a/man/sd_bus_call.xml
+++ b/man/sd_bus_call.xml
@@ -52,34 +52,39 @@
Description
sd_bus_call() takes a complete bus message object and calls the
- corresponding D-Bus method. The response is stored in reply.
+ corresponding D-Bus method. On success, the response is stored in reply.
usec indicates the timeout in microseconds. If
ret_error is not NULL and
- sd_bus_call() returns an error, ret_error is
- initialized to an instance of sd_bus_error describing the error.
+ sd_bus_call() fails (either because of an internal error or because it
+ received a D-Bus error reply), ret_error is initialized to an instance of
+ sd_bus_error describing the error.
sd_bus_call_async() is like sd_bus_call() but
- works asynchronously. The callback shall reference a function to call
- when the event source is triggered. The userdata pointer will be passed
- to the callback function, and may be chosen freely by the caller. If slot
- is not NULL and sd_bus_call_async() succeeds,
+ works asynchronously. The callback indicates the function to call when
+ the response arrives. The userdata pointer will be passed to the callback
+ function, and may be chosen freely by the caller. If slot is not
+ NULL and sd_bus_call_async() succeeds,
slot is set to a slot object which can be used to cancel the method call
at a later time using
sd_bus_slot_unref3.
If slot is NULL, the lifetime of the method call is
bound to the lifetime of the bus object itself, and it cannot be cancelled independently. See
sd_bus_slot_set_floating3
- for details. The callback function is called when the response arrives
- and receives the response, userdata and a
- sd_bus_error object as its arguments. The
- sd_bus_error object is unused here and should be ignored. If
- callback returns a non-negative integer when called, a debug message is
- logged along with details about the response.
-
- To determine whether the method call succeeded, use
+ for details. callback is called when a reply arrives with the reply,
+ userdata and an sd_bus_error output
+ parameter as its arguments. Unlike sd_bus_call(), the
+ sd_bus_error output parameter passed to the callback will be empty. To
+ determine whether the method call succeeded, use
sd_bus_message_is_method_error3
- on the reply object returned by sd_bus_call() or passed to the callback of
- sd_bus_call_async().
+ on the reply message passed to the callback instead. If the callback returns zero and the
+ sd_bus_error output parameter is still empty when the callback
+ inishes, other handlers registered with functions such as
+ sd_bus_add_filter3 or
+ sd_bus_add_match3
+ are given a chance to process the message. If the callback returns a non-zero value or the
+ sd_bus_error 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.
If usec is zero, the default D-Bus method call timeout is used. See
sd_bus_get_method_call_timeout3.