[thirdparty/systemd.git] / man / sd_event_wait.xml

<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1+ -->

<refentry id="sd_event_wait" xmlns:xi="http://www.w3.org/2001/XInclude">

  <refentryinfo>
    <title>sd_event_wait</title>
    <productname>systemd</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>sd_event_wait</refentrytitle>
    <manvolnum>3</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>sd_event_wait</refname>
    <refname>sd_event_prepare</refname>
    <refname>sd_event_dispatch</refname>
    <refname>sd_event_get_state</refname>
    <refname>sd_event_get_iteration</refname>
    <refname>SD_EVENT_INITIAL</refname>
    <refname>SD_EVENT_PREPARING</refname>
    <refname>SD_EVENT_ARMED</refname>
    <refname>SD_EVENT_PENDING</refname>
    <refname>SD_EVENT_RUNNING</refname>
    <refname>SD_EVENT_EXITING</refname>
    <refname>SD_EVENT_FINISHED</refname>

    <refpurpose>Low-level event loop operations</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>

      <funcsynopsisinfo><token>enum</token> {
        <constant>SD_EVENT_INITIAL</constant>,
        <constant>SD_EVENT_PREPARING</constant>,
        <constant>SD_EVENT_ARMED</constant>,
        <constant>SD_EVENT_PENDING</constant>,
        <constant>SD_EVENT_RUNNING</constant>,
        <constant>SD_EVENT_EXITING</constant>,
        <constant>SD_EVENT_FINISHED</constant>,
};</funcsynopsisinfo>

      <funcprototype>
        <funcdef>int <function>sd_event_prepare</function></funcdef>
        <paramdef>sd_event *<parameter>event</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>int <function>sd_event_wait</function></funcdef>
        <paramdef>sd_event *<parameter>event</parameter></paramdef>
        <paramdef>uint64_t <parameter>usec</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>int <function>sd_event_dispatch</function></funcdef>
        <paramdef>sd_event *<parameter>event</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>int <function>sd_event_get_state</function></funcdef>
        <paramdef>sd_event *<parameter>event</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>int <function>sd_event_get_iteration</function></funcdef>
        <paramdef>sd_event *<parameter>event</parameter></paramdef>
        <paramdef>uint64_t *<parameter>ret</parameter></paramdef>
      </funcprototype>

    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para>The low-level <function>sd_event_prepare()</function>,
    <function>sd_event_wait()</function> and
    <function>sd_event_dispatch()</function> functions may be used to
    execute specific phases of an event loop. See
    <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>
    and
    <citerefentry><refentrytitle>sd_event_loop</refentrytitle><manvolnum>3</manvolnum></citerefentry>
    for higher-level functions that execute individual but complete
    iterations of an event loop or run it continuously.</para>

    <para><function>sd_event_prepare()</function> 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 with
    <function>sd_event_dispatch()</function>.</para>

    <para><function>sd_event_dispatch()</function> dispatches the
    highest priority event source that has a pending event. On
    success, <function>sd_event_dispatch()</function> returns either
    zero, which indicates that no further event sources may be
    dispatched and exiting of the event loop was requested via
    <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>;
    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
    <function>sd_event_prepare()</function> again.</para>

    <para>In case <function>sd_event_prepare()</function> returned
    zero, <function>sd_event_wait()</function> 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
    <function>sd_event_dispatch()</function>. Otherwise, the event
    loop returned to its initial state and the next event loop
    iteration should be initiated by invoking
    <function>sd_event_prepare()</function> again.</para>

    <para><function>sd_event_get_state()</function> may be used to
    determine the state the event loop is currently in. It returns one
    of the states described below.</para>

    <para><function>sd_event_get_iteration()</function> may be used to determine the current iteration of the event
    loop. It returns an unsigned 64bit 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 the
    <function>sd_event_prepare()</function> invocation.</para>

    <para>All five functions take, as the first argument, the event loop object <parameter>event</parameter> that has
    been created with <function>sd_event_new()</function>. The timeout for <function>sd_event_wait()</function> is
    specified in <parameter>usec</parameter> in microseconds.  <constant>(uint64_t) -1</constant> may be used to
    specify an infinite timeout.</para>
</refsect1>

  <refsect1>
    <title>State Machine</title>

    <para>The event loop knows the following states, that may be
    queried with <function>sd_event_get_state()</function>.</para>

    <variablelist>
      <varlistentry>
        <term><constant>SD_EVENT_INITIAL</constant></term>

        <listitem><para>The initial state the event loop is in,
        before each event loop iteration. Use
        <function>sd_event_prepare()</function> to transition the
        event loop into the <constant>SD_EVENT_ARMED</constant> or
        <constant>SD_EVENT_PENDING</constant> states.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><constant>SD_EVENT_PREPARING</constant></term>

        <listitem><para>An event source is currently being prepared,
        i.e. the preparation handler is currently being executed, as
        set with
        <citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This
        state is only seen in the event source preparation handler
        that is invoked from the
        <function>sd_event_prepare()</function> call and is
        immediately followed by <constant>SD_EVENT_ARMED</constant> or
        <constant>SD_EVENT_PENDING</constant>.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><constant>SD_EVENT_ARMED</constant></term>

        <listitem><para><function>sd_event_prepare()</function> has
        been called and no event sources were ready to be
        dispatched. Use <function>sd_event_wait()</function> to wait
        for new events, and transition into
        <constant>SD_EVENT_PENDING</constant> or back into
        <constant>SD_EVENT_INITIAL</constant>.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><constant>SD_EVENT_PENDING</constant></term>

        <listitem><para><function>sd_event_prepare()</function> or
        <function>sd_event_wait()</function> have been called and
        there were event sources with events pending. Use
        <function>sd_event_dispatch()</function> to dispatch the
        highest priority event source and transition back to
        <constant>SD_EVENT_INITIAL</constant>, or
        <constant>SD_EVENT_FINISHED</constant>.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><constant>SD_EVENT_RUNNING</constant></term>

        <listitem><para>A regular event source is currently being
        dispatched. This state is only seen in the event source
        handler that is invoked from the
        <function>sd_event_dispatch()</function> call, and is
        immediately followed by <constant>SD_EVENT_INITIAL</constant>
        or <constant>SD_EVENT_FINISHED</constant> as soon the event
        source handler returns. Note that during dispatching of exit
        event sources the <constant>SD_EVENT_EXITING</constant> state
        is seen instead.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><constant>SD_EVENT_EXITING</constant></term>

        <listitem><para>Similar to
        <constant>SD_EVENT_RUNNING</constant> but is the state in
        effect while dispatching exit event sources. It is followed by
        <constant>SD_EVENT_INITIAL</constant> or
        <constant>SD_EVENT_FINISHED</constant> as soon as the event
        handler returns.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><constant>SD_EVENT_FINISHED</constant></term>

        <listitem><para>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.</para></listitem>
      </varlistentry>

    </variablelist>

    <para>A simplified flow chart of the states and the calls to
    transition between them is shown below. Note that
    <constant>SD_EVENT_PREPARING</constant>,
    <constant>SD_EVENT_RUNNING</constant> and
    <constant>SD_EVENT_EXITING</constant> are not shown here.</para>

    <programlisting>
          INITIAL -&lt;---&lt;---&lt;---&lt;---&lt;---&lt;---&lt;---&lt;---&lt;---&lt;---&lt;---&lt;---\
             |                                                     |
             |                                                     ^
             |                                                     |
             v                 ret == 0                            |
      sd_event_prepare() &gt;---&gt;---&gt;---&gt;---&gt;- ARMED                  |
             |                                |                    ^
             | ret > 0                        |                    |
             |                                |                    |
             v                                v          ret == 0  |
          PENDING &lt;---&lt;---&lt;---&lt;---&lt;---&lt; sd_event_wait() &gt;---&gt;---&gt;--+
             |           ret > 0                                   ^
             |                                                     |
             |                                                     |
             v                                                     |
      sd_event_dispatch() &gt;---&gt;---&gt;---&gt;---&gt;---&gt;---&gt;---&gt;---&gt;---&gt;---&gt;/
             |                             ret > 0
             | ret == 0
             |
             v
          FINISHED
    </programlisting>
  </refsect1>

  <refsect1>
    <title>Return Value</title>

    <para>On success, these functions return 0 or a positive integer.
    On failure, they return a negative errno-style error code. In case
    of <function>sd_event_prepare()</function> and
    <function>sd_event_wait()</function>, 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
    <function>sd_event_dispatch()</function>, a positive, non-zero
    return code indicates that the event loop returned to its initial
    state and zero indicates the event loop has
    exited. <function>sd_event_get_state()</function> returns a
    positive or zero state on success.</para>
  </refsect1>

  <refsect1>
    <title>Errors</title>

    <para>Returned errors may indicate the following problems:</para>

    <variablelist>
      <varlistentry>
        <term><constant>-EINVAL</constant></term>

        <listitem><para>The <parameter>event</parameter> parameter is
        invalid or <constant>NULL</constant>.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><constant>-EBUSY</constant></term>

        <listitem><para>The event loop object is not in the right
        state.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><constant>-ESTALE</constant></term>

        <listitem><para>The event loop is already terminated.</para></listitem>

      </varlistentry>

      <varlistentry>
        <term><constant>-ECHILD</constant></term>

        <listitem><para>The event loop has been created in a different process.</para></listitem>

      </varlistentry>

    </variablelist>

    <para>Other errors are possible, too.</para>
  </refsect1>

  <xi:include href="libsystemd-pkgconfig.xml" />

  <refsect1>
    <title>See Also</title>

    <para>
      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>
    </para>
  </refsect1>

</refentry>
Commit	Line	Data
514094f9	1	<?xml version='1.0'?>
3a54a157 ZJS	2	<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3a54a157 ZJS	3	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
0307f791	4	<!-- SPDX-License-Identifier: LGPL-2.1+ -->
42f1ab50	5
dc83f27a	6	<refentry id="sd_event_wait" xmlns:xi="http://www.w3.org/2001/XInclude">
42f1ab50 ZJS	7
	8	<refentryinfo>
	9	<title>sd_event_wait</title>
	10	<productname>systemd</productname>
42f1ab50 ZJS	11	</refentryinfo>
	12
	13	<refmeta>
	14	<refentrytitle>sd_event_wait</refentrytitle>
	15	<manvolnum>3</manvolnum>
	16	</refmeta>
	17
	18	<refnamediv>
	19	<refname>sd_event_wait</refname>
	20	<refname>sd_event_prepare</refname>
	21	<refname>sd_event_dispatch</refname>
dc83f27a	22	<refname>sd_event_get_state</refname>
60a3b1e1	23	<refname>sd_event_get_iteration</refname>
dc83f27a LP	24	<refname>SD_EVENT_INITIAL</refname>
	25	<refname>SD_EVENT_PREPARING</refname>
	26	<refname>SD_EVENT_ARMED</refname>
	27	<refname>SD_EVENT_PENDING</refname>
	28	<refname>SD_EVENT_RUNNING</refname>
	29	<refname>SD_EVENT_EXITING</refname>
	30	<refname>SD_EVENT_FINISHED</refname>
	31
	32	<refpurpose>Low-level event loop operations</refpurpose>
42f1ab50 ZJS	33	</refnamediv>
	34
	35	<refsynopsisdiv>
	36	<funcsynopsis>
	37	<funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo>
	38
dc83f27a LP	39	<funcsynopsisinfo><token>enum</token> {
	40	<constant>SD_EVENT_INITIAL</constant>,
	41	<constant>SD_EVENT_PREPARING</constant>,
	42	<constant>SD_EVENT_ARMED</constant>,
	43	<constant>SD_EVENT_PENDING</constant>,
	44	<constant>SD_EVENT_RUNNING</constant>,
	45	<constant>SD_EVENT_EXITING</constant>,
	46	<constant>SD_EVENT_FINISHED</constant>,
	47	};</funcsynopsisinfo>
	48
42f1ab50 ZJS	49	<funcprototype>
	50	<funcdef>int <function>sd_event_prepare</function></funcdef>
	51	<paramdef>sd_event *<parameter>event</parameter></paramdef>
	52	</funcprototype>
	53
	54	<funcprototype>
	55	<funcdef>int <function>sd_event_wait</function></funcdef>
	56	<paramdef>sd_event *<parameter>event</parameter></paramdef>
dc83f27a	57	<paramdef>uint64_t <parameter>usec</parameter></paramdef>
42f1ab50 ZJS	58	</funcprototype>
	59
	60	<funcprototype>
	61	<funcdef>int <function>sd_event_dispatch</function></funcdef>
	62	<paramdef>sd_event *<parameter>event</parameter></paramdef>
	63	</funcprototype>
	64
dc83f27a LP	65	<funcprototype>
	66	<funcdef>int <function>sd_event_get_state</function></funcdef>
	67	<paramdef>sd_event *<parameter>event</parameter></paramdef>
	68	</funcprototype>
	69
60a3b1e1 LP	70	<funcprototype>
	71	<funcdef>int <function>sd_event_get_iteration</function></funcdef>
	72	<paramdef>sd_event *<parameter>event</parameter></paramdef>
	73	<paramdef>uint64_t *<parameter>ret</parameter></paramdef>
	74	</funcprototype>
	75
42f1ab50 ZJS	76	</funcsynopsis>
	77	</refsynopsisdiv>
	78
	79	<refsect1>
	80	<title>Description</title>
	81
dc83f27a LP	82	<para>The low-level <function>sd_event_prepare()</function>,
	83	<function>sd_event_wait()</function> and
	84	<function>sd_event_dispatch()</function> functions may be used to
	85	execute specific phases of an event loop. See
	86	<citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>
	87	and
	88	<citerefentry><refentrytitle>sd_event_loop</refentrytitle><manvolnum>3</manvolnum></citerefentry>
	89	for higher-level functions that execute individual but complete
7f3fdb7f	90	iterations of an event loop or run it continuously.</para>
dc83f27a LP	91
dc83f27a LP	92	<para><function>sd_event_prepare()</function> checks for pending
42f1ab50	93	events and arms necessary timers. If any events are ready to be
dc83f27a LP	94	processed ("pending"), it returns a positive, non-zero value, and the caller
	95	should process these events with
	96	<function>sd_event_dispatch()</function>.</para>
	97
	98	<para><function>sd_event_dispatch()</function> dispatches the
	99	highest priority event source that has a pending event. On
	100	success, <function>sd_event_dispatch()</function> returns either
	101	zero, which indicates that no further event sources may be
	102	dispatched and exiting of the event loop was requested via
	103	<citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>;
	104	or a positive non-zero value, which means that an event source was
	105	dispatched and the loop returned to its initial state, and the
	106	caller should initiate the next event loop iteration by invoking
	107	<function>sd_event_prepare()</function> again.</para>
	108
	109	<para>In case <function>sd_event_prepare()</function> returned
	110	zero, <function>sd_event_wait()</function> should be called to
	111	wait for further events or a timeout. If any events are ready to
	112	be processed, it returns a positive, non-zero value, and the
	113	events should be dispatched with
	114	<function>sd_event_dispatch()</function>. Otherwise, the event
	115	loop returned to its initial state and the next event loop
	116	iteration should be initiated by invoking
	117	<function>sd_event_prepare()</function> again.</para>
	118
	119	<para><function>sd_event_get_state()</function> may be used to
	120	determine the state the event loop is currently in. It returns one
	121	of the states described below.</para>
	122
60a3b1e1 LP	123	<para><function>sd_event_get_iteration()</function> may be used to determine the current iteration of the event
	124	loop. It returns an unsigned 64bit integer containing a counter that increases monotonically with each iteration of
	125	the event loop, starting with 0. The counter is increased at the time of the
	126	<function>sd_event_prepare()</function> invocation.</para>
	127
	128	<para>All five functions take, as the first argument, the event loop object <parameter>event</parameter> that has
	129	been created with <function>sd_event_new()</function>. The timeout for <function>sd_event_wait()</function> is
	130	specified in <parameter>usec</parameter> in microseconds. <constant>(uint64_t) -1</constant> may be used to
	131	specify an infinite timeout.</para>
dc83f27a LP	132	</refsect1>
	133
	134	<refsect1>
	135	<title>State Machine</title>
	136
	137	<para>The event loop knows the following states, that may be
	138	queried with <function>sd_event_get_state()</function>.</para>
42f1ab50	139
dc83f27a LP	140	<variablelist>
	141	<varlistentry>
	142	<term><constant>SD_EVENT_INITIAL</constant></term>
	143
	144	<listitem><para>The initial state the event loop is in,
	145	before each event loop iteration. Use
	146	<function>sd_event_prepare()</function> to transition the
	147	event loop into the <constant>SD_EVENT_ARMED</constant> or
	148	<constant>SD_EVENT_PENDING</constant> states.</para></listitem>
	149	</varlistentry>
	150
	151	<varlistentry>
	152	<term><constant>SD_EVENT_PREPARING</constant></term>
	153
	154	<listitem><para>An event source is currently being prepared,
7f3fdb7f	155	i.e. the preparation handler is currently being executed, as
dc83f27a	156	set with
227bcd91	157	<citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This
dc83f27a LP	158	state is only seen in the event source preparation handler
	159	that is invoked from the
	160	<function>sd_event_prepare()</function> call and is
	161	immediately followed by <constant>SD_EVENT_ARMED</constant> or
	162	<constant>SD_EVENT_PENDING</constant>.</para></listitem>
	163	</varlistentry>
	164
	165	<varlistentry>
	166	<term><constant>SD_EVENT_ARMED</constant></term>
	167
	168	<listitem><para><function>sd_event_prepare()</function> has
	169	been called and no event sources were ready to be
	170	dispatched. Use <function>sd_event_wait()</function> to wait
	171	for new events, and transition into
	172	<constant>SD_EVENT_PENDING</constant> or back into
	173	<constant>SD_EVENT_INITIAL</constant>.</para></listitem>
	174	</varlistentry>
	175
	176	<varlistentry>
	177	<term><constant>SD_EVENT_PENDING</constant></term>
	178
	179	<listitem><para><function>sd_event_prepare()</function> or
	180	<function>sd_event_wait()</function> have been called and
	181	there were event sources with events pending. Use
	182	<function>sd_event_dispatch()</function> to dispatch the
	183	highest priority event source and transition back to
	184	<constant>SD_EVENT_INITIAL</constant>, or
	185	<constant>SD_EVENT_FINISHED</constant>.</para></listitem>
	186	</varlistentry>
	187
	188	<varlistentry>
	189	<term><constant>SD_EVENT_RUNNING</constant></term>
	190
	191	<listitem><para>A regular event source is currently being
	192	dispatched. This state is only seen in the event source
	193	handler that is invoked from the
	194	<function>sd_event_dispatch()</function> call, and is
	195	immediately followed by <constant>SD_EVENT_INITIAL</constant>
	196	or <constant>SD_EVENT_FINISHED</constant> as soon the event
	197	source handler returns. Note that during dispatching of exit
	198	event sources the <constant>SD_EVENT_EXITING</constant> state
	199	is seen instead.</para></listitem>
	200	</varlistentry>
	201
	202	<varlistentry>
	203	<term><constant>SD_EVENT_EXITING</constant></term>
	204
	205	<listitem><para>Similar to
	206	<constant>SD_EVENT_RUNNING</constant> but is the state in
	207	effect while dispatching exit event sources. It is followed by
	208	<constant>SD_EVENT_INITIAL</constant> or
	209	<constant>SD_EVENT_FINISHED</constant> as soon as the event
	210	handler returns.</para></listitem>
	211	</varlistentry>
	212
	213	<varlistentry>
	214	<term><constant>SD_EVENT_FINISHED</constant></term>
	215
	216	<listitem><para>The event loop has exited. All exit event
	217	sources have run. If the event loop is in this state it serves
	218	no purpose anymore, and should be freed.</para></listitem>
	219	</varlistentry>
	220
	221	</variablelist>
222
223	<para>A simplified flow chart of the states and the calls to
224	transition between them is shown below. Note that
225	<constant>SD_EVENT_PREPARING</constant>,
226	<constant>SD_EVENT_RUNNING</constant> and
227	<constant>SD_EVENT_EXITING</constant> are not shown here.</para>
42f1ab50 ZJS	228
42f1ab50 ZJS	229	<programlisting>
dc83f27a LP	230	INITIAL -<---<---<---<---<---<---<---<---<---<---<---<---\
	231	\| \|
	232	\| ^
	233	\| \|
	234	v ret == 0 \|
	235	sd_event_prepare() >--->--->--->--->- ARMED \|
	236	\| \| ^
	237	\| ret > 0 \| \|
	238	\| \| \|
	239	v v ret == 0 \|
	240	PENDING <---<---<---<---<---< sd_event_wait() >--->--->--+
	241	\| ret > 0 ^
	242	\| \|
	243	\| \|
	244	v \|
	245	sd_event_dispatch() >--->--->--->--->--->--->--->--->--->--->/
	246	\| ret > 0
	247	\| ret == 0
	248	\|
	249	v
	250	FINISHED
42f1ab50	251	</programlisting>
42f1ab50 ZJS	252	</refsect1>
	253
	254	<refsect1>
	255	<title>Return Value</title>
	256
	257	<para>On success, these functions return 0 or a positive integer.
	258	On failure, they return a negative errno-style error code. In case
dc83f27a LP	259	of <function>sd_event_prepare()</function> and
	260	<function>sd_event_wait()</function>, a positive, non-zero return
	261	code indicates that events are ready to be processed and zero
	262	indicates that no events are ready. In case of
	263	<function>sd_event_dispatch()</function>, a positive, non-zero
	264	return code indicates that the event loop returned to its initial
	265	state and zero indicates the event loop has
	266	exited. <function>sd_event_get_state()</function> returns a
	267	positive or zero state on success.</para>
42f1ab50 ZJS	268	</refsect1>
	269
	270	<refsect1>
	271	<title>Errors</title>
	272
	273	<para>Returned errors may indicate the following problems:</para>
	274
	275	<variablelist>
	276	<varlistentry>
	277	<term><constant>-EINVAL</constant></term>
	278
a8eaaee7	279	<listitem><para>The <parameter>event</parameter> parameter is
dc83f27a	280	invalid or <constant>NULL</constant>.</para></listitem>
42f1ab50 ZJS	281	</varlistentry>
	282
	283	<varlistentry>
	284	<term><constant>-EBUSY</constant></term>
	285
	286	<listitem><para>The event loop object is not in the right
	287	state.</para></listitem>
	288	</varlistentry>
	289
	290	<varlistentry>
	291	<term><constant>-ESTALE</constant></term>
	292
	293	<listitem><para>The event loop is already terminated.</para></listitem>
	294
	295	</varlistentry>
	296
	297	<varlistentry>
	298	<term><constant>-ECHILD</constant></term>
	299
	300	<listitem><para>The event loop has been created in a different process.</para></listitem>
	301
	302	</varlistentry>
	303
	304	</variablelist>
	305
b938cb90	306	<para>Other errors are possible, too.</para>
42f1ab50 ZJS	307	</refsect1>
42f1ab50 ZJS	308
dc83f27a	309	<xi:include href="libsystemd-pkgconfig.xml" />
42f1ab50 ZJS	310
	311	<refsect1>
	312	<title>See Also</title>
	313
	314	<para>
	315	<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
	316	<citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
42f1ab50 ZJS	317	<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
	318	<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
	319	<citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
8274a30d LP	320	<citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
8274a30d LP	321	<citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
42f1ab50	322	<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a LP	323	<citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
	324	<citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
	325	<citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>
42f1ab50 ZJS	326	</para>
	327	</refsect1>
	328
	329	</refentry>