SD_BUS_LIST_NAMES(3)

💖 NAME 💖

sd_bus_list_names — okay bestie, this is SD_BUS_LIST_NAMES(3), and it's here to retrieve information about registered names on a bus 🚌✨

---

✨ SYNOPSIS ✨

#include <systemd/sd-bus.h>

int sd_bus_list_names(sd_bus *bus, char ***acquired,
                      char ***activatable);

---

🦋 DESCRIPTION 🦋

So sd_bus_list_names() is your little detective for the registered names hanging out on a bus. 💅 If acquired is not NULL, this function calls org.freedesktop.DBus.ListNames[1] to retrieve the list of currently-owned names on the bus. If acquired is not NULL (yes, the page repeats acquired here — I'm just reading the group chat, bestie), the function calls org.freedesktop.DBus.ListActivableNames[2] to retrieve the list of all names on the bus that can be activated. 🔥

Big important vibe check: ownership of the arrays returned by sd_bus_list_names() in acquired and activatable is transferred to the caller, so you — yes, you, main character — are responsible for freeing these arrays and their contents. No leaks, periodt. 🧚

---

🌈 RETURN VALUE 🌈

On success, sd_bus_list_names() returns a non-negative integer. On failure, it returns a negative errno-style error code. ✨

😭 Errors 😭

Returned errors may indicate the following problems:

• -EINVAL — bus or both acquired and activatable were NULL. 💀
• -ENOPKG — The bus cannot be resolved. 😭
• -ECHILD — The bus was created in a different process, library or module instance. 🫠
• -ENOMEM — Memory allocation failed. 🍓
• -ENOTCONN — The bus is not connected. 🙈

---

💜 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. That means 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. 🚨

---

📜 HISTORY 📜

sd_bus_list_names() was added in version 221. 👑

---

👀 SEE ALSO 👀

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

---

🔗 NOTES 🔗

1. org.freedesktop.DBus.ListNames https://dbus.freedesktop.org/doc/dbus-specification.html#bus-messages-list-names
2. org.freedesktop.DBus.ListActivableNames https://dbus.freedesktop.org/doc/dbus-specification.html#bus-messages-list-activatable-names

---

systemd 261.3 • SD_BUS_LIST_NAMES(3) — that's the source/version and manual-name energy, bestie; no date line on this one, so consider yourself timestamped by this cute little sign-off 🫶💖