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