From 19f4f86bfed21c5326ed2acebe1163f3a83e832b Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 6 May 2024 04:25:50 +0200 Subject: Adding upstream version 241. Signed-off-by: Daniel Baumann --- man/sd_event_new.xml | 223 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 223 insertions(+) create mode 100644 man/sd_event_new.xml (limited to 'man/sd_event_new.xml') diff --git a/man/sd_event_new.xml b/man/sd_event_new.xml new file mode 100644 index 0000000..ddb8dac --- /dev/null +++ b/man/sd_event_new.xml @@ -0,0 +1,223 @@ + + + + + + + + + sd_event_new + systemd + + + + sd_event_new + 3 + + + + sd_event_new + sd_event_default + sd_event_ref + sd_event_unref + sd_event_unrefp + sd_event_get_tid + sd_event + + Acquire and release an event loop object + + + + + #include <systemd/sd-event.h> + + typedef struct sd_event sd_event; + + + int sd_event_new + sd_event **event + + + + int sd_event_default + sd_event **event + + + + sd_event *sd_event_ref + sd_event *event + + + + sd_event *sd_event_unref + sd_event *event + + + + void sd_event_unrefp + sd_event **event + + + + int sd_event_get_tid + sd_event *event + pid_t *tid + + + + + + + Description + + sd_event_new() allocates a new event + loop object. The event loop object is returned in the + event parameter. After use, drop + the returned reference with + sd_event_unref(). When the last reference is + dropped, the object is freed. + + sd_event_default() acquires a reference + to the default event loop object of the calling thread, possibly + allocating a new object if no default event loop object has been + allocated yet for the thread. After use, drop the returned + reference with sd_event_unref(). When the + last reference is dropped, the event loop is freed. If this + function is called while the object returned from a previous call + from the same thread is still referenced, the same object is + returned again, but the reference is increased by one. It is + recommended to use this call instead of + sd_event_new() in order to share event loop + objects between various components that are dispatched in the same + thread. All threads have exactly either zero or one default event loop + objects associated, but never more. + + After allocating an event loop object, add event sources to + it with + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_child3, + sd_event_add_inotify3, + sd_event_add_defer3, + sd_event_add_post3 or + sd_event_add_exit3, + and then execute the event loop using + sd_event_loop3. + + sd_event_ref() increases the reference + count of the specified event loop object by one. + + sd_event_unref() decreases the + reference count of the specified event loop object by one. If + the count hits zero, the object is freed. Note that it + is freed regardless of whether it is the default event loop object for a + thread or not. This means that allocating an event loop with + sd_event_default(), then releasing it, and + then acquiring a new one with + sd_event_default() will result in two + distinct objects. Note that, in order to free an event loop object, + all remaining event sources of the event loop also need to be + freed as each keeps a reference to it. + + sd_event_unrefp() is similar to + sd_event_unref() but takes a pointer to a + pointer to an sd_event object. This call is useful in + conjunction with GCC's and LLVM's Clean-up + Variable Attribute. Note that this function is defined as + inline function. Use a declaration like the following, + in order to allocate an event loop object that is freed + automatically as the code block is left: + + { + __attribute__((cleanup(sd_event_unrefp)) sd_event *event = NULL; + int r; + … + r = sd_event_default(&event); + if (r < 0) + fprintf(stderr, "Failed to allocate event loop: %s\n", strerror(-r)); + … +} + + sd_event_ref(), + sd_event_unref() and + sd_event_unrefp() execute no operation if the + passed in event loop object is NULL. + + sd_event_get_tid() retrieves the thread + identifier ("TID") of the thread the specified event loop object + is associated with. This call is only supported for event loops + allocated with sd_event_default(), and + returns the identifier for the thread the event loop is the + default event loop of. See gettid2 + for more information on thread identifiers. + + + + Return Value + + On success, sd_event_new(), + sd_event_default() and + sd_event_get_tid() return 0 or a positive + integer. On failure, they return a negative errno-style error + code. sd_event_ref() always returns a pointer + to the event loop object passed + in. sd_event_unref() always returns + NULL. + + + + Errors + + Returned errors may indicate the following problems: + + + + -ENOMEM + + Not enough memory to allocate the object. + + + + -EMFILE + + The maximum number of event loops has been allocated. + + + + + -ENXIO + + sd_event_get_tid() was + invoked on an event loop object that was not allocated with + sd_event_default(). + + + + + + + + + See Also + + + systemd1, + sd-event3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_child3, + sd_event_add_inotify3, + sd_event_add_defer3, + sd_event_run3, + gettid2 + + + + -- cgit v1.2.3