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