service: say explicitly that people should not use different NonBlocking= settings if they share socket units between multiple service units

Fixes: #29600

1 files changed, 18 insertions, 7 deletions

diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 735c98d1d6..123f1db30d 100644
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -1064,14 +1064,25 @@
 
       <varlistentry>
         <term><varname>NonBlocking=</varname></term>
-        <listitem><para>Set the <constant>O_NONBLOCK</constant> flag for all file descriptors passed via socket-based
-        activation. If true, all file descriptors >= 3 (i.e. all except stdin, stdout, stderr), excluding those passed
-        in via the file descriptor storage logic (see <varname>FileDescriptorStoreMax=</varname> for details), will
-        have the <constant>O_NONBLOCK</constant> flag set and hence are in non-blocking mode. This option is only
+        <listitem><para>Set the <constant>O_NONBLOCK</constant> flag for all file descriptors passed via
+        socket-based activation. If true, all file descriptors >= 3 (i.e. all except stdin, stdout, stderr),
+        excluding those passed in via the file descriptor storage logic (see
+        <varname>FileDescriptorStoreMax=</varname> for details), will have the
+        <constant>O_NONBLOCK</constant> flag set and hence are in non-blocking mode. This option is only
         useful in conjunction with a socket unit, as described in
-        <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> and has no
-        effect on file descriptors which were previously saved in the file-descriptor store for example.  Defaults to
-        false.</para></listitem>
+        <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+        and has no effect on file descriptors which were previously saved in the file-descriptor store for
+        example.  Defaults to false.</para>
+
+        <para>Note that if the same socket unit is configured to be passed to multiple service units (via the
+        <varname>Sockets=</varname> setting, see below), and these services have different
+        <varname>NonBlocking=</varname> configurations, the precise state of <constant>O_NONBLOCK</constant>
+        depends on the order in which these services are invoked, and will possibly change after service code
+        already took possession of the socket file descriptor, simply because the
+        <constant>O_NONBLOCK</constant> state of a socket is shared by all file descriptors referencing
+        it. Hence it is essential that all services sharing the same socket use the same
+        <varname>NonBlocking=</varname> configuration, and do not change the flag in service code
+        either.</para></listitem>
       </varlistentry>
 
       <varlistentry>