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