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 This file is part of systemd.
8 Copyright 2015 Zbigniew Jędrzejewski-Szmek
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
24 <refentry id="sd_event_run" xmlns:xi="http://www.w3.org/2001/XInclude">
27 <title>sd_event_run</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Tom</firstname>
34 <surname>Gundersen</surname>
35 <email>teg@jklm.no</email>
41 <refentrytitle>sd_event_run</refentrytitle>
42 <manvolnum>3</manvolnum>
46 <refname>sd_event_run</refname>
47 <refname>sd_event_loop</refname>
49 <refpurpose>Run an event loop</refpurpose>
54 <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo>
57 <funcdef>int <function>sd_event_run</function></funcdef>
58 <paramdef>sd_event *<parameter>event</parameter></paramdef>
59 <paramdef>uint64_t <parameter>usec</parameter></paramdef>
63 <funcdef>int <function>sd_event_loop</function></funcdef>
64 <paramdef>sd_event *<parameter>event</parameter></paramdef>
70 <title>Description</title>
72 <para><function>sd_event_run()</function> may be used to run a single
73 iteration of the event loop specified in the
74 <parameter>event</parameter> parameter. The function waits until an event to
75 process is available, and dispatches the registered handler for
76 it. The <parameter>usec</parameter> parameter specifies the
77 maximum time (in microseconds) to wait for an event. Use
78 <constant>(uint64_t) -1</constant> to specify an infinite
81 <para><function>sd_event_loop()</function> invokes
82 <function>sd_event_run()</function> in a loop, thus implementing
83 the actual event loop. The call returns as soon as exiting was
85 <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
87 <para>The event loop object <parameter>event</parameter> is
89 <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
90 Events sources to wait for and their handlers may be registered
92 <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
93 <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
94 <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
95 <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
96 <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
97 <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>
99 <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
102 <para>For low-level control of event loop execution, use
103 <citerefentry><refentrytitle>sd_event_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
104 <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>
106 <citerefentry><refentrytitle>sd_event_dispatch</refentrytitle><manvolnum>3</manvolnum></citerefentry>
107 which are wrapped by <function>sd_event_run()</function>. Along
109 <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
110 these functions allow integration of an
111 <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>
112 event loop into foreign event loop implementations.</para>
116 <title>Return Value</title>
118 <para>On failure, these functions return a negative errno-style
119 error code. <function>sd_event_run()</function> returns a
120 positive, non-zero integer if an event source was dispatched, and
121 zero when the specified timeout hit before an event source has
122 seen any event, and hence no event source was
123 dispatched. <function>sd_event_loop()</function> returns the exit
124 code specified when invoking
125 <function>sd_event_exit()</function>.</para>
129 <title>Errors</title>
131 <para>Returned errors may indicate the following problems:</para>
135 <term><constant>-EINVAL</constant></term>
137 <listitem><para>The <parameter>event</parameter> parameter is
138 invalid or <constant>NULL</constant>.</para></listitem>
142 <term><constant>-EBUSY</constant></term>
144 <listitem><para>The event loop object is not in the right
146 <citerefentry><refentrytitle>sd_event_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>
147 for an explanation of possible states).</para></listitem>
151 <term><constant>-ESTALE</constant></term>
153 <listitem><para>The event loop is already terminated.</para></listitem>
158 <term><constant>-ECHILD</constant></term>
160 <listitem><para>The event loop has been created in a different process.</para></listitem>
166 <para>Other errors are possible, too.</para>
169 <xi:include href="libelogind-pkgconfig.xml" />
172 <title>See Also</title>
175 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
176 <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
177 <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
178 <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
179 <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
180 <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
181 <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
182 <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
183 <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
184 <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
185 <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
186 <ulink url="https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html">GLib Main Event Loop</ulink>.