man/sd_listen_fds.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   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   This file is part of systemd.
   7
   8   Copyright 2010 Lennart Poettering
   9
  10   systemd is free software; you can redistribute it and/or modify it
  11   under the terms of the GNU Lesser General Public License as published by
  12   the Free Software Foundation; either version 2.1 of the License, or
  13   (at your option) any later version.
  14
  15   systemd is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   Lesser General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="sd_listen_fds"
  25         xmlns:xi="http://www.w3.org/2001/XInclude">
  26
  27         <refentryinfo>
  28                 <title>sd_listen_fds</title>
  29                 <productname>systemd</productname>
  30
  31                 <authorgroup>
  32                         <author>
  33                                 <contrib>Developer</contrib>
  34                                 <firstname>Lennart</firstname>
  35                                 <surname>Poettering</surname>
  36                                 <email>lennart@poettering.net</email>
  37                         </author>
  38                 </authorgroup>
  39         </refentryinfo>
  40
  41         <refmeta>
  42                 <refentrytitle>sd_listen_fds</refentrytitle>
  43                 <manvolnum>3</manvolnum>
  44         </refmeta>
  45
  46         <refnamediv>
  47                 <refname>sd_listen_fds</refname>
  48                 <refname>SD_LISTEN_FDS_START</refname>
  49                 <refpurpose>Check for file descriptors passed by the system manager</refpurpose>
  50         </refnamediv>
  51
  52         <refsynopsisdiv>
  53                 <funcsynopsis>
  54                         <funcsynopsisinfo>#include &lt;systemd/sd-daemon.h&gt;</funcsynopsisinfo>
  55
  56                         <funcsynopsisinfo>#define SD_LISTEN_FDS_START 3</funcsynopsisinfo>
  57
  58                         <funcprototype>
  59                                 <funcdef>int <function>sd_listen_fds</function></funcdef>
  60                                 <paramdef>int <parameter>unset_environment</parameter></paramdef>
  61                         </funcprototype>
  62                 </funcsynopsis>
  63         </refsynopsisdiv>
  64
  65         <refsect1>
  66                 <title>Description</title>
  67
  68                 <para><function>sd_listen_fds()</function> shall be
  69                 called by a daemon to check for file descriptors
  70                 passed by the init system as part of the socket-based
  71                 activation logic.</para>
  72
  73                 <para>If the <parameter>unset_environment</parameter>
  74                 parameter is non-zero,
  75                 <function>sd_listen_fds()</function> will unset the
  76                 <varname>$LISTEN_FDS</varname> and <varname>$LISTEN_PID</varname>
  77                 environment variables before returning (regardless of
  78                 whether the function call itself succeeded or
  79                 not). Further calls to
  80                 <function>sd_listen_fds()</function> will then fail,
  81                 but the variables are no longer inherited by child
  82                 processes.</para>
  83
  84                 <para>If a daemon receives more than one file
  85                 descriptor, they will be passed in the same order as
  86                 configured in the systemd socket unit file (see
  87                 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  88                 for details). Nonetheless, it is recommended to verify
  89                 the correct socket types before using them. To
  90                 simplify this checking, the functions
  91                 <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  92                 <citerefentry><refentrytitle>sd_is_socket</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  93                 <citerefentry><refentrytitle>sd_is_socket_inet</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  94                 <citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  95                 are provided. In order to maximize flexibility, it is
  96                 recommended to make these checks as loose as possible
  97                 without allowing incorrect setups. i.e. often, the
  98                 actual port number a socket is bound to matters little
  99                 for the service to work, hence it should not be
 100                 verified. On the other hand, whether a socket is a
 101                 datagram or stream socket matters a lot for the most
 102                 common program logics and should be checked.</para>
 103
 104                 <para>This function call will set the FD_CLOEXEC flag
 105                 for all passed file descriptors to avoid further
 106                 inheritance to children of the calling process.</para>
 107
 108                 <para>If multiple socket units activate the same
 109                 service the order of the file descriptors passed to
 110                 its main process is undefined. If additional file
 111                 descriptors have been passed to the service manager
 112                 using
 113                 <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>'s
 114                 <literal>FDSTORE=1</literal> messages, these file
 115                 descriptors are passed last, in arbitrary order, and
 116                 with duplicates removed.</para>
 117         </refsect1>
 118
 119         <refsect1>
 120                 <title>Return Value</title>
 121
 122                 <para>On failure, this call returns a negative
 123                 errno-style error code. If
 124                 <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname>
 125                 was not set or was not correctly set for this daemon and
 126                 hence no file descriptors were received, 0 is
 127                 returned. Otherwise, the number of file descriptors
 128                 passed is returned. The application may find them
 129                 starting with file descriptor SD_LISTEN_FDS_START,
 130                 i.e. file descriptor 3.</para>
 131         </refsect1>
 132
 133         <refsect1>
 134                 <title>Notes</title>
 135
 136                 <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
 137
 138                 <para>Internally, this function checks whether the
 139                 <varname>$LISTEN_PID</varname> environment variable
 140                 equals the daemon PID. If not, it returns
 141                 immediately. Otherwise, it parses the number passed in
 142                 the <varname>$LISTEN_FDS</varname> environment
 143                 variable, then sets the FD_CLOEXEC flag for the parsed
 144                 number of file descriptors starting from
 145                 SD_LISTEN_FDS_START. Finally, it returns the parsed
 146                 number.</para>
 147         </refsect1>
 148
 149         <refsect1>
 150                 <title>Environment</title>
 151
 152                 <variablelist class='environment-variables'>
 153                         <varlistentry>
 154                                 <term><varname>$LISTEN_PID</varname></term>
 155                                 <term><varname>$LISTEN_FDS</varname></term>
 156
 157                                 <listitem><para>Set by the init system
 158                                 for supervised processes that use
 159                                 socket-based activation. This
 160                                 environment variable specifies the
 161                                 data
 162                                 <function>sd_listen_fds()</function>
 163                                 parses. See above for
 164                                 details.</para></listitem>
 165                         </varlistentry>
 166                 </variablelist>
 167         </refsect1>
 168
 169         <refsect1>
 170                 <title>See Also</title>
 171
 172                 <para>
 173                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 174                         <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 175                         <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 176                         <citerefentry><refentrytitle>sd_is_socket</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 177                         <citerefentry><refentrytitle>sd_is_socket_inet</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 178                         <citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 179                         <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 180                         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 181                         <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 182                 </para>
 183         </refsect1>
 184
 185 </refentry>