2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 SPDX-License-Identifier: LGPL-2.1+
9 <refentry id=
"sd_event_run" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
12 <title>sd_event_run
</title>
13 <productname>systemd
</productname>
17 <refentrytitle>sd_event_run
</refentrytitle>
18 <manvolnum>3</manvolnum>
22 <refname>sd_event_run
</refname>
23 <refname>sd_event_loop
</refname>
25 <refpurpose>Run an event loop
</refpurpose>
30 <funcsynopsisinfo>#include
<systemd/sd-event.h
></funcsynopsisinfo>
33 <funcdef>int
<function>sd_event_run
</function></funcdef>
34 <paramdef>sd_event *
<parameter>event
</parameter></paramdef>
35 <paramdef>uint64_t
<parameter>usec
</parameter></paramdef>
39 <funcdef>int
<function>sd_event_loop
</function></funcdef>
40 <paramdef>sd_event *
<parameter>event
</parameter></paramdef>
46 <title>Description
</title>
48 <para><function>sd_event_run()
</function> may be used to run a single
49 iteration of the event loop specified in the
50 <parameter>event
</parameter> parameter. The function waits until an event to
51 process is available, and dispatches the registered handler for
52 it. The
<parameter>usec
</parameter> parameter specifies the
53 maximum time (in microseconds) to wait for an event. Use
54 <constant>(uint64_t) -
1</constant> to specify an infinite
57 <para><function>sd_event_loop()
</function> invokes
58 <function>sd_event_run()
</function> in a loop, thus implementing
59 the actual event loop. The call returns as soon as exiting was
61 <citerefentry><refentrytitle>sd_event_exit
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
63 <para>The event loop object
<parameter>event
</parameter> is
65 <citerefentry><refentrytitle>sd_event_new
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
66 Events sources to wait for and their handlers may be registered
68 <citerefentry><refentrytitle>sd_event_add_io
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
69 <citerefentry><refentrytitle>sd_event_add_time
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
70 <citerefentry><refentrytitle>sd_event_add_signal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
71 <citerefentry><refentrytitle>sd_event_add_child
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
72 <citerefentry><refentrytitle>sd_event_add_defer
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
73 <citerefentry><refentrytitle>sd_event_add_post
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
75 <citerefentry><refentrytitle>sd_event_add_exit
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
78 <para>For low-level control of event loop execution, use
79 <citerefentry><refentrytitle>sd_event_prepare
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
80 <citerefentry><refentrytitle>sd_event_wait
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
82 <citerefentry><refentrytitle>sd_event_dispatch
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
83 which are wrapped by
<function>sd_event_run()
</function>. Along
85 <citerefentry><refentrytitle>sd_event_get_fd
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
86 these functions allow integration of an
87 <citerefentry><refentrytitle>sd-event
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
88 event loop into foreign event loop implementations.
</para>
92 <title>Return Value
</title>
94 <para>On failure, these functions return a negative errno-style
95 error code.
<function>sd_event_run()
</function> returns a
96 positive, non-zero integer if an event source was dispatched, and
97 zero when the specified timeout hit before an event source has
98 seen any event, and hence no event source was
99 dispatched.
<function>sd_event_loop()
</function> returns the exit
100 code specified when invoking
101 <function>sd_event_exit()
</function>.
</para>
105 <title>Errors
</title>
107 <para>Returned errors may indicate the following problems:
</para>
111 <term><constant>-EINVAL
</constant></term>
113 <listitem><para>The
<parameter>event
</parameter> parameter is
114 invalid or
<constant>NULL
</constant>.
</para></listitem>
118 <term><constant>-EBUSY
</constant></term>
120 <listitem><para>The event loop object is not in the right
122 <citerefentry><refentrytitle>sd_event_prepare
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
123 for an explanation of possible states).
</para></listitem>
127 <term><constant>-ESTALE
</constant></term>
129 <listitem><para>The event loop is already terminated.
</para></listitem>
134 <term><constant>-ECHILD
</constant></term>
136 <listitem><para>The event loop has been created in a different process.
</para></listitem>
142 <para>Other errors are possible, too.
</para>
145 <xi:include href=
"libsystemd-pkgconfig.xml" />
148 <title>See Also
</title>
151 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
152 <citerefentry><refentrytitle>sd-event
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
153 <citerefentry><refentrytitle>sd_event_new
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
154 <citerefentry><refentrytitle>sd_event_add_io
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
155 <citerefentry><refentrytitle>sd_event_add_time
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
156 <citerefentry><refentrytitle>sd_event_add_signal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
157 <citerefentry><refentrytitle>sd_event_add_child
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
158 <citerefentry><refentrytitle>sd_event_add_inotify
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
159 <citerefentry><refentrytitle>sd_event_add_defer
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
160 <citerefentry><refentrytitle>sd_event_exit
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
161 <citerefentry><refentrytitle>sd_event_get_fd
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
162 <citerefentry><refentrytitle>sd_event_wait
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
163 <ulink url=
"https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html">GLib Main Event Loop
</ulink>