From b750101eb236130cf056c675997decbac904cc49 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 17:35:18 +0200 Subject: Adding upstream version 252.22. Signed-off-by: Daniel Baumann --- man/sd_bus_call.xml | 200 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 200 insertions(+) create mode 100644 man/sd_bus_call.xml (limited to 'man/sd_bus_call.xml') diff --git a/man/sd_bus_call.xml b/man/sd_bus_call.xml new file mode 100644 index 0000000..1f7dfc2 --- /dev/null +++ b/man/sd_bus_call.xml @@ -0,0 +1,200 @@ + + + + + + + + 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. On success, the response is stored in reply. + usec indicates the timeout in microseconds. If + ret_error is not NULL and + 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 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. 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 message passed to the callback instead. If the callback returns zero and the + 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. (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.) + + The message m passed to the callback is only borrowed, that is, the callback should + not call sd_bus_message_unref3 + on it. If the callback wants to hold on to the message beyond the lifetime of the callback, it needs to call + sd_bus_message_ref3 to create a + new reference. + + If usec is zero, the default D-Bus method call timeout is used. See + sd_bus_get_method_call_timeout3. + + + + + + Return Value + + On success, these functions return a non-negative integer. On failure, they return a + negative errno-style error code. + + + Errors + + When sd_bus_call() internally receives a D-Bus error reply, it will set + ret_error if it is not NULL, and will return a negative + value mapped from the error reply, see + sd_bus_error_get_errno3. + + + 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 input parameter bus is + NULL or the bus is not connected. + + + + -ECONNRESET + + The bus connection was closed 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, + sd_bus_error3 + + + + -- cgit v1.2.3