man/sd_event_run.xml

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