diff --git a/Makefile-man.am b/Makefile-man.am index c792c89324..db0416f9d1 100644 --- a/Makefile-man.am +++ b/Makefile-man.am @@ -26,6 +26,7 @@ MANPAGES += \ man/os-release.5 \ man/sd-bus-errors.3 \ man/sd-daemon.3 \ + man/sd-event.3 \ man/sd-id128.3 \ man/sd-journal.3 \ man/sd_booted.3 \ @@ -47,12 +48,23 @@ MANPAGES += \ man/sd_bus_request_name.3 \ man/sd_event_add_child.3 \ man/sd_event_add_defer.3 \ + man/sd_event_add_io.3 \ man/sd_event_add_signal.3 \ man/sd_event_add_time.3 \ + man/sd_event_exit.3 \ man/sd_event_get_fd.3 \ man/sd_event_new.3 \ + man/sd_event_now.3 \ man/sd_event_run.3 \ - man/sd_event_set_name.3 \ + man/sd_event_set_watchdog.3 \ + man/sd_event_source_get_event.3 \ + man/sd_event_source_get_pending.3 \ + man/sd_event_source_set_description.3 \ + man/sd_event_source_set_enabled.3 \ + man/sd_event_source_set_prepare.3 \ + man/sd_event_source_set_priority.3 \ + man/sd_event_source_set_userdata.3 \ + man/sd_event_source_unref.3 \ man/sd_event_wait.3 \ man/sd_id128_get_machine.3 \ man/sd_id128_randomize.3 \ @@ -199,6 +211,19 @@ MANPAGES_ALIAS += \ man/SD_DEBUG.3 \ man/SD_EMERG.3 \ man/SD_ERR.3 \ + man/SD_EVENT_ARMED.3 \ + man/SD_EVENT_EXITING.3 \ + man/SD_EVENT_FINISHED.3 \ + man/SD_EVENT_INITIAL.3 \ + man/SD_EVENT_OFF.3 \ + man/SD_EVENT_ON.3 \ + man/SD_EVENT_ONESHOT.3 \ + man/SD_EVENT_PENDING.3 \ + man/SD_EVENT_PREPARING.3 \ + man/SD_EVENT_PRIORITY_IDLE.3 \ + man/SD_EVENT_PRIORITY_IMPORTANT.3 \ + man/SD_EVENT_PRIORITY_NORMAL.3 \ + man/SD_EVENT_RUNNING.3 \ man/SD_ID128_CONST_STR.3 \ man/SD_ID128_FORMAT_STR.3 \ man/SD_ID128_FORMAT_VAL.3 \ @@ -295,21 +320,41 @@ MANPAGES_ALIAS += \ man/sd_bus_ref.3 \ man/sd_bus_release_name.3 \ man/sd_bus_unref.3 \ + man/sd_event.3 \ man/sd_event_add_exit.3 \ man/sd_event_add_post.3 \ + man/sd_event_child_handler_t.3 \ man/sd_event_default.3 \ man/sd_event_dispatch.3 \ - man/sd_event_get_name.3 \ + man/sd_event_get_exit_code.3 \ + man/sd_event_get_state.3 \ + man/sd_event_get_tid.3 \ + man/sd_event_get_watchdog.3 \ + man/sd_event_handler_t.3 \ + man/sd_event_io_handler_t.3 \ man/sd_event_loop.3 \ man/sd_event_prepare.3 \ man/sd_event_ref.3 \ + man/sd_event_signal_handler_t.3 \ + man/sd_event_source.3 \ man/sd_event_source_get_child_pid.3 \ + man/sd_event_source_get_description.3 \ + man/sd_event_source_get_enabled.3 \ + man/sd_event_source_get_io_events.3 \ + man/sd_event_source_get_io_fd.3 \ + man/sd_event_source_get_io_revents.3 \ + man/sd_event_source_get_priority.3 \ man/sd_event_source_get_signal.3 \ man/sd_event_source_get_time.3 \ man/sd_event_source_get_time_accuracy.3 \ man/sd_event_source_get_time_clock.3 \ + man/sd_event_source_get_userdata.3 \ + man/sd_event_source_ref.3 \ + man/sd_event_source_set_io_events.3 \ + man/sd_event_source_set_io_fd.3 \ man/sd_event_source_set_time.3 \ man/sd_event_source_set_time_accuracy.3 \ + man/sd_event_time_handler_t.3 \ man/sd_event_unref.3 \ man/sd_id128_equal.3 \ man/sd_id128_from_string.3 \ @@ -489,6 +534,19 @@ man/SD_CRIT.3: man/sd-daemon.3 man/SD_DEBUG.3: man/sd-daemon.3 man/SD_EMERG.3: man/sd-daemon.3 man/SD_ERR.3: man/sd-daemon.3 +man/SD_EVENT_ARMED.3: man/sd_event_wait.3 +man/SD_EVENT_EXITING.3: man/sd_event_wait.3 +man/SD_EVENT_FINISHED.3: man/sd_event_wait.3 +man/SD_EVENT_INITIAL.3: man/sd_event_wait.3 +man/SD_EVENT_OFF.3: man/sd_event_source_set_enabled.3 +man/SD_EVENT_ON.3: man/sd_event_source_set_enabled.3 +man/SD_EVENT_ONESHOT.3: man/sd_event_source_set_enabled.3 +man/SD_EVENT_PENDING.3: man/sd_event_wait.3 +man/SD_EVENT_PREPARING.3: man/sd_event_wait.3 +man/SD_EVENT_PRIORITY_IDLE.3: man/sd_event_source_set_priority.3 +man/SD_EVENT_PRIORITY_IMPORTANT.3: man/sd_event_source_set_priority.3 +man/SD_EVENT_PRIORITY_NORMAL.3: man/sd_event_source_set_priority.3 +man/SD_EVENT_RUNNING.3: man/sd_event_wait.3 man/SD_ID128_CONST_STR.3: man/sd-id128.3 man/SD_ID128_FORMAT_STR.3: man/sd-id128.3 man/SD_ID128_FORMAT_VAL.3: man/sd-id128.3 @@ -585,21 +643,41 @@ man/sd_bus_path_encode_many.3: man/sd_bus_path_encode.3 man/sd_bus_ref.3: man/sd_bus_new.3 man/sd_bus_release_name.3: man/sd_bus_request_name.3 man/sd_bus_unref.3: man/sd_bus_new.3 +man/sd_event.3: man/sd_event_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_child_handler_t.3: man/sd_event_add_child.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_get_exit_code.3: man/sd_event_exit.3 +man/sd_event_get_state.3: man/sd_event_wait.3 +man/sd_event_get_tid.3: man/sd_event_new.3 +man/sd_event_get_watchdog.3: man/sd_event_set_watchdog.3 +man/sd_event_handler_t.3: man/sd_event_add_defer.3 +man/sd_event_io_handler_t.3: man/sd_event_add_io.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_signal_handler_t.3: man/sd_event_add_signal.3 +man/sd_event_source.3: man/sd_event_add_io.3 man/sd_event_source_get_child_pid.3: man/sd_event_add_child.3 +man/sd_event_source_get_description.3: man/sd_event_source_set_description.3 +man/sd_event_source_get_enabled.3: man/sd_event_source_set_enabled.3 +man/sd_event_source_get_io_events.3: man/sd_event_add_io.3 +man/sd_event_source_get_io_fd.3: man/sd_event_add_io.3 +man/sd_event_source_get_io_revents.3: man/sd_event_add_io.3 +man/sd_event_source_get_priority.3: man/sd_event_source_set_priority.3 man/sd_event_source_get_signal.3: man/sd_event_add_signal.3 man/sd_event_source_get_time.3: man/sd_event_add_time.3 man/sd_event_source_get_time_accuracy.3: man/sd_event_add_time.3 man/sd_event_source_get_time_clock.3: man/sd_event_add_time.3 +man/sd_event_source_get_userdata.3: man/sd_event_source_set_userdata.3 +man/sd_event_source_ref.3: man/sd_event_source_unref.3 +man/sd_event_source_set_io_events.3: man/sd_event_add_io.3 +man/sd_event_source_set_io_fd.3: man/sd_event_add_io.3 man/sd_event_source_set_time.3: man/sd_event_add_time.3 man/sd_event_source_set_time_accuracy.3: man/sd_event_add_time.3 +man/sd_event_time_handler_t.3: man/sd_event_add_time.3 man/sd_event_unref.3: man/sd_event_new.3 man/sd_id128_equal.3: man/sd-id128.3 man/sd_id128_from_string.3: man/sd_id128_to_string.3 @@ -857,6 +935,45 @@ man/SD_EMERG.html: man/sd-daemon.html man/SD_ERR.html: man/sd-daemon.html $(html-alias) +man/SD_EVENT_ARMED.html: man/sd_event_wait.html + $(html-alias) + +man/SD_EVENT_EXITING.html: man/sd_event_wait.html + $(html-alias) + +man/SD_EVENT_FINISHED.html: man/sd_event_wait.html + $(html-alias) + +man/SD_EVENT_INITIAL.html: man/sd_event_wait.html + $(html-alias) + +man/SD_EVENT_OFF.html: man/sd_event_source_set_enabled.html + $(html-alias) + +man/SD_EVENT_ON.html: man/sd_event_source_set_enabled.html + $(html-alias) + +man/SD_EVENT_ONESHOT.html: man/sd_event_source_set_enabled.html + $(html-alias) + +man/SD_EVENT_PENDING.html: man/sd_event_wait.html + $(html-alias) + +man/SD_EVENT_PREPARING.html: man/sd_event_wait.html + $(html-alias) + +man/SD_EVENT_PRIORITY_IDLE.html: man/sd_event_source_set_priority.html + $(html-alias) + +man/SD_EVENT_PRIORITY_IMPORTANT.html: man/sd_event_source_set_priority.html + $(html-alias) + +man/SD_EVENT_PRIORITY_NORMAL.html: man/sd_event_source_set_priority.html + $(html-alias) + +man/SD_EVENT_RUNNING.html: man/sd_event_wait.html + $(html-alias) + man/SD_ID128_CONST_STR.html: man/sd-id128.html $(html-alias) @@ -1145,19 +1262,40 @@ man/sd_bus_release_name.html: man/sd_bus_request_name.html man/sd_bus_unref.html: man/sd_bus_new.html $(html-alias) +man/sd_event.html: man/sd_event_new.html + $(html-alias) + man/sd_event_add_exit.html: man/sd_event_add_defer.html $(html-alias) man/sd_event_add_post.html: man/sd_event_add_defer.html $(html-alias) +man/sd_event_child_handler_t.html: man/sd_event_add_child.html + $(html-alias) + 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 +man/sd_event_get_exit_code.html: man/sd_event_exit.html + $(html-alias) + +man/sd_event_get_state.html: man/sd_event_wait.html + $(html-alias) + +man/sd_event_get_tid.html: man/sd_event_new.html + $(html-alias) + +man/sd_event_get_watchdog.html: man/sd_event_set_watchdog.html + $(html-alias) + +man/sd_event_handler_t.html: man/sd_event_add_defer.html + $(html-alias) + +man/sd_event_io_handler_t.html: man/sd_event_add_io.html $(html-alias) man/sd_event_loop.html: man/sd_event_run.html @@ -1169,9 +1307,33 @@ man/sd_event_prepare.html: man/sd_event_wait.html man/sd_event_ref.html: man/sd_event_new.html $(html-alias) +man/sd_event_signal_handler_t.html: man/sd_event_add_signal.html + $(html-alias) + +man/sd_event_source.html: man/sd_event_add_io.html + $(html-alias) + man/sd_event_source_get_child_pid.html: man/sd_event_add_child.html $(html-alias) +man/sd_event_source_get_description.html: man/sd_event_source_set_description.html + $(html-alias) + +man/sd_event_source_get_enabled.html: man/sd_event_source_set_enabled.html + $(html-alias) + +man/sd_event_source_get_io_events.html: man/sd_event_add_io.html + $(html-alias) + +man/sd_event_source_get_io_fd.html: man/sd_event_add_io.html + $(html-alias) + +man/sd_event_source_get_io_revents.html: man/sd_event_add_io.html + $(html-alias) + +man/sd_event_source_get_priority.html: man/sd_event_source_set_priority.html + $(html-alias) + man/sd_event_source_get_signal.html: man/sd_event_add_signal.html $(html-alias) @@ -1184,12 +1346,27 @@ man/sd_event_source_get_time_accuracy.html: man/sd_event_add_time.html man/sd_event_source_get_time_clock.html: man/sd_event_add_time.html $(html-alias) +man/sd_event_source_get_userdata.html: man/sd_event_source_set_userdata.html + $(html-alias) + +man/sd_event_source_ref.html: man/sd_event_source_unref.html + $(html-alias) + +man/sd_event_source_set_io_events.html: man/sd_event_add_io.html + $(html-alias) + +man/sd_event_source_set_io_fd.html: man/sd_event_add_io.html + $(html-alias) + man/sd_event_source_set_time.html: man/sd_event_add_time.html $(html-alias) man/sd_event_source_set_time_accuracy.html: man/sd_event_add_time.html $(html-alias) +man/sd_event_time_handler_t.html: man/sd_event_add_time.html + $(html-alias) + man/sd_event_unref.html: man/sd_event_new.html $(html-alias) @@ -2264,6 +2441,7 @@ EXTRA_DIST += \ man/runlevel.xml \ man/sd-bus-errors.xml \ man/sd-daemon.xml \ + man/sd-event.xml \ man/sd-id128.xml \ man/sd-journal.xml \ man/sd-login.xml \ @@ -2286,12 +2464,23 @@ EXTRA_DIST += \ man/sd_bus_request_name.xml \ man/sd_event_add_child.xml \ man/sd_event_add_defer.xml \ + man/sd_event_add_io.xml \ man/sd_event_add_signal.xml \ man/sd_event_add_time.xml \ + man/sd_event_exit.xml \ man/sd_event_get_fd.xml \ man/sd_event_new.xml \ + man/sd_event_now.xml \ man/sd_event_run.xml \ - man/sd_event_set_name.xml \ + man/sd_event_set_watchdog.xml \ + man/sd_event_source_get_event.xml \ + man/sd_event_source_get_pending.xml \ + man/sd_event_source_set_description.xml \ + man/sd_event_source_set_enabled.xml \ + man/sd_event_source_set_prepare.xml \ + man/sd_event_source_set_priority.xml \ + man/sd_event_source_set_userdata.xml \ + man/sd_event_source_unref.xml \ man/sd_event_wait.xml \ man/sd_get_seats.xml \ man/sd_id128_get_machine.xml \ diff --git a/man/sd-daemon.xml b/man/sd-daemon.xml index b7ba363656..b06d99f346 100644 --- a/man/sd-daemon.xml +++ b/man/sd-daemon.xml @@ -71,10 +71,10 @@ Description - sd-daemon.h provide APIs for new-style + sd-daemon.h provides APIs for new-style daemons, as implemented by the systemd1 - init system. + service manager. See sd_listen_fds3, diff --git a/man/sd-event.xml b/man/sd-event.xml new file mode 100644 index 0000000000..47989f4421 --- /dev/null +++ b/man/sd-event.xml @@ -0,0 +1,187 @@ + + + + + + + + + sd-event + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd-event + 3 + + + + sd-event + A generic event loop implementation + + + + + #include <systemd/sd-event.h> + + + + pkg-config --cflags --libs libsystemd + + + + + + Description + + sd-event.h provides a generic event + loop implementation, based on Linux epoll7. + + + See + sd_event_new3, + sd_event_run3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_child3, + sd_event_add_defer3, + sd_event_source_unref3, + sd_event_source_set_priority3, + sd_event_source_set_enabled3, + sd_event_source_set_userdata3, + sd_event_source_get_event3, + sd_event_source_get_pending3, + sd_event_source_set_description3, + sd_event_source_set_prepare3, + sd_event_wait3, + sd_event_get_fd3, + sd_event_set_watchdog3, + sd_event_exit3, + sd_event_now3 + for more information about the functions available. + + The event loop design is targeted on running a separate + instance of the event loop in each thread; it has no concept of + distributing events from a single event loop instance onto + multiple worker threads. Dispatching events is strictly ordered + and subject to configurable priorities. In each event loop + iteration a single event source is dispatched. Each time an event + source is dispatched the kernel is polled for new events, before + the next event source is dispatched. The event loop is designed to + honour priorities and provide fairness within each priority. It is + not designed to provide optimal throughput, as this contradicts + these goals due the limitations of the underlying epoll7 + primitives. + + The event loop implementation provides the following features: + + + I/O event sources, based on epoll7's + file descriptor watching, including edge triggered events (EPOLLET). See sd_event_add_io3. + + Timer event sources, based on timerfd_create2, + supporting the CLOCK_MONOTONIC, + CLOCK_REALTIME, + CLOCK_BOOTIME clocks, as well as the + CLOCK_REALTIME_ALARM and + CLOCK_BOOTTIME_ALARM clocks that can resume + the system from suspend. When creating timer events a required + accuracy parameter may be specified which allows coalescing of + timer events to minimize power consumption. See sd_event_add_time3. + + UNIX process signal events, based on + signalfd2, + including full support for real-time signals, and queued parameters. See sd_event_add_signal3. + + Child process state change events, based on + waitid2. See sd_event_add_child3. + + Static event sources, of three types: defer, + post and exit, for invoking calls in each event loop, after + other event sources or at event loop termination. See + sd_event_add_defer3. + + Event sources may be assigned a 64bit priority + value, that controls the order in which event sources are + dispatched if multiple are pending simultanously. See + sd_event_source_set_priority3. + + The event loop may automatically send watchdog + notification messages to the service manager. See + sd_event_set_watchdog3. + + The event loop may be integrated into foreign + event loops, such as the GLib one. See + sd_event_get_fd3 + for an example. + + + + + + + + See Also + + systemd1, + sd_event_new3, + sd_event_run3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_child3, + sd_event_add_defer3, + sd_event_source_unref3, + sd_event_source_set_priority3, + sd_event_source_set_enabled3, + sd_event_source_set_userdata3, + sd_event_source_get_event3, + sd_event_source_get_pending3, + sd_event_source_set_description3, + sd_event_source_set_prepare3, + sd_event_wait3, + sd_event_get_fd3, + sd_event_set_watchdog3, + sd_event_exit3, + sd_event_now3, + epoll7, + timerfd_create2, + signalfd2, + waitid2 + + + + diff --git a/man/sd_event_add_child.xml b/man/sd_event_add_child.xml index 77bec4e706..d4b180cf03 100644 --- a/man/sd_event_add_child.xml +++ b/man/sd_event_add_child.xml @@ -21,7 +21,7 @@ along with systemd; If not, see . --> - + sd_event_add_child @@ -45,13 +45,23 @@ sd_event_add_child sd_event_source_get_child_pid + sd_event_child_handler_t - Add a child state change event source to an event loop + Add a child process state change event source to an event loop - #include <systemd/sd-bus.h> + #include <systemd/sd-event.h> + + typedef struct sd_event_source sd_event_source; + + + typedef int (*sd_event_child_handler_t) + sd_event_source *s + const siginfo_t *si + void *userdata + int sd_event_add_child @@ -63,13 +73,6 @@ void *userdata - - typedef int (*sd_event_child_handler_t) - sd_event_source *s - const siginfo_t *si - void *userdata - - int sd_event_source_get_child_pid sd_event_source *source @@ -83,42 +86,75 @@ Description sd_event_add_child() adds a new child - state change event source to an event loop object. The event loop - is specified in event, the event source is - returned in the source parameter. The - pid parameter specifies the process to - watch. The handler must reference a - function to call when the process changes state. The handler - function will be passed the userdata - pointer, which may be chosen freely by the caller. The handler - also receives a pointer to a const - siginfo_t structure containing the information about - the event. The options parameter determines - which state changes will be watched for. It must contain an OR-ed - mask of WEXITED (watch for the child + process state change event source to an event loop. The event loop + object is specified in the event parameter, + the event source object is returned in the + source parameter. The + pid parameter specifies the PID of the + process to watch. The handler must + reference a function to call when the process changes state. The + handler function will be passed the + userdata pointer, which may be chosen + freely by the caller. The handler also receives a pointer to a + siginfo_t structure containing + information about the child process event. The + options parameter determines which state + changes will be watched for. It must contain an OR-ed mask of + WEXITED (watch for the child process terminating), WSTOPPED (watch for the child - being stopped by a signal), and WCONTINUED - (watch for the child being resumed by a signal). See - waitid2 + process being stopped by a signal), and + WCONTINUED (watch for the child process being + resumed by a signal). See waitid2 for further information. Only a single handler may be installed for a specific - child. The handler is enabled - for a single event (SD_EVENT_ONESHOT), - but this may be - changed with + child process. The handler is enabled for a single event + (SD_EVENT_ONESHOT), but this may be changed + with sd_event_source_set_enabled3. If the handler function returns a negative error code, it will be - disabled after the invocation, even if - SD_EVENT_ON mode is set. + disabled after the invocation, even if the + SD_EVENT_ON mode was requested before. + To destroy an event source object use + sd_event_source_unref3, + but note that the event source is only removed from the event loop + when all references to the event source are dropped. To make sure + an event source does not fire anymore, even when there's still a + reference to it kept, consider setting the event source to + SD_EVENT_OFF with + sd_event_source_set_enabled3. + + If the the second parameter of + sd_event_add_child() is passed as NULL no + reference to the event source object is returned. In this case the + event source is considered "floating", and will be destroyed + implicitly when the event loop itself is destroyed. + + Note that the handler function is + invoked at a time where the child process is not reaped yet (and + thus still is exposed as a zombie process by the kernel). However, + the child will be reaped automatically after the function + returns. Child processes for which no child process state change + event sources are installed will not be reaped by the event loop + implementation. + + If both a child process state change event source and a + SIGCHLD signal event source is installed in + the same event loop, the configured event source priorities decide + which event source is dispatched first. If the signal handler is + processed first, it should leave the child processes for which + child process state change event sources are installed unreaped. + sd_event_source_get_child_pid() - retrieves the configured pid of a child - state change event source created previously with + retrieves the configured PID of a child process state change event + source created previously with sd_event_add_child(). It takes the event source object as the source parameter and a - pointer to pid_t to return the result in. + pointer to a pid_t variable to return the process ID + in. @@ -158,7 +194,7 @@ -EBUSY A handler is already installed for this - child. + child process. @@ -176,18 +212,16 @@ + + -EDOM + + The passed event source is not a child process event source. + + - - Notes - - sd_event_add_child() and the other functions - described here are available as a shared library, which can be - compiled and linked to with the - libsystemd pkg-config1 - file. - + See Also @@ -196,10 +230,16 @@ systemd1, sd-event3, sd_event_new3, + sd_event_now3, + sd_event_add_io3, sd_event_add_time3, sd_event_add_signal3, sd_event_add_defer3, - sd_event_source_set_enabled3 + sd_event_source_set_enabled3, + sd_event_source_set_priority3, + sd_event_source_set_userdata3, + sd_event_source_set_description3, + waitid2 diff --git a/man/sd_event_add_defer.xml b/man/sd_event_add_defer.xml index 826f2fd224..6a13ede76e 100644 --- a/man/sd_event_add_defer.xml +++ b/man/sd_event_add_defer.xml @@ -21,7 +21,7 @@ along with systemd; If not, see . --> - + sd_event_add_defer @@ -46,13 +46,22 @@ sd_event_add_defer sd_event_add_post sd_event_add_exit + sd_event_handler_t Add static event sources to an event loop - #include <systemd/sd-bus.h> + #include <systemd/sd-event.h> + + typedef struct sd_event_source sd_event_source; + + + typedef int (*sd_event_handler_t) + sd_event_source *s + void *userdata + int sd_event_add_defer @@ -78,49 +87,67 @@ void *userdata - - typedef int (*sd_event_handler_t) - sd_event_source *s - void *userdata - - Description - These three functions add new event sources to an event loop - object. The event loop is specified in - event, the event source is returned in the - source parameter. The event sources are - enabled statically and will "fire" when the event loop is run and - the conditions described below are met. The handler function will - be passed the userdata pointer, which may - be chosen freely by the caller. + These three functions add new static event sources to an + event loop. The event loop object is specified in the + event parameter, the event source object is + returned in the source parameter. The event + sources are enabled statically and will "fire" when the event loop + is run and the conditions described below are met. The handler + function will be passed the userdata + pointer, which may be chosen freely by the caller. sd_event_add_defer() adds a new event - source that will "fire" the next time the event loop is run. By - default, the handler will be called once - (SD_EVENT_ONESHOT). + source that will be dispatched instantly, before the event loop + goes to sleep again and waits for new events. By default, the + handler will be called once + (SD_EVENT_ONESHOT). Note that if the event + source is set to SD_EVENT_ON the event loop + will never go to sleep again, but continously call the handler, + possibly interleaved with other event sources. sd_event_add_post() adds a new event - source that will "fire" if any event handlers are invoked whenever - the event loop is run. By default, the source is enabled - permanently (SD_EVENT_ON). + source that is run before the event loop will sleep and wait + for new events, but only after at least one other non-post event + source was dispatched. By default, the source is enabled + permanently (SD_EVENT_ON). Note that this + event source type will still allow the event loop to go to sleep + again, even if set to SD_EVENT_ON, as long as + no other event source is ever triggered. sd_event_add_exit() adds a new event - source that will "fire" when the event loop is terminated - with sd_event_exit(). + source that will be dispatched when the event loop is terminated + with sd_event_exit3. The sd_event_source_set_enabled3 function may be used to enable the event source permanently (SD_EVENT_ON) or to make it fire just once - (SD_EVENT_ONESHOT). If the handler function - returns a negative error code, it will be disabled after the - invocation, even if SD_EVENT_ON mode is - set. + (SD_EVENT_ONESHOT). + + If the handler function returns a negative error code, it + will be disabled after the invocation, even if the + SD_EVENT_ON mode was requested before. + + To destroy an event source object use + sd_event_source_unref3, + but note that the event source is only removed from the event loop + when all references to the event source are dropped. To make sure + an event source does not fire anymore, even when there's still a + reference to it kept, consider setting the event source to + SD_EVENT_OFF with + sd_event_source_set_enabled3. + + If the second parameter of these functions is passed as + NULL no reference to the event source object is returned. In this + case the event source is considered "floating", and will be + destroyed implicitly when the event loop itself is + destroyed. @@ -164,15 +191,7 @@ - - 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 @@ -181,10 +200,16 @@ systemd1, sd-event3, sd_event_new3, + sd_event_now3, + sd_event_add_io3, sd_event_add_time3, sd_event_add_signal3, sd_event_add_child3, - sd_event_source_set_enabled3 + sd_event_source_set_enabled3, + sd_event_source_set_priority3, + sd_event_source_set_userdata3, + sd_event_source_set_description3, + sd_event_exit3 diff --git a/man/sd_event_add_io.xml b/man/sd_event_add_io.xml new file mode 100644 index 0000000000..e3ac407cdf --- /dev/null +++ b/man/sd_event_add_io.xml @@ -0,0 +1,300 @@ + + + + + + + + + sd_event_add_io + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_add_io + 3 + + + + sd_event_add_io + sd_event_source_get_io_events + sd_event_source_set_io_events + sd_event_source_get_io_revents + sd_event_source_get_io_fd + sd_event_source_set_io_fd + sd_event_source + sd_event_io_handler_t + + Add an I/O event source to an event loop + + + + + #include <systemd/sd-event.h> + + typedef struct sd_event_source sd_event_source; + + + typedef int (*sd_event_io_handler_t) + sd_event_source *s + int fd + uint32_t revents + void *userdata + + + + int sd_event_add_io + sd_event *event + sd_event_source **source + int fd + uint32_t events + sd_event_io_handler_t handler + void *userdata + + + + int sd_event_source_get_io_events + sd_event_source *source + uint32_t *events + + + + int sd_event_source_set_io_events + sd_event_source *source + uint32_t events + + + + int sd_event_source_get_io_revents + sd_event_source *source + uint32_t *revents + + + + int sd_event_source_get_io_fd + sd_event_source *source + + + + int sd_event_source_set_io_fd + sd_event_source *source + int fd + + + + + + + Description + + sd_event_add_io() adds a new I/O event + source to an event loop. The event loop object is specified in the + event parameter, the event source object is + returned in the source parameter. The + fd parameter takes the UNIX file descriptor + to watch, which may refer to a socket, a FIFO, a message queue, a + serial connection, a character device or any other file descriptor + compatible with Linux epoll7. The + events parameter takes a bit mask of I/O + events to watch the file descriptor for, a combination of the + following event flags: EPOLLIN, + EPOLLOUT, EPOLLRDHUP, + EPOLLPRI and EPOLLET, + see epoll_ctl2 + for details. The handler shall reference a + function to call when the I/O event source is triggered. The + handler function will be passed the + userdata pointer, which may be chosen + freely by the caller. The handler will also be passed the file + descriptor the event was seen on as well as the actual event flags + seen. It's generally a subset of the events watched, however may + additionally have EPOLLERR and + EPOLLHUP set. + + By default, the I/O event source will stay enabled + continously (SD_EVENT_ON), but this may be + changed with + sd_event_source_set_enabled3. + If the handler function returns a negative error code, it will be + disabled after the invocation, even if the + SD_EVENT_ON mode was requested before. Note + that an I/O event source set to SD_EVENT_ON will + fire continously unless data is read or written to the file + descriptor in order to reset the mask of events seen. + + + Setting the I/O event mask to watch for to 0 does not mean + that the event source won't be triggered anymore, as + EPOLLHUP and EPOLLERR + may be triggered even with a zero event mask. To temporarily + disable an I/O event source use + sd_event_source_set_enabled3 + with SD_EVENT_OFF instead. + + To destroy an event source object use + sd_event_source_unref3, + but note that the event source is only removed from the event loop + when all references to the event source are dropped. To make sure + an event source does not fire anymore, even when there's still a + reference to it kept, consider setting the event source to + SD_EVENT_OFF with + sd_event_source_set_enabled3. + + If the the second parameter of + sd_event_add_io() is passed as NULL no + reference to the event source object is returned. In this case the + event source is considered "floating", and will be destroyed + implicitly when the event loop itself is destroyed. + + It is recommended to use + sd_event_add_io() only in conjunction with + file descriptors that have O_NONBLOCK set, to + ensure that all I/O operations from invoked handlers are properly + asynchronous and non-blocking. Using file descriptors without + O_NONBLOCK might result in unexpected + starving of other event sources. See fcntl2 + for details on enabling O_NONBLOCK mode. + + sd_event_source_get_io_events() retrieves + the configured I/O event mask to watch of an I/O event source created + previously with sd_event_add_io(). It takes + the event source object and a pointer to a variable to store the + event mask in. + + sd_event_source_set_io_events() changes the + configured I/O event mask to watch of an I/O event source created previously + with sd_event_add_io(). It takes the event + source object and the new event mask to set. + + sd_event_source_get_io_events() + retrieves the I/O event mask of currently seen but undispatched + events from an I/O event source created previously with + sd_event_add_io(). It takes the event source + object and a pointer to a variable to store the event mask + in. When called from a handler function on the handler's event + source object this will return the same mask as passed to the + handler's revents parameter. This call is + primarily useful to check for undispatched events of an event + source from the handler of an unrelated (possibly higher priority) + event source. Note the relation between + sd_event_source_get_pending() and + sd_event_source_get_io_revents(): both + functions will report non-zero results when there's an event + pending for the event source, but the former applies to all event + source types, the latter only to I/O event sources. + + sd_event_source_get_io_fd() retrieves + the UNIX file descriptor of an I/O event source created previously + with sd_event_add_io(). It takes the event + source object and returns the positive file descriptor in the return + value, or a negative error number on error (see below). + + sd_event_source_set_io_fd() + changes the UNIX file descriptor of an I/O event source created + previously with sd_event_add_io(). It takes + the event source object and the new file descriptor to set. + + + + Return Value + + On success, these functions return 0 or a positive + integer. On failure, they return a negative errno-style error + code. + + + + Errors + + Returned errors may indicate the following problems: + + + + -ENOMEM + + Not enough memory to allocate an object. + + + + -EINVAL + + An invalid argument has been passed. + + + + + -ESTALE + + The event loop is already terminated. + + + + + -ECHILD + + The event loop has been created in a different process. + + + + -EDOM + + The passed event source is not an I/O event source. + + + + + + + + See Also + + + systemd1, + sd-event3, + sd_event_new3, + sd_event_now3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_child3, + sd_event_add_defer3, + sd_event_source_set_enabled3, + sd_event_source_set_priority3, + sd_event_source_set_userdata3, + sd_event_source_set_description3, + sd_event_source_get_pending3, + epoll_ctl3, + epoll7 + + + + diff --git a/man/sd_event_add_signal.xml b/man/sd_event_add_signal.xml index 0923fe0ae7..b5312735d2 100644 --- a/man/sd_event_add_signal.xml +++ b/man/sd_event_add_signal.xml @@ -21,7 +21,7 @@ along with systemd; If not, see . --> - + sd_event_add_signal @@ -45,13 +45,24 @@ sd_event_add_signal sd_event_source_get_signal + sd_event_signal_handler_t - Add a signal event source to an event loop + Add a UNIX process signal event source to an event + loop - #include <systemd/sd-bus.h> + #include <systemd/sd-event.h> + + typedef struct sd_event_source sd_event_source; + + + typedef int (*sd_event_signal_handler_t) + sd_event_source *s + const struct signalfd_siginfo *si + void *userdata + int sd_event_add_signal @@ -62,13 +73,6 @@ void *userdata - - typedef int (*sd_event_signal_handler_t) - sd_event_source *s - const struct signalfd_siginfo *si - void *userdata - - int sd_event_source_get_signal sd_event_source *source @@ -80,41 +84,61 @@ Description - sd_event_add_signal() adds a new signal - event source to an event loop object. The event loop is specified - in event, and the event source is returned in - the source parameter. The - signal parameter specifies the signal to be handled - (see - signal7). - The handler must reference a function to - call when the signal is delivered or be NULL. - The handler function will be passed the - userdata pointer, which may be chosen + sd_event_add_signal() adds a new UNIX + process signal event source to an event loop. The event loop + object is specified in the event parameter, + and the event source object is returned in the + source parameter. The + signal parameter specifies the numeric + signal to be handled (see signal7). + The handler parameter must reference a + function to call when the signal is received or be + NULL. The handler function will be passed + the userdata pointer, which may be chosen freely by the caller. The handler also receives a pointer to a - const struct signalfd_siginfo containing - the information about the received signal. See - signalfd2 + signalfd_siginfo structure containing + information about the received signal. See signalfd2 for further information. Only a single handler may be installed for a specific - signal. The signal will be unblocked, and must be - blocked when the function is called. If the handler is not - specified (handler is + signal. The signal will be unblocked by this call, and must be + blocked before this function is called in all threads (using + sigprocmask2). If + the handler is not specified (handler is NULL), a default handler which causes the - program to exit will be used. By default, the handler is enabled - permanently (SD_EVENT_ON), but this may be - changed with + program to exit cleanly will be used. + + By default, the event source is enabled permanently + (SD_EVENT_ON), but this may be changed with sd_event_source_set_enabled3. If the handler function returns a negative error code, it will be - disabled after the invocation, even if - SD_EVENT_ON mode is set. + disabled after the invocation, even if the + SD_EVENT_ON mode was requested before. + To destroy an event source object use + sd_event_source_unref3, + but note that the event source is only removed from the event loop + when all references to the event source are dropped. To make sure + an event source does not fire anymore, even when there's still a + reference to it kept, consider setting the event source to + SD_EVENT_OFF with + sd_event_source_set_enabled3. + + If the the second parameter of + sd_event_add_signal() is passed as NULL no + reference to the event source object is returned. In this case the + event source is considered "floating", and will be destroyed + implicitly when the event loop itself is destroyed. + sd_event_source_get_signal() retrieves - the configured signal number of a signal event source created - previously with sd_event_add_signal(). It - takes the event source object as the source + the configured UNIX process signal number of a signal event source + created previously with + sd_event_add_signal(). It takes the event + source object as the source parameter. @@ -168,18 +192,16 @@ + + -EDOM + + The passed event source is not a signal event source. + + - - Notes - - sd_event_add_signal() and the other functions - described here are available as a shared library, which can be - compiled and linked to with the - libsystemd pkg-config1 - file. - + See Also @@ -188,10 +210,16 @@ systemd1, sd-event3, sd_event_new3, + sd_event_now3, + sd_event_add_io3, sd_event_add_time3, sd_event_add_child3, sd_event_add_defer3, - sd_event_source_set_enabled3 + sd_event_source_set_enabled3, + sd_event_source_set_description3, + sd_event_source_set_userdata3, + signal7, + signalfd2 diff --git a/man/sd_event_add_time.xml b/man/sd_event_add_time.xml index c5f7aee19d..df38f52fc9 100644 --- a/man/sd_event_add_time.xml +++ b/man/sd_event_add_time.xml @@ -21,7 +21,7 @@ along with systemd; If not, see . --> - + sd_event_add_time @@ -49,13 +49,23 @@ sd_event_source_get_time_accuracy sd_event_source_set_time_accuracy sd_event_source_get_time_clock + sd_event_time_handler_t Add a timer event source to an event loop - #include <systemd/sd-bus.h> + #include <systemd/sd-event.h> + + typedef struct sd_event_source sd_event_source; + + + typedef int (*sd_event_time_handler_t) + sd_event_source *s + uint64_t usec + void *userdata + int sd_event_add_time @@ -68,35 +78,28 @@ void *userdata - - typedef int (*sd_event_time_handler_t) - sd_event_source *s - uint64_t usec - void *userdata - - int sd_event_source_get_time sd_event_source *source - usec_t *usec + uint64_t *usec int sd_event_source_set_time sd_event_source *source - usec_t usec + uint64_t usec int sd_event_source_get_time_accuracy sd_event_source *source - usec_t *usec + uint64_t *usec int sd_event_source_set_time_accuracy sd_event_source *source - usec_t usec + uint64_t usec @@ -112,73 +115,130 @@ Description sd_event_add_time() adds a new timer - event source to an event loop object. The event loop is specified - in event, the event source is returned in - the source parameter. The - clock parameter takes a clock identifier, - one of CLOCK_REALTIME, - CLOCK_MONOTONIC and + event source to an event loop. The event loop object is specified + in the event parameter, the event source + object is returned in the source + parameter. The clock parameter takes a + clock identifier, one of CLOCK_REALTIME, + CLOCK_MONOTONIC, + CLOCK_BOOTTIME, + CLOCK_REALTIME_ALARM or CLOCK_BOOTTIME_ALARM. See timerfd_create2 for details regarding the various types of clocks. The usec parameter takes a time value in - microseconds, relative to the clock's epoch specifying when the - timer shall elapse the earliest. The + microseconds (µs), relative to the clock's epoch, specifying when + the timer shall elapse the earliest. If a time that already lies + in the past is specified (including 0), the timer source is + dispatched immediately in the next event loop iterations. The accuracy parameter takes an additional - accuracy value in microseconds specifying a time the timer event - may be delayed. Specify 0 for selecting the default accuracy - (250ms). Specify 1 for most accurate timers. Consider specifying - 60000000 or larger (1h) for long-running events that may be + accuracy value in µs specifying a time the timer event may be + delayed. Specify 0 for selecting the default accuracy + (250ms). Specify 1µs for most accurate timers. Consider specifying + 60000000µs or larger (1min) for long-running events that may be delayed substantially. Picking higher accuracy values allows the system to coalesce timer events more aggressively, thus improving - power efficiency. The handler shall - reference a function to call when the timer elapses. The handler - function will be passed the userdata - pointer, which may be chosen freely by the caller. The handler is - also passed the configured time it was triggered, however it might - actually have been called at a slightly later time, subject to the - specified accuracy value, the kernel timer slack (see + power efficiency. The handler parameter + shall reference a function to call when the timer elapses. The + handler function will be passed the + userdata pointer, which may be chosen + freely by the caller. The handler is also passed the configured + time it was triggered, however it might actually have been called + at a slightly later time, subject to the specified accuracy value, + the kernel timer slack (see prctl2) - and additional scheduling latencies. + and additional scheduling latencies. To query the actual time the + handler was called use + sd_event_now3. By default, the timer will elapse once (SD_EVENT_ONESHOT), but this may be changed with sd_event_source_set_enabled3. If the handler function returns a negative error code, it will be - disabled after the invocation, even if - SD_EVENT_ON mode is set. + disabled after the invocation, even if the + SD_EVENT_ON mode was requested before. Note + that a timer event set to SD_EVENT_ON will + fire continously unless its configured time is updated using + sd_event_source_set_time(). + To destroy an event source object use + sd_event_source_unref3, + but note that the event source is only removed from the event loop + when all references to the event source are dropped. To make sure + an event source does not fire anymore, even when there's still a + reference to it kept, consider setting the event source to + SD_EVENT_OFF with + sd_event_source_set_enabled3. + + If the the second parameter of + sd_event_add_time() is passed as NULL no + reference to the event source object is returned. In this case the + event source is considered "floating", and will be destroyed + implicitly when the event loop itself is destroyed. + + If the handler to + sd_event_add_time() is passed as NULL, and + the event source fires, this will be considered a request to exit + the event loop. In this case, the userdata + parameter, cast to an integer is used for the exit code passed to + sd_event_exit3. + + Use CLOCK_BOOTTIME_ALARM and + CLOCK_REALTIME_ALARM to define event sources + that may wake up the system from suspend. + + In order to set up relative timers (that is, relative to the + current time), retrieve the current time via + sd_event_now3, + add the desired timespan to sleep to it, and pass the result as + the usec parameter to + sd_event_add_time(). + + In order to set up repetitive timers (that is, timers that + are triggered in regular intervals), set up the timer normally, + for the first invocation. Each time the event handler is invoked, + update the timer's trigger time with + sd_event_source_set_time3 for the next timer + iteration, and reenable the timer using + sd_event_source_set_enabled(). To calculate + the next point in time to pass to + sd_event_source_set_time(), either use as + base the usec parameter passed to the timer + callback, or the timestamp returned by + sd_event_now(). In the former case timer + events will be regular, while in the latter case the scheduling + latency will keep accumulating on the timer. + sd_event_source_get_time() retrieves the configured time value of a timer event source created previously with sd_event_add_time(). It takes the event source object and a pointer to a variable to store the - time in microseconds in. + time, relative to the selected clock's epoch, in µs in. sd_event_source_set_time() changes the configured time value of a timer event source created previously with sd_event_add_time(). It takes the event source object and a time relative to the selected clock's - epoch, in microseconds. + epoch, in µs. sd_event_source_get_time_accuracy() retrieves the configured accuracy value of a timer event source created previously with sd_event_add_time(). It takes the event source object and a pointer to a variable to store - the accuracy in microseconds in. + the accuracy in µs in. sd_event_source_set_time_accuracy() changes the configured accuracy of a timer event source created previously with sd_event_add_time(). It takes - the event source object and an accuracy, in microseconds. + the event source object and an accuracy, in µs. sd_event_source_get_time_clock() retrieves the configured clock of a timer event source created previously with sd_event_add_time(). It takes the event source object and a pointer to a variable to store the clock identifier in. - @@ -228,18 +288,16 @@ The selected clock is not supported by the event loop implementation. + + + -EDOM + + The passed event source is not a timer event source. + - - Notes - - sd_event_add_time() and the other functions - described here are available as a shared library, which can be - compiled and linked to with the - libsystemd pkg-config1 - file. - + See Also @@ -248,11 +306,18 @@ systemd1, sd-event3, sd_event_new3, + sd_event_now3, + sd_event_add_io3, sd_event_add_signal3, sd_event_add_child3, sd_event_add_defer3, - clock_gettime2, - sd_event_source_set_enabled3 + sd_event_source_set_enabled3, + sd_event_source_set_priority3, + sd_event_source_set_userdata3, + sd_event_source_set_description3, + clock_gettime2, + timerfd_create2, + prctl2 diff --git a/man/sd_event_exit.xml b/man/sd_event_exit.xml new file mode 100644 index 0000000000..4f34f3b122 --- /dev/null +++ b/man/sd_event_exit.xml @@ -0,0 +1,163 @@ + + + + + + + + + sd_event_exit + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_exit + 3 + + + + sd_event_exit + sd_event_get_exit_code + + Ask the event loop to exit + + + + + #include <systemd/sd-event.h> + + + int sd_event_exit + sd_event *event + int code + + + + int sd_event_get_exit_code + sd_event *event + int *code + + + + + + + Description + + sd_event_exit() requests the event loop + specified in the event event loop object to + exit. The code parameter may be any integer + value and is returned as-is by + sd_event_loop3 + after the last event loop iteration. It may also be be queried + using sd_event_get_exit_code(), see + below. + + When exiting is requested the event loop will stop listening + for and dispatching regular event sources. Instead it will proceed + with executing only event sources registered with + sd_event_add_exit3 + in the order defined by their priority. After all exit event + sources have been dispatched the event loop is terminated. + + If sd_event_exit() is invoked a second + time while the event loop is still processing exit event sources, + the exit code stored in the event loop object is updated, but + otherwise no further operation is executed. + + sd_event_get_exit_code() may be used to + query the exit code passed into + sd_event_exit() earlier. + + While the full positive and negative integer ranges may be used + for the exit code, care should be taken not pick exit codes that + conflict with regular exit codes returned by + sd_event_loop(), if these exit codes shall be + distinguishable. + + + + Return Value + + On success, sd_event_exit() and + sd_event_get_exit_code() return 0 or a positive + integer. On failure, they return a negative errno-style error + code. + + + + Errors + + Returned errors may indicate the following problems: + + + + + -EINVAL + + The event loop object or error code pointer are invalid. + + + + + -ECHILD + + The event loop was created in a different process. + + + + -ESTALE + + The event loop has exited already and all exit handlers are already processed. + + + + -ENODATA + + The event loop has not been requested to exit yet. + + + + + + + + + See Also + + + systemd1, + sd-event3, + sd_event_new3, + sd_event_add_exit3 + + + + diff --git a/man/sd_event_get_fd.xml b/man/sd_event_get_fd.xml index ecdbe76ec4..f68752dd0e 100644 --- a/man/sd_event_get_fd.xml +++ b/man/sd_event_get_fd.xml @@ -21,8 +21,7 @@ along with systemd; If not, see . --> - + sd_event_get_fd @@ -51,11 +50,11 @@ - #include <systemd/sd-bus.h> + #include <systemd/sd-event.h> int sd_event_get_fd - sd_bus *event + sd_event *event @@ -65,19 +64,29 @@ Description sd_event_get_fd() returns the file - descriptor that the event loop object returned by the + descriptor that an event loop object returned by the sd_event_new3 - function uses to wait for events. This file descriptor can be - polled for events. This makes it possible to embed the + function uses to wait for events. This file descriptor may itself + be polled for + POLLIN/EPOLLIN + events. This makes it possible to embed an sd-event3 - event loop inside of another event loop. + event loop into another, possibly foreign, event loop. + + The returned file descriptor refers to an epoll7 + object. It is recommended not to alter it by invoking + epoll_ctl2 + on it, in order to avoid interference with the event loop's inner + logic and assumptions. Return Value On success, sd_event_get_fd() returns a - non-negative integer. On failure, it returns a negative + non-negative file descriptor. On failure, it returns a negative errno-style error code. @@ -108,21 +117,13 @@ Examples - Integration in glib event loop + Integration in the GLib event loop - - Notes - - sd_event_get_fd() is available as a - shared library, which can be compiled and linked to with the - libsystemd pkg-config1 - file. - + See Also @@ -130,7 +131,9 @@ sd-event3, sd_event_new3, - sd_event_ref3 + sd_event_wait3, + epoll_ctl3, + epoll7 diff --git a/man/sd_event_new.xml b/man/sd_event_new.xml index f6c5d39814..3356faa899 100644 --- a/man/sd_event_new.xml +++ b/man/sd_event_new.xml @@ -21,7 +21,7 @@ along with systemd; If not, see . --> - + sd_event_new @@ -47,32 +47,42 @@ sd_event_default sd_event_ref sd_event_unref + sd_event_get_tid + sd_event Acquire and release an event loop object - #include <systemd/sd-bus.h> + #include <systemd/sd-event.h> + + typedef struct sd_event sd_event; int sd_event_new - sd_bus **event + sd_event **event int sd_event_default - sd_bus **event + sd_event **event - sd_bus *sd_event_ref - sd_bus *event + sd_event *sd_event_ref + sd_event *event - sd_bus *sd_event_unref - sd_bus *event + sd_event *sd_event_unref + sd_event *event + + + + int sd_event_get_tid + sd_event *event + pid_t *tid @@ -103,6 +113,17 @@ 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 + or + sd_event_add_defer3, + and then execute the event loop using + sd_event_run3. + sd_event_ref() increases the reference count of the specified event loop object by one. @@ -117,6 +138,19 @@ 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. + + Both sd_event_ref() and + sd_event_unref() 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. @@ -149,18 +183,19 @@ 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(). + + - - Notes - - sd_event_new() and the other functions - described here are available as a shared library, which can be - compiled and linked to with the - libsystemd pkg-config1 - file. - + See Also @@ -174,7 +209,9 @@ sd_event_add_child3, sd_event_add_defer3, sd_event_add_post3, - sd_event_add_exit3 + sd_event_add_exit3, + sd_event_run3, + gettid2 diff --git a/man/sd_event_now.xml b/man/sd_event_now.xml new file mode 100644 index 0000000000..f577e44c0e --- /dev/null +++ b/man/sd_event_now.xml @@ -0,0 +1,141 @@ + + + + + + + + + sd_event_now + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_now + 3 + + + + sd_event_now + + Retrieve current event loop iteration timestamp + + + + + #include <systemd/sd-event.h> + + + int sd_event_now + sd_event *event + clockid_t clock + uint64_t *usec + + + + + + + Description + + sd_event_now() returns the timestamp + the most recent event loop iteration began. This timestamp is + taken right after after returning from the event sleep, and before + dispatching any event sources. The event + parameter takes the even loop object to retrieve the timestamp + from. The clock parameter specifies the clock to + retrieve the timestamp for, and is one of + CLOCK_REALTIME (or its equivalent + CLOCK_REALTIME_ALARM), + CLOCK_MONOTONIC or + CLOCK_BOOTTIME (or its equivalent + CLOCK_BOOTTIME_ALARM), see clock_gettime2 + for more information on the various clocks. The retrieved + timestamp is stored in the usec parameter, + in µs since the clock's epoch. If this function is invoked before + the first event loop iteration the current time is returned, as + reported by clock_gettime(). To distinguish + this case from a regular invocation the return value will be + positive non-zero in this case, while it is zero when the returned + timestamp refers to the actual event loop iteration. + + + + Return Value + + If the first event loop iteration has not run yet + sd_event_now() returns the requested + timestamp in usec and returns a positive, + non-zero return value. Otherwise, on success it will return the + iteration's timestamp in usec and 0 as + return value. On failure, the call returns a negative errno-style + error code. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + An invalid parameter was + passed. + + + + + -ECHILD + + The event loop object was created in a + different process. + + + + + + + + + See Also + + + systemd1, + sd-event3, + sd_event_new3, + sd_event_add_time3, + clock_gettime2 + + + + diff --git a/man/sd_event_run.xml b/man/sd_event_run.xml index 06236fcd1a..5b68959165 100644 --- a/man/sd_event_run.xml +++ b/man/sd_event_run.xml @@ -21,7 +21,7 @@ along with systemd; If not, see . --> - + sd_event_run @@ -46,7 +46,7 @@ sd_event_run sd_event_loop - Run the libsystemd event loop + Run an event loop @@ -56,7 +56,7 @@ int sd_event_run sd_event *event - uint64_t timeout + uint64_t usec @@ -69,47 +69,60 @@ 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. The timeout parameter specifices the - maximum time (in microseconds) to wait. (uint64_t) - -1 may be used to specify an infinite timeout. + sd_event_run() may be used to run a single + iteration of the event loop specified in the + event parameter. The function waits until an event to + process is available, and dispatches the registered handler for + it. The usec parameter specifies the + maximum time (in microseconds) to wait for an event. Use + (uint64_t) -1 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. + sd_event_loop() invokes + sd_event_run() in a loop, thus implementing + the actual event loop. The call returns as soon as exiting was + requested using + sd_event_exit3. 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, + sd_event_new3. + Events sources to wait for and their handlers may be registered + with + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_child3, + sd_event_add_defer3, + sd_event_add_post3 and - sd_event_add_post. + sd_event_add_exit3. - 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. + For low-level control of event loop execution, use + sd_event_prepare3, + sd_event_wait3 + and + sd_event_dispatch3 + which are wrapped by sd_event_run(). Along + with + sd_event_get_fd3, + these functions allow integration of an + sd-event3 + event loop into foreign event loop implementations. 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. + On failure, these functions return a negative errno-style + error code. sd_event_run() returns a + positive, non-zero integer if an event source was dispatched, and + zero when the specified timeout hit before an event source has + seen any event, and hence no event source was + dispatched. sd_event_loop() returns the exit + code specified when invoking + sd_event_exit(). @@ -122,7 +135,7 @@ -EINVAL The event parameter is - NULL. + invalid or NULL. @@ -153,15 +166,7 @@ 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 @@ -169,13 +174,15 @@ 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, + sd_event_exit3, + sd_event_get_fd3, + sd_event_wait3, GLib Main Event Loop. diff --git a/man/sd_event_set_name.xml b/man/sd_event_set_name.xml deleted file mode 100644 index 1471e12e59..0000000000 --- a/man/sd_event_set_name.xml +++ /dev/null @@ -1,151 +0,0 @@ - - - - - - - - - sd_event_set_name - systemd - - - - More text - Zbigniew - Jędrzejewski-Szmek - zbyszek@in.waw.pl - - - - - - sd_event_set_name - 3 - - - - sd_event_set_name - sd_event_get_name - - Set human-readable names for event sources - - - - - #include <systemd/sd-bus.h> - - - int sd_event_set_name - sd_event_source *source - const char *name - - - - int sd_event_get_name - sd_event_source *source - const char **name - - - - - - - Description - - sd_event_set_name() can be used to set - an arbitrary name for the event source - source. This name will be used in error - messages generated by - sd-event3 - for this source. The name must point - to a NUL-terminated string or be - NULL. In the latter case, the name will be - unset. The string is copied internally, so the - name argument is not referenced after the - function returns. - - sd_event_set_name() can be used to - query the current name assigned to source - source. It returns a pointer to the current - name (possibly NULL) in - name. - - - - Return Value - - On success, sd_event_set_name() and - sd_event_get_name() 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 - structure or the name argument for - sd_event_get_name() is - NULL. - - - - -ENOMEM - - Not enough memory to copy the - name. - - - - - - Notes - - The functions described here are available as a - shared library, which can be compiled and linked to with the - libsystemd pkg-config1 - file. - - - - See Also - - - sd-event3, - sd_event_add_time3, - sd_event_add_child3, - sd_event_add_signal3, - sd_event_add_defer3, - sd_event_run3 - - - - diff --git a/man/sd_event_set_watchdog.xml b/man/sd_event_set_watchdog.xml new file mode 100644 index 0000000000..cbc5bc0836 --- /dev/null +++ b/man/sd_event_set_watchdog.xml @@ -0,0 +1,177 @@ + + + + + + + + + sd_event_set_watchdog + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_set_watchdog + 3 + + + + sd_event_set_watchdog + sd_event_get_watchdog + + Enable event loop watchdog support + + + + + #include <systemd/sd-event.h> + + + int sd_event_set_watchdog + sd_event *event + int b + + + + int sd_event_get_watchdog + sd_event *event + + + + + + + Description + + sd_event_set_watchdog() may be used to + enable or disable automatic watchdog notification support in the + event loop object specified in the event + parameter. Specifically, depending on the b + boolean argument this will make sure the event loop wakes up in + regular intervals and sends watchdog notification messages to the + service manager, if this was requested by the service + manager. Watchdog support is determined with + sd_watchdog_enabled3, + and watchdog messages are sent with + sd_notify3. See + the WatchdogSec= setting in + systemd.service5 + for details on how to enable watchdog support for a service and + the protocol used. The wake-up interval is chosen as half the + watchdog timeout declared by the service manager via the + $WATCHDOG_USEC environment variable. If the + service manager did not request watchdog notifications, or if the + process was not invoked by the service manager this call with a + true b parameter executes no + operation. Passing a false b parameter will + disable the automatic sending of watchdog notification messages if + it was enabled before. Newly allocated event loop objects have + this feature disabled. + + The first watchdog notification message is sent immediately + when set_event_set_watchdog() is invoked with + a true b parameter. + + The watchdog logic is designed to allow the service manager + to automatically detect services that ceased processing of + incoming events, and thus appear "hung". Watchdog notifications + are sent out only at the beginning of each event loop + iteration. If an event source dispatch function blocks for an + excessively long time and does not return execution to the event + loop quickly, this might hence cause the notification message to + be delayed, and possibly result in abnormal program termination, + as configured in the service unit file. + + sd_event_get_watchdog() may be used to + determine whether watchdog support was previously requested by a + call to sd_event_set_watchdog() with a true + b parameter and successfully + enabled. + + + + Return Value + + On success, sd_event_set_watchdog() and + sd_event_get_watchdog() return a non-zero + positive integer if the service manager requested watchdog support + and watchdog support was successfully enabled. They return zero if + the service manager did not request watchdog support, or if + watchdog support was explicitly disabled with a false + b parameter. On failure, they return a + negative errno-style error + code. + + + + Errors + + Returned errors may indicate the following problems: + + + + + -ECHILD + + The event loop has been created in a different process. + + + + -EINVAL + + The passed event loop object was invalid. + + + + + + + + + See Also + + + systemd1, + sd-event3, + sd_event_new3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_child3, + sd_event_add_defer3, + sd_event_add_post3, + sd_event_add_exit3, + sd_watchdog_enabled3, + sd_notify3, + systemd.service5 + + + + diff --git a/man/sd_event_source_get_event.xml b/man/sd_event_source_get_event.xml new file mode 100644 index 0000000000..2fdbd411bd --- /dev/null +++ b/man/sd_event_source_get_event.xml @@ -0,0 +1,100 @@ + + + + + + + + + sd_event_source_get_event + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_source_get_event + 3 + + + + sd_event_source_get_event + + Retrieve the event loop of an event source + + + + + #include <systemd/sd-event.h> + + + sd_event* sd_event_source_get_event + sd_event_source *source + + + + + + + Description + + sd_event_source_get_event() may be used + to retrieve the event loop object the event source object specified + as source is associated with. The event + loop object is specified when creating an event source object with + calls such as + sd_event_add_io3 + or + sd_event_add_time3. + + + + Return Value + + On success, sd_event_source_get_event() + returns the associated event loop object. On failure, it returns + NULL. + + + + + + See Also + + + sd-event3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_child3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_source_set_userdata3 + + + + diff --git a/man/sd_event_source_get_pending.xml b/man/sd_event_source_get_pending.xml new file mode 100644 index 0000000000..1c06e81fe0 --- /dev/null +++ b/man/sd_event_source_get_pending.xml @@ -0,0 +1,167 @@ + + + + + + + + + sd_event_source_get_pending + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_source_get_pending + 3 + + + + sd_event_source_get_pending + + Determine pending state of event sources + + + + + #include <systemd/sd-event.h> + + + int sd_event_source_get_pending + sd_event_source *source + + + + + + + Description + + sd_event_source_get_pending() may be + used to determine whether the event source object specified as + source has seen events but has not been + dispatched yet (and thus is marked "pending"). + + Event source objects initially are not marked pending, when + they are created with calls such as + sd_event_add_io3, + sd_event_add_time3, + with the exception of those created with + sd_event_add_defer3 + which are immediately marked pending, and + sd_event_add_exit3 + for which the "pending" concept is not defined. For details see + the respective manual pages. + + In each event loop iteration one event source of those + marked pending is dispatched, in the order defined by the event + source priority, as set with + sd_event_source_set_priority3. + + For I/O event sources, as created with + sd_event_add_io3, + the call + sd_event_get_io_revents3 + may be used to query the type of event pending in more + detail. + + + + + Return Value + + On success, + sd_event_source_get_pending() returns an + integer greater than zero when the event source is marked pending, + and zero when the event source is not marked pending. On failure, + it returns 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. + + + + -EDOM + + source refers to an + event source object created with + sd_event_add_exit3. + + + + -ENOMEM + + Not enough memory. + + + + -ESTALE + + The event loop is already terminated. + + + + + -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_child3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_source_unref3 + + + + diff --git a/man/sd_event_source_set_description.xml b/man/sd_event_source_set_description.xml new file mode 100644 index 0000000000..b9488a622f --- /dev/null +++ b/man/sd_event_source_set_description.xml @@ -0,0 +1,170 @@ + + + + + + + + + sd_event_source_set_description + systemd + + + + More text + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_event_source_set_description + 3 + + + + sd_event_source_set_description + sd_event_source_get_description + + Set or retrieve descriptive names of event sources + + + + + #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 **description + + + + + + + Description + + sd_event_source_set_description() may + be used to set an arbitrary descriptive name for the event source + object specified as source. This name will + be used in debugging messages generated by + sd-event3 + for this event source, and may be queried using + sd_event_source_get_description() for + debugging purposes. The description parameter shall + point to a NUL-terminated string or be + NULL. In the latter case, the descriptive + name will be unset. The string is copied internally, hence the + description argument is not referenced + after the function returns. + + sd_event_source_get_description() may + be used to query the current descriptive name assigned to the + event source object source. It returns a + pointer to the current name in description, + stored in memory internal to the event source. The memory is + invalidated when the event source is destroyed or the descriptive + name is changed. + + Event source objects generally have no description set when + they are created, except for UNIX signal event sources created + with + sd_event_add_signal3, + whose descriptive name is initialized to the signal's C constant + name (e.g. SIGINT or + SIGTERM). + + + + Return Value + + On success, 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 + + Returned errors may indicate the following problems: + + + + -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. + + + + -ENOMEM + + Not enough memory to copy the + name. + + + + -ECHILD + + The event loop has been created in a different process. + + + + + -ENXIO + + No name was set for the event + source. + + + + + + + + + See Also + + + sd-event3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_child3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_source_set_userdata3 + + + + diff --git a/man/sd_event_source_set_enabled.xml b/man/sd_event_source_set_enabled.xml new file mode 100644 index 0000000000..74c02e87bb --- /dev/null +++ b/man/sd_event_source_set_enabled.xml @@ -0,0 +1,179 @@ + + + + + + + + + sd_event_source_set_enabled + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_source_set_enabled + 3 + + + + sd_event_source_set_enabled + sd_event_source_get_enabled + SD_EVENT_ON + SD_EVENT_OFF + SD_EVENT_ONESHOT + + Enable or disable event sources + + + + + #include <systemd/sd-event.h> + + enum { + SD_EVENT_OFF = 0, + SD_EVENT_ON = 1, + SD_EVENT_ONESHOT = -1, +}; + + + int sd_event_source_set_enabled + sd_event_source *source + int enabled + + + + int sd_event_source_get_enabled + sd_event_source *source + int *enabled + + + + + + + Description + + sd_event_source_set_enabled() may be + used to enable or disable the event source object specified as + source. The enabled + parameter takes one of SD_EVENT_ON (to + enable), SD_EVENT_OFF (to disable) or + SD_EVENT_ONESHOT. If invoked with + SD_EVENT_ONESHOT the event source will be + enabled but automatically reset to + SD_EVENT_OFF after the event source was + dispatched once. + + Event sources that are disabled will not result in event + loop wakeups and will not be dispatched, until they are enabled + again. + + sd_event_source_get_enabled() may be + used to query whether the event source object + source is currently enabled or not. It + returns the enablement state in + enabled. + + Event source objects are enabled when they are first created + with calls such as + sd_event_add_io3, + sd_event_add_time3. However, + depending on the event source type they are enabled continously + (SD_EVENT_ON) or only for a single invocation + of the event source handler + (SD_EVENT_ONESHOT). For details see the + respective manual pages. + + As event source objects stay active and may be dispatched as + long as there is at least one reference to them, in many cases it + is a good idea to combine a call to + sd_event_source_unref3 + with a prior call to + sd_event_source_set_enabled() with + SD_EVENT_OFF, to ensure the event source is + not dispatched again until all other remaining references are dropped. + + + + Return Value + + On success, sd_event_source_set_enabled() and + sd_event_source_get_enabled() 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. + + + + -ENOMEM + + Not enough memory. + + + + -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_child3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_source_unref3 + + + + diff --git a/man/sd_event_source_set_prepare.xml b/man/sd_event_source_set_prepare.xml new file mode 100644 index 0000000000..7066a55306 --- /dev/null +++ b/man/sd_event_source_set_prepare.xml @@ -0,0 +1,171 @@ + + + + + + + + + sd_event_source_set_prepare + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_source_set_prepare + 3 + + + + sd_event_source_set_prepare + + Set a preparation callback for event sources + + + + + #include <systemd/sd-event.h> + + + int sd_event_source_set_prepare + sd_event_source *source + sd_event_handler_t callback + + + + typedef int (*sd_event_handler_t) + sd_event_source *s + void *userdata + + + + + + + Description + + sd_event_source_set_prepare() may be + used to set a prepartion callback for the event source object + specified as source. The callback function + specified as callback will be invoked + immediately before the event loop goes to sleep to wait for + incoming events. It is invoked with the user data pointer passed + when the event source was created. The callback function may be + used to reconfigure the precise events to wait for. If the + callback parameter is passed as NULL the + callback function is reset. + + Event source objects have no preparation callback associated + when they are first created with calls such as + sd_event_add_io3, + sd_event_add_time3. Preparation + callback functions are supported for all event source types with + the exception of those created with + sd_event_add_exit3. Preparation + callback functions are dispatched in the order indicated by the + event source's priority field, as set with + sd_event_source_set_priority3. Preparation + callbacks of disabled event sources (see + sd_event_source_set_enabled3) + are not invoked. + + + + Return Value + + On success, + sd_event_source_set_prepare() returns a + non-negative integer. On failure, it returns 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. + + + + -ESTALE + + The event loop is already terminated. + + + + -ENOMEM + + Not enough memory. + + + + -ECHILD + + The event loop has been created in a different process. + + + + + -EDOM + + The specified event source has been created + with + sd_event_add_exit3. + + + + + + + + + + See Also + + + sd-event3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_child3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_source_set_enabled3, + sd_event_source_set_priority3, + sd_event_source_set_userdata3 + + + + diff --git a/man/sd_event_source_set_priority.xml b/man/sd_event_source_set_priority.xml new file mode 100644 index 0000000000..cc0f5a0103 --- /dev/null +++ b/man/sd_event_source_set_priority.xml @@ -0,0 +1,189 @@ + + + + + + + + + sd_event_source_set_priority + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_source_set_priority + 3 + + + + sd_event_source_set_priority + sd_event_source_get_priority + SD_EVENT_PRIORITY_IMPORTANT + SD_EVENT_PRIORITY_NORMAL + SD_EVENT_PRIORITY_IDLE + + Set or retrieve the priority of event sources + + + + + #include <systemd/sd-event.h> + + enum { + SD_EVENT_SOURCE_IMPORTANT = -100, + SD_EVENT_SOURCE_NORMAL = 0, + SD_EVENT_SOURCE_IDLE = 100, +}; + + + int sd_event_source_set_priority + sd_event_source *source + int64_t priority + + + + int sd_event_source_get_priority + sd_event_source *source + int64_t *priority + + + + + + + Description + + sd_event_source_set_priority() may be + used to set the priority for the event source object specified as + source. The priority is specified as an + arbitrary signed 64bit integer. The priority is initialized to + SD_EVENT_PRIORITY_NORMAL (0) when the event + source is allocated with a call such as + sd_event_add_io3 + or + sd_event_add_time3, + and may be changed with this call. If multiple event sources have seen events at the same time, they are dispatched in the order indicated by the + event sources' priorities. Event sources with smaller priority + values are dispatched first. As well-known points of reference, + the constants SD_EVENT_PRIORITY_IMPORTANT + (-100), SD_EVENT_PRIORITY_NORMAL (0) and + SD_EVENT_PRIORITY_IDLE (100) may be used to + indicate event sources that shall be dispatched early, normally or + late. It is recommended to specify priorities based on these + definitions, and relative to them -- however, the full 64bit + signed integer range is available for ordering event + sources. + + Priorities define the order in which event sources that have + seen events are dispatched. Care should be taken to ensure that + high-priority event sources (those with negative priority values + assigned) do not cause starvation of low-priority event sources + (those with positive priority values assigned). + + The order in which event sources with the same priority are + dispatched is undefined, but the event loop generally tries to + dispatch them in the order it learnt about events on them. As the + backing kernel primitives do not provide accurate information + about the order in which events occured this is not necessarily + reliable. However, it is guaranteed that if events are seen on + multiple same-priority event sources at the same time, each one is + not dispatched again until all others have been dispatched + once. This behaviour guarantees that within each priority + particular event sources do not starve or dominate the event + loop. + + sd_event_source_get_priority() may be + used to query the current priority assigned to the event source + object source. + + + + Return Value + + On success, + sd_event_source_set_priority() and + sd_event_source_get_priority() 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. + + + + -ENOMEM + + Not enough memory. + + + + -ESTALE + + The event loop is already terminated. + + + + + -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_child3, + sd_event_add_signal3, + sd_event_add_defer3 + + + + diff --git a/man/sd_event_source_set_userdata.xml b/man/sd_event_source_set_userdata.xml new file mode 100644 index 0000000000..533d491b13 --- /dev/null +++ b/man/sd_event_source_set_userdata.xml @@ -0,0 +1,119 @@ + + + + + + + + + sd_event_source_set_userdata + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_source_set_userdata + 3 + + + + sd_event_source_set_userdata + sd_event_source_get_userdata + + Set or retrieve user data pointer of event sources + + + + + #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 + + sd_event_source_set_userdata() may be + used to set an arbitrary user data pointer for the event source + object specified as source. The user data + pointer is usually specified when creating an event source object + with calls such as + sd_event_add_io3 + or + sd_event_add_time3, + and may be updated with this call. The user data pointer is also + passed to all handler callback functions associated with the event + source. The userdata parameter specifies + the new user data pointer to set, the function returns the + previous user data pointer. Note that NULL is + a valid user data pointer. + + sd_event_source_get_userdata() may be + used to query the current user data pointer assigned to the event + source object source. + + + + Return Value + + On success, + sd_event_source_set_userdata() and + sd_event_source_get_userdata() return the + previously set user data pointer. On failure, they return + NULL. + + + + + + See Also + + + sd-event3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_child3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_source_set_description3 + + + + diff --git a/man/sd_event_source_unref.xml b/man/sd_event_source_unref.xml new file mode 100644 index 0000000000..579ec47e8e --- /dev/null +++ b/man/sd_event_source_unref.xml @@ -0,0 +1,125 @@ + + + + + + + + + sd_event_source_unref + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_source_unref + 3 + + + + sd_event_source_unref + sd_event_source_ref + + Increase or decrease event source reference counters + + + + + #include <systemd/sd-event.h> + + + sd_event_source* sd_event_source_unref + sd_event_source *source + + + + sd_event_source* sd_event_source_ref + sd_event_source *source + + + + + + + Description + + sd_event_source_unref() may be used to + decrement by one the reference counter of the event source object + specified as source. The reference counter + is initially set to one, when the event source is created with calls + such as + sd_event_add_io3 + or + sd_event_add_time3. When + the reference counter reaches zero it is removed from its event loop + object and destroyed. + + sd_event_source_ref() may be used + to increase by one the reference counter of the event source object + specified as source. + + Both functions execute no operation if the passed event + source object is NULL. + + Note that event source objects stay alive and may be + dispatched as long as they have a reference counter greater than + zero. In order to drop a reference of an event source and make + sure the associated event source handler function is not called + anymore it is recommended to combine a call of + sd_event_source_unref() with a prior call to + sd_event_source_set_enabled() with + SD_EVENT_OFF. + + + + Return Value + + sd_event_source_unref() always returns + NULL. + sd_event_source_ref() always returns the + event source object passed in. + + + + + + See Also + + + sd-event3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_child3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_source_set_enabled3 + + + + diff --git a/man/sd_event_wait.xml b/man/sd_event_wait.xml index 7ca50aedf9..1eefa80700 100644 --- a/man/sd_event_wait.xml +++ b/man/sd_event_wait.xml @@ -21,7 +21,7 @@ along with systemd; If not, see . --> - + sd_event_wait @@ -46,14 +46,32 @@ sd_event_wait sd_event_prepare sd_event_dispatch + sd_event_get_state + SD_EVENT_INITIAL + SD_EVENT_PREPARING + SD_EVENT_ARMED + SD_EVENT_PENDING + SD_EVENT_RUNNING + SD_EVENT_EXITING + SD_EVENT_FINISHED - Run parts of the libsystemd event loop + Low-level event loop operations #include <systemd/sd-event.h> + enum { + SD_EVENT_INITIAL, + SD_EVENT_PREPARING, + SD_EVENT_ARMED, + SD_EVENT_PENDING, + SD_EVENT_RUNNING, + SD_EVENT_EXITING, + SD_EVENT_FINISHED, +}; + int sd_event_prepare sd_event *event @@ -62,7 +80,7 @@ int sd_event_wait sd_event *event - uint64_t timeout + uint64_t usec @@ -70,66 +88,184 @@ sd_event *event + + int sd_event_get_state + sd_event *event + + Description - Functions described here form parts of an event loop. + The low-level sd_event_prepare(), + sd_event_wait() and + sd_event_dispatch() functions may be used to + execute specific phases of an event loop. See + sd_event_run3 + and + sd_event_loop3 + for higher-level functions that execute individual but complete + iterations of an event loop or run it continously. - sd_event_prepare checks for pending + 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. - + processed ("pending"), it returns a positive, non-zero value, and the caller + should process these events with + sd_event_dispatch(). - 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 initial state and sd_event_prepare - should be called again. + sd_event_dispatch() dispatches the + highest priority event source that has a pending event. On + success, sd_event_dispatch() returns either + zero, which indicates that no further event sources may be + dispatched and exiting of the event loop was requested via + sd_event_exit3; + or a positive non-zero value, which means that an event source was + dispatched and the loop returned to its initial state, and the + caller should initiate the next event loop iteration by invoking + sd_event_prepare() again. + + In case sd_event_prepare() returned + zero, sd_event_wait() should be called to + wait for further events or a timeout. If any events are ready to + be processed, it returns a positive, non-zero value, and the + events should be dispatched with + sd_event_dispatch(). Otherwise, the event + loop returned to its initial state and the next event loop + iteration should be initiated by invoking + sd_event_prepare() again. + + sd_event_get_state() may be used to + determine the state the event loop is currently in. It returns one + of the states described below. + + All four functions take, as the first argument, the event + loop object event that has been created + with sd_event_new(). The timeout for + sd_event_wait() is specified in + usec in milliseconds. (uint64_t) + -1 may be used to specify an infinite timeout. + + + + State Machine + + The event loop knows the following states, that may be + queried with sd_event_get_state(). + + + + SD_EVENT_INITIAL + + The initial state the event loop is in, + before each event loop iteration. Use + sd_event_prepare() to transition the + event loop into the SD_EVENT_ARMED or + SD_EVENT_PENDING states. + + + + SD_EVENT_PREPARING + + An event source is currently being prepared, + i.e. the preparation handler is currently being excuted, as + set with + sd_event_set_prepare3. This + state is only seen in the event source preparation handler + that is invoked from the + sd_event_prepare() call and is + immediately followed by SD_EVENT_ARMED or + SD_EVENT_PENDING. + + + + SD_EVENT_ARMED + + sd_event_prepare() has + been called and no event sources were ready to be + dispatched. Use sd_event_wait() to wait + for new events, and transition into + SD_EVENT_PENDING or back into + SD_EVENT_INITIAL. + + + + SD_EVENT_PENDING + + sd_event_prepare() or + sd_event_wait() have been called and + there were event sources with events pending. Use + sd_event_dispatch() to dispatch the + highest priority event source and transition back to + SD_EVENT_INITIAL, or + SD_EVENT_FINISHED. + + + + SD_EVENT_RUNNING + + A regular event source is currently being + dispatched. This state is only seen in the event source + handler that is invoked from the + sd_event_dispatch() call, and is + immediately followed by SD_EVENT_INITIAL + or SD_EVENT_FINISHED as soon the event + source handler returns. Note that during dispatching of exit + event sources the SD_EVENT_EXITING state + is seen instead. + + + + SD_EVENT_EXITING + + Similar to + SD_EVENT_RUNNING but is the state in + effect while dispatching exit event sources. It is followed by + SD_EVENT_INITIAL or + SD_EVENT_FINISHED as soon as the event + handler returns. + + + + SD_EVENT_FINISHED + + The event loop has exited. All exit event + sources have run. If the event loop is in this state it serves + no purpose anymore, and should be freed. + + + + + A simplified flow chart of the states and the calls to + transition between them is shown below. Note that + SD_EVENT_PREPARING, + SD_EVENT_RUNNING and + SD_EVENT_EXITING are not shown here. - ┌──────────┐ - │ initial ├──←←←←←←←←←←←←←←←←←←←─┐ - └───┬──────┘ ↑ - │ ↑ - sd_event_prepare ┌─────────┐ ↑ - ├ 0 →→→→→→→──┤ armed │ ↑ - 1 └───┬─────┘ ↑ - ↓ │ ↑ - ↓ sd_event_wait ↑ - ├───←←←←←←←─── 1 ┴─ 0 →→→→→→→─┘ - ┌───┴──────┐ ↑ - │ pending │ ↑ - └───┬──────┘ ↑ - │ ↑ - sd_event_dispatch ↑ - ↓ ↑ - ├ 1 ──────────→→→→→→→─────────┘ - 0 - ↓ - ┌───┴──────┐ - │ finished │ - └──────────┘ + INITIAL -<---<---<---<---<---<---<---<---<---<---<---<---\ + | | + | ^ + | | + v ret == 0 | + sd_event_prepare() >--->--->--->--->- ARMED | + | | ^ + | ret > 0 | | + | | | + v v ret == 0 | + PENDING <---<---<---<---<---< sd_event_wait() >--->--->--+ + | ret > 0 ^ + | | + | | + v | + sd_event_dispatch() >--->--->--->--->--->--->--->--->--->--->/ + | ret > 0 + | ret == 0 + | + v + FINISHED - - All three functions take, as the first argument, the event - loop object event that is created 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. @@ -137,13 +273,15 @@ 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 these functions, a - negative return value means the loop must be aborted. + of sd_event_prepare() and + sd_event_wait(), a positive, non-zero return + code indicates that events are ready to be processed and zero + indicates that no events are ready. In case of + sd_event_dispatch(), a positive, non-zero + return code indicates that the event loop returned to its initial + state and zero indicates the event loop has + exited. sd_event_get_state() returns a + positive or zero state on success. @@ -156,7 +294,7 @@ -EINVAL The event parameter is - NULL. + invalid or NULL. @@ -185,14 +323,7 @@ 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 @@ -200,13 +331,15 @@ 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. + sd_event_add_post3, + sd_event_run3, + sd_event_get_fd3, + sd_event_source_set_prepare3 diff --git a/man/sd_watchdog_enabled.xml b/man/sd_watchdog_enabled.xml index 144ab1db61..6e27528a71 100644 --- a/man/sd_watchdog_enabled.xml +++ b/man/sd_watchdog_enabled.xml @@ -98,6 +98,11 @@ WatchdogSec= in service files. See systemd.service5 for details. + + Use + sd_event_set_watchdog3 + to enable automatic watchdog support in + sd-event3-based event loops. @@ -168,7 +173,8 @@ sd-daemon3, daemon7, systemd.service5, - sd_notify3 + sd_notify3, + sd_event_set_watchdog3 diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 20a71afe59..596bbcda36 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -678,8 +678,10 @@ SIGPIPE. Exit status definitions can either be numeric exit codes or termination signal names, separated by spaces. For example: - SuccessExitStatus=1 2 8 - SIGKILL ensures that exit codes 1, 2, 8 and + + SuccessExitStatus=1 2 8 SIGKILL + + ensures that exit codes 1, 2, 8 and the termination signal SIGKILL are considered clean service terminations. @@ -711,14 +713,16 @@ signal names, and are separated by spaces. Defaults to the empty list, so that, by default, no exit status is excluded from the configured restart logic. For example: - RestartPreventExitStatus=1 6 - SIGABRT ensures that exit codes 1 and 6 and - the termination signal SIGABRT will not - result in automatic service restarting. This option may appear - more than once, in which case the list of restart-preventing - statuses is merged. If the empty string is assigned to this - option, the list is reset and all prior assignments of this - option will have no effect. + + RestartPreventExitStatus=1 6 SIGABRT + + ensures that exit codes 1 and 6 and the termination signal + SIGABRT will not result in automatic + service restarting. This option may appear more than once, in + which case the list of restart-preventing statuses is + merged. If the empty string is assigned to this option, the + list is reset and all prior assignments of this option will + have no effect.