--- name: "sd_bus_add_match_async" section: "3" platform: "linux" package: "libsystemd-dev" version: "257.13-1~deb13u1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/sd_bus_add_match" --- # sd\_bus\_add\_match\_async(3) Add a match rule for incoming message dispatching Part of [sd\_bus\_add\_match(3)](/sd_bus_add_match/3.md). ## NAME 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 ## SYNOPSIS ``` #include ``` **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 **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 each 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 similarly to **sd\_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. 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 tested. **sd\_bus\_match\_signal\_async()** combines the signal matching logic of **sd\_bus\_match\_signal()** with the asynchronous behaviour of **sd\_bus\_add\_match\_async()**. 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)](/sd_bus_slot_unref/3.md). 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)](/sd_bus_slot_set_floating/3.md) for details. The message *m* passed to the callback is only borrowed, that is, the callback should not call [**sd\_bus\_message\_unref**(3)](/sd_bus_message_unref/3.md) 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)](/sd_bus_message_ref/3.md) 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 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)](/sd_bus_set_bus_client/3.md)) the match is only installed on the client side, and the synchronous and asynchronous functions operate the same. ## RETURN VALUE 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 Functions described here are available as a shared library, which can be compiled against and linked to with the **libsystemd** [**pkg-config**(1)](/pkg-config/1.md) file. The code described here uses [**getenv**(3)](/getenv/3.md), which is declared to be not multi-thread-safe. This means that the code calling the functions described here must not call [**setenv**(3)](/setenv/3.md) from a parallel thread. It is recommended to only do calls to **setenv()** from an early phase of the program when no other threads have been started. ## HISTORY **sd\_bus\_add\_match()** and **sd\_bus\_message\_handler\_t()** were added in version 221. **sd\_bus\_add\_match\_async()**, **sd\_bus\_match\_signal()**, and **sd\_bus\_match\_signal\_async()** were added in version 237. ## SEE ALSO [**systemd**(1)](/systemd/1.md), [**sd-bus**(3)](/sd-bus/3.md), [**sd\_bus\_slot\_unref**(3)](/sd_bus_slot_unref/3.md), [**sd\_bus\_message\_ref**(3)](/sd_bus_message_ref/3.md), [**sd\_bus\_set\_bus\_client**(3)](/sd_bus_set_bus_client/3.md), [**sd\_bus\_slot\_set\_floating**(3)](/sd_bus_slot_set_floating/3.md) ## NOTES - 1\. D-Bus Specification https://dbus.freedesktop.org/doc/dbus-specification.html