man: document that shutdown() is only sometimes OK on sockets passed in via socket...

[elogind.git] / man / systemd.socket.xml

diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml
index 28730ca4416c1aae5c02dba35955c74757c88a4d..040305c632c55a12d6d3e0207704e33d20421d47 100644 (file)
--- a/man/systemd.socket.xml
+++ b/man/systemd.socket.xml
@@ -48,7 +48,7 @@
         </refnamediv>
 
         <refsynopsisdiv>
         </refnamediv>
 
         <refsynopsisdiv>

-                <para><filename>systemd.socket</filename></para>
+                <para><filename><replaceable>socket</replaceable>.socket</filename></para>

         </refsynopsisdiv>
 
         <refsect1>
         </refsynopsisdiv>
 
         <refsect1>


@@ -75,7 +75,7 @@
                 <option>ExecStartPre=</option>,
                 <option>ExecStartPost=</option>,
                 <option>ExecStopPre=</option> and
                 <option>ExecStartPre=</option>,
                 <option>ExecStartPost=</option>,
                 <option>ExecStopPre=</option> and

-                <option>ExecStoptPost=</option> commands are executed
+                <option>ExecStopPost=</option> commands are executed

                 in, and in
                 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                 which define the way the processes are
                 in, and in
                 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                 which define the way the processes are


@@ -374,17 +374,30 @@
                                 and only one service unit is spawned
                                 for all connections (also see
                                 above). This value is ignored for
                                 and only one service unit is spawned
                                 for all connections (also see
                                 above). This value is ignored for

-                                datagram sockets and FIFOs where
-                                a single service unit unconditionally
+                                datagram sockets and FIFOs where a
+                                single service unit unconditionally

                                 handles all incoming traffic. Defaults
                                 to <option>false</option>. For
                                 performance reasons, it is recommended
                                 to write new daemons only in a way
                                 that is suitable for
                                 handles all incoming traffic. Defaults
                                 to <option>false</option>. For
                                 performance reasons, it is recommended
                                 to write new daemons only in a way
                                 that is suitable for

-                                <option>Accept=false</option>. This
-                                option is mostly useful to allow
-                                daemons designed for usage with
-                                <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+                                <option>Accept=false</option>. A
+                                daemon listening on an AF_UNIX socket
+                                may, but does not need to, call
+                                <citerefentry><refentrytitle>close</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+                                on the received socket before
+                                exiting. However, it must not unlink
+                                the socket from a filesystem. It
+                                should note invoke
+                                <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+                                on sockets it got with
+                                <varname>Accept=false</varname>, but
+                                it may do so for sockets it got with
+                                <varname>Accept=true</varname> set.
+                                Setting <varname>Accept=true</varname>
+                                is mostly useful to allow daemons
+                                designed for usage with
+                                <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>

                                 to work unmodified with systemd socket
                                 activation.</para></listitem>
                         </varlistentry>
                                 to work unmodified with systemd socket
                                 activation.</para></listitem>
                         </varlistentry>


@@ -686,6 +699,14 @@
                           <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                   </para>
                           <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                   </para>

+
+                  <para>
+                          For more extensive descriptions see the "Systemd for Developers" series:
+                          <ulink url="http://0pointer.de/blog/projects/socket-activation.html">Socket Activation</ulink>,
+                          <ulink url="http://0pointer.de/blog/projects/socket-activation2.html">Socket Activation, part II</ulink>,
+                          <ulink url="http://0pointer.de/blog/projects/inetd.html">Converting inetd Services</ulink>,
+                          <ulink url="http://0pointer.de/blog/projects/socket-activated-containers.html">Socket Activated Internet Services and OS Containers</ulink>.
+                  </para>

         </refsect1>
 
 </refentry>
         </refsect1>
 
 </refentry>