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