SD_EVENT_ADD_SIGNAL(3)

📦
version 261.3 · 15 versions
, in ubuntu stonking

💖 SD_EVENT_ADD_SIGNAL(3) — the sd-event girlies' guide to catching signals 💖

okay so bestie, this whole page lives in the sd-event manual and it's literally about wiring up UNIX process signals as event sources. signal-handling glow-up, no cap ✨

🌸 NAME 🌸

sd_event_add_signal, sd_event_source_get_signal, sd_event_signal_handler_t, SD_EVENT_SIGNAL_PROCMASK — add a UNIX process signal event source to an event loop 🎀

She's giving "one function, three friends, and a flag." Iconic.

✨ SYNOPSIS ✨

#include <systemd/sd-event.h>

typedef struct sd_event_source sd_event_source;

SD_EVENT_SIGNAL_PROCMASK

typedef int (*sd_event_signal_handler_t)(sd_event_source *s,
                                         const struct signalfd_siginfo *si,
                                         void *userdata);

int sd_event_add_signal(sd_event *event, sd_event_source **source,
                        int signal, sd_event_signal_handler_t handler,
                        void *userdata);

int sd_event_source_get_signal(sd_event_source *source);

💅 DESCRIPTION 💅

So sd_event_add_signal() adds a brand-new UNIX process signal event source to an event loop. Slay. The event loop object? That's the event parameter. The event source object comes back to you in the source parameter. And the signal parameter specifies the numeric signal to be handled — peek signal(7) for the deets, iykyk 💜

The handler parameter is a function to call when the signal is received — or NULL, your call. Your handler function gets passed the userdata pointer, which you can choose freely, so go off bestie 🫶 The handler also receives a pointer to a signalfd_siginfo structure containing information about the received signal — signalfd(2) has further info if you wanna dig in. The handler may return negative to signal an error (see below, they're listed), and other return values are ignored. If handler is NULL, a default handler that calls sd_event_exit(3) gets used. Convenient!

⚠️ Only a single handler may be installed for a specific signal. And the signal must be blocked in all threads before this function is called — using sigprocmask(2) or pthread_sigmask(3). Not optional, bestie.

For convenience, if you OR the special flag SD_EVENT_SIGNAL_PROCMASK into the specified signal, the signal will be automatically masked as necessary, for the calling thread. Cute, right? But note that this only works reliably if the signal is already masked in all other threads of the process, or if there are no other threads at the moment of invocation. So thread timing matters, lowkey 😭

By default, the event source is enabled permanently (SD_EVENT_ON), but you can change that with sd_event_source_set_enabled(3). And if the handler function returns a negative error code, it will either be disabled after the invocation — even if the SD_EVENT_ON mode was requested before — or it will cause the loop to terminate. See sd_event_source_set_exit_on_failure(3) for that one 🦋

To destroy an event source object use sd_event_source_unref(3), but pls note the event source is only removed from the event loop when all references to the event source are dropped. So if you want to make sure an event source does not fire anymore, even if it is still referenced, disable it with sd_event_source_set_enabled(3) using SD_EVENT_OFF. That's the move 💯

If the second parameter of sd_event_add_signal() is NULL, no reference to the event source object is returned. In this case, the event source is considered "floating", and will be destroyed implicitly when the event loop itself is destroyed. Floats away like a little butterfly 🦋✨

If the handler parameter to sd_event_add_signal() is NULL, and the event source fires, this will be considered a request to exit the event loop. In that case, the userdata parameter, cast to an integer, is passed as the exit code parameter to sd_event_exit(3). Sneaky but valid.

And finally, sd_event_source_get_signal() returns the configured signal number of an event source created previously with sd_event_add_signal(). It takes the event source object as the source parameter. Very demure, very mindful 🌸

🔥 RETURN VALUE 🔥

On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error code. Main character energy either way 👑

😭 Errors

Returned errors may indicate the following problems:

  • -ENOMEM — Not enough memory to allocate an object. tragic.
  • -EINVAL — An invalid argument has been passed. check ur args bestie.
  • -EBUSY — A handler is already installed for this signal, or the signal was not blocked previously. one handler per signal, periodt.
  • -ESTALE — The event loop is already terminated. it's over, it's done 💀
  • -ECHILD — The event loop has been created in a different process, library or module instance. wrong bloodline ngl.
  • -EDOM — The passed event source is not a signal event source. ma'am that's not the vibe check you thought it was 🙈

🌈 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. Link her up 💖

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, share nicely 😌

⚠️ The code described here uses getenv(3), which is declared to be not multi-thread-safe. This 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. do it early, do it once, don't be chaotic 🫶

⭐ HISTORY ⭐

sd_event_add_signal(), sd_event_signal_handler_t(), and sd_event_source_get_signal() were added in version 217. vintage but still cute 🎀

🦋 SEE ALSO 🦋

systemd(1), sd-event(3), sd_event_new(3), sd_event_now(3), sd_event_add_io(3), sd_event_add_time(3), sd_event_add_child(3), sd_event_add_inotify(3), sd_event_add_defer(3), sd_event_source_set_enabled(3), sd_event_source_set_description(3), sd_event_source_set_userdata(3), sd_event_source_set_floating(3), signal(7), signalfd(2), sigprocmask(2), pthread_sigmask(3)

the whole friend group, honestly 💜

okay that's the whole page bestie, go catch those signals ✨ this little love letter was brought to you by systemd 261.3, dated right alongside its SD_EVENT_ADD_SIGNAL(3) header — mwah, stan 💅💖

📦 where this page comes from