SD_BUS_ME...NEW_SIGNAL(3)

🎀 SD_BUS_ME...NEW_SIGNAL(3) — sd_bus_message_new_signal 🎀

okay bestie, welcome to the sd_bus_message_new_signal manual page — manual name folded in right here: sd_bus_message_new_signal. We're making D-Bus signal messages, and the vibe is very “send it and don’t wait for a reply.” 💅

💖 NAME 💖

sd_bus_message_new_signal(), sd_bus_message_new_signal_to() — Create a signal message. That’s the whole name section, and it ate. ✨

✨ 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) 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. Its behavior is similar to calling sd_bus_message_new_signal() followed by calling sd_bus_message_set_destination(3). It’s giving “same signal energy, but with a destination attached.” 🫶

💜 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) 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), which is declared to be not multi-thread-safe. This means that the code calling the functions described here must not call setenv(3) 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. Literally main character signal behavior. 💖

👑 SEE ALSO 👑

• systemd(1)
• sd-bus(3)
• sd_bus_emit_signal(3)
• sd_bus_message_set_destination(3)

---

okay that’s the whole page, bestie. cute sign-off from the footer: source/version is systemd 261.3, and no date is listed on this page. go make some iconic signals 💖✨ periodt ✨💖