HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |SYNOPSIS |DESCRIPTION |STATE MACHINE |RETURN VALUE |NOTES |HISTORY |SEE ALSO |COLOPHON | |
SD_EVENT_WAIT(3) sd_event_waitSD_EVENT_WAIT(3)sd_event_wait, sd_event_prepare, sd_event_dispatch, sd_event_get_state, sd_event_get_iteration, SD_EVENT_INITIAL, SD_EVENT_PREPARING, SD_EVENT_ARMED, SD_EVENT_PENDING, SD_EVENT_RUNNING, SD_EVENT_EXITING, SD_EVENT_FINISHED - 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);int sd_event_wait(sd_event *event, uint64_tusec);int sd_event_dispatch(sd_event *event);int sd_event_get_state(sd_event *event);int sd_event_get_iteration(sd_event *event, uint64_t *ret); The low-levelsd_event_prepare(),sd_event_wait()andsd_event_dispatch()functions may be used to execute specific phases of an event loop. Seesd_event_run(3) andsd_event_loop(3) for higher-level functions that execute individual but complete iterations of an event loop or run it continuously.sd_event_prepare()checks for pending events and arms necessary timers. If any events are ready to be processed ("pending"), it returns a positive, non-zero value, and the caller should process these events withsd_event_dispatch().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 viasd_event_exit(3); 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 invokingsd_event_prepare()again. In casesd_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 withsd_event_dispatch(). Otherwise, the event loop returned to its initial state and the next event loop iteration should be initiated by invokingsd_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.sd_event_get_iteration()may be used to determine the current iteration of the event loop. It returns an unsigned 64-bit integer containing a counter that increases monotonically with each iteration of the event loop, starting with 0. The counter is increased at the time of thesd_event_prepare()invocation. All five functions take, as the first argument, the event loop objectevent that has been created withsd_event_new(). The timeout forsd_event_wait()is specified inusec in microseconds.(uint64_t) -1may be used to specify an infinite timeout.The event loop knows the following states, that may be queried withsd_event_get_state().SD_EVENT_INITIAL The initial state the event loop is in, before each event loop iteration. Usesd_event_prepare()to transition the event loop into theSD_EVENT_ARMEDorSD_EVENT_PENDINGstates. Added in version 229.SD_EVENT_PREPARING An event source is currently being prepared, i.e. the preparation handler is currently being executed, as set withsd_event_source_set_prepare(3). This state is only seen in the event source preparation handler that is invoked from thesd_event_prepare()call and is immediately followed bySD_EVENT_ARMEDorSD_EVENT_PENDING. Added in version 229.SD_EVENT_ARMEDsd_event_prepare()has been called and no event sources were ready to be dispatched. Usesd_event_wait()to wait for new events, and transition intoSD_EVENT_PENDINGor back intoSD_EVENT_INITIAL. Added in version 229.SD_EVENT_PENDINGsd_event_prepare()orsd_event_wait()have been called and there were event sources with events pending. Usesd_event_dispatch()to dispatch the highest priority event source and transition back toSD_EVENT_INITIAL, orSD_EVENT_FINISHED. Added in version 229.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 thesd_event_dispatch()call, and is immediately followed bySD_EVENT_INITIALorSD_EVENT_FINISHEDas soon the event source handler returns. Note that during dispatching of exit event sources theSD_EVENT_EXITINGstate is seen instead. Added in version 229.SD_EVENT_EXITING Similar toSD_EVENT_RUNNINGbut is the state in effect while dispatching exit event sources. It is followed bySD_EVENT_INITIALorSD_EVENT_FINISHEDas soon as the event handler returns. Added in version 229.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. Added in version 229. A simplified flow chart of the states and the calls to transition between them is shown below. Note thatSD_EVENT_PREPARING,SD_EVENT_RUNNINGandSD_EVENT_EXITINGare not shown here. 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
On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error code. In case ofsd_event_prepare()andsd_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 ofsd_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.Errors Returned errors may indicate the following problems:-EINVAL Theevent parameter is invalid orNULL.-EBUSY The event loop object is not in the right state.-ESTALE The event loop is already terminated.-ECHILD The event loop has been created in a different process, library or module instance. Other errors are possible, too.
Functions described here are available as a shared library, which can be compiled against and linked to with thelibsystemd pkg-config(1) file. The code described here usesgetenv(3), which is declared to be not multi-thread-safe. This means that the code calling the functions described here must not callsetenv(3) from a parallel thread. It is recommended to only do calls tosetenv()from an early phase of the program when no other threads have been started.
sd_event_prepare(),sd_event_wait(),sd_event_dispatch(), andsd_event_get_state()were added in version 221.sd_event_get_iteration()was added in version 231.
systemd(1),sd_event_new(3),sd_event_add_io(3),sd_event_add_time(3),sd_event_add_signal(3),sd_event_add_child(3),sd_event_add_inotify(3),sd_event_add_defer(3),sd_event_run(3),sd_event_get_fd(3),sd_event_source_set_prepare(3)
This page is part of thesystemd (systemd system and service manager) project. Information about the project can be found at ⟨http://www.freedesktop.org/wiki/Software/systemd⟩. If you have a bug report for this manual page, see ⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩. This page was obtained from the project's upstream Git repository ⟨https://github.com/systemd/systemd.git⟩ on 2025-08-11. (At that time, the date of the most recent commit that was found in the repository was 2025-08-11.) If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up-to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgsystemd 258~rc2SD_EVENT_WAIT(3)Pages that refer to this page:sd-event(3), sd_event_get_fd(3), sd_event_run(3), systemd.directives(7), systemd.index(7)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |