a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt<?xml version='1.0'?> <!--*-nxml-*-->

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt<refentry id="sd_listen_fds">

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <refentryinfo>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <title>sd_listen_fds</title>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <productname>systemd</productname>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <authorgroup>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <author>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <contrib>Developer</contrib>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <firstname>Lennart</firstname>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <surname>Poettering</surname>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <email>lennart@poettering.net</email>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt </author>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt </authorgroup>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt </refentryinfo>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <refmeta>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <refentrytitle>sd_listen_fds</refentrytitle>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <manvolnum>3</manvolnum>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt </refmeta>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <refnamediv>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <refname>sd_listen_fds</refname>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <refpurpose>Check for file descriptors passed by the init system.</refpurpose>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt </refnamediv>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <refsynopsisdiv>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <funcsynopsis>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <funcsynopsisinfo>#include &lt;systemd/sd-daemon.h&gt;</funcsynopsisinfo>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <funcsynopsisinfo>#define SD_LISTEN_FDS_START 3</funcsynopsisinfo>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <funcprototype>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <funcdef>int <function>sd_listen_fds</function></funcdef>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <paramdef>int <parameter>unset_environment</parameter></paramdef>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt </funcprototype>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt </funcsynopsis>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt </refsynopsisdiv>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <refsect1>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <title>Description</title>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <para><function>sd_listen_fds()</function> shall be

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt called by a daemon to check for file descriptors

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt passed by the init system as part of the socket-based

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt activation logic.</para>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <para>If the <parameter>unset_environment</parameter>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt parameter is non-zero

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <function>sd_listen_fds()</function> will unset the

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt environment variables before returning (regardless

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt whether the function call itself succeeded or

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt not). Further calls to

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <function>sd_listen_fds()</function> will then fail,

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt but the variables are no longer inherited by child

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt processes.</para>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <para>If a daemon receives more than one file

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt descriptor, they will be passed in the same order as

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt configured in the systemd socket definition

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt file. Nonetheless it is recommended to verify the

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt correct socket types before using them. To simplify

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt this checking the functions

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_is_socket</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_is_socket_inet</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry>

are provided. In order to maximize flexibility it is

recommended to make these checks as loose as possible

without allowing incorrect setups. i.e. often the

actual port number a socket is bound to matters little

for the service to work, hence it should not be

verified. On the other hand, whether a socket is a

datagram or stream socket matters a lot for the most

common program logics and should be checked.</para>

<para>This function call will set the FD_CLOEXEC flag

for all passed file descriptors to avoid further

inheritance to children of the calling process.</para>

</refsect1>

<refsect1>

<title>Return Value</title>

<para>On failure, this call returns a negative

errno-style error code. If

<varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname>

was not set or was not correctly set for this daemon and

hence no file descriptors were received, 0 is

returned. Otherwise the number of file descriptors

passed is returned. The application may find them

starting with file descriptor SD_LISTEN_FDS_START,

i.e. file descriptor 3.</para>

</refsect1>

<refsect1>

<title>Notes</title>

<para>This function is provided by the reference

implementation of APIs for new-style daemons and

distributed with the systemd package. The algorithm it

implements is simple, and can easily be reimplemented

in daemons if it is important to support this

interface without using the reference

implementation.</para>

<para>Internally, this function checks whether the

<varname>$LISTEN_PID</varname> environment variable

equals the daemon PID. If not, it returns

immediately. Otherwise it parses the number passed in

the <varname>$LISTEN_FDS</varname> environment

variable, then sets the FD_CLOEXEC flag for the parsed

number of file descriptors starting from

SD_LISTEN_FDS_START. Finally it returns the parsed

number.</para>

<para>For details about the algorithm check the

liberally licensed reference implementation sources:

<ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/sd-daemon.c"/>

resp. <ulink

url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h"/></para>

<para><function>sd_listen_fds()</function> is

implemented in the reference implementation's

<filename>sd-daemon.c</filename> and

<filename>sd-daemon.h</filename> files. These

interfaces are available as shared library, which can

be compiled and linked to with the

<literal>libsystemd-daemon</literal>

<citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>

file. Alternatively, applications consuming these APIs

may copy the implementation into their source

tree. For more details about the reference

implementation see

<citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>

<para>If the reference implementation is used as

drop-in files and -DDISABLE_SYSTEMD is set during

compilation this function will always return 0 and

otherwise become a NOP.</para>

</refsect1>

<refsect1>

<title>Environment</title>

<variablelist>

<varlistentry>

<term><varname>$LISTEN_PID</varname></term>

<term><varname>$LISTEN_FDS</varname></term>

<listitem><para>Set by the init system

for supervised processes that use

socket-based activation. This

environment variable specifies the

data

<function>sd_listen_fds()</function>

parses. See above for

details.</para></listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1>

<title>See Also</title>

<para>

<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_is_socket</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_is_socket_inet</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>

</para>

</refsect1>

</refentry>