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" conditional="ENABLE_KDBUS">
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 libsystemd 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>timeout</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> can be used to run one
73 iteration of the event loop of libsystemd. This function waits
74 until an event to process is available and dispatches a handler
75 for it. Parameter <parameter>timeout</parameter> specifices the
76 maximum time (in microseconds) to wait. <constant>(uint64_t)
77 -1</constant> may be used to specify an infinite timeout.</para>
79 <para><function>sd_event_loop</function> runs
80 <function>sd_event_wait</function> in a loop with a timeout of
81 infinity. This makes it suitable for the main event loop of a
84 <para>The event loop object <parameter>event</parameter> is
86 <function>sd_event_new</function>.
87 Events to wait for and their handlers can be registered with
88 <function>sd_event_add_time</function>,
89 <function>sd_event_add_child</function>,
90 <function>sd_event_add_signal</function>,
91 <function>sd_event_add_defer</function>,
92 <function>sd_event_add_exit</function>,
94 <function>sd_event_add_post</function>.
97 <para>For more fine-grained control,
98 <function>sd_event_prepare</function>,
99 <function>sd_event_wait</function>, and
100 <function>sd_event_dispatch</function> may be used. Along with
101 <function>sd_event_get_fd</function>, those functions make it
102 possible to integrate the libsystemd loop inside of another event
107 <title>Return Value</title>
109 <para>On success, these functions return 0 or a positive integer.
110 On failure, they return a negative errno-style error code.
111 <function>sd_event_run</function> returns 0 if the event loop is
112 finished, and a positive value if it can be continued.</para>
116 <title>Errors</title>
118 <para>Returned errors may indicate the following problems:</para>
122 <term><constant>-EINVAL</constant></term>
124 <listitem><para>Parameter <parameter>event</parameter> is
125 <constant>NULL</constant>.</para></listitem>
129 <term><constant>-EBUSY</constant></term>
131 <listitem><para>The event loop object is not in the right
133 <citerefentry><refentrytitle>sd_event_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>
134 for an explanation of possible states).</para></listitem>
138 <term><constant>-ESTALE</constant></term>
140 <listitem><para>The event loop is already terminated.</para></listitem>
145 <term><constant>-ECHILD</constant></term>
147 <listitem><para>The event loop has been created in a different process.</para></listitem>
153 <para>Other errors are possible too.</para>
159 <para><function>sd_event_run()</function> and
160 <function>sd_event_loop()</function> are available
161 as a shared library, which can be compiled and linked to with the
162 <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
167 <title>See Also</title>
170 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
171 <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
172 <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
173 <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
174 <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
175 <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
176 <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
177 <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
178 <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>.