SD_BUS_SLOT_REF(3)

💅 SD_BUS_SLOT_REF(3) — aka sd_bus_slot_ref, sd_bus_slot_unref, sd_bus_slot_unrefp ✨

okay so bestie, today's main character is the <systemd/sd-bus.h> bus slot refcount trio 💖 no cap, this one's short and sweet, so let's go 🫶

---

🌸 NAME 🌸

sd_bus_slot_ref, sd_bus_slot_unref, sd_bus_slot_unrefp — literally just creating and destroying references to a bus slot object ✨ it's giving "refcount era" and honestly? iconic 👑

---

🎀 SYNOPSIS 🎀

#include <systemd/sd-bus.h>

sd_bus_slot *sd_bus_slot_ref(sd_bus_slot *slot);

sd_bus_slot *sd_bus_slot_unref(sd_bus_slot *slot);

void sd_bus_slot_unrefp(sd_bus_slot **slotp);

three functions, one vibe 🦋

---

💜 DESCRIPTION 💜

sd_bus_slot_ref() bumps the internal reference counter of slot up by one. increment, bestie, that's it, that's the whole job 💅

sd_bus_slot_unref() drops the internal reference counter of slot by one. and here's the dramatic part 😭 once that reference count has dropped to zero, the slot object is destroyed and cannot be used anymore — so any further calls to sd_bus_slot_ref() or sd_bus_slot_unref() are illegal. like, off-limits. do not. it's so over at that point 💀

okay real talk, that last bit is a hard warning — after the refcount hits zero the object is gone for good, and touching it again is undefined-behavior territory. no take-backsies 🙈

sd_bus_slot_unrefp() is basically sd_bus_slot_unref()'s cousin who takes a pointer to a pointer to an sd_bus_slot object instead. this one is lowkey the cleanup-attribute bestie — it pairs perfectly with GCC's and LLVM's Clean-up Variable Attribute[1] 🔥 (peep sd_bus_new(3) if you want an actual example of how to use the cleanup attribute, it's right there for you 🌈).

aaaaand the NULL handling rules, because of course 👀 — sd_bus_slot_ref() and sd_bus_slot_unref() execute no operation if the passed-in bus object address is NULL. meanwhile sd_bus_slot_unrefp() will first dereference its argument, which must not be NULL, and then execute no operation if that thing is NULL. two-step vibe check, iykyk 💫

---

⭐ RETURN VALUE ⭐

• sd_bus_slot_ref() — always returns the argument. always. it's loyal like that 🫶
• sd_bus_slot_unref() — always returns NULL. no notes 💅

---

🦋 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 🌸

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 like, share the object on a schedule, not simultaneously, bestie 😌)

⚠️ caveat time: the code described here uses getenv(3), which is declared to be not multi-thread-safe. this means any code calling the functions described here must not call setenv(3) from a parallel thread. the recommendation? only do calls to setenv() from an early phase of the program, when no other threads have been started. do it before the group chat gets loud 📣

---

👑 HISTORY 👑

sd_bus_slot_ref(), sd_bus_slot_unref(), and sd_bus_slot_unrefp() were added in version 240. vintage but still slaying 💜

---

🌈 SEE ALSO 🌈

systemd(1), sd-bus(3), sd_bus_new(3), sd_bus_message_new(3), sd_bus_call_method_async(3) — go read them, they're literally right there 🎀

---

🍓 NOTES (the footnote one) 🍓

1. Clean-up Variable Attribute — https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html

---

and that's the whole page, bestie ✨ this little gem is from systemd 261.3 — mwah, go refcount responsibly 💖🎀🦋