SD_BUS_ADD_MATCH(3)           sd_bus_add_match           SD_BUS_ADD_MATCH(3)

NAME         top

       sd_bus_add_match - Add a match rule for message dispatching

SYNOPSIS         top

       #include <systemd/sd-bus.h>

       int sd_bus_add_match(sd_bus *bus, sd_bus_slot **slot,
                            const char *match,
                            sd_bus_message_handler_t callback,
                            void *userdata);

       typedef int (*sd_bus_message_handler_t)(sd_bus_message *m,
                                               void *userdata,
                                               sd_bus_error *ret_error);

DESCRIPTION         top

       sd_bus_add_match() installs a match rule for incoming 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.

       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
       cannot be removed independently.

       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. If it wants other callbacks
       that match the same rule to be called, it should return 0. Otherwise
       it should return a positive integer.

RETURN VALUE         top

       On success, sd_bus_add_match() returns 0 or a positive integer. On
       failure, it returns a negative errno-style error code.

SEE ALSO         top

       systemd(1), sd-bus(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 2019-05-09.  (At that
       time, the date of the most recent commit that was found in the repos‐
       itory was 2019-05-09.)  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 is not part
       of the original manual page), send a mail to

systemd 234                                              SD_BUS_ADD_MATCH(3)

Pages that refer to this page: busctl(1)systemd.directives(7)systemd.index(7)