From: Daan De Meyer Date: Tue, 17 Mar 2020 20:52:30 +0000 (+0100) Subject: sd-bus: sd_bus_call/sd_bus_call_async_docs + cleanups. X-Git-Tag: v246-rc1~733 X-Git-Url: http://git.ipfire.org/?p=thirdparty%2Fsystemd.git;a=commitdiff_plain;h=953ee402cba52518f57105ae9c3c630d8a421f00 sd-bus: sd_bus_call/sd_bus_call_async_docs + cleanups. --- diff --git a/man/rules/meson.build b/man/rules/meson.build index d54e3bf78b4..f9762ffb2e1 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -137,6 +137,7 @@ manpages = [ 'sd_bus_add_fallback_vtable'], ''], ['sd_bus_attach_event', '3', ['sd_bus_detach_event', 'sd_bus_get_event'], ''], + ['sd_bus_call', '3', ['sd_bus_call_async'], ''], ['sd_bus_call_method', '3', ['sd_bus_call_method_async'], ''], ['sd_bus_close', '3', ['sd_bus_flush'], ''], ['sd_bus_creds_get_pid', diff --git a/man/sd-bus.xml b/man/sd-bus.xml index 35db2bb69d5..2f6013b7b04 100644 --- a/man/sd-bus.xml +++ b/man/sd-bus.xml @@ -43,6 +43,8 @@ sd_bus_add_match3, sd_bus_add_object_vtable3, sd_bus_attach_event3, +sd_bus_call3, +sd_bus_call_async3, sd_bus_call_method3, sd_bus_call_method_async3, sd_bus_creds_get_pid3, diff --git a/man/sd_bus_call.xml b/man/sd_bus_call.xml new file mode 100644 index 00000000000..689f9505856 --- /dev/null +++ b/man/sd_bus_call.xml @@ -0,0 +1,186 @@ + + + + + + + + sd_bus_call + systemd + + + + sd_bus_call + 3 + + + + sd_bus_call + sd_bus_call_async + + Invoke a D-Bus method call + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_call + sd_bus *bus + sd_bus_message *m + uint64_t usec + sd_bus_error *ret_error + sd_bus_message **reply + + + + int sd_bus_call_async + sd_bus *bus + sd_bus_slot **slot + sd_bus_message *m + sd_bus_message_handler_t callback + void *userdata + uint64_t usec + + + + + + Description + + sd_bus_call() takes a complete bus message object and calls the + corresponding D-Bus method. 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_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, + 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 + 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(). + + If usec is zero, the timeout set using + sd_bus_set_method_call_timeout3 + is used. If no method call timeout was set, the timeout is read from the + $SYSTEMD_BUS_TIMEOUT environment variable. If this environment variable is + unset or does not contain a valid timeout, the implementation falls back to a predefined method + call timeout of 25 seconds. Note that $SYSTEMD_BUS_TIMEOUT is read once and + cached so callers should not rely on being able to change the default method call timeout at + runtime by changing the value of $SYSTEMD_BUS_TIMEOUT. Instead, call + sd_bus_set_method_call_timeout() to change the default method call timeout. + + + + + + Return Value + + On success, these functions return a non-negative integer. On failure, they return a + negative errno-style error code. + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + The input parameter m is NULL. + + + The input parameter m is not a D-Bus method call. + To create a new D-Bus method call, use + sd_bus_message_new_method_call3. + + + The input parameter m has the + BUS_MESSAGE_NO_REPLY_EXPECTED flag set. + + The input parameter error is + non-NULL but was not set to SD_BUS_ERROR_NULL. + + + + + -ECHILD + + The bus connection was allocated in a parent process and is being reused + in a child process after fork(). + + + + -ENOTCONN + + The bus parameter bus is NULL + or the bus is not connected. + + + + -ECONNRESET + + The client was disconnected while waiting for the response. + + + + + -ETIMEDOUT + + A response was not received within the given timeout. + + + + -ELOOP + + The message m is addressed to its own client. + + + + + -ENOMEM + + Memory allocation failed. + + + + + + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_call_method3, + sd_bus_call_method_async3, + sd_bus_message_new_method_call3, + sd_bus_message_append3 + + + + diff --git a/man/sd_bus_call_method.xml b/man/sd_bus_call_method.xml index 1565bab82d7..de29ac96105 100644 --- a/man/sd_bus_call_method.xml +++ b/man/sd_bus_call_method.xml @@ -20,7 +20,8 @@ sd_bus_call_method sd_bus_call_method_async - Invoke a D-Bus method call + Initialize a bus message object and invoke the corresponding D-Bus method call + @@ -59,15 +60,15 @@ Description - sd_bus_call_method() is a convenience function for calling a D-Bus - method. It combines the + sd_bus_call_method() is a convenience function for initializing a + bus message object and calling the corresponding D-Bus method. It combines the sd_bus_message_new_method_call3, sd_bus_message_append3 and sd_bus_call3 functions into a single function call. - sd_bus_call_method_async() is a convenience function for calling a - D-Bus method asynchronously. It combines the + sd_bus_call_method_async() is a convenience function for initializing + a bus message object and calling the corresponding D-Bus method asynchronously. It combines the sd_bus_message_new_method_call3, sd_bus_message_append3 and sd_bus_call_async3 @@ -77,7 +78,7 @@ Return Value - On success, these functions returns a non-negative integer. On failure, they return a + On success, these functions return a non-negative integer. On failure, they return a negative errno-style error code. diff --git a/man/sd_bus_message_new_method_call.xml b/man/sd_bus_message_new_method_call.xml index 1201262690d..cfb13af51fa 100644 --- a/man/sd_bus_message_new_method_call.xml +++ b/man/sd_bus_message_new_method_call.xml @@ -84,7 +84,7 @@ Return Value - On success, these functions returns a non-negative integer. On failure, they return a + On success, these functions return a non-negative integer. On failure, they return a negative errno-style error code. @@ -163,8 +163,9 @@ systemd1, sd-bus3, + sd_bus_call3, + sd_bus_call_method3, sd_bus_path_encode3 - sd_bus_call_method3 diff --git a/man/sd_bus_message_read.xml b/man/sd_bus_message_read.xml index ee7bdc4bfdd..53cda9f3293 100644 --- a/man/sd_bus_message_read.xml +++ b/man/sd_bus_message_read.xml @@ -63,7 +63,7 @@ pointers to appropriate types (a pointer to int8_t for a y in the type string, a pointer to int32_t for an i, a pointer to const char* for an s, ...) which are set based on the values in - the message. As an exception, in case or array and variant types, the first argument is an + the message. As an exception, in case of array and variant types, the first argument is an "input" argument that further specifies how the message should be read. See the table below for a complete list of allowed arguments and their types. Note that, if the basic type is a pointer (e.g., const char * in the case of a string), the argument is a pointer to a