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 elogind.
   7
   8   Copyright 2015 Lennart Poettering
   9
  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.
  14
  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.
  19
  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/>.
  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>elogind</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;elogind/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 <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>,
 131     see <citerefentry
 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>
 142
 143     <para>By default, the I/O event source will stay enabled
 144     continuously (<constant>SD_EVENT_ON</constant>), but this may be
 145     changed with
 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.
 153     </para>
 154
 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>
 162
 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>
 171
 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>
 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     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>
 187
 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>
 193
 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>
 198
 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>
 215
 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>
 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 to set.</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 errors 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="libelogind-pkgconfig.xml" />
 277
 278   <refsect1>
 279     <title>See Also</title>
 280
 281     <para>
 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>
 297     </para>
 298   </refsect1>
 299
 300 </refentry>