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