build-sys: add check for --help width

[elogind.git] / man / sd_listen_fds.xml

diff --git a/man/sd_listen_fds.xml b/man/sd_listen_fds.xml
index aaabdbf3e84480495fa8c87cdd955a946c242d1b..4377745634195611b0461d3878cf7cd20d5b98d5 100644 (file)
--- a/man/sd_listen_fds.xml
+++ b/man/sd_listen_fds.xml
@@ -21,7 +21,8 @@
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 

-<refentry id="sd_listen_fds">
+<refentry id="sd_listen_fds"
+        xmlns:xi="http://www.w3.org/2001/XInclude">

 
         <refentryinfo>
                 <title>sd_listen_fds</title>
 
         <refentryinfo>
                 <title>sd_listen_fds</title>


@@ -72,7 +73,7 @@
                 <para>If the <parameter>unset_environment</parameter>
                 parameter is non-zero,
                 <function>sd_listen_fds()</function> will unset the
                 <para>If the <parameter>unset_environment</parameter>
                 parameter is non-zero,
                 <function>sd_listen_fds()</function> will unset the

-                <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname>
+                <varname>$LISTEN_FDS</varname> and <varname>$LISTEN_PID</varname>

                 environment variables before returning (regardless of
                 whether the function call itself succeeded or
                 not). Further calls to
                 environment variables before returning (regardless of
                 whether the function call itself succeeded or
                 not). Further calls to


@@ -82,10 +83,11 @@
 
                 <para>If a daemon receives more than one file
                 descriptor, they will be passed in the same order as
 
                 <para>If a daemon receives more than one file
                 descriptor, they will be passed in the same order as

-                configured in the systemd socket definition
-                file. Nonetheless, it is recommended to verify the
-                correct socket types before using them. To simplify
-                this checking, the functions
+                configured in the systemd socket unit file (see
+                <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                for details). Nonetheless, it is recommended to verify
+                the correct socket types before using them. To
+                simplify this checking, the functions

                 <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                 <citerefentry><refentrytitle>sd_is_socket</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                 <citerefentry><refentrytitle>sd_is_socket_inet</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                 <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                 <citerefentry><refentrytitle>sd_is_socket</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                 <citerefentry><refentrytitle>sd_is_socket_inet</refentrytitle><manvolnum>3</manvolnum></citerefentry>,


@@ -102,6 +104,16 @@
                 <para>This function call will set the FD_CLOEXEC flag
                 for all passed file descriptors to avoid further
                 inheritance to children of the calling process.</para>
                 <para>This function call will set the FD_CLOEXEC flag
                 for all passed file descriptors to avoid further
                 inheritance to children of the calling process.</para>

+
+                <para>If multiple socket units activate the same
+                service the order of the file descriptors passed to
+                its main process is undefined. If additional file
+                descriptors have been passed to the service manager
+                using
+                <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>'s
+                <literal>FDSTORE=1</literal> messages, these file
+                descriptors are passed last, in arbitrary order, and
+                with duplicates removed.</para>

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


@@ -121,13 +133,7 @@
         <refsect1>
                 <title>Notes</title>
 
         <refsect1>
                 <title>Notes</title>
 

-                <para>This function is provided by the reference
-                implementation of APIs for new-style daemons and
-                distributed with the systemd package. The algorithm it
-                implements is simple, and can easily be reimplemented
-                in daemons if it is important to support this
-                interface without using the reference
-                implementation.</para>
+                <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>

 
                 <para>Internally, this function checks whether the
                 <varname>$LISTEN_PID</varname> environment variable
 
                 <para>Internally, this function checks whether the
                 <varname>$LISTEN_PID</varname> environment variable


@@ -138,30 +144,6 @@
                 number of file descriptors starting from
                 SD_LISTEN_FDS_START. Finally, it returns the parsed
                 number.</para>
                 number of file descriptors starting from
                 SD_LISTEN_FDS_START. Finally, it returns the parsed
                 number.</para>

-
-                <para>For details about the algorithm check the
-                liberally licensed reference implementation sources:
-                <ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/libsystemd-daemon/sd-daemon.c"/>
-                and <ulink
-                url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h"/></para>
-
-                <para><function>sd_listen_fds()</function> is
-                implemented in the reference implementation's
-                <filename>sd-daemon.c</filename> and
-                <filename>sd-daemon.h</filename> files. These
-                interfaces are available as a shared library, which can
-                be compiled and linked to with the
-                <constant>libsystemd-daemon</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-                file. Alternatively, applications consuming these APIs
-                may copy the implementation into their source
-                tree. For more details about the reference
-                implementation see
-                <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
-
-                <para>If the reference implementation is used as
-                drop-in files and -DDISABLE_SYSTEMD is set during
-                compilation, this function will always return 0 and
-                otherwise become a NOP.</para>

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