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 <citerefentry
125 project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
126 <parameter>events</parameter> parameter takes a bit mask of I/O
127 events to watch the file descriptor for, a combination of the
128 following event flags: <constant>EPOLLIN</constant>,
129 <constant>EPOLLOUT</constant>, <constant>EPOLLRDHUP</constant>,
130 <constant>EPOLLPRI</constant> and <constant>EPOLLET</constant>,
132 project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
133 for details. The <parameter>handler</parameter> shall reference a
134 function to call when the I/O event source is triggered. The
135 handler function will be passed the
136 <parameter>userdata</parameter> pointer, which may be chosen
137 freely by the caller. The handler will also be passed the file
138 descriptor the event was seen on as well as the actual event flags
139 seen. It's generally a subset of the events watched, however may
140 additionally have <constant>EPOLLERR</constant> and
141 <constant>EPOLLHUP</constant> set.</para>
143 <para>By default, the I/O event source will stay enabled
144 continuously (<constant>SD_EVENT_ON</constant>), but this may be
146 <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
147 If the handler function returns a negative error code, it will be
148 disabled after the invocation, even if the
149 <constant>SD_EVENT_ON</constant> mode was requested before. Note
150 that an I/O event source set to <constant>SD_EVENT_ON</constant> will
151 fire continuously unless data is read or written to the file
152 descriptor in order to reset the mask of events seen.
155 <para>Setting the I/O event mask to watch for to 0 does not mean
156 that the event source won't be triggered anymore, as
157 <constant>EPOLLHUP</constant> and <constant>EPOLLERR</constant>
158 may be triggered even with a zero event mask. To temporarily
159 disable an I/O event source use
160 <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
161 with <constant>SD_EVENT_OFF</constant> instead.</para>
163 <para>To destroy an event source object use
164 <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
165 but note that the event source is only removed from the event loop
166 when all references to the event source are dropped. To make sure
167 an event source does not fire anymore, even when there's still a
168 reference to it kept, consider setting the event source to
169 <constant>SD_EVENT_OFF</constant> with
170 <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
172 <para>If the second parameter of
173 <function>sd_event_add_io()</function> is passed as NULL no
174 reference to the event source object is returned. In this case the
175 event source is considered "floating", and will be destroyed
176 implicitly when the event loop 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 starving of other event sources. See <citerefentry
185 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 I/O event mask to watch of an I/O 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
192 event mask in.</para>
194 <para><function>sd_event_source_set_io_events()</function> changes the
195 configured I/O event mask to watch of an I/O event source created previously
196 with <function>sd_event_add_io()</function>. It takes the event
197 source object and the new event mask to set.</para>
199 <para><function>sd_event_source_get_io_events()</function>
200 retrieves the I/O event mask of currently seen but undispatched
201 events from an I/O 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 I/O event source created previously
218 with <function>sd_event_add_io()</function>. It takes the event
219 source object and returns the positive file descriptor in the return
220 value, 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 to set.</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 errors 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>1</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>