From 0bca2831275c2705b1153eb9493cd88eb5647c9c Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 27 Nov 2019 17:11:44 +0100 Subject: [PATCH] man: document sd_event_source_set_floating() Let's make sure we get back to 100% man page documentation coverage of our sd-event APIs. We are bad enough at the others, let's get these ones right at least. --- man/rules/meson.build | 1 + man/sd_event_add_child.xml | 1 + man/sd_event_add_defer.xml | 1 + man/sd_event_add_inotify.xml | 1 + man/sd_event_add_io.xml | 1 + man/sd_event_add_signal.xml | 1 + man/sd_event_add_time.xml | 1 + man/sd_event_source_set_floating.xml | 118 +++++++++++++++++++++++++++ 8 files changed, 125 insertions(+) create mode 100644 man/sd_event_source_set_floating.xml diff --git a/man/rules/meson.build b/man/rules/meson.build index 8eba0a52ce5..20c3d09da08 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -437,6 +437,7 @@ manpages = [ 'SD_EVENT_ONESHOT', 'sd_event_source_get_enabled'], ''], + ['sd_event_source_set_floating', '3', ['sd_event_source_get_floating'], ''], ['sd_event_source_set_prepare', '3', [], ''], ['sd_event_source_set_priority', '3', diff --git a/man/sd_event_add_child.xml b/man/sd_event_add_child.xml index 23fa78ea729..509803d5c17 100644 --- a/man/sd_event_add_child.xml +++ b/man/sd_event_add_child.xml @@ -213,6 +213,7 @@ sd_event_source_set_priority3, sd_event_source_set_userdata3, sd_event_source_set_description3, + sd_event_source_set_floating3, waitid2 diff --git a/man/sd_event_add_defer.xml b/man/sd_event_add_defer.xml index 636c61e99c8..92be8353e64 100644 --- a/man/sd_event_add_defer.xml +++ b/man/sd_event_add_defer.xml @@ -183,6 +183,7 @@ sd_event_source_set_priority3, sd_event_source_set_userdata3, sd_event_source_set_description3, + sd_event_source_set_floating3, sd_event_exit3 diff --git a/man/sd_event_add_inotify.xml b/man/sd_event_add_inotify.xml index 3c9f2fbe3eb..8860699db3d 100644 --- a/man/sd_event_add_inotify.xml +++ b/man/sd_event_add_inotify.xml @@ -183,6 +183,7 @@ sd_event_source_set_priority3, sd_event_source_set_userdata3, sd_event_source_set_description3, + sd_event_source_set_floating3, waitid2 diff --git a/man/sd_event_add_io.xml b/man/sd_event_add_io.xml index 398b938e3c2..35d02a17000 100644 --- a/man/sd_event_add_io.xml +++ b/man/sd_event_add_io.xml @@ -296,6 +296,7 @@ sd_event_source_set_userdata3, sd_event_source_set_description3, sd_event_source_get_pending3, + sd_event_source_set_floating3, epoll_ctl2, epoll7 diff --git a/man/sd_event_add_signal.xml b/man/sd_event_add_signal.xml index 9bf777c1071..a7148ca8dd1 100644 --- a/man/sd_event_add_signal.xml +++ b/man/sd_event_add_signal.xml @@ -187,6 +187,7 @@ sd_event_source_set_enabled3, sd_event_source_set_description3, sd_event_source_set_userdata3, + sd_event_source_set_floating3, signal7, signalfd2 diff --git a/man/sd_event_add_time.xml b/man/sd_event_add_time.xml index 731636451c7..8d3511ef638 100644 --- a/man/sd_event_add_time.xml +++ b/man/sd_event_add_time.xml @@ -278,6 +278,7 @@ sd_event_source_set_priority3, sd_event_source_set_userdata3, sd_event_source_set_description3, + sd_event_source_set_floating3, clock_gettime2, timerfd_create2, prctl2 diff --git a/man/sd_event_source_set_floating.xml b/man/sd_event_source_set_floating.xml new file mode 100644 index 00000000000..89341d18c43 --- /dev/null +++ b/man/sd_event_source_set_floating.xml @@ -0,0 +1,118 @@ + + + + + + + + sd_event_source_set_floating + systemd + + + + sd_event_source_set_floating + 3 + + + + sd_event_source_set_floating + sd_event_source_get_floating + + Set or retrieve 'floating' state of event sources + + + + + #include <systemd/sd-event.h> + + + int sd_event_source_set_floating + sd_event_source *source + int floating + + + + int sd_event_source_get_floating + sd_event_source *source + + + + + + + Description + + sd_event_source_set_floating() takes a boolean and sets the 'floating' state + of the specified event source object. This is used to change the direction of reference counts for the + object and the event loop it is associated with. In non-floating mode, the event source object holds a + reference to the event loop object, but not vice versa. The creator of the event source object must hold + a reference to it as long as the source should exist. In floating mode, the event loop holds a reference + to the source object, and will decrease the reference count when being freed. This means that a reference + to the event loop should be held to prevent both from being destroyed. + + Various calls that allocate event source objects (i.e. + sd_event_add_io3, + sd_event_add_time3 and + similar) will automatically set an event source object to 'floating' mode if the caller passed + NULL in the parameter used to return a reference to the event source object. + Nevertheless, it may be necessary to gain temporary access to the source object, for example to adjust + event source properties after allocation (e.g. its priority or description string). In those cases the + object may be created in non-floating mode, and the returned reference used to adjust the properties, and + the object marked as floating afterwards, and the reference in the caller dropped. + + sd_event_source_get_floating() may be used to query the current 'floating' + state of the event source object source. It returns zero if 'floating' mode is + off, positive if it is on. + + + + Return Value + + On success, sd_event_source_set_floating() and + sd_event_source_get_floating() return a non-negative integer. On failure, they + return a negative errno-style error code. + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + source is not a valid pointer to an + sd_event_source object. + + + + -ECHILD + + The event loop has been created in a different process. + + + + + + + + + + + See Also + + + 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_source_set_description3, + sd_event_source_set_priority3 + + + +