From c896eb7ad65f4dbe968fdf01fa51e9ef4d2d11ed Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Thu, 28 Oct 2021 11:05:22 +0200
Subject: [PATCH] man: document that daemons can close fds they receive via
 sd_listen_fds() if they like

Fixes: #18872
---
 man/sd_listen_fds.xml | 26 ++++++++++++++++++--------
 1 file changed, 18 insertions(+), 8 deletions(-)

diff --git a/man/sd_listen_fds.xml b/man/sd_listen_fds.xml
index 9ddd129aae6..a71c291adf2 100644
--- a/man/sd_listen_fds.xml
+++ b/man/sd_listen_fds.xml
@@ -45,14 +45,24 @@
   <refsect1>
     <title>Description</title>
 
-    <para><function>sd_listen_fds()</function> may be invoked by a
-    daemon to check for file descriptors passed by the service manager as
-    part of the socket-based activation logic. It returns the number
-    of received file descriptors. If no file descriptors have been
-    received, zero is returned. The first file descriptor may be found
-    at file descriptor number 3
-    (i.e. <constant>SD_LISTEN_FDS_START</constant>), the remaining
-    descriptors follow at 4, 5, 6, …, if any.</para>
+    <para><function>sd_listen_fds()</function> may be invoked by a daemon to check for file descriptors
+    passed by the service manager as part of the socket-based activation logic. It returns the number of
+    received file descriptors. If no file descriptors have been received, zero is returned. The first file
+    descriptor may be found at file descriptor number 3 (i.e. <constant>SD_LISTEN_FDS_START</constant>), the
+    remaining descriptors follow at 4, 5, 6, …, if any.</para>
+
+    <para>The file descriptors passed this way may be closed at will by the processes receiving them: it's up
+    to the processes themselves to close them after use or whether to leave them open until the process exits
+    (in which case the kernel closes them automatically). Note that the file descriptors received by daemons
+    are duplicates of the file descriptors the service manager originally allocated and bound and of which it
+    continously keeps a copy (except if <varname>Accept=yes</varname> is used). This means any socket option
+    changes and other changes made to the sockets will visible to the service manager too. Most importanly
+    this means it's generally not a good idea to invoke <citerefentry
+    project='man-pages'><refentrytitle>shutdown</refentrytitle><manvolnum>2</manvolnum></citerefentry> on
+    such sockets, since it will shut down communication on the file descriptor the service manager holds for
+    the same socket, too. Also note that if a daemon is restarted (and its associated sockets are not) it
+    will receive file descriptors to the very same sockets as the earlier invocations, thus all socket
+    options applied then will still apply.</para>
 
     <para>If a daemon receives more than one file descriptor, they will be passed in the same order as
     configured in the systemd socket unit file (see