man/sd_notify.html

   1 <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>
   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 208</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="idm274675548480"></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                 by a daemon to notify the init system about status
  24                 changes. It can be used to send arbitrary information,
  25                 encoded in an environment-block-like string. Most
  26                 importantly it can be used for start-up completion
  27                 notification.</p><p>If the <em class="parameter"><code>unset_environment</code></em>
  28                 parameter is non-zero, <code class="function">sd_notify()</code>
  29                 will unset the <code class="varname">$NOTIFY_SOCKET</code>
  30                 environment variable before returning (regardless
  31                 whether the function call itself succeeded or
  32                 not). Further calls to
  33                 <code class="function">sd_notify()</code> will then fail, but
  34                 the variable is no longer inherited by child
  35                 processes.</p><p>The <em class="parameter"><code>state</code></em> parameter
  36                 should contain a newline-separated list of variable
  37                 assignments, similar in style to an environment
  38                 block. A trailing newline is implied if none is
  39                 specified. The string may contain any kind of variable
  40                 assignments, but the following shall be considered
  41                 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
  42                                 that daemon startup is finished. This
  43                                 is only used by systemd if the service
  44                                 definition file has Type=notify
  45                                 set. The passed argument is a boolean
  46                                 "1" or "0". Since there is little
  47                                 value in signaling non-readiness, the
  48                                 only value daemons should send is
  49                                 "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
  50                                 status string back to the init system
  51                                 that describes the daemon state. This
  52                                 is free-form and can be used for
  53                                 various purposes: general state
  54                                 feedback, fsck-like programs could
  55                                 pass completion percentages and
  56                                 failing programs could pass a human
  57                                 readable error message. Example:
  58                                 "STATUS=Completed 66% of file system
  59                                 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
  60                                 errno-style error code, formatted as
  61                                 string. Example: "ERRNO=2" for
  62                                 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
  63                                 D-Bus error-style error code. Example:
  64                                 "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
  65                                 daemon, in case the init system did
  66                                 not fork off the process
  67                                 itself. Example:
  68                                 "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
  69                                 update the watchdog timestamp. This is
  70                                 the keep-alive ping that services need
  71                                 to issue in regular intervals if
  72                                 <code class="varname">WatchdogSec=</code> is
  73                                 enabled for it. See
  74                                 <a href="systemd.service.html"><span class="citerefentry"><span class="refentrytitle">systemd.service</span>(5)</span></a>
  75                                 for details. It is recommended to send
  76                                 this message if the
  77                                 <code class="varname">WATCHDOG_USEC=</code>
  78                                 environment variable has been set for
  79                                 the service process, in every half the
  80                                 time interval that is specified in the
  81                                 variable.</p></dd></dl></div><p>It is recommended to prefix variable names that
  82                 are not shown in the list above with
  83                 <code class="varname">X_</code> to avoid namespace
  84                 clashes.</p><p>Note that systemd will accept status data sent
  85                 from a daemon only if the
  86                 <code class="varname">NotifyAccess=</code> option is correctly
  87                 set in the service definition file. See
  88                 <a href="systemd.service.html"><span class="citerefentry"><span class="refentrytitle">systemd.service</span>(5)</span></a>
  89                 for details.</p><p><code class="function">sd_notifyf()</code> is similar to
  90                 <code class="function">sd_notify()</code> but takes a
  91                 <code class="function">printf()</code>-like format string plus
  92                 arguments.</p></div><div class="refsect1"><a name="idm274679414896"></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
  93                 errno-style error code. If
  94                 <code class="varname">$NOTIFY_SOCKET</code> was not set and
  95                 hence no status data could be sent, 0 is returned. If
  96                 the status was sent, these functions return with a
  97                 positive return value. In order to support both, init
  98                 systems that implement this scheme and those which
  99                 do not, it is generally recommended to ignore the return
 100                 value of this call.</p></div><div class="refsect1"><a name="idm274679412768"></a><h2 id="Notes">Notes<a class="headerlink" title="Permalink to this headline" href="#Notes">¶</a></h2><p>These functions are provided by the reference
 101                 implementation of APIs for new-style daemons and
 102                 distributed with the systemd package. The algorithms
 103                 they implement are simple, and can easily be
 104                 reimplemented in daemons if it is important to support
 105                 this interface without using the reference
 106                 implementation.</p><p>Internally, these functions send a single
 107                 datagram with the state string as payload to the
 108                 <code class="constant">AF_UNIX</code> socket referenced in the
 109                 <code class="varname">$NOTIFY_SOCKET</code> environment
 110                 variable. If the first character of
 111                 <code class="varname">$NOTIFY_SOCKET</code> is "<code class="literal">@</code>", the string is
 112                 understood as Linux abstract namespace socket. The
 113                 datagram is accompanied by the process credentials of
 114                 the sending daemon, using SCM_CREDENTIALS.</p><p>For details about the algorithms check the
 115                 liberally licensed reference implementation sources:
 116                 <a class="ulink" href="http://cgit.freedesktop.org/systemd/systemd/plain/src/libsystemd-daemon/sd-daemon.c" target="_top">http://cgit.freedesktop.org/systemd/systemd/plain/src/libsystemd-daemon/sd-daemon.c</a>
 117                 and <a class="ulink" href="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h" target="_top">http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h</a></p><p><code class="function">sd_notify()</code> and
 118                 <code class="function">sd_notifyf()</code> are implemented in
 119                 the reference implementation's
 120                 <code class="filename">sd-daemon.c</code> and
 121                 <code class="filename">sd-daemon.h</code> files. These
 122                 interfaces are available as shared library, which can
 123                 be compiled and linked to with the
 124                 <code class="constant">libsystemd-daemon</code> <a href="pkg-config.html"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
 125                 file. Alternatively, applications consuming these APIs
 126                 may copy the implementation into their source tree. For
 127                 more details about the reference implementation see
 128                 <a href="sd-daemon.html"><span class="citerefentry"><span class="refentrytitle">sd-daemon</span>(3)</span></a>.</p><p>If the reference implementation is used as
 129                 drop-in files and -DDISABLE_SYSTEMD is set during
 130                 compilation, these functions will always return 0 and
 131                 otherwise become a NOP.</p></div><div class="refsect1"><a name="idm274679400816"></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
 132                                 for supervised processes for status
 133                                 and start-up completion
 134                                 notification. This environment variable
 135                                 specifies the socket
 136                                 <code class="function">sd_notify()</code> talks
 137                                 to. See above for details.</p></dd></dl></div></div><div class="refsect1"><a name="idm274679396912"></a><h2 id="Examples">Examples<a class="headerlink" title="Permalink to this headline" href="#Examples">¶</a></h2><div class="example"><a name="idm274679396240"></a><p class="title"><b>Example 1. Start-up Notification</b></p><div class="example-contents"><p>When a daemon finished starting up, it
 138                         might issue the following call to notify
 139                         the init system:</p><pre class="programlisting">sd_notify(0, "READY=1");</pre></div></div><br class="example-break"><div class="example"><a name="idm274679394192"></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
 140                         completing initialization:</p><pre class="programlisting">sd_notifyf(0, "READY=1\n"
 141               "STATUS=Processing requests...\n"
 142               "MAINPID=%lu",
 143               (unsigned long) getpid());</pre></div></div><br class="example-break"><div class="example"><a name="idm274679392064"></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"
 144               "ERRNO=%i",
 145               strerror(errno),
 146               errno);</pre></div></div><br class="example-break"></div><div class="refsect1"><a name="idm274674480384"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
 147                         <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
 148                         <a href="sd-daemon.html"><span class="citerefentry"><span class="refentrytitle">sd-daemon</span>(3)</span></a>,
 149                         <a href="daemon.html"><span class="citerefentry"><span class="refentrytitle">daemon</span>(7)</span></a>,
 150                         <a href="systemd.service.html"><span class="citerefentry"><span class="refentrytitle">systemd.service</span>(5)</span></a>
 151                 </p></div></div></body></html>