]>
Commit | Line | Data |
---|---|---|
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 <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="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> |