SD_EVENT_..._USERDATA(3)

📦
version 261.3 · 17 versions
, in ubuntu stonking

💅 SD_EVENT_..._USERDATA — sd_event_source_set_userdata / sd_event_source_get_userdata

okay bestie, so this is the <systemd/sd-event.h> girlies' guide to the manual page SD_EVENT_..._USERDATA(3) — aka how to stash your own little pointer on an event source and get it back later. it's giving "coat check at the club" but for C. 🎀

✨ NAME ✨

sd_event_source_set_userdata, sd_event_source_get_userdata — set or retrieve the user data pointer of event sources. that's it. that's the whole job. 🫶

🌸 SYNOPSIS 🌸

#include <systemd/sd-event.h>

void* sd_event_source_set_userdata(sd_event_source *source,
                                   void *userdata);

void* sd_event_source_get_userdata(sd_event_source *source);

💖 DESCRIPTION 💖

So sd_event_source_set_userdata() is literally your main character move for attaching an arbitrary user data pointer to the event source object you pass in as source. 🦋

Usually you'd set that pointer way back when you created the event source in the first place — with calls like sd_event_add_io(3) or sd_event_add_time(3) — and this call is how you update it afterwards. no cap. 🔥

And it's not just decor either: that same user data pointer is also passed to all the handler callback functions tied to the event source. so everybody's on the same page, iykyk.

The userdata parameter is the shiny new pointer you're setting, and the function hands you back the previous user data pointer — like a trade, but make it cute. and yes, NULL is a completely valid user data pointer. NULL is a vibe too. 💀

Meanwhile sd_event_source_get_userdata() is the lowkey "hey what's on there right now" call — it queries the current user data pointer assigned to the event source object source. slay. 👑

⭐ RETURN VALUE ⭐

On success, sd_event_source_set_userdata() and sd_event_source_get_userdata() both return the previously set user data pointer. 🌈

On failure, they return NULL. 🙈

🧚 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. very demure, very build-system-friendly. 🎀
  • 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, sharing is allowed, snatching at the same moment is not. 💅
  • The code described here uses getenv(3), which is declared to be not multi-thread-safe. That means if you're calling the functions described here, you must not call setenv(3) from a parallel thread. the recommendation? only do calls to setenv() from an early phase of the program, back when no other threads have been started. do it before the group chat gets loud. 🫶
fr fr, take that last one seriously — the manpage says it plainly and we're not out here inventing lore.

🦋 HISTORY 🦋

sd_event_source_set_userdata() and sd_event_source_get_userdata() were added in version 229. an icon. a legend. the moment. ✨

👑 SEE ALSO 👑

and that's the page, bestie! 🍓 this whole thing is from systemd 261.3 — go forth, set your userdata, retrieve your userdata, and remember: NULL was never the enemy. mwah 💜🧚

📦 where this page comes from