From a06c92eb484d6193d5f45e3002acfe4d6518151a Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Thu, 10 Aug 2023 15:01:16 +0200
Subject: [PATCH] sd-event: explicit document what to do with
 epoll-incompatible fds

---
 man/sd_event_add_io.xml | 41 +++++++++++++++++++++++++----------------
 1 file changed, 25 insertions(+), 16 deletions(-)

diff --git a/man/sd_event_add_io.xml b/man/sd_event_add_io.xml
index 4201c68f0d0..d5495732a79 100644
--- a/man/sd_event_add_io.xml
+++ b/man/sd_event_add_io.xml
@@ -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>
-- 
2.47.3