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