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