From: Lennart Poettering Date: Tue, 19 May 2020 17:06:22 +0000 (+0200) Subject: man: let's document explicitly that method reply handlers won't get ret_error set... X-Git-Tag: v246-rc1~317^2 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F15854%2Fhead;p=thirdparty%2Fsystemd.git man: let's document explicitly that method reply handlers won't get ret_error set to method error Fixes: #8108 --- diff --git a/man/sd_bus_call.xml b/man/sd_bus_call.xml index b93efb2622c..f47f9c8526e 100644 --- a/man/sd_bus_call.xml +++ b/man/sd_bus_call.xml @@ -61,32 +61,33 @@ 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 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_call_async() is like sd_bus_call() but 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 + 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. 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 + 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 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_error output parameter is still empty when the callback finishes, 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. + 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. (Note that the + sd_bus_error 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.) If usec is zero, the default D-Bus method call timeout is used. See sd_bus_get_method_call_timeout3.