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

Fixes: #29600
(cherry picked from commit 2856219)
(cherry picked from commit 009e780)
(cherry picked from commit 2dbf94e)

Author: poettering

man/systemd.service.xml

@@ -1009,14 +1009,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>