a354329f72
With this change it is possible to send file descriptors to PID 1, via sd_pid_notify_with_fds() which PID 1 will store individually for each service, and pass via the usual fd passing logic on next invocation. This is useful for enable daemon reload schemes where daemons serialize their state to /run, push their fds into PID 1 and terminate, restoring their state on next start from the data in /run and passed in from PID 1. The fds are kept by PID 1 as long as no POLLHUP or POLLERR is seen on them, and the service they belong to are either not dead or failed, or have a job queued.
186 lines
9 KiB
XML
186 lines
9 KiB
XML
<?xml version='1.0'?> <!--*-nxml-*-->
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
|
|
<!--
|
|
This file is part of systemd.
|
|
|
|
Copyright 2010 Lennart Poettering
|
|
|
|
systemd is free software; you can redistribute it and/or modify it
|
|
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
|
|
(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
|
|
Lesser General Public License for more details.
|
|
|
|
You should have received a copy of the GNU Lesser General Public License
|
|
along with systemd; If not, see <http://www.gnu.org/licenses/>.
|
|
-->
|
|
|
|
<refentry id="sd_listen_fds"
|
|
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>
|
|
<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>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para><function>sd_listen_fds()</function> shall be
|
|
called by a daemon to check for file descriptors
|
|
passed by the init system as part of the socket-based
|
|
activation logic.</para>
|
|
|
|
<para>If the <parameter>unset_environment</parameter>
|
|
parameter is non-zero,
|
|
<function>sd_listen_fds()</function> will unset the
|
|
<varname>$LISTEN_FDS</varname> and <varname>$LISTEN_PID</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 fail,
|
|
but the variables are no longer inherited by child
|
|
processes.</para>
|
|
|
|
<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>
|
|
|
|
<para>If multiple socket units activate the same
|
|
service the order 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>
|
|
</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>
|
|
|
|
<xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
|
|
|
|
<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>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Environment</title>
|
|
|
|
<variablelist class='environment-variables'>
|
|
<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>
|