man/sd_listen_fds.html

   1 <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>
   2     a.headerlink {
   3       color: #c60f0f;
   4       font-size: 0.8em;
   5       padding: 0 4px 0 4px;
   6       text-decoration: none;
   7       visibility: hidden;
   8     }
   9
  10     a.headerlink:hover {
  11       background-color: #c60f0f;
  12       color: white;
  13     }
  14
  15     h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
  16       visibility: visible;
  17     }
  18   </style><a href="index.html">Index </a>·
  19   <a href="systemd.directives.html">Directives </a>·
  20   <a href="../python-systemd/index.html">Python </a>·
  21   <a href="../libudev/index.html">libudev </a>·
  22   <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 219</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="idm140327131529648"></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 called by a
  23     daemon to check for file descriptors passed by the init system as
  24     part of the socket-based activation logic.</p><p>If the <em class="parameter"><code>unset_environment</code></em> parameter is
  25     non-zero, <code class="function">sd_listen_fds()</code> will unset the
  26     <code class="varname">$LISTEN_FDS</code> and <code class="varname">$LISTEN_PID</code>
  27     environment variables before returning (regardless of whether the
  28     function call itself succeeded or not). Further calls to
  29     <code class="function">sd_listen_fds()</code> will then fail, but the
  30     variables are no longer inherited by child processes.</p><p>If a daemon receives more than one file descriptor, they
  31     will be passed in the same order as configured in the systemd
  32     socket unit file (see
  33     <a href="systemd.socket.html"><span class="citerefentry"><span class="refentrytitle">systemd.socket</span>(5)</span></a>
  34     for details). Nonetheless, it is recommended to verify the correct
  35     socket types before using them. To simplify this checking, the
  36     functions
  37     <a href="sd_is_fifo.html"><span class="citerefentry"><span class="refentrytitle">sd_is_fifo</span>(3)</span></a>,
  38     <a href="sd_is_socket.html"><span class="citerefentry"><span class="refentrytitle">sd_is_socket</span>(3)</span></a>,
  39     <a href="sd_is_socket_inet.html"><span class="citerefentry"><span class="refentrytitle">sd_is_socket_inet</span>(3)</span></a>,
  40     <a href="sd_is_socket_unix.html"><span class="citerefentry"><span class="refentrytitle">sd_is_socket_unix</span>(3)</span></a>
  41     are provided. In order to maximize flexibility, it is recommended
  42     to make these checks as loose as possible without allowing
  43     incorrect setups. i.e. often, the actual port number a socket is
  44     bound to matters little for the service to work, hence it should
  45     not be verified. On the other hand, whether a socket is a datagram
  46     or stream socket matters a lot for the most common program logics
  47     and should be checked.</p><p>This function call will set the FD_CLOEXEC flag for all
  48     passed file descriptors to avoid further inheritance to children
  49     of the calling process.</p><p>If multiple socket units activate the same service the order
  50     of the file descriptors passed to its main process is undefined.
  51     If additional file descriptors have been passed to the service
  52     manager using
  53     <a href="sd_pid_notify_with_fds.html"><span class="citerefentry"><span class="refentrytitle">sd_pid_notify_with_fds</span>(3)</span></a>'s
  54     "<code class="literal">FDSTORE=1</code>" messages, these file descriptors are
  55     passed last, in arbitrary order, and with duplicates
  56     removed.</p></div><div class="refsect1"><a name="idm140327135414800"></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 errno-style error
  57     code. If
  58     <code class="varname">$LISTEN_FDS</code>/<code class="varname">$LISTEN_PID</code> was
  59     not set or was not correctly set for this daemon and hence no file
  60     descriptors were received, 0 is returned. Otherwise, the number of
  61     file descriptors passed is returned. The application may find them
  62     starting with file descriptor SD_LISTEN_FDS_START, i.e. file
  63     descriptor 3.</p></div><div class="refsect1"><a name="idm140327135412464"></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
  64   library, which can be compiled and linked to with the
  65   <code class="constant">libsystemd</code> <a href="http://linux.die.net/man/1/pkg-config"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
  66   file.</p><p>Internally, this function checks whether the
  67     <code class="varname">$LISTEN_PID</code> environment variable equals the
  68     daemon PID. If not, it returns immediately. Otherwise, it parses
  69     the number passed in the <code class="varname">$LISTEN_FDS</code>
  70     environment variable, then sets the FD_CLOEXEC flag for the parsed
  71     number of file descriptors starting from SD_LISTEN_FDS_START.
  72     Finally, it returns the parsed number.</p></div><div class="refsect1"><a name="idm140327135409200"></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         for supervised processes that use
  74         socket-based activation. This
  75         environment variable specifies the
  76         data
  77         <code class="function">sd_listen_fds()</code>
  78         parses. See above for
  79         details.</p></dd></dl></div></div><div class="refsect1"><a name="idm140327135404896"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
  80       <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
  81       <a href="sd-daemon.html"><span class="citerefentry"><span class="refentrytitle">sd-daemon</span>(3)</span></a>,
  82       <a href="sd_is_fifo.html"><span class="citerefentry"><span class="refentrytitle">sd_is_fifo</span>(3)</span></a>,
  83       <a href="sd_is_socket.html"><span class="citerefentry"><span class="refentrytitle">sd_is_socket</span>(3)</span></a>,
  84       <a href="sd_is_socket_inet.html"><span class="citerefentry"><span class="refentrytitle">sd_is_socket_inet</span>(3)</span></a>,
  85       <a href="sd_is_socket_unix.html"><span class="citerefentry"><span class="refentrytitle">sd_is_socket_unix</span>(3)</span></a>,
  86       <a href="daemon.html"><span class="citerefentry"><span class="refentrytitle">daemon</span>(7)</span></a>,
  87       <a href="systemd.service.html"><span class="citerefentry"><span class="refentrytitle">systemd.service</span>(5)</span></a>,
  88       <a href="systemd.socket.html"><span class="citerefentry"><span class="refentrytitle">systemd.socket</span>(5)</span></a>
  89     </p></div></div></body></html>