SD_BUS_ADD_NODE_ENUMERATOR(3)

💅 sd_bus_add_node_enumerator(3) — like, the whole manual page, bestie

okay so this is the page for sd_bus_add_node_enumerator in the sd_bus_add_node_enumerator manual, and by the end of it you're gonna know exactly how to make sd-bus spill the tea about which child objects exist under a path prefix. it's giving backend magic. let's go 🦋

---

✨ NAME ✨

sd_bus_add_node_enumerator — adds a node enumerator for a D-Bus object path prefix 🎀

---

🌸 SYNOPSIS 🌸

#include <systemd/sd-bus.h>

typedef int (*sd_bus_node_enumerator_t)(sd_bus *bus, const char *prefix,
                                        void *userdata,
                                        char ***ret_nodes,
                                        sd_bus_error *ret_error);

int sd_bus_add_node_enumerator(sd_bus *bus, sd_bus_slot **slot,
                               const char *path,
                               sd_bus_node_enumerator_t callback,
                               void *userdata);

---

👑 DESCRIPTION 👑

sd_bus_add_node_enumerator() adds a D-Bus node enumerator for the given path prefix. basically: when someone needs the list of available objects sitting under that prefix, your callback gets called to do the enumerating. when exactly? like when org.freedesktop.DBus.Introspectable.Introspect or org.freedesktop.DBus.ObjectManager.GetManagedObjects get called on a D-Bus service that sd-bus is managing. so it's on-demand, not eager. iconic behavior tbh ✨

callback is called with the path and the userdata pointer that you registered with sd_bus_add_node_enumerator(). when it runs, it should store all the child object paths of the given path prefix in ret_nodes, with a NULL terminator item at the end, periodt. the callback should return a non-negative value on success. if something goes wrong, it can either return a negative integer, set ret_error to a non-empty error, or do both — dealer's choice 💅. any errors your callback returns get encoded as D-Bus errors and sent right back to whoever called. and heads up: errors in ret_error take priority over negative return values. no cap.

🫶 real talk: a node enumerator callback will only ever be called for a single path prefix, so for normal operation you can literally ignore prefix. yes, it's an argument you probably never touch. also, a node enumerator only exists to enumerate the available child objects under a given prefix. if what you actually want is to install a handler for a set of dynamic child objects, that's a different vibe — use sd_bus_add_fallback_vtable(3) instead. iykyk.

when sd_bus_add_node_enumerator() succeeds, a slot is created internally. if the output parameter slot is NULL, a "floating" slot object is created — see sd_bus_slot_set_floating(3). otherwise, a pointer to the slot object gets returned to you. in that case you should drop the reference to the slot object when you don't need the node enumerator anymore, see sd_bus_slot_unref(3). clean up after yourself bestie 💖

---

⭐ RETURN VALUE ⭐

on success, sd_bus_add_node_enumerator() returns a non-negative integer. slay. on failure, it returns a negative errno-style error code 😭

🍓 Errors

the errors it can hand you back may indicate these problems:

• -EINVAL — one of the required parameters is NULL, or path is not a valid object path. check ur inputs bestie 🙈
• -ENOPKG — the bus cannot be resolved.
• -ECHILD — the bus was created in a different process, library or module instance. awkward 💀
• -ENOMEM — memory allocation failed.

---

🧚 NOTES 🧚

the functions described here are available as a shared library, which you can compile against and link to with the libsystemd pkg-config(1) file. yes, the usual setup 🌈

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. and multiple independent objects may be used from different threads in parallel. so: taking turns is fine, tag-teaming the same object at the same time is not 🎀

💀 caveat time: 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. the recommendation is to only do calls to setenv() from an early phase of the program when no other threads have been started yet. get in, set ur env, get out. periodt.

---

🦋 HISTORY 🦋

sd_bus_node_enumerator_t() and sd_bus_add_node_enumerator() were added in version 221. vintage, honestly 👑

---

🔥 SEE ALSO 🔥

• sd-bus(3)
• busctl(1)
• sd_bus_add_fallback_vtable(3)
• sd_bus_slot_unref(3)

---

and that's the whole page, bestie 💜 this cutie is from systemd 261.3 — go forth and enumerate those nodes, you absolute main character 🌟💅✨