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+ -->
   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   </refsect1>
 100
 101   <refsect1>
 102     <title>Errors</title>
 103
 104     <para>Returned errors may indicate the following problems:</para>
 105
 106     <variablelist>
 107       <varlistentry>
 108         <term><constant>-EINVAL</constant></term>
 109
 110         <listitem><para>The <parameter>event</parameter> parameter is
 111         invalid or <constant>NULL</constant>.</para></listitem>
 112       </varlistentry>
 113
 114       <varlistentry>
 115         <term><constant>-EBUSY</constant></term>
 116
 117         <listitem><para>The event loop object is not in the right
 118         state (see
 119         <citerefentry><refentrytitle>sd_event_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 120         for an explanation of possible states).</para></listitem>
 121       </varlistentry>
 122
 123       <varlistentry>
 124         <term><constant>-ESTALE</constant></term>
 125
 126         <listitem><para>The event loop is already terminated.</para></listitem>
 127
 128       </varlistentry>
 129
 130       <varlistentry>
 131         <term><constant>-ECHILD</constant></term>
 132
 133         <listitem><para>The event loop has been created in a different process.</para></listitem>
 134
 135       </varlistentry>
 136
 137     </variablelist>
 138
 139     <para>Other errors are possible, too.</para>
 140   </refsect1>
 141
 142   <xi:include href="libsystemd-pkgconfig.xml" />
 143
 144   <refsect1>
 145     <title>See Also</title>
 146
 147     <para>
 148       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 149       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 150       <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 151       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 152       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 153       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 154       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 155       <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 156       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 157       <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 158       <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 159       <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 160       <ulink url="https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html">GLib Main Event Loop</ulink>
 161     </para>
 162   </refsect1>
 163
 164 </refentry>