man/sd_listen_fds.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   5
   6 <refentry id="sd_listen_fds"
   7   xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>sd_listen_fds</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>sd_listen_fds</refentrytitle>
  16     <manvolnum>3</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>sd_listen_fds</refname>
  21     <refname>sd_listen_fds_with_names</refname>
  22     <refname>SD_LISTEN_FDS_START</refname>
  23     <refpurpose>Check for file descriptors passed by the system manager</refpurpose>
  24   </refnamediv>
  25
  26   <refsynopsisdiv>
  27     <funcsynopsis>
  28       <funcsynopsisinfo>#include &lt;systemd/sd-daemon.h&gt;</funcsynopsisinfo>
  29
  30       <funcsynopsisinfo>#define SD_LISTEN_FDS_START 3</funcsynopsisinfo>
  31
  32       <funcprototype>
  33         <funcdef>int <function>sd_listen_fds</function></funcdef>
  34         <paramdef>int <parameter>unset_environment</parameter></paramdef>
  35       </funcprototype>
  36
  37       <funcprototype>
  38         <funcdef>int <function>sd_listen_fds_with_names</function></funcdef>
  39         <paramdef>int <parameter>unset_environment</parameter></paramdef>
  40         <paramdef>char*** <parameter>names</parameter></paramdef>
  41       </funcprototype>
  42     </funcsynopsis>
  43   </refsynopsisdiv>
  44
  45   <refsect1>
  46     <title>Description</title>
  47
  48     <para><function>sd_listen_fds()</function> may be invoked by a
  49     daemon to check for file descriptors passed by the service manager as
  50     part of the socket-based activation logic. It returns the number
  51     of received file descriptors. If no file descriptors have been
  52     received, zero is returned. The first file descriptor may be found
  53     at file descriptor number 3
  54     (i.e. <constant>SD_LISTEN_FDS_START</constant>), the remaining
  55     descriptors follow at 4, 5, 6, …, if any.</para>
  56
  57     <para>If a daemon receives more than one file descriptor, they
  58     will be passed in the same order as configured in the systemd
  59     socket unit file (see
  60     <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  61     for details). Nonetheless, it is recommended to verify the correct
  62     socket types before using them. To simplify this checking, the
  63     functions
  64     <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  65     <citerefentry><refentrytitle>sd_is_socket</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  66     <citerefentry><refentrytitle>sd_is_socket_inet</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  67     <citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  68     are provided. In order to maximize flexibility, it is recommended
  69     to make these checks as loose as possible without allowing
  70     incorrect setups. i.e. often, the actual port number a socket is
  71     bound to matters little for the service to work, hence it should
  72     not be verified. On the other hand, whether a socket is a datagram
  73     or stream socket matters a lot for the most common program logics
  74     and should be checked.</para>
  75
  76     <para>This function call will set the FD_CLOEXEC flag for all
  77     passed file descriptors to avoid further inheritance to children
  78     of the calling process.</para>
  79
  80     <para>If multiple socket units activate the same service, the order
  81     of the file descriptors passed to its main process is undefined.
  82     If additional file descriptors have been passed to the service
  83     manager using
  84     <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>'s
  85     <literal>FDSTORE=1</literal> messages, these file descriptors are
  86     passed last, in arbitrary order, and with duplicates
  87     removed.</para>
  88
  89     <para>If the <parameter>unset_environment</parameter> parameter is
  90     non-zero, <function>sd_listen_fds()</function> will unset the
  91     <varname>$LISTEN_FDS</varname>, <varname>$LISTEN_PID</varname> and
  92     <varname>$LISTEN_FDNAMES</varname> environment variables before
  93     returning (regardless of whether the function call itself
  94     succeeded or not). Further calls to
  95     <function>sd_listen_fds()</function> will then return zero, but the
  96     variables are no longer inherited by child processes.</para>
  97
  98     <para><function>sd_listen_fds_with_names()</function> is like
  99     <function>sd_listen_fds()</function>, but optionally also returns
 100     an array of strings with identification names for the passed file
 101     descriptors, if that is available and the
 102     <parameter>names</parameter> parameter is non-NULL. This
 103     information is read from the <varname>$LISTEN_FDNAMES</varname>
 104     variable, which may contain a colon-separated list of names. For
 105     socket-activated services, these names may be configured with the
 106     <varname>FileDescriptorName=</varname> setting in socket unit
 107     files, see
 108     <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 109     for details. For file descriptors pushed into the file descriptor
 110     store (see above), the name is set via the
 111     <varname>FDNAME=</varname> field transmitted via
 112     <function>sd_pid_notify_with_fds()</function>. The primary usecase
 113     for these names are services which accept a variety of file
 114     descriptors which are not recognizable with functions like
 115     <function>sd_is_socket()</function> alone, and thus require
 116     identification via a name. It is recommended to rely on named file
 117     descriptors only if identification via
 118     <function>sd_is_socket()</function> and related calls is not
 119     sufficient. Note that the names used are not unique in any
 120     way. The returned array of strings has as many entries as file
 121     descriptors have been received, plus a final NULL pointer
 122     terminating the array. The caller needs to free the array itself
 123     and each of its elements with libc's <function>free()</function>
 124     call after use. If the <parameter>names</parameter> parameter is
 125     NULL, the call is entirely equivalent to
 126     <function>sd_listen_fds()</function>.</para>
 127
 128     <para>Under specific conditions, the following automatic file
 129     descriptor names are returned:
 130
 131     <table>
 132       <title>
 133          <command>Special names</command>
 134       </title>
 135
 136       <tgroup cols='2'>
 137         <thead>
 138           <row>
 139             <entry>Name</entry>
 140             <entry>Description</entry>
 141           </row>
 142         </thead>
 143         <tbody>
 144           <row>
 145             <entry><literal>unknown</literal></entry>
 146             <entry>The process received no name for the specific file descriptor from the service manager.</entry>
 147           </row>
 148
 149           <row>
 150             <entry><literal>stored</literal></entry>
 151             <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>
 152           </row>
 153
 154           <row>
 155             <entry><literal>connection</literal></entry>
 156             <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>
 157           </row>
 158         </tbody>
 159       </tgroup>
 160     </table>
 161     </para>
 162   </refsect1>
 163
 164   <refsect1>
 165     <title>Return Value</title>
 166
 167     <para>On failure, these calls returns a negative errno-style error
 168     code. If
 169     <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname> was
 170     not set or was not correctly set for this daemon and hence no file
 171     descriptors were received, 0 is returned. Otherwise, the number of
 172     file descriptors passed is returned. The application may find them
 173     starting with file descriptor SD_LISTEN_FDS_START, i.e. file
 174     descriptor 3.</para>
 175   </refsect1>
 176
 177   <refsect1>
 178     <title>Notes</title>
 179
 180     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
 181
 182     <para>Internally, <function>sd_listen_fds()</function> checks
 183     whether the <varname>$LISTEN_PID</varname> environment variable
 184     equals the daemon PID. If not, it returns immediately. Otherwise,
 185     it parses the number passed in the <varname>$LISTEN_FDS</varname>
 186     environment variable, then sets the FD_CLOEXEC flag for the parsed
 187     number of file descriptors starting from SD_LISTEN_FDS_START.
 188     Finally, it returns the parsed
 189     number. <function>sd_listen_fds_with_names()</function> does the
 190     same but also parses <varname>$LISTEN_FDNAMES</varname> if
 191     set.</para>
 192   </refsect1>
 193
 194   <refsect1>
 195     <title>Environment</title>
 196
 197     <variablelist class='environment-variables'>
 198       <varlistentry>
 199         <term><varname>$LISTEN_PID</varname></term>
 200         <term><varname>$LISTEN_FDS</varname></term>
 201         <term><varname>$LISTEN_FDNAMES</varname></term>
 202
 203         <listitem><para>Set by the service manager for supervised
 204         processes that use socket-based activation. This environment
 205         variable specifies the data
 206         <function>sd_listen_fds()</function> and
 207         <function>sd_listen_fds_with_names()</function> parses. See
 208         above for details.</para></listitem>
 209       </varlistentry>
 210     </variablelist>
 211   </refsect1>
 212
 213   <refsect1>
 214     <title>See Also</title>
 215
 216     <para>
 217       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 218       <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 219       <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 220       <citerefentry><refentrytitle>sd_is_socket</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 221       <citerefentry><refentrytitle>sd_is_socket_inet</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 222       <citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 223       <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 224       <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 225       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 226       <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 227     </para>
 228   </refsect1>
 229
 230 </refentry>