SD_EVENT_SET_SIGNAL_EXIT(3)

📦
version 261.3 · 15 versions
, in ubuntu stonking

💖 SD_EVENT_SET_SIGNAL_EXIT(3) 💖

okay so bestie, gather round — this one's from the sd-event family (that's section 3 of the manual, iykyk) and it's genuinely one of the comfiest little functions ever. it's called sd_event_set_signal_exit and it's literally "Automatically leave event loop on SIGINT and SIGTERM". no cap, that's the whole vibe 🎀

✨ SYNOPSIS ✨

#include <systemd/sd-event.h>

int sd_event_set_signal_exit(sd_event *event, int b);

🌸 DESCRIPTION 🌸

sd_event_set_signal_exit() is your new bestie for making sure your event loop actually stops when someone hits it with a SIGINT or a SIGTERM. it's a convenience wrapper around calling sd_event_add_signal(3) for both of those signals — like, you could do it manually, but why would you when this exists 💅

and listen, there's a lil catch: both signals get automatically added to the calling thread's signal mask. so if your program is multi-threaded, be careful — either invoke this function before the first thread is started, or manually block the two signals process-wide first. do not skip this step, it's giving "I didn't read the docs" energy 🙈

here's how the b parameter works, bestie:

  • pass b as true → the event loop will terminate on SIGINT and SIGTERM. iconic behavior, honestly 👑
  • pass b as false → it will no longer do that. and when you turn this functionality off, the calling thread's signal mask gets restored to match the state it was in before you turned it on, for those two signals. very "we're so back / it's so over" of it ✨

by default (like, out of the box), those two signals are not handled by the event loop, and Linux' default signal handling for them is in effect.

and here's a little cultural note: it is customary for UNIX programs to exit on either of these two signals, so it's typically a good idea to enable this functionality for the main event loop of a program. fr fr, do it 🫶

⭐ RETURN VALUE ⭐

sd_event_set_signal_exit() is out here returning three different vibes depending on how it went:

  • a positive non-zero value when the setting was successfully changed — slay 💖
  • zero when the specified setting was already in effect — like, we been knew, no change needed
  • on failure, a negative errno-style error code — 😭

💀 Errors

returned errors may indicate the following problems:

  • -ECHILD — the event loop has been created in a different process, library or module instance. awkward. added in version 252.
  • -EINVAL — the passed event loop object was invalid. added in version 252.

🦋 NOTES 🦋

the functions described here are available as a shared library, which can be compiled against and linked to with the libsystemd pkg-config(1) file. standard bestie behavior 🎀

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, just don't all touch it at literally the same moment, okay? 💅

⚠️ heads up: 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. please, for the love of everything, respect this one 🙏

🌈 HISTORY 🌈

sd_event_set_signal_exit() was added in version 252. a relatively recent queen, but a queen nonetheless 👑

🔥 SEE ALSO 🔥

okay that's the whole page!! this beauty is from systemd 261.3, page SD_EVENT_SET_SIGNAL_EXIT(3) — go forth and let your event loop exit gracefully on SIGINT and SIGTERM, bestie 🍓✨💜

📦 where this page comes from