]> git.ipfire.org Git - thirdparty/systemd.git/blame - man/sd_event_add_io.xml
journald: bring order of MaxLevelXYZ= setting explanations in sync with listed names
[thirdparty/systemd.git] / man / sd_event_add_io.xml
CommitLineData
514094f9 1<?xml version='1.0'?>
3a54a157 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
eea10b26 3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
db9ecf05 4<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
dc83f27a
LP
5
6<refentry id="sd_event_add_io" xmlns:xi="http://www.w3.org/2001/XInclude">
7
8 <refentryinfo>
9 <title>sd_event_add_io</title>
10 <productname>systemd</productname>
dc83f27a
LP
11 </refentryinfo>
12
13 <refmeta>
14 <refentrytitle>sd_event_add_io</refentrytitle>
15 <manvolnum>3</manvolnum>
16 </refmeta>
17
18 <refnamediv>
19 <refname>sd_event_add_io</refname>
20 <refname>sd_event_source_get_io_events</refname>
21 <refname>sd_event_source_set_io_events</refname>
22 <refname>sd_event_source_get_io_revents</refname>
23 <refname>sd_event_source_get_io_fd</refname>
24 <refname>sd_event_source_set_io_fd</refname>
90b1fa59
LP
25 <refname>sd_event_source_get_io_fd_own</refname>
26 <refname>sd_event_source_set_io_fd_own</refname>
dc83f27a
LP
27 <refname>sd_event_source</refname>
28 <refname>sd_event_io_handler_t</refname>
29
30 <refpurpose>Add an I/O event source to an event loop</refpurpose>
31 </refnamediv>
32
33 <refsynopsisdiv>
34 <funcsynopsis>
35 <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
36
37 <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo>
38
39 <funcprototype>
40 <funcdef>typedef int (*<function>sd_event_io_handler_t</function>)</funcdef>
41 <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
42 <paramdef>int <parameter>fd</parameter></paramdef>
43 <paramdef>uint32_t <parameter>revents</parameter></paramdef>
44 <paramdef>void *<parameter>userdata</parameter></paramdef>
45 </funcprototype>
46
47 <funcprototype>
48 <funcdef>int <function>sd_event_add_io</function></funcdef>
49 <paramdef>sd_event *<parameter>event</parameter></paramdef>
50 <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
51 <paramdef>int <parameter>fd</parameter></paramdef>
52 <paramdef>uint32_t <parameter>events</parameter></paramdef>
53 <paramdef>sd_event_io_handler_t <parameter>handler</parameter></paramdef>
54 <paramdef>void *<parameter>userdata</parameter></paramdef>
55 </funcprototype>
56
57 <funcprototype>
58 <funcdef>int <function>sd_event_source_get_io_events</function></funcdef>
59 <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
60 <paramdef>uint32_t *<parameter>events</parameter></paramdef>
61 </funcprototype>
62
63 <funcprototype>
64 <funcdef>int <function>sd_event_source_set_io_events</function></funcdef>
65 <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
66 <paramdef>uint32_t <parameter>events</parameter></paramdef>
67 </funcprototype>
68
69 <funcprototype>
70 <funcdef>int <function>sd_event_source_get_io_revents</function></funcdef>
71 <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
72 <paramdef>uint32_t *<parameter>revents</parameter></paramdef>
73 </funcprototype>
74
75 <funcprototype>
76 <funcdef>int <function>sd_event_source_get_io_fd</function></funcdef>
77 <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
78 </funcprototype>
79
80 <funcprototype>
81 <funcdef>int <function>sd_event_source_set_io_fd</function></funcdef>
82 <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
83 <paramdef>int <parameter>fd</parameter></paramdef>
84 </funcprototype>
85
90b1fa59
LP
86 <funcprototype>
87 <funcdef>int <function>sd_event_source_get_io_fd_own</function></funcdef>
88 <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
89 </funcprototype>
90
91 <funcprototype>
92 <funcdef>int <function>sd_event_source_set_io_fd_own</function></funcdef>
93 <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
94 <paramdef>int <parameter>b</parameter></paramdef>
95 </funcprototype>
96
dc83f27a
LP
97 </funcsynopsis>
98 </refsynopsisdiv>
99
100 <refsect1>
101 <title>Description</title>
102
a06c92eb
LP
103 <para><function>sd_event_add_io()</function> adds a new I/O event source to an event loop. The event loop
104 object is specified in the <parameter>event</parameter> parameter, the event source object is returned in
105 the <parameter>source</parameter> parameter. The <parameter>fd</parameter> parameter takes the UNIX file
106 descriptor to watch, which may refer to a socket, a FIFO, a message queue, a serial connection, a
107 character device, or any other file descriptor compatible with Linux <citerefentry
108 project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
109 <parameter>events</parameter> parameter takes a bit mask of events to watch for, a combination of the
110 following event flags: <constant>EPOLLIN</constant>, <constant>EPOLLOUT</constant>,
111 <constant>EPOLLRDHUP</constant>, <constant>EPOLLPRI</constant>, and <constant>EPOLLET</constant>, see
112 <citerefentry
113 project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> for
114 details. Note that not all file descriptors are compatible with epoll, for example regular file or
115 directories are not. If this function is called with a file descriptor that does not support epoll,
116 <constant>-EPERM</constant> is returned (also see below). In most cases such file descriptors may be
117 treated as always-readable or always-writable, so that IO event watching is unnecessary.</para>
9809a788
ZJS
118
119 <para>The <parameter>handler</parameter> is a function to call when the event source is triggered or
120 <constant>NULL</constant>. The <parameter>userdata</parameter> pointer will be passed to the handler
121 function, and may be chosen freely by the caller. The handler will also be passed the file descriptor the
122 event was seen on, as well as the actual event flags. It's generally a subset of the events watched,
123 however may additionally include <constant>EPOLLERR</constant> and <constant>EPOLLHUP</constant>. The
124 handler may return negative to signal an error (see below), other return values are ignored. If
125 <parameter>handler</parameter> is <constant>NULL</constant>, a default handler that calls
126 <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> will be
127 used.</para>
128
129 <para>By default, an event source will stay enabled continuously (<constant>SD_EVENT_ON</constant>), but
130 this may be changed with
dc83f27a 131 <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
9809a788
ZJS
132 If the handler function returns a negative error code, it will either be disabled after the invocation,
133 even if the <constant>SD_EVENT_ON</constant> mode was requested before, or it will cause the loop to
134 terminate, see
135 <citerefentry><refentrytitle>sd_event_source_set_exit_on_failure</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
136 Note that an event source set to <constant>SD_EVENT_ON</constant> will fire continuously unless data is
137 read from or written to the file descriptor to reset the mask of events seen.</para>
dc83f27a
LP
138
139 <para>Setting the I/O event mask to watch for to 0 does not mean
140 that the event source won't be triggered anymore, as
141 <constant>EPOLLHUP</constant> and <constant>EPOLLERR</constant>
142 may be triggered even with a zero event mask. To temporarily
143 disable an I/O event source use
144 <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
145 with <constant>SD_EVENT_OFF</constant> instead.</para>
146
147 <para>To destroy an event source object use
148 <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
149 but note that the event source is only removed from the event loop
150 when all references to the event source are dropped. To make sure
f23e83b1
ZJS
151 an event source does not fire anymore, even if it is still referenced,
152 disable the event source using
153 <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
154 with <constant>SD_EVENT_OFF</constant>.</para>
dc83f27a 155
7f3fdb7f 156 <para>If the second parameter of
f23e83b1
ZJS
157 <function>sd_event_add_io()</function> is
158 <constant>NULL</constant> no reference to the event source object
159 is returned. In this case the event source is considered
160 "floating", and will be destroyed implicitly when the event loop
161 itself is destroyed.</para>
dc83f27a 162
b9350e70
LP
163 <para>If the <parameter>handler</parameter> to <function>sd_event_add_io()</function> is
164 <constant>NULL</constant>, and the event source fires, this will be considered a request to exit the
165 event loop. In this case, the <parameter>userdata</parameter> parameter, cast to an integer, is passed as
166 the exit code parameter to
167 <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
168
30ab7a51
LP
169 <para>Note that this call does not take possession of the file descriptor passed in, ownership (and thus
170 the duty to close it when it is no longer needed) remains with the caller. However, with the
171 <function>sd_event_source_set_io_fd_own()</function> call (see below) the event source may optionally
172 take ownership of the file descriptor after the event source has been created. In that case the file
173 descriptor is closed automatically as soon as the event source is released.</para>
174
dc83f27a
LP
175 <para>It is recommended to use
176 <function>sd_event_add_io()</function> only in conjunction with
177 file descriptors that have <constant>O_NONBLOCK</constant> set, to
178 ensure that all I/O operations from invoked handlers are properly
179 asynchronous and non-blocking. Using file descriptors without
180 <constant>O_NONBLOCK</constant> might result in unexpected
f23e83b1
ZJS
181 starvation of other event sources. See
182 <citerefentry project='man-pages'><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
dc83f27a
LP
183 for details on enabling <constant>O_NONBLOCK</constant> mode.</para>
184
185 <para><function>sd_event_source_get_io_events()</function> retrieves
f23e83b1 186 the configured mask of watched I/O events of an event source created
dc83f27a
LP
187 previously with <function>sd_event_add_io()</function>. It takes
188 the event source object and a pointer to a variable to store the
f23e83b1 189 mask in.</para>
dc83f27a 190
f23e83b1
ZJS
191 <para><function>sd_event_source_set_io_events()</function>
192 configures the mask of watched I/O events of an event source created
193 previously with <function>sd_event_add_io()</function>. It takes the
194 event source object and the new event mask.</para>
dc83f27a 195
13b6b49f 196 <para><function>sd_event_source_get_io_revents()</function>
dc83f27a 197 retrieves the I/O event mask of currently seen but undispatched
f23e83b1 198 events from an event source created previously with
dc83f27a
LP
199 <function>sd_event_add_io()</function>. It takes the event source
200 object and a pointer to a variable to store the event mask
201 in. When called from a handler function on the handler's event
202 source object this will return the same mask as passed to the
203 handler's <parameter>revents</parameter> parameter. This call is
204 primarily useful to check for undispatched events of an event
205 source from the handler of an unrelated (possibly higher priority)
206 event source. Note the relation between
207 <function>sd_event_source_get_pending()</function> and
208 <function>sd_event_source_get_io_revents()</function>: both
209 functions will report non-zero results when there's an event
210 pending for the event source, but the former applies to all event
211 source types, the latter only to I/O event sources.</para>
212
213 <para><function>sd_event_source_get_io_fd()</function> retrieves
f23e83b1 214 the UNIX file descriptor of an event source created previously
dc83f27a 215 with <function>sd_event_add_io()</function>. It takes the event
f23e83b1
ZJS
216 source object and returns the non-negative file descriptor
217 or a negative error number on error (see below).</para>
dc83f27a 218
2fa48059
YW
219 <para><function>sd_event_source_set_io_fd()</function> changes the UNIX file descriptor of an I/O event
220 source created previously with <function>sd_event_add_io()</function>. It takes the event source object
221 and the new file descriptor. If the event source takes the ownership of the previous file descriptor,
222 that is, <function>sd_event_source_set_io_fd_own()</function> was called for the event source with a
223 non-zero value, then the previous file descriptor will be closed and the event source will also take the
224 ownership of the new file descriptor on success.</para>
225
226 <para><function>sd_event_source_set_io_fd_own()</function> controls whether the file descriptor of the
227 event source shall be closed automatically when the event source is freed (or when the file descriptor
228 assigned to the event source is replaced by <function>sd_event_source_set_io_fd()</function>), i.e.
229 whether it shall be considered 'owned' by the event source object. By default it is not closed
230 automatically, and the application has to do this on its own. The <parameter>b</parameter> parameter is a
231 boolean parameter: if zero, the file descriptor is not closed automatically when the event source is
232 freed, otherwise it is closed.</para>
90b1fa59
LP
233
234 <para><function>sd_event_source_get_io_fd_own()</function> may be used to query the current setting of the file
235 descriptor ownership boolean flag as set with <function>sd_event_source_set_io_fd_own()</function>. It returns
236 positive if the file descriptor is closed automatically when the event source is destroyed, zero if not, and
237 negative on error.</para>
dc83f27a
LP
238 </refsect1>
239
240 <refsect1>
241 <title>Return Value</title>
242
243 <para>On success, these functions return 0 or a positive
244 integer. On failure, they return a negative errno-style error
f23e83b1 245 code.</para>
dc83f27a 246
b1de39de
ZJS
247 <refsect2>
248 <title>Errors</title>
dc83f27a 249
b1de39de 250 <para>Returned values may indicate the following problems:</para>
dc83f27a 251
b1de39de
ZJS
252 <variablelist>
253 <varlistentry>
254 <term><constant>-ENOMEM</constant></term>
dc83f27a 255
b1de39de
ZJS
256 <listitem><para>Not enough memory to allocate an object.</para></listitem>
257 </varlistentry>
dc83f27a 258
b1de39de
ZJS
259 <varlistentry>
260 <term><constant>-EINVAL</constant></term>
dc83f27a 261
b1de39de 262 <listitem><para>An invalid argument has been passed.</para></listitem>
dc83f27a 263
b1de39de 264 </varlistentry>
dc83f27a 265
b1de39de
ZJS
266 <varlistentry>
267 <term><constant>-ESTALE</constant></term>
dc83f27a 268
b1de39de 269 <listitem><para>The event loop is already terminated.</para></listitem>
dc83f27a 270
b1de39de 271 </varlistentry>
dc83f27a 272
b1de39de
ZJS
273 <varlistentry>
274 <term><constant>-ECHILD</constant></term>
dc83f27a 275
2eeff0f4 276 <listitem><para>The event loop has been created in a different process, library or module instance.</para></listitem>
b1de39de 277 </varlistentry>
dc83f27a 278
b1de39de
ZJS
279 <varlistentry>
280 <term><constant>-EDOM</constant></term>
dc83f27a 281
b1de39de
ZJS
282 <listitem><para>The passed event source is not an I/O event source.</para></listitem>
283 </varlistentry>
a06c92eb
LP
284
285 <varlistentry>
286 <term><constant>-EPERM</constant></term>
287
288 <listitem><para>The passed file descriptor does not support the <citerefentry
289 project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>
290 API, for example because it is a regular file or directory. See <citerefentry
291 project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
ec07c3c8
AK
292 for details.</para>
293
294 <xi:include href="version-info.xml" xpointer="v255"/></listitem>
a06c92eb 295 </varlistentry>
b1de39de
ZJS
296 </variablelist>
297 </refsect2>
dc83f27a
LP
298 </refsect1>
299
300 <xi:include href="libsystemd-pkgconfig.xml" />
301
69106f47
AK
302 <refsect1>
303 <title>History</title>
00f95506
AK
304 <para><function>sd_event_io_handler_t()</function>,
305 <function>sd_event_add_io()</function>,
306 <function>sd_event_source_get_io_events()</function>,
307 <function>sd_event_source_set_io_events()</function>,
308 <function>sd_event_source_get_io_revents()</function>,
309 <function>sd_event_source_get_io_fd()</function>, and
310 <function>sd_event_source_set_io_fd()</function> were added in version 229.</para>
311 <para><function>sd_event_source_get_io_fd_own()</function> and
312 <function>sd_event_source_set_io_fd_own()</function> were added in version 239.</para>
69106f47
AK
313 </refsect1>
314
dc83f27a
LP
315 <refsect1>
316 <title>See Also</title>
317
13a69c12
DT
318 <para><simplelist type="inline">
319 <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
320 <member><citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
321 <member><citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
322 <member><citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
323 <member><citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
324 <member><citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
325 <member><citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
326 <member><citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
327 <member><citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
328 <member><citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
329 <member><citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
330 <member><citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
331 <member><citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
332 <member><citerefentry><refentrytitle>sd_event_source_get_pending</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
333 <member><citerefentry><refentrytitle>sd_event_source_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
334 <member><citerefentry project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry></member>
335 <member><citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
336 </simplelist></para>
dc83f27a
LP
337 </refsect1>
338
339</refentry>