mirror of
https://git.proxmox.com/git/systemd
synced 2026-01-07 00:42:24 +00:00
ba573a3afc
Instead of tracking git upstream directly, the upstream branch now contains the contents of the orig tarball available at http://www.freedesktop.org/software/systemd/
153 lines
15 KiB
HTML
153 lines
15 KiB
HTML
<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 204</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 <systemd/sd-daemon.h></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="idm259769923200"></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
|
||
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
|
||
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
|
||
<code class="varname">WATCHDOG_USEC=</code>
|
||
environment variable has been set for
|
||
the service process, in every half the
|
||
time interval that is specified in the
|
||
variable.</p></dd></dl></div><p>It is recommended to prefix variable names that
|
||
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="idm259773789536"></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
|
||
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
|
||
positive return value. In order to support both, init
|
||
systems that implement this scheme and those which
|
||
don't, it is generally recommended to ignore the return
|
||
value of this call.</p></div><div class="refsect1"><a name="idm259773787408"></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
|
||
implementation of APIs for new-style daemons and
|
||
distributed with the systemd package. The algorithms
|
||
they implement are simple, and can easily be
|
||
reimplemented in daemons if it is important to support
|
||
this interface without using the reference
|
||
implementation.</p><p>Internally, these functions send a single
|
||
datagram with the state string as payload to the
|
||
AF_UNIX socket referenced in the
|
||
<code class="varname">$NOTIFY_SOCKET</code> environment
|
||
variable. If the first character of
|
||
<code class="varname">$NOTIFY_SOCKET</code> is @ the string is
|
||
understood as Linux abstract namespace socket. The
|
||
datagram is accompanied by the process credentials of
|
||
the sending daemon, using SCM_CREDENTIALS.</p><p>For details about the algorithms check the
|
||
liberally licensed reference implementation sources:
|
||
<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>
|
||
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
|
||
<code class="function">sd_notifyf()</code> are implemented in
|
||
the reference implementation's
|
||
<code class="filename">sd-daemon.c</code> and
|
||
<code class="filename">sd-daemon.h</code> files. These
|
||
interfaces are available as shared library, which can
|
||
be compiled and linked to with the
|
||
<code class="literal">libsystemd-daemon</code>
|
||
<a href="pkg-config.html"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
|
||
file. Alternatively, applications consuming these APIs
|
||
may copy the implementation into their source tree. For
|
||
more details about the reference implementation see
|
||
<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
|
||
drop-in files and -DDISABLE_SYSTEMD is set during
|
||
compilation these functions will always return 0 and
|
||
otherwise become a NOP.</p></div><div class="refsect1"><a name="idm259773776320"></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
|
||
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="idm259773772416"></a><h2 id="Examples">Examples<a class="headerlink" title="Permalink to this headline" href="#Examples">¶</a></h2><div class="example"><a name="idm259773771744"></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="idm259773769696"></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
|
||
completing initialization:</p><pre class="programlisting">sd_notifyf(0, "READY=1\n"
|
||
"STATUS=Processing requests...\n"
|
||
"MAINPID=%lu",
|
||
(unsigned long) getpid());</pre></div></div><br class="example-break"><div class="example"><a name="idm259773767568"></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"
|
||
"ERRNO=%i",
|
||
strerror(errno),
|
||
errno);</pre></div></div><br class="example-break"></div><div class="refsect1"><a name="idm259768857824"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
|
||
<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>,
|
||
<a href="systemd.service.html"><span class="citerefentry"><span class="refentrytitle">systemd.service</span>(5)</span></a>
|
||
</p></div></div></body></html>
|