man/sd_event_exit.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
   9 <refentry id="sd_event_exit" xmlns:xi="http://www.w3.org/2001/XInclude">
  10
  11   <refentryinfo>
  12     <title>sd_event_exit</title>
  13     <productname>elogind</productname>
  14
  15     <authorgroup>
  16       <author>
  17         <contrib>Developer</contrib>
  18         <firstname>Lennart</firstname>
  19         <surname>Poettering</surname>
  20         <email>lennart@poettering.net</email>
  21       </author>
  22     </authorgroup>
  23   </refentryinfo>
  24
  25   <refmeta>
  26     <refentrytitle>sd_event_exit</refentrytitle>
  27     <manvolnum>3</manvolnum>
  28   </refmeta>
  29
  30   <refnamediv>
  31     <refname>sd_event_exit</refname>
  32     <refname>sd_event_get_exit_code</refname>
  33
  34     <refpurpose>Ask the event loop to exit</refpurpose>
  35   </refnamediv>
  36
  37   <refsynopsisdiv>
  38     <funcsynopsis>
  39       <funcsynopsisinfo>#include &lt;elogind/sd-event.h&gt;</funcsynopsisinfo>
  40
  41       <funcprototype>
  42         <funcdef>int <function>sd_event_exit</function></funcdef>
  43         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  44         <paramdef>int <parameter>code</parameter></paramdef>
  45       </funcprototype>
  46
  47       <funcprototype>
  48         <funcdef>int <function>sd_event_get_exit_code</function></funcdef>
  49         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  50         <paramdef>int *<parameter>code</parameter></paramdef>
  51       </funcprototype>
  52
  53     </funcsynopsis>
  54   </refsynopsisdiv>
  55
  56   <refsect1>
  57     <title>Description</title>
  58
  59     <para><function>sd_event_exit()</function> requests the event loop
  60     specified in the <parameter>event</parameter> event loop object to
  61     exit. The <parameter>code</parameter> parameter may be any integer
  62     value and is returned as-is by
  63     <citerefentry><refentrytitle>sd_event_loop</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  64     after the last event loop iteration. It may also be queried
  65     using <function>sd_event_get_exit_code()</function>, see
  66     below. </para>
  67
  68     <para>When exiting is requested the event loop will stop listening
  69     for and dispatching regular event sources. Instead it will proceed
  70     with executing only event sources registered with
  71     <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  72     in the order defined by their priority. After all exit event
  73     sources have been dispatched the event loop is terminated.</para>
  74
  75     <para>If <function>sd_event_exit()</function> is invoked a second
  76     time while the event loop is still processing exit event sources,
  77     the exit code stored in the event loop object is updated, but
  78     otherwise no further operation is executed.</para>
  79
  80     <para><function>sd_event_get_exit_code()</function> may be used to
  81     query the exit code passed into
  82     <function>sd_event_exit()</function> earlier.</para>
  83
  84     <para>While the full positive and negative integer ranges may be used
  85     for the exit code, care should be taken not pick exit codes that
  86     conflict with regular exit codes returned by
  87     <function>sd_event_loop()</function>, if these exit codes shall be
  88     distinguishable.</para>
  89   </refsect1>
  90
  91   <refsect1>
  92     <title>Return Value</title>
  93
  94     <para>On success, <function>sd_event_exit()</function> and
  95     <function>sd_event_get_exit_code()</function> return 0 or a positive
  96     integer. On failure, they return a negative errno-style error
  97     code.</para>
  98   </refsect1>
  99
 100   <refsect1>
 101     <title>Errors</title>
 102
 103     <para>Returned errors may indicate the following problems:</para>
 104
 105     <variablelist>
 106
 107       <varlistentry>
 108         <term><constant>-EINVAL</constant></term>
 109
 110         <listitem><para>The event loop object or error code pointer are invalid.</para></listitem>
 111
 112       </varlistentry>
 113
 114       <varlistentry>
 115         <term><constant>-ECHILD</constant></term>
 116
 117         <listitem><para>The event loop was created in a different process.</para></listitem>
 118       </varlistentry>
 119
 120       <varlistentry>
 121         <term><constant>-ESTALE</constant></term>
 122
 123         <listitem><para>The event loop has exited already and all exit handlers are already processed.</para></listitem>
 124       </varlistentry>
 125
 126       <varlistentry>
 127         <term><constant>-ENODATA</constant></term>
 128
 129         <listitem><para>The event loop has not been requested to exit yet.</para></listitem>
 130       </varlistentry>
 131
 132     </variablelist>
 133   </refsect1>
 134
 135   <xi:include href="libelogind-pkgconfig.xml" />
 136
 137   <refsect1>
 138     <title>See Also</title>
 139
 140     <para>
 141       <!-- 0 /// elogind is in section 8
 142       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 143       --><!-- else -->
 144       <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 145       <!-- // 0 -->
 146       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 147       <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 148       <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 149     </para>
 150   </refsect1>
 151
 152 </refentry>