2018-07-03 00:15:39 +03:00
<?xml version='1.0'?>
2019-03-14 16:40:58 +03:00
< !DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
2020-11-09 07:23:58 +03:00
<!-- SPDX - License - Identifier: LGPL - 2.1 - or - later -->
2015-03-14 04:35:32 +03:00
2015-11-20 01:38:54 +03:00
<refentry id= "sd_event_run" xmlns:xi= "http://www.w3.org/2001/XInclude" >
2015-03-14 04:35:32 +03:00
<refentryinfo >
<title > sd_event_run</title>
<productname > systemd</productname>
</refentryinfo>
<refmeta >
<refentrytitle > sd_event_run</refentrytitle>
<manvolnum > 3</manvolnum>
</refmeta>
<refnamediv >
<refname > sd_event_run</refname>
<refname > sd_event_loop</refname>
2015-11-20 01:38:54 +03:00
<refpurpose > Run an event loop</refpurpose>
2015-03-14 04:35:32 +03:00
</refnamediv>
<refsynopsisdiv >
<funcsynopsis >
<funcsynopsisinfo > #include < systemd/sd-event.h> </funcsynopsisinfo>
<funcprototype >
<funcdef > int <function > sd_event_run</function> </funcdef>
<paramdef > sd_event *<parameter > event</parameter> </paramdef>
2015-11-20 01:38:54 +03:00
<paramdef > uint64_t <parameter > usec</parameter> </paramdef>
2015-03-14 04:35:32 +03:00
</funcprototype>
<funcprototype >
<funcdef > int <function > sd_event_loop</function> </funcdef>
<paramdef > sd_event *<parameter > event</parameter> </paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 >
<title > Description</title>
2015-11-20 01:38:54 +03:00
<para > <function > sd_event_run()</function> may be used to run a single
iteration of the event loop specified in the
<parameter > event</parameter> parameter. The function waits until an event to
process is available, and dispatches the registered handler for
it. The <parameter > usec</parameter> parameter specifies the
maximum time (in microseconds) to wait for an event. Use
<constant > (uint64_t) -1</constant> to specify an infinite
timeout.</para>
<para > <function > sd_event_loop()</function> invokes
<function > sd_event_run()</function> in a loop, thus implementing
the actual event loop. The call returns as soon as exiting was
requested using
<citerefentry > <refentrytitle > sd_event_exit</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> .</para>
2015-03-14 04:35:32 +03:00
<para > The event loop object <parameter > event</parameter> is
created with
2015-11-20 01:38:54 +03:00
<citerefentry > <refentrytitle > sd_event_new</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> .
Events sources to wait for and their handlers may be registered
with
<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_defer</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > sd_event_add_post</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry>
2015-03-14 04:35:32 +03:00
and
2015-11-20 01:38:54 +03:00
<citerefentry > <refentrytitle > sd_event_add_exit</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> .
2015-03-14 04:35:32 +03:00
</para>
2015-11-20 01:38:54 +03:00
<para > For low-level control of event loop execution, use
<citerefentry > <refentrytitle > sd_event_prepare</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > sd_event_wait</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry>
and
<citerefentry > <refentrytitle > sd_event_dispatch</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry>
which are wrapped by <function > sd_event_run()</function> . Along
with
<citerefentry > <refentrytitle > sd_event_get_fd</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
these functions allow integration of an
<citerefentry > <refentrytitle > sd-event</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry>
event loop into foreign event loop implementations.</para>
2015-03-14 04:35:32 +03:00
</refsect1>
<refsect1 >
<title > Return Value</title>
2015-11-20 01:38:54 +03:00
<para > On failure, these functions return a negative errno-style
error code. <function > sd_event_run()</function> returns a
positive, non-zero integer if an event source was dispatched, and
zero when the specified timeout hit before an event source has
seen any event, and hence no event source was
dispatched. <function > sd_event_loop()</function> returns the exit
code specified when invoking
<function > sd_event_exit()</function> .</para>
2015-03-14 04:35:32 +03:00
2019-03-21 16:53:00 +03:00
<refsect2 >
<title > Errors</title>
2015-03-14 04:35:32 +03:00
2019-03-21 16:53:00 +03:00
<para > Returned errors may indicate the following problems:</para>
2015-03-14 04:35:32 +03:00
2019-03-21 16:53:00 +03:00
<variablelist >
<varlistentry >
<term > <constant > -EINVAL</constant> </term>
2015-03-14 04:35:32 +03:00
2019-03-21 16:53:00 +03:00
<listitem > <para > The <parameter > event</parameter> parameter is invalid or
<constant > NULL</constant> .</para> </listitem>
</varlistentry>
2015-03-14 04:35:32 +03:00
2019-03-21 16:53:00 +03:00
<varlistentry >
<term > <constant > -EBUSY</constant> </term>
2015-03-14 04:35:32 +03:00
2019-03-21 16:53:00 +03:00
<listitem > <para > The event loop object is not in the right
state (see
<citerefentry > <refentrytitle > sd_event_prepare</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry>
for an explanation of possible states).</para> </listitem>
</varlistentry>
2015-03-14 04:35:32 +03:00
2019-03-21 16:53:00 +03:00
<varlistentry >
<term > <constant > -ESTALE</constant> </term>
2015-03-14 04:35:32 +03:00
2019-03-21 16:53:00 +03:00
<listitem > <para > The event loop is already terminated.</para> </listitem>
2015-03-14 04:35:32 +03:00
2019-03-21 16:53:00 +03:00
</varlistentry>
2015-03-14 04:35:32 +03:00
2019-03-21 16:53:00 +03:00
<varlistentry >
<term > <constant > -ECHILD</constant> </term>
2015-03-14 04:35:32 +03:00
2023-04-25 03:46:22 +03:00
<listitem > <para > The event loop has been created in a different process, library or module instance.</para> </listitem>
2015-03-14 04:35:32 +03:00
2019-03-21 16:53:00 +03:00
</varlistentry>
2015-03-14 04:35:32 +03:00
2019-03-21 16:53:00 +03:00
</variablelist>
2015-03-14 04:35:32 +03:00
2019-03-21 16:53:00 +03:00
<para > Other errors are possible, too.</para>
</refsect2>
2015-03-14 04:35:32 +03:00
</refsect1>
2015-11-20 01:38:54 +03:00
<xi:include href= "libsystemd-pkgconfig.xml" />
2015-03-14 04:35:32 +03:00
2023-09-04 15:46:35 +03:00
<refsect1 >
<title > History</title>
<para > <function > sd_event_loop()</function> was added in version 220.</para>
<para > <function > sd_event_run()</function> was added in version 220.</para>
</refsect1>
2015-03-14 04:35:32 +03:00
<refsect1 >
<title > See Also</title>
<para >
<citerefentry > <refentrytitle > systemd</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry> ,
2018-10-12 13:09:29 +03:00
<citerefentry > <refentrytitle > sd-event</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
2015-03-14 04:35:32 +03:00
<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> ,
2018-10-12 13:09:29 +03:00
<citerefentry > <refentrytitle > sd_event_add_child</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > sd_event_add_inotify</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
2015-03-14 04:35:32 +03:00
<citerefentry > <refentrytitle > sd_event_add_defer</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
2015-11-20 01:38:54 +03:00
<citerefentry > <refentrytitle > sd_event_exit</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > sd_event_get_fd</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > sd_event_wait</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
2018-10-12 13:09:29 +03:00
<ulink url= "https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html" > GLib Main Event Loop</ulink>
2015-03-14 04:35:32 +03:00
</para>
</refsect1>
</refentry>