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">
6 This file is part of elogind.
8 Copyright 2015 Lennart Poettering
10 elogind is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
15 elogind is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with elogind; If not, see <http://www.gnu.org/licenses/>.
24 <refentry id="sd_event_add_io" xmlns:xi="http://www.w3.org/2001/XInclude">
27 <title>sd_event_add_io</title>
28 <productname>elogind</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>sd_event_add_io</refentrytitle>
42 <manvolnum>3</manvolnum>
46 <refname>sd_event_add_io</refname>
47 <refname>sd_event_source_get_io_events</refname>
48 <refname>sd_event_source_set_io_events</refname>
49 <refname>sd_event_source_get_io_revents</refname>
50 <refname>sd_event_source_get_io_fd</refname>
51 <refname>sd_event_source_set_io_fd</refname>
52 <refname>sd_event_source</refname>
53 <refname>sd_event_io_handler_t</refname>
55 <refpurpose>Add an I/O event source to an event loop</refpurpose>
60 <funcsynopsisinfo>#include <elogind/sd-event.h></funcsynopsisinfo>
62 <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo>
65 <funcdef>typedef int (*<function>sd_event_io_handler_t</function>)</funcdef>
66 <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
67 <paramdef>int <parameter>fd</parameter></paramdef>
68 <paramdef>uint32_t <parameter>revents</parameter></paramdef>
69 <paramdef>void *<parameter>userdata</parameter></paramdef>
73 <funcdef>int <function>sd_event_add_io</function></funcdef>
74 <paramdef>sd_event *<parameter>event</parameter></paramdef>
75 <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
76 <paramdef>int <parameter>fd</parameter></paramdef>
77 <paramdef>uint32_t <parameter>events</parameter></paramdef>
78 <paramdef>sd_event_io_handler_t <parameter>handler</parameter></paramdef>
79 <paramdef>void *<parameter>userdata</parameter></paramdef>
83 <funcdef>int <function>sd_event_source_get_io_events</function></funcdef>
84 <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
85 <paramdef>uint32_t *<parameter>events</parameter></paramdef>
89 <funcdef>int <function>sd_event_source_set_io_events</function></funcdef>
90 <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
91 <paramdef>uint32_t <parameter>events</parameter></paramdef>
95 <funcdef>int <function>sd_event_source_get_io_revents</function></funcdef>
96 <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
97 <paramdef>uint32_t *<parameter>revents</parameter></paramdef>
101 <funcdef>int <function>sd_event_source_get_io_fd</function></funcdef>
102 <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
106 <funcdef>int <function>sd_event_source_set_io_fd</function></funcdef>
107 <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
108 <paramdef>int <parameter>fd</parameter></paramdef>
115 <title>Description</title>
117 <para><function>sd_event_add_io()</function> adds a new I/O event
118 source to an event loop. The event loop object is specified in the
119 <parameter>event</parameter> parameter, the event source object is
120 returned in the <parameter>source</parameter> parameter. The
121 <parameter>fd</parameter> parameter takes the UNIX file descriptor
122 to watch, which may refer to a socket, a FIFO, a message queue, a
123 serial connection, a character device, or any other file descriptor
124 compatible with Linux
125 <citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
126 <parameter>events</parameter> parameter takes a bit mask of events
127 to watch for, a combination of the following event flags:
128 <constant>EPOLLIN</constant>, <constant>EPOLLOUT</constant>,
129 <constant>EPOLLRDHUP</constant>, <constant>EPOLLPRI</constant>,
130 and <constant>EPOLLET</constant>, see
131 <citerefentry project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
132 for details. The <parameter>handler</parameter> shall reference a
133 function to call when the event source is triggered. The
134 <parameter>userdata</parameter> pointer will be passed to the
135 handler function, and may be chosen freely by the caller. The
136 handler will also be passed the file descriptor the event was seen
137 on, as well as the actual event flags. It's generally a subset of
138 the events watched, however may additionally include
139 <constant>EPOLLERR</constant> and <constant>EPOLLHUP</constant>.
142 <para>By default, an event source will stay enabled
143 continuously (<constant>SD_EVENT_ON</constant>), but this may be
145 <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
146 If the handler function returns a negative error code, it will be
147 disabled after the invocation, even if the
148 <constant>SD_EVENT_ON</constant> mode was requested before. Note
149 that an event source set to <constant>SD_EVENT_ON</constant> will
150 fire continuously unless data is read from or written to the file
151 descriptor to reset the mask of events seen.
154 <para>Setting the I/O event mask to watch for to 0 does not mean
155 that the event source won't be triggered anymore, as
156 <constant>EPOLLHUP</constant> and <constant>EPOLLERR</constant>
157 may be triggered even with a zero event mask. To temporarily
158 disable an I/O event source use
159 <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
160 with <constant>SD_EVENT_OFF</constant> instead.</para>
162 <para>To destroy an event source object use
163 <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
164 but note that the event source is only removed from the event loop
165 when all references to the event source are dropped. To make sure
166 an event source does not fire anymore, even if it is still referenced,
167 disable the event source using
168 <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
169 with <constant>SD_EVENT_OFF</constant>.</para>
171 <para>If the second parameter of
172 <function>sd_event_add_io()</function> is
173 <constant>NULL</constant> no reference to the event source object
174 is returned. In this case the event source is considered
175 "floating", and will be destroyed implicitly when the event loop
176 itself is destroyed.</para>
178 <para>It is recommended to use
179 <function>sd_event_add_io()</function> only in conjunction with
180 file descriptors that have <constant>O_NONBLOCK</constant> set, to
181 ensure that all I/O operations from invoked handlers are properly
182 asynchronous and non-blocking. Using file descriptors without
183 <constant>O_NONBLOCK</constant> might result in unexpected
184 starvation of other event sources. See
185 <citerefentry project='man-pages'><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
186 for details on enabling <constant>O_NONBLOCK</constant> mode.</para>
188 <para><function>sd_event_source_get_io_events()</function> retrieves
189 the configured mask of watched I/O events of an event source created
190 previously with <function>sd_event_add_io()</function>. It takes
191 the event source object and a pointer to a variable to store the
194 <para><function>sd_event_source_set_io_events()</function>
195 configures the mask of watched I/O events of an event source created
196 previously with <function>sd_event_add_io()</function>. It takes the
197 event source object and the new event mask.</para>
199 <para><function>sd_event_source_get_io_revents()</function>
200 retrieves the I/O event mask of currently seen but undispatched
201 events from an event source created previously with
202 <function>sd_event_add_io()</function>. It takes the event source
203 object and a pointer to a variable to store the event mask
204 in. When called from a handler function on the handler's event
205 source object this will return the same mask as passed to the
206 handler's <parameter>revents</parameter> parameter. This call is
207 primarily useful to check for undispatched events of an event
208 source from the handler of an unrelated (possibly higher priority)
209 event source. Note the relation between
210 <function>sd_event_source_get_pending()</function> and
211 <function>sd_event_source_get_io_revents()</function>: both
212 functions will report non-zero results when there's an event
213 pending for the event source, but the former applies to all event
214 source types, the latter only to I/O event sources.</para>
216 <para><function>sd_event_source_get_io_fd()</function> retrieves
217 the UNIX file descriptor of an event source created previously
218 with <function>sd_event_add_io()</function>. It takes the event
219 source object and returns the non-negative file descriptor
220 or a negative error number on error (see below).</para>
222 <para><function>sd_event_source_set_io_fd()</function>
223 changes the UNIX file descriptor of an I/O event source created
224 previously with <function>sd_event_add_io()</function>. It takes
225 the event source object and the new file descriptor.</para>
229 <title>Return Value</title>
231 <para>On success, these functions return 0 or a positive
232 integer. On failure, they return a negative errno-style error
237 <title>Errors</title>
239 <para>Returned values may indicate the following problems:</para>
243 <term><constant>-ENOMEM</constant></term>
245 <listitem><para>Not enough memory to allocate an object.</para></listitem>
249 <term><constant>-EINVAL</constant></term>
251 <listitem><para>An invalid argument has been passed.</para></listitem>
256 <term><constant>-ESTALE</constant></term>
258 <listitem><para>The event loop is already terminated.</para></listitem>
263 <term><constant>-ECHILD</constant></term>
265 <listitem><para>The event loop has been created in a different process.</para></listitem>
269 <term><constant>-EDOM</constant></term>
271 <listitem><para>The passed event source is not an I/O event source.</para></listitem>
276 <xi:include href="libelogind-pkgconfig.xml" />
279 <title>See Also</title>
282 <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
283 <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
284 <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
285 <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
286 <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
287 <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
288 <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
289 <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
290 <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
291 <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
292 <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
293 <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
294 <citerefentry><refentrytitle>sd_event_source_get_pending</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
295 <citerefentry project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
296 <citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>