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