]> git.proxmox.com Git - systemd.git/blame - man/sd_notify.html
Imported Upstream version 218
[systemd.git] / man / sd_notify.html
CommitLineData
663996b3
MS
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>·
f47781d8 22 <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 218</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 service 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="idm139898376842944"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description">¶</a></h2><p><code class="function">sd_notify()</code> may be called
5eef597e
MP
23 by a service to notify the service manager about
24 state changes. It can be used to send arbitrary
25 information, encoded in an environment-block-like
26 string. Most importantly it can be used for start-up
27 completion notification.</p><p>If the <em class="parameter"><code>unset_environment</code></em>
14228c0d 28 parameter is non-zero, <code class="function">sd_notify()</code>
663996b3 29 will unset the <code class="varname">$NOTIFY_SOCKET</code>
60f067b4 30 environment variable before returning (regardless of
663996b3
MS
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
5eef597e
MP
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 service
42 manager that service startup is
43 finished. This is only used by systemd
44 if the service definition file has
45 Type=notify set. Since there is little
663996b3 46 value in signaling non-readiness, the
5eef597e
MP
47 only value services should send is
48 "<code class="literal">READY=1</code>"
49 (i.e. "<code class="literal">READY=0</code>" is
50 not defined).</p></dd><dt id="RELOADING=1"><span class="term">RELOADING=1</span><a class="headerlink" title="Permalink to this term" href="#RELOADING=1">¶</a></dt><dd><p>Tells the service manager
51 that the service is reloading its
52 configuration. This is useful to allow
53 the service manager to track the service's
54 internal state, and present it to the
55 user. Note that a service that sends
56 this notification must also send a
57 "<code class="literal">READY=1</code>"
58 notification when it completed
59 reloading its
60 configuration.</p></dd><dt id="STOPPING=1"><span class="term">STOPPING=1</span><a class="headerlink" title="Permalink to this term" href="#STOPPING=1">¶</a></dt><dd><p>Tells the service manager
61 that the service is beginning its
62 shutdown. This is useful to allow the
63 service manager to track the service's
64 internal state, and present it to the
65 user.</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
66 UTF-8 status string back to the service manager
67 that describes the service state. This
663996b3
MS
68 is free-form and can be used for
69 various purposes: general state
70 feedback, fsck-like programs could
71 pass completion percentages and
72 failing programs could pass a human
73 readable error message. Example:
5eef597e
MP
74 "<code class="literal">STATUS=Completed 66% of file
75 system
76 check...</code>"</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 service fails, the
663996b3 77 errno-style error code, formatted as
5eef597e
MP
78 string. Example: "<code class="literal">ERRNO=2</code>" for
79 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 service fails, the
663996b3 80 D-Bus error-style error code. Example:
5eef597e
MP
81 "<code class="literal">BUSERROR=org.freedesktop.DBus.Error.TimedOut</code>"</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
82 service, in case the service manager did
663996b3
MS
83 not fork off the process
84 itself. Example:
5eef597e 85 "<code class="literal">MAINPID=4711</code>"</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
663996b3
MS
86 update the watchdog timestamp. This is
87 the keep-alive ping that services need
88 to issue in regular intervals if
89 <code class="varname">WatchdogSec=</code> is
90 enabled for it. See
91 <a href="systemd.service.html"><span class="citerefentry"><span class="refentrytitle">systemd.service</span>(5)</span></a>
5eef597e
MP
92 for information how to enable this
93 functionality and
60f067b4 94 <a href="sd_watchdog_enabled.html"><span class="citerefentry"><span class="refentrytitle">sd_watchdog_enabled</span>(3)</span></a>
5eef597e
MP
95 for the details of how the service can
96 check if the the watchdog is enabled.
97 </p></dd></dl></div><p>It is recommended to prefix variable names that
663996b3
MS
98 are not shown in the list above with
99 <code class="varname">X_</code> to avoid namespace
100 clashes.</p><p>Note that systemd will accept status data sent
5eef597e 101 from a service only if the
663996b3
MS
102 <code class="varname">NotifyAccess=</code> option is correctly
103 set in the service definition file. See
104 <a href="systemd.service.html"><span class="citerefentry"><span class="refentrytitle">systemd.service</span>(5)</span></a>
105 for details.</p><p><code class="function">sd_notifyf()</code> is similar to
106 <code class="function">sd_notify()</code> but takes a
107 <code class="function">printf()</code>-like format string plus
f47781d8 108 arguments.</p></div><div class="refsect1"><a name="idm139898380706672"></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
663996b3
MS
109 errno-style error code. If
110 <code class="varname">$NOTIFY_SOCKET</code> was not set and
111 hence no status data could be sent, 0 is returned. If
14228c0d 112 the status was sent, these functions return with a
663996b3
MS
113 positive return value. In order to support both, init
114 systems that implement this scheme and those which
14228c0d 115 do not, it is generally recommended to ignore the return
f47781d8 116 value of this call.</p></div><div class="refsect1"><a name="idm139898380704544"></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
60f067b4 117 library, which can be compiled and linked to with the
5eef597e 118 <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>
60f067b4 119 file.</p><p>Internally, these functions send a single
663996b3 120 datagram with the state string as payload to the
14228c0d 121 <code class="constant">AF_UNIX</code> socket referenced in the
663996b3
MS
122 <code class="varname">$NOTIFY_SOCKET</code> environment
123 variable. If the first character of
14228c0d 124 <code class="varname">$NOTIFY_SOCKET</code> is "<code class="literal">@</code>", the string is
663996b3
MS
125 understood as Linux abstract namespace socket. The
126 datagram is accompanied by the process credentials of
f47781d8 127 the sending service, using SCM_CREDENTIALS.</p></div><div class="refsect1"><a name="idm139898380700096"></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 service manager
663996b3
MS
128 for supervised processes for status
129 and start-up completion
130 notification. This environment variable
131 specifies the socket
132 <code class="function">sd_notify()</code> talks
f47781d8 133 to. See above for details.</p></dd></dl></div></div><div class="refsect1"><a name="idm139898380696192"></a><h2 id="Examples">Examples<a class="headerlink" title="Permalink to this headline" href="#Examples">¶</a></h2><div class="example"><a name="idm139898380695520"></a><p class="title"><b>Example 1. Start-up Notification</b></p><div class="example-contents"><p>When a service finished starting up, it
663996b3 134 might issue the following call to notify
f47781d8 135 the service manager:</p><pre class="programlisting">sd_notify(0, "READY=1");</pre></div></div><br class="example-break"><div class="example"><a name="idm139898380693472"></a><p class="title"><b>Example 2. Extended Start-up Notification</b></p><div class="example-contents"><p>A service could send the following after
663996b3
MS
136 completing initialization:</p><pre class="programlisting">sd_notifyf(0, "READY=1\n"
137 "STATUS=Processing requests...\n"
138 "MAINPID=%lu",
f47781d8 139 (unsigned long) getpid());</pre></div></div><br class="example-break"><div class="example"><a name="idm139898375775424"></a><p class="title"><b>Example 3. Error Cause Notification</b></p><div class="example-contents"><p>A service could send the following shortly before exiting, on failure</p><pre class="programlisting">sd_notifyf(0, "STATUS=Failed to start up: %s\n"
663996b3
MS
140 "ERRNO=%i",
141 strerror(errno),
f47781d8 142 errno);</pre></div></div><br class="example-break"></div><div class="refsect1"><a name="idm139898375773376"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
663996b3
MS
143 <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
144 <a href="sd-daemon.html"><span class="citerefentry"><span class="refentrytitle">sd-daemon</span>(3)</span></a>,
145 <a href="daemon.html"><span class="citerefentry"><span class="refentrytitle">daemon</span>(7)</span></a>,
60f067b4
JS
146 <a href="systemd.service.html"><span class="citerefentry"><span class="refentrytitle">systemd.service</span>(5)</span></a>,
147 <a href="sd_watchdog_enabled.html"><span class="citerefentry"><span class="refentrytitle">sd_watchdog_enabled</span>(3)</span></a>
663996b3 148 </p></div></div></body></html>