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 |NOTES |COLOPHON | |
SD_BUS_ADD_MATCH(3) sd_bus_add_matchSD_BUS_ADD_MATCH(3)sd_bus_add_match, sd_bus_add_match_async, sd_bus_match_signal, sd_bus_match_signal_async - Add a match rule for incoming message dispatching
#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_add_match(sd_bus *bus, sd_bus_slot **slot,const char *match,sd_bus_message_handler_tcallback,void *userdata);int sd_bus_add_match_async(sd_bus *bus, sd_bus_slot **slot,const char *match,sd_bus_message_handler_tcallback,sd_bus_message_handler_tinstall_callback,void *userdata);int sd_bus_match_signal(sd_bus *bus, sd_bus_slot **slot,const char *sender, const char *path,const char *interface, const char *member,sd_bus_message_handler_tcallback,void *userdata);int sd_bus_match_signal_async(sd_bus *bus, sd_bus_slot **slot,const char *sender,const char *path,const char *interface,const char *member,sd_bus_message_handler_tcallback,sd_bus_message_handler_tinstall_callback,void *userdata);
sd_bus_add_match()installs a match rule for messages received on the specified bus connection objectbus. The syntax of the match rule expression passed inmatch is described in theD-BusSpecification[1]. The specified handler functioncallback is called for each incoming message matching the specified expression, theuserdata parameter is passed as-is to the callback function. The match is installed synchronously when connected to a bus broker, i.e. the call sends a control message requested the match to be added to the broker and waits until the broker confirms the match has been installed successfully.sd_bus_add_match_async()operates very similarly tosd_bus_add_match(), however it installs the match asynchronously, in a non-blocking fashion: a request is sent to the broker, but the call does not wait for a response. Theinstall_callback function is called when the response is later received, with the response message from the broker as parameter. If this function is specified asNULLa default implementation is used that terminates the bus connection should installing the match fail.sd_bus_match_signal()is very similar tosd_bus_add_match(), but only matches signals, and instead of a match expression accepts four parameters:sender (the service name of the sender),path (the object path of the emitting object),interface (the interface the signal belongs to),member (the signal name), from which the match string is internally generated. Optionally, these parameters may be specified asNULLin which case the relevant field of incoming signals is not tested.sd_bus_match_signal_async()combines the signal matching logic ofsd_bus_match_signal()with the asynchronous behaviour ofsd_bus_add_match_async(). On success, and if non-NULL, theslot return parameter will be set to a slot object that may be used as a reference to the installed match, and may be utilized to remove it again at a later time withsd_bus_slot_unref(3). If specified asNULLthe lifetime of the match is bound to the lifetime of the bus object itself, and the match is generally not removed independently. Seesd_bus_slot_set_floating(3) for details. 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. If an error occurs during the callback invocation, the callback should return a negative error number (optionally, a more precise error may be returned inret_error, as well). If it wants other callbacks that match the same rule to be called, it should return 0. Otherwise, it should return a positive integer. If thebus refers to a direct connection (i.e. not a bus connection, as set withsd_bus_set_bus_client(3)) the match is only installed on the client side, and the synchronous and asynchronous functions operate the same.
On success,sd_bus_add_match()and the other calls return 0 or a positive integer. On failure, they return a negative errno-style error code.
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_add_match()andsd_bus_message_handler_t()were added in version 221.sd_bus_add_match_async(),sd_bus_match_signal(), andsd_bus_match_signal_async()were added in version 237.
systemd(1),sd-bus(3),sd_bus_slot_unref(3),sd_bus_message_ref(3),sd_bus_set_bus_client(3),sd_bus_slot_set_floating(3)
1. D-Bus Specificationhttps://dbus.freedesktop.org/doc/dbus-specification.html
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_ADD_MATCH(3)Pages that refer to this page:busctl(1), sd-bus(3), sd_bus_call(3), sd_bus_default(3), sd_bus_process(3), sd_bus_set_connected_signal(3), sd_bus_set_watch_bind(3), sd_bus_slot_set_destroy_callback(3), sd_bus_slot_set_floating(3), sd_bus_slot_set_userdata(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. | |