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   SPDX-License-Identifier: LGPL-2.1+
   8
   9
  10   Copyright 2015 Lennart Poettering
  11 -->
  12
  13 <refentry id="sd_event_add_io" xmlns:xi="http://www.w3.org/2001/XInclude">
  14
  15   <refentryinfo>
  16     <title>sd_event_add_io</title>
  17     <productname>elogind</productname>
  18
  19     <authorgroup>
  20       <author>
  21         <contrib>Developer</contrib>
  22         <firstname>Lennart</firstname>
  23         <surname>Poettering</surname>
  24         <email>lennart@poettering.net</email>
  25       </author>
  26     </authorgroup>
  27   </refentryinfo>
  28
  29   <refmeta>
  30     <refentrytitle>sd_event_add_io</refentrytitle>
  31     <manvolnum>3</manvolnum>
  32   </refmeta>
  33
  34   <refnamediv>
  35     <refname>sd_event_add_io</refname>
  36     <refname>sd_event_source_get_io_events</refname>
  37     <refname>sd_event_source_set_io_events</refname>
  38     <refname>sd_event_source_get_io_revents</refname>
  39     <refname>sd_event_source_get_io_fd</refname>
  40     <refname>sd_event_source_set_io_fd</refname>
  41     <refname>sd_event_source_get_io_fd_own</refname>
  42     <refname>sd_event_source_set_io_fd_own</refname>
  43     <refname>sd_event_source</refname>
  44     <refname>sd_event_io_handler_t</refname>
  45
  46     <refpurpose>Add an I/O event source to an event loop</refpurpose>
  47   </refnamediv>
  48
  49   <refsynopsisdiv>
  50     <funcsynopsis>
  51       <funcsynopsisinfo>#include &lt;elogind/sd-event.h&gt;</funcsynopsisinfo>
  52
  53       <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo>
  54
  55       <funcprototype>
  56         <funcdef>typedef int (*<function>sd_event_io_handler_t</function>)</funcdef>
  57         <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
  58         <paramdef>int <parameter>fd</parameter></paramdef>
  59         <paramdef>uint32_t <parameter>revents</parameter></paramdef>
  60         <paramdef>void *<parameter>userdata</parameter></paramdef>
  61       </funcprototype>
  62
  63       <funcprototype>
  64         <funcdef>int <function>sd_event_add_io</function></funcdef>
  65         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  66         <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
  67         <paramdef>int <parameter>fd</parameter></paramdef>
  68         <paramdef>uint32_t <parameter>events</parameter></paramdef>
  69         <paramdef>sd_event_io_handler_t <parameter>handler</parameter></paramdef>
  70         <paramdef>void *<parameter>userdata</parameter></paramdef>
  71       </funcprototype>
  72
  73       <funcprototype>
  74         <funcdef>int <function>sd_event_source_get_io_events</function></funcdef>
  75         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  76         <paramdef>uint32_t *<parameter>events</parameter></paramdef>
  77       </funcprototype>
  78
  79       <funcprototype>
  80         <funcdef>int <function>sd_event_source_set_io_events</function></funcdef>
  81         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  82         <paramdef>uint32_t <parameter>events</parameter></paramdef>
  83       </funcprototype>
  84
  85       <funcprototype>
  86         <funcdef>int <function>sd_event_source_get_io_revents</function></funcdef>
  87         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  88         <paramdef>uint32_t *<parameter>revents</parameter></paramdef>
  89       </funcprototype>
  90
  91       <funcprototype>
  92         <funcdef>int <function>sd_event_source_get_io_fd</function></funcdef>
  93         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  94       </funcprototype>
  95
  96       <funcprototype>
  97         <funcdef>int <function>sd_event_source_set_io_fd</function></funcdef>
  98         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  99         <paramdef>int <parameter>fd</parameter></paramdef>
 100       </funcprototype>
 101
 102       <funcprototype>
 103         <funcdef>int <function>sd_event_source_get_io_fd_own</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_own</function></funcdef>
 109         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
 110         <paramdef>int <parameter>b</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
 229     <para><function>sd_event_source_set_io_fd_own()</function> controls whether the file descriptor of the event source
 230     shall be closed automatically when the event source is freed, i.e. whether it shall be considered 'owned' by the
 231     event source object. By default it is not closed automatically, and the application has to do this on its own. The
 232     <parameter>b</parameter> parameter is a boolean parameter: if zero, the file descriptor is not closed automatically
 233     when the event source is freed, otherwise it is closed.</para>
 234
 235     <para><function>sd_event_source_get_io_fd_own()</function> may be used to query the current setting of the file
 236     descriptor ownership boolean flag as set with <function>sd_event_source_set_io_fd_own()</function>. It returns
 237     positive if the file descriptor is closed automatically when the event source is destroyed, zero if not, and
 238     negative on error.</para>
 239   </refsect1>
 240
 241   <refsect1>
 242     <title>Return Value</title>
 243
 244     <para>On success, these functions return 0 or a positive
 245     integer. On failure, they return a negative errno-style error
 246     code.</para>
 247   </refsect1>
 248
 249   <refsect1>
 250     <title>Errors</title>
 251
 252     <para>Returned values may indicate the following problems:</para>
 253
 254     <variablelist>
 255       <varlistentry>
 256         <term><constant>-ENOMEM</constant></term>
 257
 258         <listitem><para>Not enough memory to allocate an object.</para></listitem>
 259       </varlistentry>
 260
 261       <varlistentry>
 262         <term><constant>-EINVAL</constant></term>
 263
 264         <listitem><para>An invalid argument has been passed.</para></listitem>
 265
 266       </varlistentry>
 267
 268       <varlistentry>
 269         <term><constant>-ESTALE</constant></term>
 270
 271         <listitem><para>The event loop is already terminated.</para></listitem>
 272
 273       </varlistentry>
 274
 275       <varlistentry>
 276         <term><constant>-ECHILD</constant></term>
 277
 278         <listitem><para>The event loop has been created in a different process.</para></listitem>
 279       </varlistentry>
 280
 281       <varlistentry>
 282         <term><constant>-EDOM</constant></term>
 283
 284         <listitem><para>The passed event source is not an I/O event source.</para></listitem>
 285       </varlistentry>
 286     </variablelist>
 287   </refsect1>
 288
 289   <xi:include href="libelogind-pkgconfig.xml" />
 290
 291   <refsect1>
 292     <title>See Also</title>
 293
 294     <para>
 295       <!-- 0 /// elogind is in section 8
 296       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 297       <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 298       --><!-- else -->
 299       <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 300       <!-- // 0 -->
 301       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 302       <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 303       <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 304       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 305       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 306       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 307       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 308       <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 309       <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 310       <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 311       <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 312       <citerefentry><refentrytitle>sd_event_source_get_pending</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 313       <citerefentry project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 314       <citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 315     </para>
 316   </refsect1>
 317
 318 </refentry>