SD_EVEN...ALLBACK(3)

💅 SD_EVEN...ALLBACK(3) — the destroy-callback girlies

okay so bestie, we're in sd_event_source_set_destroy_callback territory today — that's the manual page name, iykyk. this whole page is about defining the callback function for resource cleanup, and it's genuinely so useful. let's get into it 🎀

---

✨ SYNOPSIS ✨

like, first you gotta let it know you're interested:

#include <systemd/sd-event.h>

typedef int (*sd_event_destroy_t)(void *userdata);

int sd_event_source_set_destroy_callback(sd_event_source *source,
                                         sd_event_destroy_t callback);

int sd_event_source_get_destroy_callback(sd_event_source *source,
                                         sd_event_destroy_t *callback);

---

🌸 DESCRIPTION 🌸

setting it — sd_event_source_set_destroy_callback()

so this one sets callback as the callback function that gets called right before the event source object source is deallocated. right before. like the last thing that happens. the way that it's the final goodbye 😭

when it runs, the userdata pointer from the event source object gets passed in as the userdata parameter. and where does that pointer come from? you can set it by passing an argument to the constructor functions — see sd_event_add_io(3) — or you can set it directly, see sd_event_source_set_userdata(3). either way, slay.

and listen, this callback function is called even if userdata is NULL. no skipping, no ghosting, it shows up regardless 💅

⚠️ but here's the serious part, bestie, don't sleep on it: this callback is invoked at a time where the event source object itself is already invalidated. so executing operations on it, or taking new references to the event source object? not permissible. at all. it's giving "too late, the vibe check already happened." do not try it. 🙈

getting it — sd_event_source_get_destroy_callback()

this one just returns the current callback for source, tucked into the callback parameter. cute, simple, iconic. ✨

---

🦋 RETURN VALUE 🦋

on success, sd_event_source_set_destroy_callback() returns 0 or a positive integer. on failure, it returns a negative errno-style error code. that's the whole deal.

sd_event_source_get_destroy_callback() returns positive if the destroy callback function is set, and 0 if it's not. on failure, it returns a negative errno-style error code. so like: positive = yes bestie, zero = nope, negative = something went wrong 😭

🌈 Errors

the errors it can return may indicate these problems, and there's literally one:

• -EINVAL — the source parameter is NULL. that's it. that's the error. don't pass NULL, periodt.

---

⭐ 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. standard systemd behavior, we love her 💖

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, though. and multiple independent objects may be used from different threads in parallel. so like — one object, one thread at a time. no sharing, no chaos. 🫶

the code described here uses getenv(3), which is declared to be not multi-thread-safe. which means: the code calling the functions described here must not call setenv(3) from a parallel thread. ngl the recommendation is to only do calls to setenv() from an early phase of the program, when no other threads have been started. get it done early, then move on. 🧚

---

👑 HISTORY 👑

sd_event_destroy_t(), sd_event_source_set_destroy_callback(), and sd_event_source_get_destroy_callback() were added in version 239. so they've been around. veterans, honestly. 🔥

---

💜 SEE ALSO 💜

go read these next, they're all in the family:

systemd(1), sd-event(3), sd_event_add_io(3), sd_event_add_time(3), sd_event_add_signal(3), sd_event_add_child(3), sd_event_add_inotify(3), sd_event_add_defer(3), sd_event_source_set_userdata(3)

---

okay that's the whole page, bestie, you're officially educated 💅✨ this was systemd 261.3 — go forth and clean up your resources responsibly, mwah 🎀🦋💖