]>
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>· | |
e735f4d4 MP |
22 | <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 219</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, sd_pid_notify, sd_pid_notifyf, sd_pid_notify_with_fds — 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><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_pid_notify</b>(</code></td><td>pid_t <var class="pdparam">pid</var>, </td></tr><tr><td> </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_pid_notifyf</b>(</code></td><td>pid_t <var class="pdparam">pid</var>, </td></tr><tr><td> </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><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_pid_notify_with_fds</b>(</code></td><td>pid_t <var class="pdparam">pid</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">unset_environment</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">state</var>, </td></tr><tr><td> </td><td>const int *<var class="pdparam">fds</var>, </td></tr><tr><td> </td><td>unsigned <var class="pdparam">n_fds</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a name="idm139804571070448"></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 by a service |
23 | to notify the service manager about state changes. It can be used | |
24 | to send arbitrary information, encoded in an | |
25 | environment-block-like string. Most importantly it can be used for | |
26 | start-up completion notification.</p><p>If the <em class="parameter"><code>unset_environment</code></em> parameter is | |
27 | non-zero, <code class="function">sd_notify()</code> will unset the | |
28 | <code class="varname">$NOTIFY_SOCKET</code> environment variable before | |
29 | returning (regardless of whether the function call itself | |
30 | succeeded or not). Further calls to | |
31 | <code class="function">sd_notify()</code> will then fail, but the variable | |
32 | is no longer inherited by child processes.</p><p>The <em class="parameter"><code>state</code></em> parameter should contain a | |
33 | newline-separated list of variable assignments, similar in style | |
34 | to an environment block. A trailing newline is implied if none is | |
35 | specified. The string may contain any kind of variable | |
36 | assignments, but the following shall be considered | |
37 | 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 manager that service startup | |
38 | is finished. This is only used by systemd if the service | |
39 | definition file has Type=notify set. Since there is little | |
40 | value in signaling non-readiness, the only value services | |
41 | should send is "<code class="literal">READY=1</code>" (i.e. | |
42 | "<code class="literal">READY=0</code>" is 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 that the service is | |
43 | reloading its configuration. This is useful to allow the | |
44 | service manager to track the service's internal state, and | |
45 | present it to the user. Note that a service that sends this | |
46 | notification must also send a "<code class="literal">READY=1</code>" | |
47 | notification when it completed reloading its | |
48 | 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 that the service is | |
49 | beginning its shutdown. This is useful to allow the service | |
50 | manager to track the service's internal state, and present it | |
51 | to the 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 UTF-8 status string back | |
52 | to the service manager that describes the service state. This | |
53 | is free-form and can be used for various purposes: general | |
54 | state feedback, fsck-like programs could pass completion | |
55 | percentages and failing programs could pass a human readable | |
56 | error message. Example: "<code class="literal">STATUS=Completed 66% of file | |
57 | system 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 errno-style error | |
58 | code, formatted as string. Example: "<code class="literal">ERRNO=2</code>" | |
59 | 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 service fails, the D-Bus error-style | |
60 | error code. Example: | |
61 | "<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 process ID (PID) of the service, in | |
62 | case the service manager did not fork off the process itself. | |
63 | Example: "<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 the service manager to update the | |
64 | watchdog timestamp. This is the keep-alive ping that services | |
65 | need to issue in regular intervals if | |
66 | <code class="varname">WatchdogSec=</code> is enabled for it. See | |
67 | <a href="systemd.service.html"><span class="citerefentry"><span class="refentrytitle">systemd.service</span>(5)</span></a> | |
68 | for information how to enable this functionality and | |
69 | <a href="sd_watchdog_enabled.html"><span class="citerefentry"><span class="refentrytitle">sd_watchdog_enabled</span>(3)</span></a> | |
70 | for the details of how the service can check if the the | |
71 | watchdog is enabled. </p></dd><dt id="FDSTORE=1"><span class="term">FDSTORE=1</span><a class="headerlink" title="Permalink to this term" href="#FDSTORE=1">¶</a></dt><dd><p>Stores additional file descriptors in the | |
72 | service manager. File descriptors sent this way will be | |
73 | maintained per-service by the service manager and be passed | |
74 | again using the usual file descriptor passing logic on the | |
75 | next invocation of the service (see | |
76 | <a href="sd_listen_fds.html"><span class="citerefentry"><span class="refentrytitle">sd_listen_fds</span>(3)</span></a>). | |
77 | This is useful for implementing service restart schemes where | |
78 | services serialize their state to <code class="filename">/run</code>, | |
79 | push their file descriptors to the system manager, and are | |
80 | then restarted, retrieving their state again via socket | |
81 | passing and <code class="filename">/run</code>. Note that the service | |
82 | manager will accept messages for a service only if | |
83 | <code class="varname">FileDescriptorStoreMax=</code> is set to non-zero | |
84 | for it (defaults to zero). See | |
85 | <a href="systemd.service.html"><span class="citerefentry"><span class="refentrytitle">systemd.service</span>(5)</span></a> | |
86 | for details. Multiple arrays of file descriptors may be sent | |
87 | in separate messages, in which case the arrays are combined. | |
88 | Note that the service manager removes duplicate file | |
89 | descriptors before passing them to the service. Use | |
90 | <code class="function">sd_pid_notify_with_fds()</code> to send messages | |
91 | with "<code class="literal">FDSTORE=1</code>", see | |
92 | below.</p></dd></dl></div><p>It is recommended to prefix variable names that are not | |
93 | listed above with <code class="varname">X_</code> to avoid namespace | |
94 | clashes.</p><p>Note that systemd will accept status data sent from a | |
95 | service only if the <code class="varname">NotifyAccess=</code> option is | |
96 | correctly set in the service definition file. See | |
97 | <a href="systemd.service.html"><span class="citerefentry"><span class="refentrytitle">systemd.service</span>(5)</span></a> | |
98 | for details.</p><p><code class="function">sd_notifyf()</code> is similar to | |
99 | <code class="function">sd_notify()</code> but takes a | |
100 | <code class="function">printf()</code>-like format string plus | |
101 | arguments.</p><p><code class="function">sd_pid_notify()</code> and | |
102 | <code class="function">sd_pid_notifyf()</code> are similar to | |
103 | <code class="function">sd_notify()</code> and | |
104 | <code class="function">sd_notifyf()</code> but take a process ID (PID) to | |
105 | use as originating PID for the message as first argument. This is | |
106 | useful to send notification messages on behalf of other processes, | |
107 | provided the appropriate privileges are available. If the PID | |
108 | argument is specified as 0 the process ID of the calling process | |
109 | is used, in which case the calls are fully equivalent to | |
110 | <code class="function">sd_notify()</code> and | |
111 | <code class="function">sd_notifyf()</code>.</p><p><code class="function">sd_pid_notify_with_fds()</code> is similar to | |
112 | <code class="function">sd_pid_notify()</code> but takes an additional array | |
113 | of file descriptors. These file descriptors are sent along the | |
114 | notification message to the service manager. This is particularly | |
115 | useful for sending "<code class="literal">FDSTORE=1</code>" messages, as | |
116 | described above. The additional arguments are a pointer to the | |
117 | file descriptor array plus the number of file descriptors in the | |
118 | array. If the number of file descriptors is passed as 0, the call | |
119 | is fully equivalent to <code class="function">sd_pid_notify()</code>, i.e. | |
120 | no file descriptors are passed. Note that sending file descriptors | |
121 | to the service manager on messages that do not expect them (i.e. | |
122 | without "<code class="literal">FDSTORE=1</code>") they are immediately closed | |
123 | on reception.</p></div><div class="refsect1"><a name="idm139804566108384"></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 | |
124 | code. If <code class="varname">$NOTIFY_SOCKET</code> was not set and hence | |
125 | no status data could be sent, 0 is returned. If the status was | |
126 | sent, these functions return with a positive return value. In | |
127 | order to support both, init systems that implement this scheme and | |
128 | those which do not, it is generally recommended to ignore the | |
129 | return value of this call.</p></div><div class="refsect1"><a name="idm139804566106416"></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 | 130 | library, which can be compiled and linked to with the |
5eef597e | 131 | <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> |
e735f4d4 MP |
132 | file.</p><p>Internally, these functions send a single datagram with the |
133 | state string as payload to the <code class="constant">AF_UNIX</code> socket | |
134 | referenced in the <code class="varname">$NOTIFY_SOCKET</code> environment | |
135 | variable. If the first character of | |
136 | <code class="varname">$NOTIFY_SOCKET</code> is "<code class="literal">@</code>", the | |
137 | string is understood as Linux abstract namespace socket. The | |
138 | datagram is accompanied by the process credentials of the sending | |
139 | service, using SCM_CREDENTIALS.</p></div><div class="refsect1"><a name="idm139804566102448"></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 for supervised | |
140 | processes for status and start-up completion notification. | |
141 | This environment variable specifies the socket | |
142 | <code class="function">sd_notify()</code> talks to. See above for | |
143 | details.</p></dd></dl></div></div><div class="refsect1"><a name="idm139804566098832"></a><h2 id="Examples">Examples<a class="headerlink" title="Permalink to this headline" href="#Examples">¶</a></h2><div class="example"><a name="idm139804566098192"></a><p class="title"><b>Example 1. Start-up Notification</b></p><div class="example-contents"><p>When a service finished starting up, it might issue the | |
144 | following call to notify the service manager:</p><pre class="programlisting">sd_notify(0, "READY=1");</pre></div></div><br class="example-break"><div class="example"><a name="idm139804566096288"></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 completing | |
145 | initialization:</p><pre class="programlisting">sd_notifyf(0, "READY=1\n" | |
146 | "STATUS=Processing requests...\n" | |
147 | "MAINPID=%lu", | |
148 | (unsigned long) getpid());</pre></div></div><br class="example-break"><div class="example"><a name="idm139804566094272"></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" | |
149 | "ERRNO=%i", | |
150 | strerror(errno), | |
151 | errno);</pre></div></div><br class="example-break"><div class="example"><a name="idm139804566092368"></a><p class="title"><b>Example 4. Store a File Descriptor in the Service Manager</b></p><div class="example-contents"><p>To store an open file descriptor in the service manager, | |
152 | in order to continue operation after a service restart without | |
153 | losing state use "<code class="literal">FDSTORE=1</code>":</p><pre class="programlisting">sd_pid_notify_with_fds(0, 0, "FDSTORE=1", &fd, 1);</pre></div></div><br class="example-break"></div><div class="refsect1"><a name="idm139804566089584"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p> | |
154 | <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>, | |
155 | <a href="sd-daemon.html"><span class="citerefentry"><span class="refentrytitle">sd-daemon</span>(3)</span></a>, | |
156 | <a href="daemon.html"><span class="citerefentry"><span class="refentrytitle">daemon</span>(7)</span></a>, | |
157 | <a href="systemd.service.html"><span class="citerefentry"><span class="refentrytitle">systemd.service</span>(5)</span></a>, | |
158 | <a href="sd_watchdog_enabled.html"><span class="citerefentry"><span class="refentrytitle">sd_watchdog_enabled</span>(3)</span></a> | |
159 | </p></div></div></body></html> |