Lennart Poettering | f937842 | 2010-06-23 00:31:54 +0200 | [diff] [blame] | 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 |
Lennart Poettering | 5430f7f | 2012-04-12 00:20:58 +0200 | [diff] [blame^] | 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 |
Lennart Poettering | f937842 | 2010-06-23 00:31:54 +0200 | [diff] [blame] | 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 |
Lennart Poettering | 5430f7f | 2012-04-12 00:20:58 +0200 | [diff] [blame^] | 18 | Lesser General Public License for more details. |
Lennart Poettering | f937842 | 2010-06-23 00:31:54 +0200 | [diff] [blame] | 19 | |
Lennart Poettering | 5430f7f | 2012-04-12 00:20:58 +0200 | [diff] [blame^] | 20 | You should have received a copy of the GNU Lesser General Public License |
Lennart Poettering | f937842 | 2010-06-23 00:31:54 +0200 | [diff] [blame] | 21 | along with systemd; If not, see <http://www.gnu.org/licenses/>. |
| 22 | --> |
| 23 | |
| 24 | <refentry id="sd_listen_fds"> |
| 25 | |
| 26 | <refentryinfo> |
| 27 | <title>sd_listen_fds</title> |
| 28 | <productname>systemd</productname> |
| 29 | |
| 30 | <authorgroup> |
| 31 | <author> |
| 32 | <contrib>Developer</contrib> |
| 33 | <firstname>Lennart</firstname> |
| 34 | <surname>Poettering</surname> |
| 35 | <email>lennart@poettering.net</email> |
| 36 | </author> |
| 37 | </authorgroup> |
| 38 | </refentryinfo> |
| 39 | |
| 40 | <refmeta> |
| 41 | <refentrytitle>sd_listen_fds</refentrytitle> |
| 42 | <manvolnum>3</manvolnum> |
| 43 | </refmeta> |
| 44 | |
| 45 | <refnamediv> |
| 46 | <refname>sd_listen_fds</refname> |
| 47 | <refpurpose>Check for file descriptors passed by the init system.</refpurpose> |
| 48 | </refnamediv> |
| 49 | |
| 50 | <refsynopsisdiv> |
| 51 | <funcsynopsis> |
Lennart Poettering | a822cbf | 2011-12-19 13:11:42 +0100 | [diff] [blame] | 52 | <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo> |
Lennart Poettering | f937842 | 2010-06-23 00:31:54 +0200 | [diff] [blame] | 53 | |
| 54 | <funcsynopsisinfo>#define SD_LISTEN_FDS_START 3</funcsynopsisinfo> |
| 55 | |
| 56 | <funcprototype> |
| 57 | <funcdef>int <function>sd_listen_fds</function></funcdef> |
| 58 | <paramdef>int <parameter>unset_environment</parameter></paramdef> |
| 59 | </funcprototype> |
| 60 | </funcsynopsis> |
| 61 | </refsynopsisdiv> |
| 62 | |
| 63 | <refsect1> |
| 64 | <title>Description</title> |
| 65 | |
| 66 | <para><function>sd_listen_fds()</function> shall be |
| 67 | called by a daemon to check for file descriptors |
| 68 | passed by the init system as part of the socket-based |
| 69 | activation logic.</para> |
| 70 | |
| 71 | <para>If the <parameter>unset_environment</parameter> |
| 72 | parameter is non-zero |
| 73 | <function>sd_listen_fds()</function> will unset the |
| 74 | <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname> |
| 75 | environment variables before returning (regardless |
| 76 | whether the function call itself succeeded or |
| 77 | not). Further calls to |
| 78 | <function>sd_listen_fds()</function> will then fail, |
| 79 | but the variables are no longer inherited by child |
| 80 | processes.</para> |
| 81 | |
| 82 | <para>If a daemon receives more than one file |
| 83 | descriptor, they will be passed in the same order as |
| 84 | configured in the systemd socket definition |
| 85 | file. Nonetheless it is recommended to verify the |
| 86 | correct socket types before using them. To simplify |
| 87 | this checking the functions |
| 88 | <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>, |
| 89 | <citerefentry><refentrytitle>sd_is_socket</refentrytitle><manvolnum>3</manvolnum></citerefentry>, |
| 90 | <citerefentry><refentrytitle>sd_is_socket_inet</refentrytitle><manvolnum>3</manvolnum></citerefentry>, |
| 91 | <citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry> |
| 92 | are provided. In order to maximize flexibility it is |
Kay Sievers | 436c44a | 2010-06-24 17:25:16 +0200 | [diff] [blame] | 93 | recommended to make these checks as loose as possible |
Lennart Poettering | f937842 | 2010-06-23 00:31:54 +0200 | [diff] [blame] | 94 | without allowing incorrect setups. i.e. often the |
| 95 | actual port number a socket is bound to matters little |
| 96 | for the service to work, hence it should not be |
| 97 | verified. On the other hand, whether a socket is a |
| 98 | datagram or stream socket matters a lot for the most |
Kay Sievers | af62c70 | 2010-06-25 00:04:29 +0200 | [diff] [blame] | 99 | common program logics and should be checked.</para> |
Lennart Poettering | f937842 | 2010-06-23 00:31:54 +0200 | [diff] [blame] | 100 | |
| 101 | <para>This function call will set the FD_CLOEXEC flag |
| 102 | for all passed file descriptors to avoid further |
| 103 | inheritance to children of the calling process.</para> |
| 104 | </refsect1> |
| 105 | |
| 106 | <refsect1> |
| 107 | <title>Return Value</title> |
| 108 | |
| 109 | <para>On failure, this call returns a negative |
| 110 | errno-style error code. If |
| 111 | <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname> |
Conrad Meyer | ad678a0 | 2010-07-06 18:24:38 -0700 | [diff] [blame] | 112 | was not set or was not correctly set for this daemon and |
| 113 | hence no file descriptors were received, 0 is |
Lennart Poettering | f937842 | 2010-06-23 00:31:54 +0200 | [diff] [blame] | 114 | returned. Otherwise the number of file descriptors |
Kay Sievers | af62c70 | 2010-06-25 00:04:29 +0200 | [diff] [blame] | 115 | passed is returned. The application may find them |
Lennart Poettering | f937842 | 2010-06-23 00:31:54 +0200 | [diff] [blame] | 116 | starting with file descriptor SD_LISTEN_FDS_START, |
| 117 | i.e. file descriptor 3.</para> |
| 118 | </refsect1> |
| 119 | |
| 120 | <refsect1> |
| 121 | <title>Notes</title> |
| 122 | |
| 123 | <para>This function is provided by the reference |
| 124 | implementation of APIs for new-style daemons and |
| 125 | distributed with the systemd package. The algorithm it |
| 126 | implements is simple, and can easily be reimplemented |
| 127 | in daemons if it is important to support this |
| 128 | interface without using the reference |
| 129 | implementation.</para> |
| 130 | |
| 131 | <para>Internally, this function checks whether the |
| 132 | <varname>$LISTEN_PID</varname> environment variable |
| 133 | equals the daemon PID. If not, it returns |
| 134 | immediately. Otherwise it parses the number passed in |
| 135 | the <varname>$LISTEN_FDS</varname> environment |
| 136 | variable, then sets the FD_CLOEXEC flag for the parsed |
| 137 | number of file descriptors starting from |
| 138 | SD_LISTEN_FDS_START. Finally it returns the parsed |
| 139 | number.</para> |
| 140 | |
| 141 | <para>For details about the algorithm check the |
| 142 | liberally licensed reference implementation sources: |
Michael Biebl | a26c9cc | 2012-02-13 17:46:46 +0100 | [diff] [blame] | 143 | <ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/sd-daemon.c"/> |
Lennart Poettering | f937842 | 2010-06-23 00:31:54 +0200 | [diff] [blame] | 144 | resp. <ulink |
Michael Biebl | a26c9cc | 2012-02-13 17:46:46 +0100 | [diff] [blame] | 145 | url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h"/></para> |
Lennart Poettering | f937842 | 2010-06-23 00:31:54 +0200 | [diff] [blame] | 146 | |
| 147 | <para><function>sd_listen_fds()</function> is |
Lennart Poettering | 71e6c1c | 2011-09-22 21:13:41 +0200 | [diff] [blame] | 148 | implemented in the reference implementation's |
Lennart Poettering | f937842 | 2010-06-23 00:31:54 +0200 | [diff] [blame] | 149 | <filename>sd-daemon.c</filename> and |
Lennart Poettering | 71e6c1c | 2011-09-22 21:13:41 +0200 | [diff] [blame] | 150 | <filename>sd-daemon.h</filename> files. These |
| 151 | interfaces are available as shared library, which can |
| 152 | be compiled and linked to with the |
| 153 | <literal>libsystemd-daemon</literal> |
| 154 | <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> |
| 155 | file. Alternatively, applications consuming these APIs |
| 156 | may copy the implementation into their source |
| 157 | tree. For more details about the reference |
| 158 | implementation see |
| 159 | <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> |
Lennart Poettering | f937842 | 2010-06-23 00:31:54 +0200 | [diff] [blame] | 160 | |
Lennart Poettering | 71e6c1c | 2011-09-22 21:13:41 +0200 | [diff] [blame] | 161 | <para>If the reference implementation is used as |
| 162 | drop-in files and -DDISABLE_SYSTEMD is set during |
| 163 | compilation this function will always return 0 and |
| 164 | otherwise become a NOP.</para> |
Lennart Poettering | f937842 | 2010-06-23 00:31:54 +0200 | [diff] [blame] | 165 | </refsect1> |
| 166 | |
| 167 | <refsect1> |
Lennart Poettering | 7874bcd | 2010-06-24 03:09:36 +0200 | [diff] [blame] | 168 | <title>Environment</title> |
| 169 | |
| 170 | <variablelist> |
| 171 | <varlistentry> |
| 172 | <term><varname>$LISTEN_PID</varname></term> |
| 173 | <term><varname>$LISTEN_FDS</varname></term> |
| 174 | |
| 175 | <listitem><para>Set by the init system |
| 176 | for supervised processes that use |
| 177 | socket-based activation. This |
| 178 | environment variable specifies the |
| 179 | data |
| 180 | <function>sd_listen_fds()</function> |
| 181 | parses. See above for |
| 182 | details.</para></listitem> |
| 183 | </varlistentry> |
| 184 | </variablelist> |
| 185 | </refsect1> |
| 186 | |
| 187 | <refsect1> |
Lennart Poettering | f937842 | 2010-06-23 00:31:54 +0200 | [diff] [blame] | 188 | <title>See Also</title> |
| 189 | |
| 190 | <para> |
Lennart Poettering | 160cd5c | 2010-06-24 00:11:04 +0200 | [diff] [blame] | 191 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |
| 192 | <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, |
Lennart Poettering | f937842 | 2010-06-23 00:31:54 +0200 | [diff] [blame] | 193 | <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>, |
| 194 | <citerefentry><refentrytitle>sd_is_socket</refentrytitle><manvolnum>3</manvolnum></citerefentry>, |
| 195 | <citerefentry><refentrytitle>sd_is_socket_inet</refentrytitle><manvolnum>3</manvolnum></citerefentry>, |
| 196 | <citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry>, |
| 197 | <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, |
Lennart Poettering | f937842 | 2010-06-23 00:31:54 +0200 | [diff] [blame] | 198 | <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
| 199 | <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> |
| 200 | </para> |
| 201 | </refsect1> |
| 202 | |
| 203 | </refentry> |