Adding upstream version 252.22.upstream/252.22upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 238 insertions, 0 deletions

diff --git a/man/sd_listen_fds.xml b/man/sd_listen_fds.xml
new file mode 100644
index 0000000..c37771b
--- /dev/null
+++ b/man/sd_listen_fds.xml
@@ -0,0 +1,238 @@
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
+
+<refentry id="sd_listen_fds"
+  xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>sd_listen_fds</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd_listen_fds</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd_listen_fds</refname>
+    <refname>sd_listen_fds_with_names</refname>
+    <refname>SD_LISTEN_FDS_START</refname>
+    <refpurpose>Check for file descriptors passed by the system manager</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;systemd/sd-daemon.h&gt;</funcsynopsisinfo>
+
+      <funcsynopsisinfo>#define SD_LISTEN_FDS_START 3</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>int <function>sd_listen_fds</function></funcdef>
+        <paramdef>int <parameter>unset_environment</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_listen_fds_with_names</function></funcdef>
+        <paramdef>int <parameter>unset_environment</parameter></paramdef>
+        <paramdef>char*** <parameter>names</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <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>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
+    continuously 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 be visible to the service manager too. Most
+    importantly 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
+    <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
+    details) — if there's only one such file (see below).  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_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry> are
+    provided. In order to maximize flexibility, it is recommended to make these checks as loose as possible
+    without allowing incorrect setups. i.e. often, the actual port number a socket is bound to matters little
+    for the service to work, hence it should not be verified. On the other hand, whether a socket is a
+    datagram or stream socket matters a lot for the most common program logics and should be checked.</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>
+
+    <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> and
+    <varname>$LISTEN_FDNAMES</varname> environment variables before
+    returning (regardless of whether the function call itself
+    succeeded or not). Further calls to
+    <function>sd_listen_fds()</function> will then return zero, but the
+    variables are no longer inherited by child processes.</para>
+
+    <para><function>sd_listen_fds_with_names()</function> is like
+    <function>sd_listen_fds()</function>, but optionally also returns
+    an array of strings with identification names for the passed file
+    descriptors, if that is available and the
+    <parameter>names</parameter> parameter is non-<constant>NULL</constant>. This
+    information is read from the <varname>$LISTEN_FDNAMES</varname>
+    variable, which may contain a colon-separated list of names. For
+    socket-activated services, these names may be configured with the
+    <varname>FileDescriptorName=</varname> setting in socket unit
+    files, see
+    <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    for details. For file descriptors pushed into the file descriptor
+    store (see above), the name is set via the
+    <varname>FDNAME=</varname> field transmitted via
+    <function>sd_pid_notify_with_fds()</function>. The primary usecase
+    for these names are services which accept a variety of file
+    descriptors which are not recognizable with functions like
+    <function>sd_is_socket()</function> alone, and thus require
+    identification via a name. It is recommended to rely on named file
+    descriptors only if identification via
+    <function>sd_is_socket()</function> and related calls is not
+    sufficient. Note that the names used are not unique in any
+    way. The returned array of strings has as many entries as file
+    descriptors have been received, plus a final <constant>NULL</constant> pointer
+    terminating the array. The caller needs to free the array itself
+    and each of its elements with libc's <function>free()</function>
+    call after use. If the <parameter>names</parameter> parameter is
+    <constant>NULL</constant>, the call is entirely equivalent to
+    <function>sd_listen_fds()</function>.</para>
+
+    <para>Under specific conditions, the following automatic file
+    descriptor names are returned:
+
+    <table>
+      <title>
+         <command>Special names</command>
+      </title>
+
+      <tgroup cols='2'>
+        <thead>
+          <row>
+            <entry>Name</entry>
+            <entry>Description</entry>
+          </row>
+        </thead>
+        <tbody>
+          <row>
+            <entry><literal>unknown</literal></entry>
+            <entry>The process received no name for the specific file descriptor from the service manager.</entry>
+          </row>
+
+          <row>
+            <entry><literal>stored</literal></entry>
+            <entry>The file descriptor originates in the service manager's per-service file descriptor store, and the <varname>FDNAME=</varname> field was absent when the file descriptor was submitted to the service manager.</entry>
+          </row>
+
+          <row>
+            <entry><literal>connection</literal></entry>
+            <entry>The service was activated in per-connection style using <varname>Accept=yes</varname> in the socket unit file, and the file descriptor is the connection socket.</entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </table>
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Return Value</title>
+
+    <para>On failure, these calls returns a negative errno-style error
+    code. If
+    <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname> was
+    not set or was not correctly set for this daemon and hence no file
+    descriptors were received, 0 is returned. Otherwise, the number of
+    file descriptors passed is returned. The application may find them
+    starting with file descriptor SD_LISTEN_FDS_START, i.e. file
+    descriptor 3.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Notes</title>
+
+    <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
+
+    <para>Internally, <function>sd_listen_fds()</function> checks
+    whether the <varname>$LISTEN_PID</varname> environment variable
+    equals the daemon PID. If not, it returns immediately. Otherwise,
+    it parses the number passed in the <varname>$LISTEN_FDS</varname>
+    environment variable, then sets the FD_CLOEXEC flag for the parsed
+    number of file descriptors starting from SD_LISTEN_FDS_START.
+    Finally, it returns the parsed
+    number. <function>sd_listen_fds_with_names()</function> does the
+    same but also parses <varname>$LISTEN_FDNAMES</varname> if
+    set.</para>
+
+    <para>These functions are not designed for services that specify <varname>StandardInput=socket</varname>
+    as the <varname>$LISTEN_FDS</varname> variable is not set in their environment.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Environment</title>
+
+    <variablelist class='environment-variables'>
+      <varlistentry>
+        <term><varname>$LISTEN_PID</varname></term>
+        <term><varname>$LISTEN_FDS</varname></term>
+        <term><varname>$LISTEN_FDNAMES</varname></term>
+
+        <listitem><para>Set by the service manager for supervised
+        processes that use socket-based activation. This environment
+        variable specifies the data
+        <function>sd_listen_fds()</function> and
+        <function>sd_listen_fds_with_names()</function> parses. See
+        above for details.</para></listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+
+    <para>
+      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd-daemon</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>,
+      <citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>