SD_EVENT...SCRIPTION(3)

📦
version 261.3 · 17 versions
, in ubuntu stonking

👑 sd_event_source_set_description(3) — giving your event sources cute lil names 💅

Okay bestie, so this page lives in manual section 3, it's called sd_event_source_set_description, and it's literally all about naming your event sources so debugging doesn't make you cry 😭. Two functions, one goal: labels. Let's go 🫶

🌸 NAME

sd_event_source_set_description, sd_event_source_get_description — set or retrieve descriptive names of event sources ✨

💖 SYNOPSIS

#include <systemd/sd-event.h>

int sd_event_source_set_description(sd_event_source *source,
                                    const char *description);

int sd_event_source_get_description(sd_event_source *source,
                                    const char **ret);

🦋 DESCRIPTION

So sd_event_source_set_description() is the one that lets you slap an arbitrary descriptive name on the event source object you passed in as source 🎀. Like, give it a name, it deserves one. That name then shows up in debugging messages that sd-event(3) generates for this event source, and you can pull it back out later with sd_event_source_get_description() when you're in debugging mode and need to know which source is which 👀. The description parameter has to point at a NUL-terminated string, or be NULL. If you pass NULL, the descriptive name just gets unset — poof, gone 💨. The string gets copied internally, so after the function returns, the description argument is not referenced anymore. No dangling vibes ✨.

Then sd_event_source_get_description() is the getter, the retrieval girlie 💁‍♀️ — it queries the current descriptive name assigned to the event source object source and hands you back a pointer to that current name in ret, stored in memory internal to the event source. Important though, bestie: that memory is invalidated when the event source is destroyed or the descriptive name is changed ⚠️. So don't go hoarding that pointer, it's not yours forever, no cap.

And here's a fun fact 🍓: event source objects generally have no description set when they're created — like a fresh account with no bio 💀 — except for UNIX signal event sources created with sd_event_add_signal(3), whose descriptive name is initialized to the signal's C constant name (e.g. "SIGINT" or "SIGTERM"). Those ones came pre-named, main character energy 👑.

🔥 RETURN VALUE

On success, both sd_event_source_set_description() and sd_event_source_get_description() return a non-negative integer 🎉. On failure, they return a negative errno-style error code 😔.

💀 Errors

The errors you might get back mean these things, iykyk:

  • -EINVAL — source is not a valid pointer to an sd_event_source object, or the description argument for sd_event_source_get_description() is NULL. Basically you handed it nonsense 🙈.
  • -ENOMEM — not enough memory to copy the name 😭.
  • -ECHILD — the event loop has been created in a different process, library or module instance. Wrong building, wrong floor 🏢.
  • -ENXIO — no name was set for the event source. Nothing to get, bestie, the bio is empty 💔.

🌈 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 — parallel slay, but one thread per object at a time, periodt 💅.

⚠️ Also listen 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's recommended to only do calls to setenv() from an early phase of the program when no other threads have been started. Do your env stuff first, then start the threads, fr fr 🧚.

⭐ HISTORY

sd_event_source_set_description() and sd_event_source_get_description() were added in version 229 🎂. Old but iconic, honestly.

💜 SEE ALSO

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) — go read the whole friend group 🌸

🌟 That's the whole page, bestie! Straight from systemd 261.3, dated and everything, on the SD_EVENT...SCRIPTION(3) page. Go name your event sources and live your truth 💖✨🎀🦋
📦 where this page comes from