HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |SYNOPSIS |DESCRIPTION |RETURN VALUE |NOTES |HISTORY |SEE ALSO |COLOPHON | |
SD_BUS_CALL(3) sd_bus_callSD_BUS_CALL(3)sd_bus_call, sd_bus_call_async - Invoke a D-Bus method call
#include <systemd/sd-bus.h>typedef int (*sd_bus_message_handler_t)(sd_bus_message *m,void *userdata,sd_bus_error *ret_error);int sd_bus_call(sd_bus *bus, sd_bus_message *m, uint64_tusec,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_tcallback,void *userdata, uint64_tusec);
sd_bus_call()takes a complete bus message object and calls the corresponding D-Bus method. On success, the response is stored inreply.usec indicates the timeout in microseconds. Ifret_error is notNULLandsd_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 likesd_bus_call()but works asynchronously. Thecallback indicates the function to call when the response arrives. Theuserdata pointer will be passed to the callback function, and may be chosen freely by the caller. Ifslot is notNULLandsd_bus_call_async()succeeds,slot is set to a slot object which can be used to cancel the method call at a later time usingsd_bus_slot_unref(3). Ifslot isNULL, the lifetime of the method call is bound to the lifetime of the bus object itself, and it cannot be cancelled independently. Seesd_bus_slot_set_floating(3) for details.callback is called when a reply arrives with the reply,userdata and an sd_bus_error output parameter as its arguments. Unlikesd_bus_call(), the sd_bus_error output parameter passed to the callback will be empty. To determine whether the method call succeeded, usesd_bus_message_is_method_error(3) 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 assd_bus_add_filter(3) orsd_bus_add_match(3) 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 messagem passed to the callback is only borrowed, that is, the callback should not callsd_bus_message_unref(3) on it. If the callback wants to hold on to the message beyond the lifetime of the callback, it needs to callsd_bus_message_ref(3) to create a new reference. Ifusec is zero, the default D-Bus method call timeout is used. Seesd_bus_get_method_call_timeout(3).
On success, these functions return a non-negative integer. On failure, they return a negative errno-style error code.Errors Whensd_bus_call()internally receives a D-Bus error reply, it will setret_error if it is notNULL, and will return a negative value mapped from the error reply, seesd_bus_error_get_errno(3). Returned errors may indicate the following problems:-EINVAL The input parameterm isNULL. The input parameterm is not a D-Bus method call. To create a new D-Bus method call, usesd_bus_message_new_method_call(3). The input parameterm has theBUS_MESSAGE_NO_REPLY_EXPECTED flag set. The input parametererror is non-NULLbut was not set toSD_BUS_ERROR_NULL.-ECHILD The bus connection was allocated in a parent process and is being reused in a child process afterfork().-ENOTCONN The input parameterbus isNULLor 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 messagem is addressed to its own client.-ENOMEM Memory allocation failed.
Functions described here are available as a shared library, which can be compiled against and linked to with thelibsystemd pkg-config(1) file. The code described here usesgetenv(3), which is declared to be not multi-thread-safe. This means that the code calling the functions described here must not callsetenv(3) from a parallel thread. It is recommended to only do calls tosetenv()from an early phase of the program when no other threads have been started.
sd_bus_call()andsd_bus_call_async()were added in version 221.
systemd(1),sd-bus(3),sd_bus_call_method(3),sd_bus_call_method_async(3),sd_bus_message_new_method_call(3),sd_bus_message_append(3),sd_bus_error(3)
This page is part of thesystemd (systemd system and service manager) project. Information about the project can be found at ⟨http://www.freedesktop.org/wiki/Software/systemd⟩. If you have a bug report for this manual page, see ⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩. This page was obtained from the project's upstream Git repository ⟨https://github.com/systemd/systemd.git⟩ on 2025-08-11. (At that time, the date of the most recent commit that was found in the repository was 2025-08-11.) If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up-to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgsystemd 258~rc2SD_BUS_CALL(3)Pages that refer to this page:sd-bus(3), sd_bus_call_method(3), sd_bus_message_new_method_call(3), sd_bus_message_seal(3), sd_bus_pending_method_calls(3), sd_bus_set_method_call_timeout(3), sd_bus_set_watch_bind(3), sd_bus_slot_set_userdata(3), sd_bus_start(3), systemd.directives(7), systemd.index(7)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |