man/sd_event_run.xml

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