← Back to branch summary

~ubuntu-branches/debian/jessie/systemd/jessie

« back to all changes in this revision

Viewing changes to man/sd_notify.html

  • Committer: Package Import Robot
  • Author(s): Tollef Fog Heen, Tollef Fog Heen, Michael Biebl
  • Date: 2012-04-03 19:59:17 UTC
  • mfrom: (1.1.10) (6.1.3 experimental)
  • Revision ID: package-import@ubuntu.com-20120403195917-l532urrbg4pkreas
Tags: 44-1
http://bugs.debian.org/664364
http://bugs.debian.org/663219
http://bugs.debian.org/663323
[ Tollef Fog Heen ]
* New upstream version.
  - Backport 3492207: journal: PAGE_SIZE is not known on ppc and other
    archs
  - Backport 5a2a2a1: journal: react with immediate rotation to a couple
    of more errors
  - Backport 693ce21: util: never follow symlinks in rm_rf_children()
    Fixes CVE-2012-1174, closes: #664364
* Drop output message from init-functions hook, it's pointless.
* Only rmdir /lib/init/rw if it exists.
* Explicitly order debian-fixup before sysinit.target to prevent a
  possible race condition with the creation of sockets.  Thanks to
  Michael Biebl for debugging this.
* Always restart the initctl socket on upgrades, to mask sysvinit
  removing it.

[ Michael Biebl ]
* Remove workaround for non-interactive sessions from pam config again.
* Create compat /dev/initctl symlink in case we are upgrading from a system
  running a newer version of sysvinit (using /run/initctl) and sysvinit is
  replaced with systemd-sysv during the upgrade. Closes: #663219
* Install new man pages.
* Build-Depend on valac (>= 0.12) instead of valac-0.12. Closes: #663323

Show diffs side-by-side

added added

removed removed

Lines of Context:
man/sd_notify.html
1
 
<?xml version="1.0" encoding="UTF-8"?>
2
 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3
 
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>sd_notify</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"/></head><body><div class="refentry" title="sd_notify"><a id="sd_notify"/><div class="titlepage"/><div class="refnamediv"><h2>Name</h2><p>sd_notify, sd_notifyf — Notify init system about start-up completion and other daemon status changes</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include "sd-daemon.h"</pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">int <strong>fsfuncsd_notify</strong>(</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" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">int <strong>fsfuncsd_notifyf</strong>(</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" title="Description"><a id="id536582"/><h2>Description</h2><p><code class="function">sd_notify()</code> shall be called
 
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.76.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" title="sd_notify"><a name="sd_notify"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>sd_notify, sd_notifyf — Notify init system about start-up completion and other daemon status changes</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include &lt;systemd/sd-daemon.h&gt;</pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><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" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><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" title="Description"><a name="id516282"></a><h2>Description</h2><p><code class="function">sd_notify()</code> shall be called
4
2
                by a daemon to notify the init system about status
5
3
                changes. It can be used to send arbitrary information,
6
4
                encoded in an environment-block-like string. Most
46
44
                                daemon, in case the init system did
47
45
                                not fork off the process
48
46
                                itself. Example:
49
 
                                "MAINPID=4711"</p></dd></dl></div><p>It is recommended to prefix variable names that
 
47
                                "MAINPID=4711"</p></dd><dt><span class="term">WATCHDOG=1</span></dt><dd><p>Tells systemd to
 
48
                                update the watchdog timestamp.
 
49
                                Services using this feature should do
 
50
                                this in regular intervals. A watchdog
 
51
                                framework can use the timestamps to
 
52
                                detect failed
 
53
                                services.</p></dd></dl></div><p>It is recommended to prefix variable names that
50
54
                are not shown in the list above with
51
55
                <code class="varname">X_</code> to avoid namespace
52
56
                clashes.</p><p>Note that systemd will accept status data sent
55
59
                set in the service definition file. See
56
60
                <span class="citerefentry"><span class="refentrytitle">systemd.service</span>(5)</span>
57
61
                for details.</p><p><code class="function">sd_notifyf()</code> is similar to
58
 
                <code class="function">sd_notifyf()</code> but takes a
 
62
                <code class="function">sd_notify()</code> but takes a
59
63
                <code class="function">printf()</code>-like format string plus
60
 
                arguments.</p></div><div class="refsect1" title="Return Value"><a id="id504113"/><h2>Return Value</h2><p>On failure, these calls return a negative
 
64
                arguments.</p></div><div class="refsect1" title="Return Value"><a name="id548599"></a><h2>Return Value</h2><p>On failure, these calls return a negative
61
65
                errno-style error code. If
62
66
                <code class="varname">$NOTIFY_SOCKET</code> was not set and
63
67
                hence no status data could be sent, 0 is returned. If
65
69
                positive return value. In order to support both, init
66
70
                systems that implement this scheme and those which
67
71
                don't, it is generally recommended to ignore the return
68
 
                value of this call.</p></div><div class="refsect1" title="Notes"><a id="id504131"/><h2>Notes</h2><p>These functions are provided by the reference
 
72
                value of this call.</p></div><div class="refsect1" title="Notes"><a name="id516013"></a><h2>Notes</h2><p>These functions are provided by the reference
69
73
                implementation of APIs for new-style daemons and
70
74
                distributed with the systemd package. The algorithms
71
75
                they implement are simple, and can easily be
81
85
                datagram is accompanied by the process credentials of
82
86
                the sending daemon, using SCM_CREDENTIALS.</p><p>For details about the algorithms check the
83
87
                liberally licensed reference implementation sources:
84
 
                <a class="ulink" href="http://cgit.freedesktop.org/systemd/tree/src/sd-daemon.c">http://cgit.freedesktop.org/systemd/tree/src/sd-daemon.c</a>
85
 
                resp. <a class="ulink" href="http://cgit.freedesktop.org/systemd/tree/src/sd-daemon.h">http://cgit.freedesktop.org/systemd/tree/src/sd-daemon.h</a></p><p><code class="function">sd_notify()</code> and
 
88
                <a class="ulink" href="http://cgit.freedesktop.org/systemd/systemd/plain/src/sd-daemon.c" target="_top">http://cgit.freedesktop.org/systemd/systemd/plain/src/sd-daemon.c</a>
 
89
                resp. <a class="ulink" href="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h" target="_top">http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h</a></p><p><code class="function">sd_notify()</code> and
86
90
                <code class="function">sd_notifyf()</code> are implemented in
87
91
                the reference implementation's
88
92
                <code class="filename">sd-daemon.c</code> and
97
101
                <span class="citerefentry"><span class="refentrytitle">sd_daemon</span>(7)</span>.</p><p>If the reference implementation is used as
98
102
                drop-in files and -DDISABLE_SYSTEMD is set during
99
103
                compilation these functions will always return 0 and
100
 
                otherwise become a NOP.</p></div><div class="refsect1" title="Environment"><a id="id504298"/><h2>Environment</h2><div class="variablelist"><dl><dt><span class="term"><code class="varname">$NOTIFY_SOCKET</code></span></dt><dd><p>Set by the init system
 
104
                otherwise become a NOP.</p></div><div class="refsect1" title="Environment"><a name="id516107"></a><h2>Environment</h2><div class="variablelist"><dl><dt><span class="term"><code class="varname">$NOTIFY_SOCKET</code></span></dt><dd><p>Set by the init system
101
105
                                for supervised processes for status
102
106
                                and start-up completion
103
107
                                notification. This environment variable
104
108
                                specifies the socket
105
109
                                <code class="function">sd_notify()</code> talks
106
 
                                to. See above for details.</p></dd></dl></div></div><div class="refsect1" title="Examples"><a id="id504329"/><h2>Examples</h2><div class="example"><a id="id504334"/><p class="title"><strong>Example 1. Start-up Notification</strong></p><div class="example-contents"><p>When a daemon finished starting up, it
 
110
                                to. See above for details.</p></dd></dl></div></div><div class="refsect1" title="Examples"><a name="id516137"></a><h2>Examples</h2><div class="example"><a name="id516143"></a><p class="title"><b>Example 1. Start-up Notification</b></p><div class="example-contents"><p>When a daemon finished starting up, it
107
111
                        might issue the following call to notify
108
 
                        the init system:</p><pre class="programlisting">sd_notify(0, "READY=1");</pre></div></div><br class="example-break"/><div class="example"><a id="id504351"/><p class="title"><strong>Example 2. Extended Start-up Notification</strong></p><div class="example-contents"><p>A daemon could send the following after
 
112
                        the init system:</p><pre class="programlisting">sd_notify(0, "READY=1");</pre></div></div><br class="example-break"><div class="example"><a name="id516160"></a><p class="title"><b>Example 2. Extended Start-up Notification</b></p><div class="example-contents"><p>A daemon could send the following after
109
113
                        completing initialization:</p><pre class="programlisting">sd_notifyf(0, "READY=1\n"
110
114
              "STATUS=Processing requests...\n"
111
115
              "MAINPID=%lu",
112
 
              (unsigned long) getpid());</pre></div></div><br class="example-break"/><div class="example"><a id="id504369"/><p class="title"><strong>Example 3. Error Cause Notification</strong></p><div class="example-contents"><p>A daemon could send the following shortly before exiting, on failure</p><pre class="programlisting">sd_notifyf(0, "STATUS=Failed to start up: %s\n"
 
116
              (unsigned long) getpid());</pre></div></div><br class="example-break"><div class="example"><a name="id516177"></a><p class="title"><b>Example 3. Error Cause Notification</b></p><div class="example-contents"><p>A daemon could send the following shortly before exiting, on failure</p><pre class="programlisting">sd_notifyf(0, "STATUS=Failed to start up: %s\n"
113
117
              "ERRNO=%i",
114
118
              strerror(errno),
115
 
              errno);</pre></div></div><br class="example-break"/></div><div class="refsect1" title="See Also"><a id="id504387"/><h2>See Also</h2><p>
 
119
              errno);</pre></div></div><br class="example-break"></div><div class="refsect1" title="See Also"><a name="id516195"></a><h2>See Also</h2><p>
116
120
                        <span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span>,
117
121
                        <span class="citerefentry"><span class="refentrytitle">sd_daemon</span>(7)</span>,
118
122
                        <span class="citerefentry"><span class="refentrytitle">daemon</span>(7)</span>,