---
name: "sd_bus_message_new_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_message_new_signal"
---

# sd\_bus\_message\_new\_signal(3)

Create a signal message

## NAME

sd\_bus\_message\_new\_signal, sd\_bus\_message\_new\_signal\_to - Create a signal message

## SYNOPSIS

```
#include <systemd/sd-bus.h>
```

**int sd\_bus\_message\_new\_signal(sd\_bus \****bus***, sd\_bus\_message \*\****m***, const char \****path***, const char \****interface***, const char \****member***);**

**int sd\_bus\_message\_new\_signal\_to(sd\_bus \****bus***, sd\_bus\_message \*\****m***, const char \****destination***, const char \****path***, const char \****interface***, const char \****member***);**

## DESCRIPTION

The **sd\_bus\_message\_new\_signal()** function creates a new bus message object that encapsulates a D-Bus signal, and returns it in the *m* output parameter. The signal will be sent to path *path*, on the interface *interface*, member *member*. When this message is sent, no reply is expected. See [**sd\_bus\_message\_new\_method\_call**(3)](/sd_bus_message_new_method_call/3.md) for a short description of the meaning of the *path*, *interface*, and *member* parameters.

**sd\_bus\_message\_new\_signal\_to()** is a shorthand for creating a new bus message to a specific destination. It's behavior is similar to calling **sd\_bus\_message\_new\_signal()** followed by calling [**sd\_bus\_message\_set\_destination**(3)](/sd_bus_message_set_destination/3.md).

## RETURN VALUE

This function returns 0 if the message object was successfully created, and a negative errno-style error code otherwise.

### Errors

Returned errors may indicate the following problems:

**-EINVAL**

The output parameter *m* is **NULL**.

The *path* parameter is not a valid D-Bus path ("/an/object/path"), the *interface* parameter is not a valid D-Bus interface name ("an.interface.name"), or the *member* parameter is not a valid D-Bus member ("Name").

**-ENOTCONN**

The bus parameter *bus* is **NULL** or the bus is not connected.

**-ENOMEM**

Memory allocation failed.

## 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.

## EXAMPLES

**Example 1. Send a simple signal**

```
/* SPDX-License-Identifier: MIT-0 */
#include <systemd/sd-bus.h>
#define _cleanup_(f) __attribute__((cleanup(f)))
int send_unit_files_changed(sd_bus *bus) {
  _cleanup_(sd_bus_message_unrefp) sd_bus_message *message = NULL;
  int r;
  r = sd_bus_message_new_signal(bus, &message,
                                "/org/freedesktop/systemd1",
                                "org.freedesktop.systemd1.Manager",
                                "UnitFilesChanged");
  if (r < 0)
    return r;
  return sd_bus_send(bus, message, NULL);
}
```

This function in systemd sources is used to emit the "UnitFilesChanged" signal when the unit files have been changed.

## SEE ALSO

[**systemd**(1)](/systemd/1.md), [**sd-bus**(3)](/sd-bus/3.md), [**sd\_bus\_emit\_signal**(3)](/sd_bus_emit_signal/3.md), [**sd\_bus\_message\_set\_destination**(3)](/sd_bus_message_set_destination/3.md)