man/sd_event_add_io.xml

   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">
   4
   5 <!--
   6   This file is part of systemd.
   7
   8   Copyright 2015 Lennart Poettering
   9
  10   systemd 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.
  14
  15   systemd 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.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="sd_event_add_io" xmlns:xi="http://www.w3.org/2001/XInclude">
  25
  26   <refentryinfo>
  27     <title>sd_event_add_io</title>
  28     <productname>systemd</productname>
  29
  30     <authorgroup>
  31       <author>
  32         <contrib>Developer</contrib>
  33         <firstname>Lennart</firstname>
  34         <surname>Poettering</surname>
  35         <email>lennart@poettering.net</email>
  36       </author>
  37     </authorgroup>
  38   </refentryinfo>
  39
  40   <refmeta>
  41     <refentrytitle>sd_event_add_io</refentrytitle>
  42     <manvolnum>3</manvolnum>
  43   </refmeta>
  44
  45   <refnamediv>
  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>
  54
  55     <refpurpose>Add an I/O event source to an event loop</refpurpose>
  56   </refnamediv>
  57
  58   <refsynopsisdiv>
  59     <funcsynopsis>
  60       <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
  61
  62       <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo>
  63
  64       <funcprototype>
  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>
  70       </funcprototype>
  71
  72       <funcprototype>
  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>
  80       </funcprototype>
  81
  82       <funcprototype>
  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>
  86       </funcprototype>
  87
  88       <funcprototype>
  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>
  92       </funcprototype>
  93
  94       <funcprototype>
  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>
  98       </funcprototype>
  99
 100       <funcprototype>
 101         <funcdef>int <function>sd_event_source_get_io_fd</function></funcdef>
 102         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
 103       </funcprototype>
 104
 105       <funcprototype>
 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>
 109       </funcprototype>
 110
 111     </funcsynopsis>
 112   </refsynopsisdiv>
 113
 114   <refsect1>
 115     <title>Description</title>
 116
 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>.
 140     </para>
 141
 142     <para>By default, an event source will stay enabled
 143     continuously (<constant>SD_EVENT_ON</constant>), but this may be
 144     changed with
 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.
 152     </para>
 153
 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>
 161
 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>
 170
 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>
 177
 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>
 187
 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
 192     mask in.</para>
 193
 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>
 198
 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>
 215
 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>
 221
 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>
 226   </refsect1>
 227
 228   <refsect1>
 229     <title>Return Value</title>
 230
 231     <para>On success, these functions return 0 or a positive
 232     integer. On failure, they return a negative errno-style error
 233     code.</para>
 234   </refsect1>
 235
 236   <refsect1>
 237     <title>Errors</title>
 238
 239     <para>Returned values may indicate the following problems:</para>
 240
 241     <variablelist>
 242       <varlistentry>
 243         <term><constant>-ENOMEM</constant></term>
 244
 245         <listitem><para>Not enough memory to allocate an object.</para></listitem>
 246       </varlistentry>
 247
 248       <varlistentry>
 249         <term><constant>-EINVAL</constant></term>
 250
 251         <listitem><para>An invalid argument has been passed.</para></listitem>
 252
 253       </varlistentry>
 254
 255       <varlistentry>
 256         <term><constant>-ESTALE</constant></term>
 257
 258         <listitem><para>The event loop is already terminated.</para></listitem>
 259
 260       </varlistentry>
 261
 262       <varlistentry>
 263         <term><constant>-ECHILD</constant></term>
 264
 265         <listitem><para>The event loop has been created in a different process.</para></listitem>
 266       </varlistentry>
 267
 268       <varlistentry>
 269         <term><constant>-EDOM</constant></term>
 270
 271         <listitem><para>The passed event source is not an I/O event source.</para></listitem>
 272       </varlistentry>
 273     </variablelist>
 274   </refsect1>
 275
 276   <xi:include href="libsystemd-pkgconfig.xml" />
 277
 278   <refsect1>
 279     <title>See Also</title>
 280
 281     <para>
 282       <citerefentry><refentrytitle>systemd</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>
 297     </para>
 298   </refsect1>
 299
 300 </refentry>