2015-10-04 15:36:19 +00:00
<?xml version='1.0'?> <!-- * - Mode: nxml; nxml - child - indent: 2; indent - tabs - mode: nil - * -->
2010-06-22 22:31:54 +00:00
< !DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2015-06-18 17:47:44 +00:00
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
2010-06-22 22:31:54 +00:00
<!--
This file is part of systemd.
Copyright 2010 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
2012-04-11 22:20:58 +00:00
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
2010-06-22 22:31:54 +00:00
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
2012-04-11 22:20:58 +00:00
Lesser General Public License for more details.
2010-06-22 22:31:54 +00:00
2012-04-11 22:20:58 +00:00
You should have received a copy of the GNU Lesser General Public License
2010-06-22 22:31:54 +00:00
along with systemd; If not, see <http: / / w w w . g n u . o r g / l i c e n s e s /> .
-->
2014-02-21 03:39:26 +00:00
<refentry id= "sd_listen_fds"
2015-02-04 02:14:13 +00:00
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo >
<title > sd_listen_fds</title>
<productname > systemd</productname>
<authorgroup >
<author >
<contrib > Developer</contrib>
<firstname > Lennart</firstname>
<surname > Poettering</surname>
<email > lennart@poettering.net</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta >
<refentrytitle > sd_listen_fds</refentrytitle>
<manvolnum > 3</manvolnum>
</refmeta>
<refnamediv >
<refname > sd_listen_fds</refname>
2015-10-04 15:36:19 +00:00
<refname > sd_listen_fds_with_names</refname>
2015-02-04 02:14:13 +00:00
<refname > SD_LISTEN_FDS_START</refname>
<refpurpose > Check for file descriptors passed by the system manager</refpurpose>
</refnamediv>
<refsynopsisdiv >
<funcsynopsis >
<funcsynopsisinfo > #include < systemd/sd-daemon.h> </funcsynopsisinfo>
<funcsynopsisinfo > #define SD_LISTEN_FDS_START 3</funcsynopsisinfo>
<funcprototype >
<funcdef > int <function > sd_listen_fds</function> </funcdef>
<paramdef > int <parameter > unset_environment</parameter> </paramdef>
</funcprototype>
2015-10-04 15:36:19 +00:00
<funcprototype >
<funcdef > int <function > sd_listen_fds_with_names</function> </funcdef>
<paramdef > int <parameter > unset_environment</parameter> </paramdef>
<paramdef > char*** <parameter > names</parameter> </paramdef>
</funcprototype>
2015-02-04 02:14:13 +00:00
</funcsynopsis>
</refsynopsisdiv>
<refsect1 >
<title > Description</title>
2015-10-04 15:36:19 +00:00
<para > <function > sd_listen_fds()</function> may be invoked by a
daemon to check for file descriptors passed by the service manager as
part of the socket-based activation logic. It returns the number
of received file descriptors. If no file descriptors have been
2014-08-03 05:11:12 +00:00
received, zero is returned. The first file descriptor may be found
2015-10-04 15:36:19 +00:00
at file descriptor number 3
(i.e. <constant > SD_LISTEN_FDS_START</constant> ), the remaining
descriptors follow at 4, 5, 6, ..., if any.</para>
2015-02-04 02:14:13 +00:00
<para > If a daemon receives more than one file descriptor, they
will be passed in the same order as configured in the systemd
socket unit file (see
<citerefentry > <refentrytitle > systemd.socket</refentrytitle> <manvolnum > 5</manvolnum> </citerefentry>
for details). Nonetheless, it is recommended to verify the correct
socket types before using them. To simplify this checking, the
functions
<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>
2014-08-03 05:11:12 +00:00
<para > If multiple socket units activate the same service, the order
2015-02-04 02:14:13 +00:00
of the file descriptors passed to its main process is undefined.
If additional file descriptors have been passed to the service
manager using
<citerefentry > <refentrytitle > sd_pid_notify_with_fds</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> 's
<literal > FDSTORE=1</literal> messages, these file descriptors are
passed last, in arbitrary order, and with duplicates
removed.</para>
2015-10-04 15:36:19 +00:00
<para > If the <parameter > unset_environment</parameter> parameter is
non-zero, <function > sd_listen_fds()</function> will unset the
<varname > $LISTEN_FDS</varname> , <varname > $LISTEN_PID</varname> and
<varname > $LISTEN_FDNAMES</varname> environment variables before
returning (regardless of whether the function call itself
succeeded or not). Further calls to
<function > sd_listen_fds()</function> will then return zero, but the
variables are no longer inherited by child processes.</para>
<para > <function > sd_listen_fds_with_names()</function> is like
2014-08-03 05:11:12 +00:00
<function > sd_listen_fds()</function> , but optionally also returns
2015-10-04 15:36:19 +00:00
an array of strings with identification names for the passed file
2014-08-03 05:11:12 +00:00
descriptors, if that is available and the
2015-10-04 15:36:19 +00:00
<parameter > names</parameter> parameter is non-NULL. This
information is read from the <varname > $LISTEN_FDNAMES</varname>
variable, which may contain a colon-separated list of names. For
socket-activated services, these names may be configured with the
<varname > FileDescriptorName=</varname> setting in socket unit
files, see
<citerefentry > <refentrytitle > systemd.socket</refentrytitle> <manvolnum > 5</manvolnum> </citerefentry>
for details. For file descriptors pushed into the file descriptor
2014-08-03 05:11:12 +00:00
store (see above), the name is set via the
2015-10-04 15:36:19 +00:00
<varname > FDNAME=</varname> field transmitted via
<function > sd_pid_notify_with_fds()</function> . The primary usecase
for these names are services which accept a variety of file
descriptors which are not recognizable with functions like
<function > sd_is_socket()</function> alone, and thus require
identification via a name. It is recommended to rely on named file
descriptors only if identification via
<function > sd_is_socket()</function> and related calls is not
sufficient. Note that the names used are not unique in any
way. The returned array of strings has as many entries as file
2014-08-03 05:11:37 +00:00
descriptors have been received, plus a final NULL pointer
2015-10-04 15:36:19 +00:00
terminating the array. The caller needs to free the array itself
2015-10-06 10:32:15 +00:00
and each of its elements with libc's <function > free()</function>
2015-10-04 15:36:19 +00:00
call after use. If the <parameter > names</parameter> parameter is
2014-08-03 05:11:12 +00:00
NULL, the call is entirely equivalent to
2015-10-04 15:36:19 +00:00
<function > sd_listen_fds()</function> .</para>
2014-08-03 05:11:12 +00:00
<para > Under specific conditions, the following automatic file
2015-10-04 15:36:19 +00:00
descriptor names are returned:
<table >
<title >
<command > Special names</command>
</title>
<tgroup cols= '2' >
<thead >
<row >
<entry > Name</entry>
<entry > Description</entry>
</row>
</thead>
<tbody >
<row >
<entry > <literal > unknown</literal> </entry>
<entry > The process received no name for the specific file descriptor from the service manager.</entry>
</row>
<row >
<entry > <literal > stored</literal> </entry>
<entry > The file descriptor originates in the service manager's per-service file descriptor store, and the <varname > FDNAME=</varname> field was absent when the file descriptor was submitted to the service manager.</entry>
</row>
<row >
<entry > <literal > connection</literal> </entry>
<entry > The service was activated in per-connection style using <varname > Accept=yes</varname> in the socket unit file, and the file descriptor is the connection socket.</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
2015-02-04 02:14:13 +00:00
</refsect1>
<refsect1 >
<title > Return Value</title>
2015-10-04 15:36:19 +00:00
<para > On failure, these calls returns a negative errno-style error
2015-02-04 02:14:13 +00:00
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>
<xi:include href= "libsystemd-pkgconfig.xml" xpointer= "pkgconfig-text" />
2015-10-04 15:36:19 +00:00
<para > Internally, <function > sd_listen_fds()</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>
2015-02-04 02:14:13 +00:00
environment variable, then sets the FD_CLOEXEC flag for the parsed
number of file descriptors starting from SD_LISTEN_FDS_START.
2015-10-04 15:36:19 +00:00
Finally, it returns the parsed
number. <function > sd_listen_fds_with_names()</function> does the
same but also parses <varname > $LISTEN_FDNAMES</varname> if
set.</para>
2015-02-04 02:14:13 +00:00
</refsect1>
<refsect1 >
<title > Environment</title>
<variablelist class= 'environment-variables' >
<varlistentry >
<term > <varname > $LISTEN_PID</varname> </term>
<term > <varname > $LISTEN_FDS</varname> </term>
2015-10-04 15:36:19 +00:00
<term > <varname > $LISTEN_FDNAMES</varname> </term>
2015-02-04 02:14:13 +00:00
2015-10-04 15:36:19 +00:00
<listitem > <para > Set by the service manager for supervised
processes that use socket-based activation. This environment
variable specifies the data
<function > sd_listen_fds()</function> and
<function > sd_listen_fds_with_names()</function> parses. See
above for details.</para> </listitem>
2015-02-04 02:14:13 +00:00
</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> ,
2015-10-04 15:36:19 +00:00
<citerefentry > <refentrytitle > sd_pid_notify_with_fds</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
2015-02-04 02:14:13 +00:00
<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>
2010-06-22 22:31:54 +00:00
</refentry>