man/sd_listen_fds.xml

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