sd_notify.html 13.3 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_notify</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>·
  <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 215</span><hr><div class="refentry"><a name="sd_notify"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>sd_notify, sd_notifyf — Notify service manager about start-up completion and other daemon status changes</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include &lt;systemd/sd-daemon.h&gt;</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_notify</b>(</code></td><td>int <var class="pdparam">unset_environment</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">state</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_notifyf</b>(</code></td><td>int <var class="pdparam">unset_environment</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">format</var>, </td></tr><tr><td> </td><td>...<code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a name="idm214198380880"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description"></a></h2><p><code class="function">sd_notify()</code> shall be called
23 24 25 26 27
                by a daemon to notify the init system about status
                changes. It can be used to send arbitrary information,
                encoded in an environment-block-like string. Most
                importantly it can be used for start-up completion
                notification.</p><p>If the <em class="parameter"><code>unset_environment</code></em>
                parameter is non-zero, <code class="function">sd_notify()</code>
                will unset the <code class="varname">$NOTIFY_SOCKET</code>
                environment variable before returning (regardless of
31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76
                whether the function call itself succeeded or
                not). Further calls to
                <code class="function">sd_notify()</code> will then fail, but
                the variable is no longer inherited by child
                processes.</p><p>The <em class="parameter"><code>state</code></em> parameter
                should contain a newline-separated list of variable
                assignments, similar in style to an environment
                block. A trailing newline is implied if none is
                specified. The string may contain any kind of variable
                assignments, but the following shall be considered
                well-known:</p><div class="variablelist"><dl class="variablelist"><dt id="READY=1"><span class="term">READY=1</span><a class="headerlink" title="Permalink to this term" href="#READY=1"></a></dt><dd><p>Tells the init system
                                that daemon startup is finished. This
                                is only used by systemd if the service
                                definition file has Type=notify
                                set. The passed argument is a boolean
                                "1" or "0". Since there is little
                                value in signaling non-readiness, the
                                only value daemons should send is
                                "READY=1".</p></dd><dt id="STATUS=..."><span class="term">STATUS=...</span><a class="headerlink" title="Permalink to this term" href="#STATUS=..."></a></dt><dd><p>Passes a single-line
                                status string back to the init system
                                that describes the daemon state. This
                                is free-form and can be used for
                                various purposes: general state
                                feedback, fsck-like programs could
                                pass completion percentages and
                                failing programs could pass a human
                                readable error message. Example:
                                "STATUS=Completed 66% of file system
                                check..."</p></dd><dt id="ERRNO=..."><span class="term">ERRNO=...</span><a class="headerlink" title="Permalink to this term" href="#ERRNO=..."></a></dt><dd><p>If a daemon fails, the
                                errno-style error code, formatted as
                                string. Example: "ERRNO=2" for
                                ENOENT.</p></dd><dt id="BUSERROR=..."><span class="term">BUSERROR=...</span><a class="headerlink" title="Permalink to this term" href="#BUSERROR=..."></a></dt><dd><p>If a daemon fails, the
                                D-Bus error-style error code. Example:
                                "BUSERROR=org.freedesktop.DBus.Error.TimedOut"</p></dd><dt id="MAINPID=..."><span class="term">MAINPID=...</span><a class="headerlink" title="Permalink to this term" href="#MAINPID=..."></a></dt><dd><p>The main pid of the
                                daemon, in case the init system did
                                not fork off the process
                                itself. Example:
                                "MAINPID=4711"</p></dd><dt id="WATCHDOG=1"><span class="term">WATCHDOG=1</span><a class="headerlink" title="Permalink to this term" href="#WATCHDOG=1"></a></dt><dd><p>Tells systemd to
                                update the watchdog timestamp. This is
                                the keep-alive ping that services need
                                to issue in regular intervals if
                                <code class="varname">WatchdogSec=</code> is
                                enabled for it. See
                                <a href="systemd.service.html"><span class="citerefentry"><span class="refentrytitle">systemd.service</span>(5)</span></a>
                                for details. It is recommended to send
                                this message if the
77 78 79 80 81 82 83 84 85
                                <code class="varname">$WATCHDOG_PID</code>
                                environment variable has been set to
                                the PID of the service process, in
                                every half the time interval that is
                                specified in the
                                <code class="varname">$WATCHDOG_USEC</code>
                                environment variable. See
                                <a href="sd_watchdog_enabled.html"><span class="citerefentry"><span class="refentrytitle">sd_watchdog_enabled</span>(3)</span></a>
                                for details.</p></dd></dl></div><p>It is recommended to prefix variable names that
86 87 88 89 90 91 92 93 94 95
                are not shown in the list above with
                <code class="varname">X_</code> to avoid namespace
                clashes.</p><p>Note that systemd will accept status data sent
                from a daemon only if the
                <code class="varname">NotifyAccess=</code> option is correctly
                set in the service definition file. See
                <a href="systemd.service.html"><span class="citerefentry"><span class="refentrytitle">systemd.service</span>(5)</span></a>
                for details.</p><p><code class="function">sd_notifyf()</code> is similar to
                <code class="function">sd_notify()</code> but takes a
                <code class="function">printf()</code>-like format string plus
                arguments.</p></div><div class="refsect1"><a name="idm214198431088"></a><h2 id="Return Value">Return Value<a class="headerlink" title="Permalink to this headline" href="#Return%20Value"></a></h2><p>On failure, these calls return a negative
97 98 99
                errno-style error code. If
                <code class="varname">$NOTIFY_SOCKET</code> was not set and
                hence no status data could be sent, 0 is returned. If
                the status was sent, these functions return with a
101 102
                positive return value. In order to support both, init
                systems that implement this scheme and those which
                do not, it is generally recommended to ignore the return
                value of this call.</p></div><div class="refsect1"><a name="idm214198428960"></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
105 106 107
  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, these functions send a single
                datagram with the state string as payload to the
                <code class="constant">AF_UNIX</code> socket referenced in the
110 111
                <code class="varname">$NOTIFY_SOCKET</code> environment
                variable. If the first character of
                <code class="varname">$NOTIFY_SOCKET</code> is "<code class="literal">@</code>", the string is
113 114
                understood as Linux abstract namespace socket. The
                datagram is accompanied by the process credentials of
                the sending daemon, using SCM_CREDENTIALS.</p></div><div class="refsect1"><a name="idm214198417120"></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="$NOTIFY_SOCKET"><span class="term"><code class="varname">$NOTIFY_SOCKET</code></span><a class="headerlink" title="Permalink to this term" href="#%24NOTIFY_SOCKET"></a></dt><dd><p>Set by the init system
116 117 118 119 120
                                for supervised processes for status
                                and start-up completion
                                notification. This environment variable
                                specifies the socket
                                <code class="function">sd_notify()</code> talks
                                to. See above for details.</p></dd></dl></div></div><div class="refsect1"><a name="idm214198413216"></a><h2 id="Examples">Examples<a class="headerlink" title="Permalink to this headline" href="#Examples"></a></h2><div class="example"><a name="idm214198412544"></a><p class="title"><b>Example 1. Start-up Notification</b></p><div class="example-contents"><p>When a daemon finished starting up, it
                        might issue the following call to notify
                        the init system:</p><pre class="programlisting">sd_notify(0, "READY=1");</pre></div></div><br class="example-break"><div class="example"><a name="idm214198410496"></a><p class="title"><b>Example 2. Extended Start-up Notification</b></p><div class="example-contents"><p>A daemon could send the following after
124 125 126
                        completing initialization:</p><pre class="programlisting">sd_notifyf(0, "READY=1\n"
              "STATUS=Processing requests...\n"
              (unsigned long) getpid());</pre></div></div><br class="example-break"><div class="example"><a name="idm214198408368"></a><p class="title"><b>Example 3. Error Cause Notification</b></p><div class="example-contents"><p>A daemon could send the following shortly before exiting, on failure</p><pre class="programlisting">sd_notifyf(0, "STATUS=Failed to start up: %s\n"
128 129
              errno);</pre></div></div><br class="example-break"></div><div class="refsect1"><a name="idm214198406240"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also"></a></h2><p>
131 132 133
                        <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="daemon.html"><span class="citerefentry"><span class="refentrytitle">daemon</span>(7)</span></a>,
134 135
                        <a href="systemd.service.html"><span class="citerefentry"><span class="refentrytitle">systemd.service</span>(5)</span></a>,
                        <a href="sd_watchdog_enabled.html"><span class="citerefentry"><span class="refentrytitle">sd_watchdog_enabled</span>(3)</span></a>