man/sd_event_run.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="sd_event_run" xmlns:xi="http://www.w3.org/2001/XInclude">
   7
   8   <refentryinfo>
   9     <title>sd_event_run</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>sd_event_run</refentrytitle>
  15     <manvolnum>3</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>sd_event_run</refname>
  20     <refname>sd_event_loop</refname>
  21
  22     <refpurpose>Run an event loop</refpurpose>
  23   </refnamediv>
  24
  25   <refsynopsisdiv>
  26     <funcsynopsis>
  27       <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
  28
  29       <funcprototype>
  30         <funcdef>int <function>sd_event_run</function></funcdef>
  31         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  32         <paramdef>uint64_t <parameter>usec</parameter></paramdef>
  33       </funcprototype>
  34
  35       <funcprototype>
  36         <funcdef>int <function>sd_event_loop</function></funcdef>
  37         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  38       </funcprototype>
  39     </funcsynopsis>
  40   </refsynopsisdiv>
  41
  42   <refsect1>
  43     <title>Description</title>
  44
  45     <para><function>sd_event_run()</function> may be used to run a single
  46     iteration of the event loop specified in the
  47     <parameter>event</parameter> parameter. The function waits until an event to
  48     process is available, and dispatches the registered handler for
  49     it. The <parameter>usec</parameter> parameter specifies the
  50     maximum time (in microseconds) to wait for an event. Use
  51     <constant>(uint64_t) -1</constant> to specify an infinite
  52     timeout.</para>
  53
  54     <para><function>sd_event_loop()</function> invokes
  55     <function>sd_event_run()</function> in a loop, thus implementing
  56     the actual event loop. The call returns as soon as exiting was
  57     requested using
  58     <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
  59
  60     <para>The event loop object <parameter>event</parameter> is
  61     created with
  62     <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
  63     Events sources to wait for and their handlers may be registered
  64     with
  65     <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  66     <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  67     <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  68     <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  69     <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  70     <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  71     and
  72     <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
  73     </para>
  74
  75     <para>For low-level control of event loop execution, use
  76     <citerefentry><refentrytitle>sd_event_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  77     <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  78     and
  79     <citerefentry><refentrytitle>sd_event_dispatch</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  80     which are wrapped by <function>sd_event_run()</function>. Along
  81     with
  82     <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  83     these functions allow integration of an
  84     <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  85     event loop into foreign event loop implementations.</para>
  86   </refsect1>
  87
  88   <refsect1>
  89     <title>Return Value</title>
  90
  91     <para>On failure, these functions return a negative errno-style
  92     error code. <function>sd_event_run()</function> returns a
  93     positive, non-zero integer if an event source was dispatched, and
  94     zero when the specified timeout hit before an event source has
  95     seen any event, and hence no event source was
  96     dispatched. <function>sd_event_loop()</function> returns the exit
  97     code specified when invoking
  98     <function>sd_event_exit()</function>.</para>
  99
 100     <refsect2>
 101       <title>Errors</title>
 102
 103       <para>Returned errors may indicate the following problems:</para>
 104
 105       <variablelist>
 106         <varlistentry>
 107           <term><constant>-EINVAL</constant></term>
 108
 109           <listitem><para>The <parameter>event</parameter> parameter is invalid or
 110           <constant>NULL</constant>.</para></listitem>
 111         </varlistentry>
 112
 113         <varlistentry>
 114           <term><constant>-EBUSY</constant></term>
 115
 116           <listitem><para>The event loop object is not in the right
 117           state (see
 118           <citerefentry><refentrytitle>sd_event_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 119           for an explanation of possible states).</para></listitem>
 120         </varlistentry>
 121
 122         <varlistentry>
 123           <term><constant>-ESTALE</constant></term>
 124
 125           <listitem><para>The event loop is already terminated.</para></listitem>
 126
 127         </varlistentry>
 128
 129         <varlistentry>
 130           <term><constant>-ECHILD</constant></term>
 131
 132           <listitem><para>The event loop has been created in a different process, library or module instance.</para></listitem>
 133
 134         </varlistentry>
 135
 136       </variablelist>
 137
 138       <para>Other errors are possible, too.</para>
 139     </refsect2>
 140   </refsect1>
 141
 142   <xi:include href="libsystemd-pkgconfig.xml" />
 143
 144   <refsect1>
 145     <title>History</title>
 146     <para><function>sd_event_run()</function> and
 147     <function>sd_event_loop()</function> were added in version 220.</para>
 148   </refsect1>
 149
 150   <refsect1>
 151     <title>See Also</title>
 152
 153     <para>
 154       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 155       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 156       <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 157       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 158       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 159       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 160       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 161       <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 162       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 163       <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 164       <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 165       <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 166       <ulink url="https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html">GLib Main Event Loop</ulink>
 167     </para>
 168   </refsect1>
 169
 170 </refentry>