--- name: "sd_bus_emit_signal" section: "3" platform: "linux" package: "systemd-libs" version: "262.1-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/sd_bus_emit_signal" --- # sd\_bus\_emit\_signal(3) Convenience functions for emitting (standard) D-Bus signals ## NAME sd\_bus\_emit\_signal, sd\_bus\_emit\_signalv, sd\_bus\_emit\_signal\_to, sd\_bus\_emit\_signal\_tov, sd\_bus\_emit\_interfaces\_added, sd\_bus\_emit\_interfaces\_added\_strv, sd\_bus\_emit\_interfaces\_removed, sd\_bus\_emit\_interfaces\_removed\_strv, sd\_bus\_emit\_properties\_changed, sd\_bus\_emit\_properties\_changed\_strv, sd\_bus\_emit\_object\_added, sd\_bus\_emit\_object\_removed - Convenience functions for emitting (standard) D-Bus signals ## SYNOPSIS ``` #include ``` **int sd\_bus\_emit\_signal(sd\_bus \****bus***, const char \****path***, const char \****interface***, const char \****member***, const char \****types***, ...);** **int sd\_bus\_emit\_signalv(sd\_bus \****bus***, const char \****path***, const char \****interface***, const char \****member***, const char \****types***, va\_list** *ap***);** **int sd\_bus\_emit\_signal\_to(sd\_bus \****bus***, const char \****destination***, const char \****path***, const char \****interface***, const char \****member***, const char \****types***, ...);** **int sd\_bus\_emit\_signal\_tov(sd\_bus \****bus***, const char \****destination***, const char \****path***, const char \****interface***, const char \****member***, const char \****types***, va\_list** *ap***);** **int sd\_bus\_emit\_interfaces\_added(sd\_bus \****bus***, const char \****path***, const char \****interface***, ...);** **int sd\_bus\_emit\_interfaces\_added\_strv(sd\_bus \****bus***, const char \****path***, char \*\****interfaces***);** **int sd\_bus\_emit\_interfaces\_removed(sd\_bus \****bus***, const char \****path***, const char \****interface***, ...);** **int sd\_bus\_emit\_interfaces\_removed\_strv(sd\_bus \****bus***, const char \****path***, char \*\****interfaces***);** **int sd\_bus\_emit\_properties\_changed(sd\_bus \****bus***, const char \****path***, const char \****interface***, const char \****name***, ...);** **int sd\_bus\_emit\_properties\_changed\_strv(sd\_bus \****bus***, const char \****path***, const char \****interface***, char \*\****names***);** **int sd\_bus\_emit\_object\_added(sd\_bus \****bus***, const char \****path***);** **int sd\_bus\_emit\_object\_removed(sd\_bus \****bus***, const char \****path***);** ## DESCRIPTION **sd\_bus\_emit\_signal()** is a convenience function for initializing a bus message object and emitting the corresponding D-Bus signal. It combines the [**sd\_bus\_message\_new\_signal**(3)](/sd_bus_message_new_signal/3.md), [**sd\_bus\_message\_append**(3)](/sd_bus_message_append/3.md) and [**sd\_bus\_send**(3)](/sd_bus_send/3.md) functions into a single function call. **sd\_bus\_emit\_signalv()** is equivalent to **sd\_bus\_message\_append()**, except that it is called with a "va\_list" instead of a variable number of arguments. **sd\_bus\_emit\_signal\_to()** and **sd\_bus\_emit\_signal\_tov()** are identical to **sd\_bus\_emit\_signal()** and **sd\_bus\_emit\_signalv()**, except that they can emit the signal to a single destination. Give *destination* as **NULL** to broadcast the signal. **sd\_bus\_emit\_interfaces\_added()** and **sd\_bus\_emit\_interfaces\_removed()** are used to implement the **InterfacesAdded** and **InterfacesRemoved** signals of the **org.freedesktop.DBus.ObjectManager** interface. They take a path whose interfaces have been modified as an argument and a variable list of interfaces that have been added or removed, respectively. The final argument passed to **sd\_bus\_emit\_interfaces\_added()** and **sd\_bus\_emit\_interfaces\_removed()** *must* be **NULL**. This allows both functions to safely determine the number of passed interface arguments. **sd\_bus\_emit\_interfaces\_added\_strv()** and **sd\_bus\_emit\_interfaces\_removed\_strv()** are identical to their respective counterparts but both take the list of interfaces as a single argument instead of a variable number of arguments. **sd\_bus\_emit\_properties\_changed()** is used to implement the **PropertiesChanged** signal of the **org.freedesktop.DBus.Properties** interface. It takes an object path, interface and a variable list of property names as its arguments. The final argument passed to **sd\_bus\_emit\_properties\_changed()** *must* be **NULL**. This allows it to safely determine the number of passed property names. **sd\_bus\_emit\_properties\_changed\_strv()** is identical to **sd\_bus\_emit\_properties\_changed()** but takes the list of property names as a single argument instead of a variable number of arguments. **sd\_bus\_emit\_object\_added()** and **sd\_bus\_emit\_object\_removed()** are convenience functions for emitting the **InterfacesAdded** or **InterfacesRemoved** signals for all interfaces registered on a specific object path, respectively. This includes any parent fallback vtables if they are not overridden by a more applicable child vtable. It also includes all the standard D-Bus interfaces implemented by sd-bus itself on any registered object. Note that **sd\_bus\_emit\_interfaces\_added()**, **sd\_bus\_emit\_interfaces\_removed()**, **sd\_bus\_emit\_object\_added()** and **sd\_bus\_emit\_object\_removed()** require an object manager to have been registered on the given object path or one of its parent object paths using [**sd\_bus\_add\_object\_manager**(3)](/sd_bus_add_object_manager/3.md). ## RETURN VALUE On success, these functions return a non-negative integer. On failure, they return a negative errno-style error code. ### Errors Returned errors may indicate the following problems: **-EINVAL** One of the required parameters is **NULL** or invalid. A reserved D-Bus interface was passed as the *interface* parameter. **-ENOPKG** The bus cannot be resolved. **-ECHILD** The bus was created in a different process, library or module instance. **-ENOMEM** Memory allocation failed. **-ESRCH** One of **sd\_bus\_emit\_interfaces\_added()**, **sd\_bus\_emit\_interfaces\_removed()**, **sd\_bus\_emit\_object\_added()** or **sd\_bus\_emit\_object\_removed()** was called on an object without an object manager registered on its own object path or one of its parent object paths. See the man pages of [**sd\_bus\_message\_new\_signal**(3)](/sd_bus_message_new_signal/3.md), [**sd\_bus\_message\_append**(3)](/sd_bus_message_append/3.md) and [**sd\_bus\_send**(3)](/sd_bus_send/3.md) for more possible errors. ## 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. All functions listed here are thread-agnostic and only a single thread may operate on a given object at any given time. Different threads may access the same object at different times. Multiple independent objects may be used from different threads in parallel. 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\_emit\_signal()**, **sd\_bus\_emit\_interfaces\_added()**, **sd\_bus\_emit\_interfaces\_added\_strv()**, **sd\_bus\_emit\_interfaces\_removed()**, **sd\_bus\_emit\_interfaces\_removed\_strv()**, **sd\_bus\_emit\_properties\_changed()**, **sd\_bus\_emit\_properties\_changed\_strv()**, were added in version 221. **sd\_bus\_emit\_object\_added()**, and **sd\_bus\_emit\_object\_removed()** were added in version 222. **sd\_bus\_emit\_signalv()** was added in version 246. **sd\_bus\_emit\_signal\_to()** and **sd\_bus\_emit\_signal\_tov()** were added in version 253. ## SEE ALSO [**sd-bus**(3)](/sd-bus/3.md), [**busctl**(1)](/busctl/1.md), [**sd\_bus\_message\_new\_signal**(3)](/sd_bus_message_new_signal/3.md), [**sd\_bus\_message\_append**(3)](/sd_bus_message_append/3.md), [**sd\_bus\_send**(3)](/sd_bus_send/3.md), [**sd\_bus\_call\_method**(3)](/sd_bus_call_method/3.md)