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