1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
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+
8 This file is part of systemd.
10 Copyright 2015 Zbigniew Jędrzejewski-Szmek
13 <refentry id="sd_event_run" xmlns:xi="http://www.w3.org/2001/XInclude">
16 <title>sd_event_run</title>
17 <productname>systemd</productname>
21 <contrib>Developer</contrib>
22 <firstname>Tom</firstname>
23 <surname>Gundersen</surname>
24 <email>teg@jklm.no</email>
30 <refentrytitle>sd_event_run</refentrytitle>
31 <manvolnum>3</manvolnum>
35 <refname>sd_event_run</refname>
36 <refname>sd_event_loop</refname>
38 <refpurpose>Run an event loop</refpurpose>
43 <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo>
46 <funcdef>int <function>sd_event_run</function></funcdef>
47 <paramdef>sd_event *<parameter>event</parameter></paramdef>
48 <paramdef>uint64_t <parameter>usec</parameter></paramdef>
52 <funcdef>int <function>sd_event_loop</function></funcdef>
53 <paramdef>sd_event *<parameter>event</parameter></paramdef>
59 <title>Description</title>
61 <para><function>sd_event_run()</function> may be used to run a single
62 iteration of the event loop specified in the
63 <parameter>event</parameter> parameter. The function waits until an event to
64 process is available, and dispatches the registered handler for
65 it. The <parameter>usec</parameter> parameter specifies the
66 maximum time (in microseconds) to wait for an event. Use
67 <constant>(uint64_t) -1</constant> to specify an infinite
70 <para><function>sd_event_loop()</function> invokes
71 <function>sd_event_run()</function> in a loop, thus implementing
72 the actual event loop. The call returns as soon as exiting was
74 <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
76 <para>The event loop object <parameter>event</parameter> is
78 <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
79 Events sources to wait for and their handlers may be registered
81 <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
82 <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
83 <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
84 <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
85 <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
86 <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>
88 <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
91 <para>For low-level control of event loop execution, use
92 <citerefentry><refentrytitle>sd_event_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
93 <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>
95 <citerefentry><refentrytitle>sd_event_dispatch</refentrytitle><manvolnum>3</manvolnum></citerefentry>
96 which are wrapped by <function>sd_event_run()</function>. Along
98 <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
99 these functions allow integration of an
100 <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>
101 event loop into foreign event loop implementations.</para>
105 <title>Return Value</title>
107 <para>On failure, these functions return a negative errno-style
108 error code. <function>sd_event_run()</function> returns a
109 positive, non-zero integer if an event source was dispatched, and
110 zero when the specified timeout hit before an event source has
111 seen any event, and hence no event source was
112 dispatched. <function>sd_event_loop()</function> returns the exit
113 code specified when invoking
114 <function>sd_event_exit()</function>.</para>
118 <title>Errors</title>
120 <para>Returned errors may indicate the following problems:</para>
124 <term><constant>-EINVAL</constant></term>
126 <listitem><para>The <parameter>event</parameter> parameter is
127 invalid or <constant>NULL</constant>.</para></listitem>
131 <term><constant>-EBUSY</constant></term>
133 <listitem><para>The event loop object is not in the right
135 <citerefentry><refentrytitle>sd_event_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>
136 for an explanation of possible states).</para></listitem>
140 <term><constant>-ESTALE</constant></term>
142 <listitem><para>The event loop is already terminated.</para></listitem>
147 <term><constant>-ECHILD</constant></term>
149 <listitem><para>The event loop has been created in a different process.</para></listitem>
155 <para>Other errors are possible, too.</para>
158 <xi:include href="libelogind-pkgconfig.xml" />
161 <title>See Also</title>
164 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
165 <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
166 <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
167 <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
168 <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
169 <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
170 <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
171 <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
172 <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
173 <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
174 <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
175 <ulink url="https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html">GLib Main Event Loop</ulink>.