diff options
| author | Martin Pitt <martin.pitt@ubuntu.com> | 2015-07-08 07:08:31 +0200 |
|---|---|---|
| committer | Martin Pitt <martin.pitt@ubuntu.com> | 2015-07-08 07:08:31 +0200 |
| commit | fb183854ab9b5774094a753ad3f46b653a9055da (patch) | |
| tree | f3854bb3a4703a39aedff451b874e7cf9e53c699 /man/sd_pid_notify_with_fds.html | |
| parent | 86f210e9c914ba12477d4b2e7fa6f5cfa196a324 (diff) | |
| download | systemd-fb183854ab9b5774094a753ad3f46b653a9055da.tar.gz | |
Imported Upstream version 222
Diffstat (limited to 'man/sd_pid_notify_with_fds.html')
| -rw-r--r-- | man/sd_pid_notify_with_fds.html | 159 |
1 files changed, 0 insertions, 159 deletions
diff --git a/man/sd_pid_notify_with_fds.html b/man/sd_pid_notify_with_fds.html deleted file mode 100644 index 9bfaa7338f..0000000000 --- a/man/sd_pid_notify_with_fds.html +++ /dev/null @@ -1,159 +0,0 @@ -<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>· - - <span style="float:right">systemd 221</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="idm47268061686672"></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 - to notify the service manager about state 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 of 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 service manager that service startup - is finished. This is only used by systemd if the service - definition file has Type=notify set. Since there is little - value in signaling non-readiness, the only value services - should send is "<code class="literal">READY=1</code>" (i.e. - "<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 - reloading its configuration. This is useful to allow the - service manager to track the service's internal state, and - present it to the user. Note that a service that sends this - notification must also send a "<code class="literal">READY=1</code>" - notification when it completed reloading its - 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 - beginning its shutdown. This is useful to allow the service - manager to track the service's internal state, and present it - 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 - to the service manager that describes the service 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: "<code class="literal">STATUS=Completed 66% of file - 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 - code, formatted as string. Example: "<code class="literal">ERRNO=2</code>" - 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 - error code. Example: - "<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 - case the service manager did not fork off the process itself. - 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 - 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 information how to enable this functionality and - <a href="sd_watchdog_enabled.html"><span class="citerefentry"><span class="refentrytitle">sd_watchdog_enabled</span>(3)</span></a> - for the details of how the service can check if the the - 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 - service manager. File descriptors sent this way will be - maintained per-service by the service manager and be passed - again using the usual file descriptor passing logic on the - next invocation of the service (see - <a href="sd_listen_fds.html"><span class="citerefentry"><span class="refentrytitle">sd_listen_fds</span>(3)</span></a>). - This is useful for implementing service restart schemes where - services serialize their state to <code class="filename">/run</code>, - push their file descriptors to the system manager, and are - then restarted, retrieving their state again via socket - passing and <code class="filename">/run</code>. Note that the service - manager will accept messages for a service only if - <code class="varname">FileDescriptorStoreMax=</code> is set to non-zero - for it (defaults to zero). See - <a href="systemd.service.html"><span class="citerefentry"><span class="refentrytitle">systemd.service</span>(5)</span></a> - for details. Multiple arrays of file descriptors may be sent - in separate messages, in which case the arrays are combined. - Note that the service manager removes duplicate file - descriptors before passing them to the service. Use - <code class="function">sd_pid_notify_with_fds()</code> to send messages - with "<code class="literal">FDSTORE=1</code>", see - below.</p></dd></dl></div><p>It is recommended to prefix variable names that are not - listed above with <code class="varname">X_</code> to avoid namespace - clashes.</p><p>Note that systemd will accept status data sent from a - service 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><p><code class="function">sd_pid_notify()</code> and - <code class="function">sd_pid_notifyf()</code> are similar to - <code class="function">sd_notify()</code> and - <code class="function">sd_notifyf()</code> but take a process ID (PID) to - use as originating PID for the message as first argument. This is - useful to send notification messages on behalf of other processes, - provided the appropriate privileges are available. If the PID - argument is specified as 0 the process ID of the calling process - is used, in which case the calls are fully equivalent to - <code class="function">sd_notify()</code> and - <code class="function">sd_notifyf()</code>.</p><p><code class="function">sd_pid_notify_with_fds()</code> is similar to - <code class="function">sd_pid_notify()</code> but takes an additional array - of file descriptors. These file descriptors are sent along the - notification message to the service manager. This is particularly - useful for sending "<code class="literal">FDSTORE=1</code>" messages, as - described above. The additional arguments are a pointer to the - file descriptor array plus the number of file descriptors in the - array. If the number of file descriptors is passed as 0, the call - is fully equivalent to <code class="function">sd_pid_notify()</code>, i.e. - no file descriptors are passed. Note that sending file descriptors - to the service manager on messages that do not expect them (i.e. - without "<code class="literal">FDSTORE=1</code>") they are immediately closed - on reception.</p></div><div class="refsect1"><a name="idm47268061642384"></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 do not, it is generally recommended to ignore the - return value of this call.</p></div><div class="refsect1"><a name="idm47268061640416"></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 - library, which can be compiled and linked to with the - <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> - file.</p><p>Internally, these functions send a single datagram with the - state string as payload to the <code class="constant">AF_UNIX</code> socket - referenced in the <code class="varname">$NOTIFY_SOCKET</code> environment - variable. If the first character of - <code class="varname">$NOTIFY_SOCKET</code> is "<code class="literal">@</code>", the - string is understood as Linux abstract namespace socket. The - datagram is accompanied by the process credentials of the sending - service, using SCM_CREDENTIALS.</p></div><div class="refsect1"><a name="idm47268061636448"></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 - 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="idm47268061632832"></a><h2 id="Examples">Examples<a class="headerlink" title="Permalink to this headline" href="#Examples">¶</a></h2><div class="example"><a name="idm47268061632192"></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 - 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="idm47268061630288"></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 - 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="idm47268061628272"></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" - "ERRNO=%i", - strerror(errno), - errno);</pre></div></div><br class="example-break"><div class="example"><a name="idm47268061626368"></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, - in order to continue operation after a service restart without - 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="idm47268061623584"></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>, - <a href="sd_watchdog_enabled.html"><span class="citerefentry"><span class="refentrytitle">sd_watchdog_enabled</span>(3)</span></a> - </p></div></div></body></html> |