SD_LISTEN_FDS_START.html 8.34 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>sd_listen_fds</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><style>
    a.headerlink {
      color: #c60f0f;
      font-size: 0.8em;
      padding: 0 4px 0 4px;
      text-decoration: none;
      visibility: hidden;
    }

    a.headerlink:hover {
      background-color: #c60f0f;
      color: white;
    }

    h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
      visibility: visible;
    }
  </style><a href="index.html">Index </a>·
  <a href="systemd.directives.html">Directives </a>·
  <a href="../python-systemd/index.html">Python </a>·
  <a href="../libudev/index.html">libudev </a>·
22
  <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 215</span><hr><div class="refentry"><a name="sd_listen_fds"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>sd_listen_fds, SD_LISTEN_FDS_START — Check for file descriptors passed by the system manager</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include &lt;systemd/sd-daemon.h&gt;</pre><pre class="funcsynopsisinfo">#define SD_LISTEN_FDS_START 3</pre><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_listen_fds</b>(</code></td><td>int <var class="pdparam">unset_environment</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a name="idm214197560512"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description"></a></h2><p><code class="function">sd_listen_fds()</code> shall be
23 24 25
                called by a daemon to check for file descriptors
                passed by the init system as part of the socket-based
                activation logic.</p><p>If the <em class="parameter"><code>unset_environment</code></em>
26
                parameter is non-zero,
27 28
                <code class="function">sd_listen_fds()</code> will unset the
                <code class="varname">$LISTEN_FDS</code>/<code class="varname">$LISTEN_PID</code>
29
                environment variables before returning (regardless of
30 31 32 33 34 35 36
                whether the function call itself succeeded or
                not). Further calls to
                <code class="function">sd_listen_fds()</code> will then fail,
                but the variables are no longer inherited by child
                processes.</p><p>If a daemon receives more than one file
                descriptor, they will be passed in the same order as
                configured in the systemd socket definition
37
                file. Nonetheless, it is recommended to verify the
38
                correct socket types before using them. To simplify
39
                this checking, the functions
40 41 42 43
                <a href="sd_is_fifo.html"><span class="citerefentry"><span class="refentrytitle">sd_is_fifo</span>(3)</span></a>,
                <a href="sd_is_socket.html"><span class="citerefentry"><span class="refentrytitle">sd_is_socket</span>(3)</span></a>,
                <a href="sd_is_socket_inet.html"><span class="citerefentry"><span class="refentrytitle">sd_is_socket_inet</span>(3)</span></a>,
                <a href="sd_is_socket_unix.html"><span class="citerefentry"><span class="refentrytitle">sd_is_socket_unix</span>(3)</span></a>
44
                are provided. In order to maximize flexibility, it is
45
                recommended to make these checks as loose as possible
46
                without allowing incorrect setups. i.e. often, the
47 48 49 50 51 52
                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.</p><p>This function call will set the FD_CLOEXEC flag
                for all passed file descriptors to avoid further
53
                inheritance to children of the calling process.</p></div><div class="refsect1"><a name="idm214197624416"></a><h2 id="Return Value">Return Value<a class="headerlink" title="Permalink to this headline" href="#Return%20Value"></a></h2><p>On failure, this call returns a negative
54 55 56 57
                errno-style error code. If
                <code class="varname">$LISTEN_FDS</code>/<code class="varname">$LISTEN_PID</code>
                was not set or was not correctly set for this daemon and
                hence no file descriptors were received, 0 is
58
                returned. Otherwise, the number of file descriptors
59 60
                passed is returned. The application may find them
                starting with file descriptor SD_LISTEN_FDS_START,
61
                i.e. file descriptor 3.</p></div><div class="refsect1"><a name="idm214197551888"></a><h2 id="Notes">Notes<a class="headerlink" title="Permalink to this headline" href="#Notes"></a></h2><p><a name="pkgconfig-text"></a>These APIs are implemented as a shared
62 63 64
  library, which can be compiled and linked to with the
  <code class="constant">libsystemd</code> <a href="pkg-config.html"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
  file.</p><p>Internally, this function checks whether the
65 66
                <code class="varname">$LISTEN_PID</code> environment variable
                equals the daemon PID. If not, it returns
67
                immediately. Otherwise, it parses the number passed in
68 69 70
                the <code class="varname">$LISTEN_FDS</code> environment
                variable, then sets the FD_CLOEXEC flag for the parsed
                number of file descriptors starting from
71
                SD_LISTEN_FDS_START. Finally, it returns the parsed
72
                number.</p></div><div class="refsect1"><a name="idm214197548512"></a><h2 id="Environment">Environment<a class="headerlink" title="Permalink to this headline" href="#Environment"></a></h2><div class="variablelist"><dl class="variablelist"><dt id="$LISTEN_PID"><span class="term"><code class="varname">$LISTEN_PID</code>, </span><span class="term"><code class="varname">$LISTEN_FDS</code></span><a class="headerlink" title="Permalink to this term" href="#%24LISTEN_PID"></a></dt><dd><p>Set by the init system
73 74 75 76 77 78
                                for supervised processes that use
                                socket-based activation. This
                                environment variable specifies the
                                data
                                <code class="function">sd_listen_fds()</code>
                                parses. See above for
79
                                details.</p></dd></dl></div></div><div class="refsect1"><a name="idm214197690240"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also"></a></h2><p>
80 81 82 83 84 85 86 87 88 89
                        <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
                        <a href="sd-daemon.html"><span class="citerefentry"><span class="refentrytitle">sd-daemon</span>(3)</span></a>,
                        <a href="sd_is_fifo.html"><span class="citerefentry"><span class="refentrytitle">sd_is_fifo</span>(3)</span></a>,
                        <a href="sd_is_socket.html"><span class="citerefentry"><span class="refentrytitle">sd_is_socket</span>(3)</span></a>,
                        <a href="sd_is_socket_inet.html"><span class="citerefentry"><span class="refentrytitle">sd_is_socket_inet</span>(3)</span></a>,
                        <a href="sd_is_socket_unix.html"><span class="citerefentry"><span class="refentrytitle">sd_is_socket_unix</span>(3)</span></a>,
                        <a href="daemon.html"><span class="citerefentry"><span class="refentrytitle">daemon</span>(7)</span></a>,
                        <a href="systemd.service.html"><span class="citerefentry"><span class="refentrytitle">systemd.service</span>(5)</span></a>,
                        <a href="systemd.socket.html"><span class="citerefentry"><span class="refentrytitle">systemd.socket</span>(5)</span></a>
                </p></div></div></body></html>