projects / systemd.git / blame
| Commit | Line | Data |
|---|---|---|
| e735f4d4 MP |
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>· | |
| e3bff60a | 22 | <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 220</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="idm140642539207712"></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 |
| e735f4d4 MP |
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 | |
| e3bff60a | 123 | on reception.</p></div><div class="refsect1"><a name="idm140642539163424"></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 |
| e735f4d4 MP |
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 | |
| e3bff60a | 129 | return value of this call.</p></div><div class="refsect1"><a name="idm140642539161456"></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 |
| e735f4d4 MP |
130 | library, which can be compiled and linked to with the |
| 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> | |
| 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 | |
| e3bff60a | 139 | service, using SCM_CREDENTIALS.</p></div><div class="refsect1"><a name="idm140642539157488"></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 |
| e735f4d4 MP |
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 | |
| e3bff60a MP |
143 | details.</p></dd></dl></div></div><div class="refsect1"><a name="idm140642539153872"></a><h2 id="Examples">Examples<a class="headerlink" title="Permalink to this headline" href="#Examples">¶</a></h2><div class="example"><a name="idm140642539153232"></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="idm140642539151328"></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 | |
| e735f4d4 MP |
145 | initialization:</p><pre class="programlisting">sd_notifyf(0, "READY=1\n" |
| 146 | "STATUS=Processing requests...\n" | |
| 147 | "MAINPID=%lu", | |
| e3bff60a | 148 | (unsigned long) getpid());</pre></div></div><br class="example-break"><div class="example"><a name="idm140642539149312"></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" |
| e735f4d4 MP |
149 | "ERRNO=%i", |
| 150 | strerror(errno), | |
| e3bff60a | 151 | errno);</pre></div></div><br class="example-break"><div class="example"><a name="idm140642539147408"></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, |
| e735f4d4 | 152 | in order to continue operation after a service restart without |
| e3bff60a | 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="idm140642539144624"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p> |
| e735f4d4 MP |
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> |