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