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>/<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 definition
  87                 file. Nonetheless, it is recommended to verify the
  88                 correct socket types before using them. To simplify
  89                 this checking, the functions
  90                 <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  91                 <citerefentry><refentrytitle>sd_is_socket</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  92                 <citerefentry><refentrytitle>sd_is_socket_inet</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  93                 <citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  94                 are provided. In order to maximize flexibility, it is
  95                 recommended to make these checks as loose as possible
  96                 without allowing incorrect setups. i.e. often, the
  97                 actual port number a socket is bound to matters little
  98                 for the service to work, hence it should not be
  99                 verified. On the other hand, whether a socket is a
 100                 datagram or stream socket matters a lot for the most
 101                 common program logics and should be checked.</para>
 102
 103                 <para>This function call will set the FD_CLOEXEC flag
 104                 for all passed file descriptors to avoid further
 105                 inheritance to children of the calling process.</para>
 106         </refsect1>
 107
 108         <refsect1>
 109                 <title>Return Value</title>
 110
 111                 <para>On failure, this call returns a negative
 112                 errno-style error code. If
 113                 <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname>
 114                 was not set or was not correctly set for this daemon and
 115                 hence no file descriptors were received, 0 is
 116                 returned. Otherwise, the number of file descriptors
 117                 passed is returned. The application may find them
 118                 starting with file descriptor SD_LISTEN_FDS_START,
 119                 i.e. file descriptor 3.</para>
 120         </refsect1>
 121
 122         <refsect1>
 123                 <title>Notes</title>
 124
 125                 <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
 126
 127                 <para>Internally, this function checks whether the
 128                 <varname>$LISTEN_PID</varname> environment variable
 129                 equals the daemon PID. If not, it returns
 130                 immediately. Otherwise, it parses the number passed in
 131                 the <varname>$LISTEN_FDS</varname> environment
 132                 variable, then sets the FD_CLOEXEC flag for the parsed
 133                 number of file descriptors starting from
 134                 SD_LISTEN_FDS_START. Finally, it returns the parsed
 135                 number.</para>
 136         </refsect1>
 137
 138         <refsect1>
 139                 <title>Environment</title>
 140
 141                 <variablelist class='environment-variables'>
 142                         <varlistentry>
 143                                 <term><varname>$LISTEN_PID</varname></term>
 144                                 <term><varname>$LISTEN_FDS</varname></term>
 145
 146                                 <listitem><para>Set by the init system
 147                                 for supervised processes that use
 148                                 socket-based activation. This
 149                                 environment variable specifies the
 150                                 data
 151                                 <function>sd_listen_fds()</function>
 152                                 parses. See above for
 153                                 details.</para></listitem>
 154                         </varlistentry>
 155                 </variablelist>
 156         </refsect1>
 157
 158         <refsect1>
 159                 <title>See Also</title>
 160
 161                 <para>
 162                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 163                         <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 164                         <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 165                         <citerefentry><refentrytitle>sd_is_socket</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 166                         <citerefentry><refentrytitle>sd_is_socket_inet</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 167                         <citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 168                         <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 169                         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 170                         <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 171                 </para>
 172         </refsect1>
 173
 174 </refentry>