sd_listen_fds.xml 9.91 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
<?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
11
12
  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
13
14
15
16
17
  (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
18
  Lesser General Public License for more details.
19

20
  You should have received a copy of the GNU Lesser General Public License
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
  along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->

<refentry id="sd_listen_fds">

        <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>
                <refpurpose>Check for file descriptors passed by the init system.</refpurpose>
        </refnamediv>

        <refsynopsisdiv>
                <funcsynopsis>
52
                        <funcsynopsisinfo>#include &lt;systemd/sd-daemon.h&gt;</funcsynopsisinfo>
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

                        <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>/<varname>$LISTEN_PID</varname>
                environment variables before returning (regardless
                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 definition
                file. 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
Kay Sievers's avatar
Kay Sievers committed
93
                recommended to make these checks as loose as possible
94
95
96
97
98
                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
Kay Sievers's avatar
Kay Sievers committed
99
                common program logics and should be checked.</para>
100
101
102
103
104
105
106
107
108
109
110
111

                <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>
112
113
                was not set or was not correctly set for this daemon and
                hence no file descriptors were received, 0 is
114
                returned. Otherwise the number of file descriptors
Kay Sievers's avatar
Kay Sievers committed
115
                passed is returned. The application may find them
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
                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:
Michael Biebl's avatar
Michael Biebl committed
143
                <ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/sd-daemon.c"/>
144
                resp. <ulink
Michael Biebl's avatar
Michael Biebl committed
145
                url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h"/></para>
146
147

                <para><function>sd_listen_fds()</function> is
148
                implemented in the reference implementation's
149
                <filename>sd-daemon.c</filename> and
150
151
152
153
154
155
156
157
158
                <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
159
                <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
160
161
162
163
164

                <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>
165
166
        </refsect1>

167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
        <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>

187
188
189
190
        <refsect1>
                <title>See Also</title>

                <para>
Lennart Poettering's avatar
Lennart Poettering committed
191
                        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
192
                        <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
193
194
195
196
197
198
199
200
201
202
203
                        <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>