From dc83f27a7cf03757dec11a69ec18504ad4ea8f89 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Thu, 19 Nov 2015 23:38:54 +0100 Subject: man: fully document sd-event interfaces This completes the set of man pages for sd-event and contains some minor other fixes for other man pages too. The sd_event_set_name(3) man page is renamed to sd_event_source_set_description(3), which is the correct name of the concept today. --- man/sd_event_run.xml | 95 ++++++++++++++++++++++++++++------------------------ 1 file changed, 51 insertions(+), 44 deletions(-) (limited to 'man/sd_event_run.xml') 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_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_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() 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. -- cgit v1.2.3-54-g00ecf