From 42f1ab5009eed71f0d4f83681b8fdbed8664fca3 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 13 Mar 2015 21:35:32 -0400 Subject: [PATCH] man: add sd_event_{run,wait,prepare,dispatch,loop} --- Makefile-man.am | 19 +++++ man/sd_event_run.xml | 182 ++++++++++++++++++++++++++++++++++++++++++ man/sd_event_wait.xml | 213 ++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 414 insertions(+) create mode 100644 man/sd_event_run.xml create mode 100644 man/sd_event_wait.xml diff --git a/Makefile-man.am b/Makefile-man.am index 7a9612e..ab1db33 100644 --- a/Makefile-man.am +++ b/Makefile-man.am @@ -810,7 +810,9 @@ MANPAGES += \ man/sd_event_add_time.3 \ man/sd_event_get_fd.3 \ man/sd_event_new.3 \ + man/sd_event_run.3 \ man/sd_event_set_name.3 \ + man/sd_event_wait.3 \ man/systemd-bus-proxyd.8 \ man/systemd-bus-proxyd@.service.8 MANPAGES_ALIAS += \ @@ -871,7 +873,10 @@ MANPAGES_ALIAS += \ man/sd_event_add_exit.3 \ man/sd_event_add_post.3 \ man/sd_event_default.3 \ + man/sd_event_dispatch.3 \ man/sd_event_get_name.3 \ + man/sd_event_loop.3 \ + man/sd_event_prepare.3 \ man/sd_event_ref.3 \ man/sd_event_source_get_child_pid.3 \ man/sd_event_source_get_signal.3 \ @@ -939,7 +944,10 @@ man/sd_bus_unref.3: man/sd_bus_new.3 man/sd_event_add_exit.3: man/sd_event_add_defer.3 man/sd_event_add_post.3: man/sd_event_add_defer.3 man/sd_event_default.3: man/sd_event_new.3 +man/sd_event_dispatch.3: man/sd_event_wait.3 man/sd_event_get_name.3: man/sd_event_set_name.3 +man/sd_event_loop.3: man/sd_event_run.3 +man/sd_event_prepare.3: man/sd_event_wait.3 man/sd_event_ref.3: man/sd_event_new.3 man/sd_event_source_get_child_pid.3: man/sd_event_add_child.3 man/sd_event_source_get_signal.3: man/sd_event_add_signal.3 @@ -1121,9 +1129,18 @@ man/sd_event_add_post.html: man/sd_event_add_defer.html man/sd_event_default.html: man/sd_event_new.html $(html-alias) +man/sd_event_dispatch.html: man/sd_event_wait.html + $(html-alias) + man/sd_event_get_name.html: man/sd_event_set_name.html $(html-alias) +man/sd_event_loop.html: man/sd_event_run.html + $(html-alias) + +man/sd_event_prepare.html: man/sd_event_wait.html + $(html-alias) + man/sd_event_ref.html: man/sd_event_new.html $(html-alias) @@ -1693,7 +1710,9 @@ EXTRA_DIST += \ man/sd_event_add_time.xml \ man/sd_event_get_fd.xml \ man/sd_event_new.xml \ + man/sd_event_run.xml \ man/sd_event_set_name.xml \ + man/sd_event_wait.xml \ man/sd_get_seats.xml \ man/sd_id128_get_machine.xml \ man/sd_id128_randomize.xml \ diff --git a/man/sd_event_run.xml b/man/sd_event_run.xml new file mode 100644 index 0000000..d9ffe46 --- /dev/null +++ b/man/sd_event_run.xml @@ -0,0 +1,182 @@ + + + + + + + + + sd_event_run + systemd + + + + Developer + Tom + Gundersen + teg@jklm.no + + + + + + sd_event_run + 3 + + + + sd_event_run + sd_event_loop + + Run libsystemd event loop + + + + + #include <systemd/sd-event.h> + + + int sd_event_run + sd_event *event + uint64_t timeout + + + + int sd_event_loop + sd_event *event + + + + + + Description + + sd_event_run() can be used to run one + iteration of the event loop of libsystemd. This function waits + until an event to process is available and dispatches a handler + for it. Parameter timeout specifices the + maximum time (in microseconds) to wait. (uint64_t) + -1 may be used to specify an infinite timeout. + + sd_event_loop runs + sd_event_wait in a loop with a timeout of + infinity. This makes it suitable for the main event loop of a + program. + + The event loop object event is + created with + sd_event_new. + Events to wait for and their handlers can be registered with + sd_event_add_time, + sd_event_add_child, + sd_event_add_signal, + sd_event_add_defer, + sd_event_add_exit, + and + sd_event_add_post. + + + For more fine-grained control, + sd_event_prepare, + sd_event_wait, and + sd_event_dispatch may be used. Along with + sd_event_get_fd, those functions make it + possible to integrate the libsystemd loop inside of another event + loop. + + + + Return Value + + On success, these functions return 0 or a positive integer. + On failure, they return a negative errno-style error code. + sd_event_run returns 0 if the event loop is + finished, and a positive value if it can be continued. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + Parameter event is + NULL. + + + + -EBUSY + + The event loop object is not in the right + state (see + sd_event_prepare3 + for an explanation of possible states). + + + + -ESTALE + + The event loop is already terminated. + + + + + -ECHILD + + The event loop has been created in a different process. + + + + + + Other errors are possible too. + + + + Notes + + sd_event_run() and + sd_event_loop() are available + as a shared library, which can be compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd_event_new3, + sd_event_wait3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_add_exit3, + sd_event_add_post3. + + + + diff --git a/man/sd_event_wait.xml b/man/sd_event_wait.xml new file mode 100644 index 0000000..4b7cf50 --- /dev/null +++ b/man/sd_event_wait.xml @@ -0,0 +1,213 @@ + + + + + + + + + sd_event_wait + systemd + + + + Developer + Tom + Gundersen + teg@jklm.no + + + + + + sd_event_wait + 3 + + + + sd_event_wait + sd_event_prepare + sd_event_dispatch + + Run parts of libsystemd event loop + + + + + #include <systemd/sd-event.h> + + + int sd_event_prepare + sd_event *event + + + + int sd_event_wait + sd_event *event + uint64_t timeout + + + + int sd_event_dispatch + sd_event *event + + + + + + + Description + + Functions described here form parts of an event loop. + + sd_event_prepare checks for pending + events and arms necessary timers. If any events are ready to be + processed, it returns a positive value, and the events should be + processed with sd_event_dispatch. + sd_event_dispatch runs a handler for one of + the events from the sources with the highest priority. On success, + sd_event_dispatch returns either 0, which + means that the loop is finished, or a positive value, which means + that the loop is again in the initial state and + sd_event_prepare should be called again. + + + In case sd_event_prepare returned 0, + sd_event_wait should be called to wait for + events or a timeout. If any events are ready to be processed, it + returns a positive value, and the events should be processed with + sd_event_dispatch. Otherwise, the loop is + back in the inital state and sd_event_prepare + should be called again. + + + ┌──────────┐ + │ initial ├──←←←←←←←←←←←←←←←←←←←─┐ + └───┬──────┘ ↑ + │ ↑ + sd_event_prepare ┌─────────┐ ↑ + ├ 0 →→→→→→→──┤ armed │ ↑ + 1 └───┬─────┘ ↑ + ↓ │ ↑ + ↓ sd_event_wait ↑ + ├───←←←←←←←─── 1 ┴─ 0 →→→→→→→─┘ + ┌───┴──────┐ ↑ + │ pending │ ↑ + └───┬──────┘ ↑ + │ ↑ + sd_event_dispatch ↑ + ↓ ↑ + ├ 1 ──────────→→→→→→→─────────┘ + 0 + ↓ + ┌───┴──────┐ + │ finished │ + └──────────┘ + + + All three functions as the first argument take the event + loop object event that is created with with + sd_event_new. The timeout for + sd_event_wait is specified with + timeout in milliseconds. + (uint64_t) -1 may be used to specify an + infinite timeout. + + + + Return Value + + On success, these functions return 0 or a positive integer. + On failure, they return a negative errno-style error code. In case + of sd_event_prepare and + sd_event_wait a positive value means that + events are ready to be processed and 0 means that no events are + ready. In case of sd_event_dispatch a + positive value means that the loop is again in the initial state + and 0 means the loop is finished. For any of those functions, a + negative return value means the loop must be aborted. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + Parameter event is + NULL. + + + + -EBUSY + + The event loop object is not in the right + state. + + + + -ESTALE + + The event loop is already terminated. + + + + + -ECHILD + + The event loop has been created in a different process. + + + + + + Other errors are possible too. + + + + Notes + + Functions described here are available + as a shared library, which can be compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd_event_new3, + sd_event_run3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_add_exit3, + sd_event_add_post3. + + + + -- 2.7.4