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" conditional="ENABLE_KDBUS">
  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 libsystemd 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>timeout</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> can be used to run one
  73     iteration of the event loop of libsystemd. This function waits
  74     until an event to process is available and dispatches a handler
  75     for it. Parameter <parameter>timeout</parameter> specifices the
  76     maximum time (in microseconds) to wait. <constant>(uint64_t)
  77     -1</constant> may be used to specify an infinite timeout.</para>
  78
  79     <para><function>sd_event_loop</function> runs
  80     <function>sd_event_wait</function> in a loop with a timeout of
  81     infinity. This makes it suitable for the main event loop of a
  82     program.</para>
  83
  84     <para>The event loop object <parameter>event</parameter> is
  85     created with
  86     <function>sd_event_new</function>.
  87     Events to wait for and their handlers can be registered with
  88     <function>sd_event_add_time</function>,
  89     <function>sd_event_add_child</function>,
  90     <function>sd_event_add_signal</function>,
  91     <function>sd_event_add_defer</function>,
  92     <function>sd_event_add_exit</function>,
  93     and
  94     <function>sd_event_add_post</function>.
  95     </para>
  96
  97     <para>For more fine-grained control,
  98     <function>sd_event_prepare</function>,
  99     <function>sd_event_wait</function>, and
 100     <function>sd_event_dispatch</function> may be used. Along with
 101     <function>sd_event_get_fd</function>, those functions make it
 102     possible to integrate the libsystemd loop inside of another event
 103     loop.</para>
 104   </refsect1>
 105
 106   <refsect1>
 107     <title>Return Value</title>
 108
 109     <para>On success, these functions return 0 or a positive integer.
 110     On failure, they return a negative errno-style error code.
 111     <function>sd_event_run</function> returns 0 if the event loop is
 112     finished, and a positive value if it can be continued.</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>Parameter <parameter>event</parameter> is
 125         <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   <refsect1>
 157     <title>Notes</title>
 158
 159     <para><function>sd_event_run()</function> and
 160     <function>sd_event_loop()</function> are available
 161     as a shared library, which can be compiled and linked to with the
 162     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 163     file.</para>
 164   </refsect1>
 165
 166   <refsect1>
 167     <title>See Also</title>
 168
 169     <para>
 170       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 171       <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 172       <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 173       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 174       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 175       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 176       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 177       <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 178       <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 179     </para>
 180   </refsect1>
 181
 182 </refentry>