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