man/sd_event_add_io.xml

   1 <?xml version='1.0'?>
   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
   9 <refentry id="sd_event_add_io" xmlns:xi="http://www.w3.org/2001/XInclude">
  10
  11   <refentryinfo>
  12     <title>sd_event_add_io</title>
  13     <productname>systemd</productname>
  14   </refentryinfo>
  15
  16   <refmeta>
  17     <refentrytitle>sd_event_add_io</refentrytitle>
  18     <manvolnum>3</manvolnum>
  19   </refmeta>
  20
  21   <refnamediv>
  22     <refname>sd_event_add_io</refname>
  23     <refname>sd_event_source_get_io_events</refname>
  24     <refname>sd_event_source_set_io_events</refname>
  25     <refname>sd_event_source_get_io_revents</refname>
  26     <refname>sd_event_source_get_io_fd</refname>
  27     <refname>sd_event_source_set_io_fd</refname>
  28     <refname>sd_event_source_get_io_fd_own</refname>
  29     <refname>sd_event_source_set_io_fd_own</refname>
  30     <refname>sd_event_source</refname>
  31     <refname>sd_event_io_handler_t</refname>
  32
  33     <refpurpose>Add an I/O event source to an event loop</refpurpose>
  34   </refnamediv>
  35
  36   <refsynopsisdiv>
  37     <funcsynopsis>
  38       <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
  39
  40       <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo>
  41
  42       <funcprototype>
  43         <funcdef>typedef int (*<function>sd_event_io_handler_t</function>)</funcdef>
  44         <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
  45         <paramdef>int <parameter>fd</parameter></paramdef>
  46         <paramdef>uint32_t <parameter>revents</parameter></paramdef>
  47         <paramdef>void *<parameter>userdata</parameter></paramdef>
  48       </funcprototype>
  49
  50       <funcprototype>
  51         <funcdef>int <function>sd_event_add_io</function></funcdef>
  52         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  53         <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
  54         <paramdef>int <parameter>fd</parameter></paramdef>
  55         <paramdef>uint32_t <parameter>events</parameter></paramdef>
  56         <paramdef>sd_event_io_handler_t <parameter>handler</parameter></paramdef>
  57         <paramdef>void *<parameter>userdata</parameter></paramdef>
  58       </funcprototype>
  59
  60       <funcprototype>
  61         <funcdef>int <function>sd_event_source_get_io_events</function></funcdef>
  62         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  63         <paramdef>uint32_t *<parameter>events</parameter></paramdef>
  64       </funcprototype>
  65
  66       <funcprototype>
  67         <funcdef>int <function>sd_event_source_set_io_events</function></funcdef>
  68         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  69         <paramdef>uint32_t <parameter>events</parameter></paramdef>
  70       </funcprototype>
  71
  72       <funcprototype>
  73         <funcdef>int <function>sd_event_source_get_io_revents</function></funcdef>
  74         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  75         <paramdef>uint32_t *<parameter>revents</parameter></paramdef>
  76       </funcprototype>
  77
  78       <funcprototype>
  79         <funcdef>int <function>sd_event_source_get_io_fd</function></funcdef>
  80         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  81       </funcprototype>
  82
  83       <funcprototype>
  84         <funcdef>int <function>sd_event_source_set_io_fd</function></funcdef>
  85         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  86         <paramdef>int <parameter>fd</parameter></paramdef>
  87       </funcprototype>
  88
  89       <funcprototype>
  90         <funcdef>int <function>sd_event_source_get_io_fd_own</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_own</function></funcdef>
  96         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  97         <paramdef>int <parameter>b</parameter></paramdef>
  98       </funcprototype>
  99
 100     </funcsynopsis>
 101   </refsynopsisdiv>
 102
 103   <refsect1>
 104     <title>Description</title>
 105
 106     <para><function>sd_event_add_io()</function> adds a new I/O event
 107     source to an event loop. The event loop object is specified in the
 108     <parameter>event</parameter> parameter, the event source object is
 109     returned in the <parameter>source</parameter> parameter. The
 110     <parameter>fd</parameter> parameter takes the UNIX file descriptor
 111     to watch, which may refer to a socket, a FIFO, a message queue, a
 112     serial connection, a character device, or any other file descriptor
 113     compatible with Linux
 114     <citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
 115     <parameter>events</parameter> parameter takes a bit mask of events
 116     to watch for, a combination of the following event flags:
 117     <constant>EPOLLIN</constant>, <constant>EPOLLOUT</constant>,
 118     <constant>EPOLLRDHUP</constant>, <constant>EPOLLPRI</constant>,
 119     and <constant>EPOLLET</constant>, see
 120     <citerefentry project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 121     for details. The <parameter>handler</parameter> shall reference a
 122     function to call when the event source is triggered. The
 123     <parameter>userdata</parameter> pointer will be passed to the
 124     handler function, and may be chosen freely by the caller. The
 125     handler will also be passed the file descriptor the event was seen
 126     on, as well as the actual event flags. It's generally a subset of
 127     the events watched, however may additionally include
 128     <constant>EPOLLERR</constant> and <constant>EPOLLHUP</constant>.
 129     </para>
 130
 131     <para>By default, an event source will stay enabled
 132     continuously (<constant>SD_EVENT_ON</constant>), but this may be
 133     changed with
 134     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 135     If the handler function returns a negative error code, it will be
 136     disabled after the invocation, even if the
 137     <constant>SD_EVENT_ON</constant> mode was requested before. Note
 138     that an event source set to <constant>SD_EVENT_ON</constant> will
 139     fire continuously unless data is read from or written to the file
 140     descriptor to reset the mask of events seen.
 141     </para>
 142
 143     <para>Setting the I/O event mask to watch for to 0 does not mean
 144     that the event source won't be triggered anymore, as
 145     <constant>EPOLLHUP</constant> and <constant>EPOLLERR</constant>
 146     may be triggered even with a zero event mask. To temporarily
 147     disable an I/O event source use
 148     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 149     with <constant>SD_EVENT_OFF</constant> instead.</para>
 150
 151     <para>To destroy an event source object use
 152     <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 153     but note that the event source is only removed from the event loop
 154     when all references to the event source are dropped. To make sure
 155     an event source does not fire anymore, even if it is still referenced,
 156     disable the event source using
 157     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 158     with <constant>SD_EVENT_OFF</constant>.</para>
 159
 160     <para>If the second parameter of
 161     <function>sd_event_add_io()</function> is
 162     <constant>NULL</constant> no reference to the event source object
 163     is returned. In this case the event source is considered
 164     "floating", and will be destroyed implicitly when the event loop
 165     itself is destroyed.</para>
 166
 167     <para>It is recommended to use
 168     <function>sd_event_add_io()</function> only in conjunction with
 169     file descriptors that have <constant>O_NONBLOCK</constant> set, to
 170     ensure that all I/O operations from invoked handlers are properly
 171     asynchronous and non-blocking. Using file descriptors without
 172     <constant>O_NONBLOCK</constant> might result in unexpected
 173     starvation of other event sources. See
 174     <citerefentry project='man-pages'><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 175     for details on enabling <constant>O_NONBLOCK</constant> mode.</para>
 176
 177     <para><function>sd_event_source_get_io_events()</function> retrieves
 178     the configured mask of watched I/O events of an event source created
 179     previously with <function>sd_event_add_io()</function>. It takes
 180     the event source object and a pointer to a variable to store the
 181     mask in.</para>
 182
 183     <para><function>sd_event_source_set_io_events()</function>
 184     configures the mask of watched I/O events of an event source created
 185     previously with <function>sd_event_add_io()</function>. It takes the
 186     event source object and the new event mask.</para>
 187
 188     <para><function>sd_event_source_get_io_revents()</function>
 189     retrieves the I/O event mask of currently seen but undispatched
 190     events from an event source created previously with
 191     <function>sd_event_add_io()</function>. It takes the event source
 192     object and a pointer to a variable to store the event mask
 193     in. When called from a handler function on the handler's event
 194     source object this will return the same mask as passed to the
 195     handler's <parameter>revents</parameter> parameter. This call is
 196     primarily useful to check for undispatched events of an event
 197     source from the handler of an unrelated (possibly higher priority)
 198     event source. Note the relation between
 199     <function>sd_event_source_get_pending()</function> and
 200     <function>sd_event_source_get_io_revents()</function>: both
 201     functions will report non-zero results when there's an event
 202     pending for the event source, but the former applies to all event
 203     source types, the latter only to I/O event sources.</para>
 204
 205     <para><function>sd_event_source_get_io_fd()</function> retrieves
 206     the UNIX file descriptor of an event source created previously
 207     with <function>sd_event_add_io()</function>. It takes the event
 208     source object and returns the non-negative file descriptor
 209     or a negative error number on error (see below).</para>
 210
 211     <para><function>sd_event_source_set_io_fd()</function>
 212     changes the UNIX file descriptor of an I/O event source created
 213     previously with <function>sd_event_add_io()</function>. It takes
 214     the event source object and the new file descriptor.</para>
 215
 216     <para><function>sd_event_source_set_io_fd_own()</function> controls whether the file descriptor of the event source
 217     shall be closed automatically when the event source is freed, i.e. whether it shall be considered 'owned' by the
 218     event source object. By default it is not closed automatically, and the application has to do this on its own. The
 219     <parameter>b</parameter> parameter is a boolean parameter: if zero, the file descriptor is not closed automatically
 220     when the event source is freed, otherwise it is closed.</para>
 221
 222     <para><function>sd_event_source_get_io_fd_own()</function> may be used to query the current setting of the file
 223     descriptor ownership boolean flag as set with <function>sd_event_source_set_io_fd_own()</function>. It returns
 224     positive if the file descriptor is closed automatically when the event source is destroyed, zero if not, and
 225     negative on error.</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_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 290       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 291       <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 292       <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 293       <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 294       <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 295       <citerefentry><refentrytitle>sd_event_source_get_pending</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 296       <citerefentry project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 297       <citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 298     </para>
 299   </refsect1>
 300
 301 </refentry>