SD_EVENT_EXIT(3)

✨ SD_EVENT_EXIT ✨

okay bestie so picture this: you're deep in sd-event land (that's the manual page, iykyk) and you need your event loop to leave the party gracefully 💅 that's literally what sd_event_exit and sd_event_get_exit_code are for. two little functions, huge main character energy.

---

🌸 SYNOPSIS 🌸

#include <systemd/sd-event.h>

int sd_event_exit(sd_event *event, int code);

int sd_event_get_exit_code(sd_event *event, int *ret);

---

🎀 DESCRIPTION 🎀

💖 sd_event_exit() — the "we're leaving, grab your coat" function

sd_event_exit() politely but firmly requests that the event loop you passed in as the event event loop object exit. the code parameter can literally be any integer value you want — no cap, any int — and it gets returned as-is by sd_event_loop(3) after the last event loop iteration. you can also come back and ask for it later with sd_event_get_exit_code() (more on that below 👇).

so when exiting gets requested, here's the vibe: the event loop stops listening for and dispatching regular event sources. rude? maybe. necessary? absolutely. instead it proceeds to execute only the event sources registered with sd_event_add_exit(3), in the order defined by their priority. once all the exit event sources have been dispatched, the event loop is terminated. done. finished. ghosted. 🦋

and here's a lil edge case for you: if sd_event_exit() gets invoked a second time while the event loop is still processing exit event sources, the exit code stored in the event loop object is updated, but otherwise no further operation is executed. so like, the code changes, but nothing else happens. noted. 📝

🧚 sd_event_get_exit_code() — the "wait, what did we say earlier?" function

sd_event_get_exit_code() lets you query the exit code that was passed to an earlier call of sd_event_exit(). and plot twist: the return parameter ret may be set to NULL, which is the move when you just wanna check if sd_event_exit() has been called before — because sd_event_get_exit_code() fails with -ENODATA if that's not the case (see below, bestie, it's all listed 💜).

⚠️ a real warning, not a fake one

while the full positive and negative integer ranges may be used for the exit code, care should be taken not pick exit codes that conflict with regular exit codes returned by sd_event_loop(), if these exit codes shall be distinguishable. like, don't be out here making your codes ambiguous, that's not the slay you think it is 😭

✨ the coolest part honestly

note that for most event source types, passing the callback pointer as NULL in the respective constructor call (i.e. in sd_event_add_time(3), sd_event_add_signal(3), ...) has the effect of sd_event_exit() being invoked once the event source triggers — with the specified userdata pointer cast to an integer as the exit code parameter. this is so useful to automatically terminate an event loop after some condition, such as a timeout or reception of SIGTERM or similar. see the documentation for the respective constructor call for the deets. iconic behaviour tbh 👑

---

🔥 RETURN VALUE 🔥

on success, sd_event_exit() and sd_event_get_exit_code() return 0 or a positive integer. on failure, they return a negative errno-style error code. classic.

💀 Errors

returned errors may indicate the following problems:

• -EINVAL — the event loop object or error code pointer are invalid. check ur pointers bestie 🙈
• -ECHILD — the event loop was created in a different process, library or module instance. not yours, not your problem.
• -ESTALE — the event loop has exited already and all exit handlers are already processed. it's over, it's done, the party's cleaned up.
• -ENODATA — returned by sd_event_get_exit_code() in case the event loop has not been requested to exit yet. nothing to report yet, come back later 🍓

---

🌈 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. so like, take turns. sharing is caring but also sharing is scheduling.
• 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.

ok this one's a real caveat, not a vibe — don't be calling setenv() from a parallel thread while using these. keep your env setup in the early phase before any other threads start. periodt. 💅

---

⭐ HISTORY ⭐

sd_event_exit() and sd_event_get_exit_code() were added in version 229. they're old money at this point, lowkey legendary.

---

👑 SEE ALSO 👑

systemd(1), sd-event(3), sd_event_new(3), sd_event_add_exit(3), sd_event_add_time(3), sd_event_add_signal(3), sd_event_add_io(3), sd_event_add_defer(3), sd_event_add_inotify(3)

---

ok that's the whole page, you're officially educated 🎓💖 this is from systemd 261.3, the SD_EVENT_EXIT(3) page — go forth and exit your event loops with confidence, bestie. mwah 💋✨