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