sd_bus_add_match_async(3) — Linux manual page


SD_BUS_ADD_MATCH(3)           sd_bus_add_match           SD_BUS_ADD_MATCH(3)

NAME         top

       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

SYNOPSIS         top

       #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_t callback,
                            void *userdata);

       int sd_bus_add_match_async(sd_bus *bus, sd_bus_slot **slot,
                                  const char *match,
                                  sd_bus_message_handler_t callback,
                                  sd_bus_message_handler_t install_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_t callback,
                               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_t callback,
                                     sd_bus_message_handler_t install_callback,
                                     void *userdata);

DESCRIPTION         top

       sd_bus_add_match() installs a match rule for messages received on the
       specified bus connection object bus. The syntax of the match rule
       expression passed in match is described in the D-Bus
       Specification[1]. The specified handler function callback is called
       for eaching incoming message matching the specified expression, the
       userdata 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 similar to
       sd_bus_match_signal(), 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. The install_callback function is
       called when the response is later received, with the response message
       from the broker as parameter. If this function is specified as NULL a
       default implementation is used that terminates the bus connection
       should installing the match fail.

       sd_bus_match_signal() is very similar to sd_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
       as NULL in which case the relevant field of incoming signals is not

       sd_bus_match_signal_async() combines the signal matching logic of
       sd_bus_match_signal() with the asynchronous behaviour of

       On success, and if non-NULL, the slot 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 with
       sd_bus_slot_unref(3). If specified as NULL the lifetime of the match
       is bound to the lifetime of the bus object itself, and the match is
       generally not removed independently. See sd_bus_slot_set_floating(3)
       for details.

       The message m passed to the callback is only borrowed, that is, the
       callback should not call sd_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 call sd_bus_message_ref(3) to create a new

       If an error occurs during the callback invocation, the callback
       should return a negative error number (optionally, a more precise
       error may be returned in ret_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 the bus refers to a direct connection (i.e. not a bus connection,
       as set with sd_bus_set_bus_client(3)) the match is only installed on
       the client side, and the synchronous and asynchronous functions
       operate the same.

RETURN VALUE         top

       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.

NOTES         top

       These APIs are implemented as a shared library, which can be compiled
       and linked to with the libsystemd pkg-config(1) file.

SEE ALSO         top

       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)

NOTES         top

        1. D-Bus Specification

COLOPHON         top

       This page is part of the systemd (systemd system and service manager)
       project.  Information about the project can be found at 
       ⟨⟩.  If you have a bug
       report for this manual page, see
       ⟨⟩.  This
       page was obtained from the project's upstream Git repository
       ⟨⟩ on 2020-11-01.  (At that
       time, the date of the most recent commit that was found in the repos‐
       itory was 2020-11-01.)  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 im‐
       provements to the information in this COLOPHON (which is not part of
       the original manual page), send a mail to

systemd 247                                              SD_BUS_ADD_MATCH(3)

Pages that refer to this page: sd_bus_get_watch_bind(3)sd_bus_set_watch_bind(3)30-systemd-environment-d-generator(7)systemd.index(7)