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