1<?xml version='1.0'?> 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 4<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> 5 6<refentry id="sd_event_exit" xmlns:xi="http://www.w3.org/2001/XInclude"> 7 8 <refentryinfo> 9 <title>sd_event_exit</title> 10 <productname>systemd</productname> 11 </refentryinfo> 12 13 <refmeta> 14 <refentrytitle>sd_event_exit</refentrytitle> 15 <manvolnum>3</manvolnum> 16 </refmeta> 17 18 <refnamediv> 19 <refname>sd_event_exit</refname> 20 <refname>sd_event_get_exit_code</refname> 21 22 <refpurpose>Ask the event loop to exit</refpurpose> 23 </refnamediv> 24 25 <refsynopsisdiv> 26 <funcsynopsis> 27 <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> 28 29 <funcprototype> 30 <funcdef>int <function>sd_event_exit</function></funcdef> 31 <paramdef>sd_event *<parameter>event</parameter></paramdef> 32 <paramdef>int <parameter>code</parameter></paramdef> 33 </funcprototype> 34 35 <funcprototype> 36 <funcdef>int <function>sd_event_get_exit_code</function></funcdef> 37 <paramdef>sd_event *<parameter>event</parameter></paramdef> 38 <paramdef>int *<parameter>code</parameter></paramdef> 39 </funcprototype> 40 41 </funcsynopsis> 42 </refsynopsisdiv> 43 44 <refsect1> 45 <title>Description</title> 46 47 <para><function>sd_event_exit()</function> requests the event loop 48 specified in the <parameter>event</parameter> event loop object to 49 exit. The <parameter>code</parameter> parameter may be any integer 50 value and is returned as-is by 51 <citerefentry><refentrytitle>sd_event_loop</refentrytitle><manvolnum>3</manvolnum></citerefentry> 52 after the last event loop iteration. It may also be queried 53 using <function>sd_event_get_exit_code()</function>, see 54 below. </para> 55 56 <para>When exiting is requested the event loop will stop listening 57 for and dispatching regular event sources. Instead it will proceed 58 with executing only event sources registered with 59 <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> 60 in the order defined by their priority. After all exit event 61 sources have been dispatched the event loop is terminated.</para> 62 63 <para>If <function>sd_event_exit()</function> is invoked a second 64 time while the event loop is still processing exit event sources, 65 the exit code stored in the event loop object is updated, but 66 otherwise no further operation is executed.</para> 67 68 <para><function>sd_event_get_exit_code()</function> may be used to 69 query the exit code passed into 70 <function>sd_event_exit()</function> earlier.</para> 71 72 <para>While the full positive and negative integer ranges may be used 73 for the exit code, care should be taken not pick exit codes that 74 conflict with regular exit codes returned by 75 <function>sd_event_loop()</function>, if these exit codes shall be 76 distinguishable.</para> 77 78 <para>Note that for most event source types passing the callback pointer as <constant>NULL</constant> in 79 the respective constructor call (i.e. in 80 <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 81 <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 82 …) has the effect of <function>sd_event_exit()</function> being invoked once the event source triggers, 83 with the specified userdata pointer cast to an integer as the exit code parameter. This is useful to 84 automatically terminate an event loop after some condition, such as a time-out or reception of 85 <constant>SIGTERM</constant> or similar. See the documentation for the respective constructor call for 86 details.</para> 87 </refsect1> 88 89 <refsect1> 90 <title>Return Value</title> 91 92 <para>On success, <function>sd_event_exit()</function> and <function>sd_event_get_exit_code()</function> 93 return 0 or a positive integer. On failure, they return a negative errno-style error code.</para> 94 95 <refsect2> 96 <title>Errors</title> 97 98 <para>Returned errors may indicate the following problems:</para> 99 100 <variablelist> 101 102 <varlistentry> 103 <term><constant>-EINVAL</constant></term> 104 105 <listitem><para>The event loop object or error code pointer are invalid.</para></listitem> 106 107 </varlistentry> 108 109 <varlistentry> 110 <term><constant>-ECHILD</constant></term> 111 112 <listitem><para>The event loop was created in a different process.</para></listitem> 113 </varlistentry> 114 115 <varlistentry> 116 <term><constant>-ESTALE</constant></term> 117 118 <listitem><para>The event loop has exited already and all exit handlers are already processed. 119 </para></listitem> 120 </varlistentry> 121 122 <varlistentry> 123 <term><constant>-ENODATA</constant></term> 124 125 <listitem><para>The event loop has not been requested to exit yet.</para></listitem> 126 </varlistentry> 127 128 </variablelist> 129 </refsect2> 130 </refsect1> 131 132 <xi:include href="libsystemd-pkgconfig.xml" /> 133 134 <refsect1> 135 <title>See Also</title> 136 137 <para> 138 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 139 <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 140 <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 141 <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 142 <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 143 <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 144 <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 145 <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 146 <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry> 147 </para> 148 </refsect1> 149 150</refentry> 151