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