man: elaborate on fd ownership in sd_event_add_io(3)

Replaces: #12239

diff --git a/man/sd_event_add_io.xml b/man/sd_event_add_io.xml
index 4f2b09bf59f17cbe35533c8e166a190af3c758bd..398b938e3c21809795c9303325c4428a34182641 100644 (file)
--- a/man/sd_event_add_io.xml
+++ b/man/sd_event_add_io.xml
@@ -161,6 +161,12 @@
     "floating", and will be destroyed implicitly when the event loop
     itself is destroyed.</para>
 
+    <para>Note that this call does not take possession of the file descriptor passed in, ownership (and thus
+    the duty to close it when it is no longer needed) remains with the caller. However, with the
+    <function>sd_event_source_set_io_fd_own()</function> call (see below) the event source may optionally
+    take ownership of the file descriptor after the event source has been created. In that case the file
+    descriptor is closed automatically as soon as the event source is released.</para>
+
     <para>It is recommended to use
     <function>sd_event_add_io()</function> only in conjunction with
     file descriptors that have <constant>O_NONBLOCK</constant> set, to