shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2025-02-03 17:47:28 +03:00
Code

sd-event: explicit document what to do with epoll-incompatible fds

Browse Source
This commit is contained in:
Lennart Poettering 2023-08-10 15:01:16 +02:00
parent 9050632ec0
commit a06c92eb48
1 changed files with 25 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
man/sd_event_add_io.xml
View File

@ -100,22 +100,21 @@
<refsect1>
<title>Description</title>
<para><function>sd_event_add_io()</function> adds a new I/O event
source to an event loop. The event loop object is specified in the
<parameter>event</parameter> parameter, the event source object is
returned in the <parameter>source</parameter> parameter. The
<parameter>fd</parameter> parameter takes the UNIX file descriptor
to watch, which may refer to a socket, a FIFO, a message queue, a
serial connection, a character device, or any other file descriptor
compatible with Linux
<citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
<parameter>events</parameter> parameter takes a bit mask of events
to watch for, a combination of the following event flags:
<constant>EPOLLIN</constant>, <constant>EPOLLOUT</constant>,
<constant>EPOLLRDHUP</constant>, <constant>EPOLLPRI</constant>,
and <constant>EPOLLET</constant>, see
<citerefentry project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
for details.</para>
<para><function>sd_event_add_io()</function> adds a new I/O event source to an event loop. The event loop
object is specified in the <parameter>event</parameter> parameter, the event source object is returned in
the <parameter>source</parameter> parameter. The <parameter>fd</parameter> parameter takes the UNIX file
descriptor to watch, which may refer to a socket, a FIFO, a message queue, a serial connection, a
character device, or any other file descriptor compatible with Linux <citerefentry
project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
<parameter>events</parameter> parameter takes a bit mask of events to watch for, a combination of the
following event flags: <constant>EPOLLIN</constant>, <constant>EPOLLOUT</constant>,
<constant>EPOLLRDHUP</constant>, <constant>EPOLLPRI</constant>, and <constant>EPOLLET</constant>, see
<citerefentry
project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> for
details. Note that not all file descriptors are compatible with epoll, for example regular file or
directories are not. If this function is called with a file descriptor that does not support epoll,
<constant>-EPERM</constant> is returned (also see below). In most cases such file descriptors may be
treated as always-readable or always-writable, so that IO event watching is unnecessary.</para>
<para>The <parameter>handler</parameter> is a function to call when the event source is triggered or
<constant>NULL</constant>. The <parameter>userdata</parameter> pointer will be passed to the handler
@ -278,6 +277,16 @@
<listitem><para>The passed event source is not an I/O event source.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-EPERM</constant></term>
<listitem><para>The passed file descriptor does not support the <citerefentry
project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>
API, for example because it is a regular file or directory. See <citerefentry
project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
for details.</para></listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>