core: fix timestamp assignment

[elogind.git] / man / sd_notify.xml

diff --git a/man/sd_notify.xml b/man/sd_notify.xml
index 80856a22d534ba984b41737fec9238732cf1369d..55965ffce4e999d9f0a1b34e1b674683976cf497 100644 (file)
--- a/man/sd_notify.xml
+++ b/man/sd_notify.xml
@@ -8,16 +8,16 @@
   Copyright 2010 Lennart Poettering
 
   systemd is free software; you can redistribute it and/or modify it
   Copyright 2010 Lennart Poettering
 
   systemd is free software; you can redistribute it and/or modify it

-  under the terms of the GNU General Public License as published by
-  the Free Software Foundation; either version 2 of the License, or
+  under the terms of the GNU Lesser General Public License as published by
+  the Free Software Foundation; either version 2.1 of the License, or

   (at your option) any later version.
 
   systemd is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
   (at your option) any later version.
 
   systemd is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU

-  General Public License for more details.
+  Lesser General Public License for more details.

 
 

-  You should have received a copy of the GNU General Public License
+  You should have received a copy of the GNU Lesser General Public License

   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 


@@ -45,12 +45,12 @@
         <refnamediv>
                 <refname>sd_notify</refname>
                 <refname>sd_notifyf</refname>
         <refnamediv>
                 <refname>sd_notify</refname>
                 <refname>sd_notifyf</refname>

-                <refpurpose>Notify init system about start-up completion and other daemon status changes</refpurpose>
+                <refpurpose>Notify service manager about start-up completion and other daemon status changes</refpurpose>

         </refnamediv>
 
         <refsynopsisdiv>
                 <funcsynopsis>
         </refnamediv>
 
         <refsynopsisdiv>
                 <funcsynopsis>

-                        <funcsynopsisinfo>#include "sd-daemon.h"</funcsynopsisinfo>
+                        <funcsynopsisinfo>#include &lt;systemd/sd-daemon.h&gt;</funcsynopsisinfo>

 
                         <funcprototype>
                                 <funcdef>int <function>sd_notify</function></funcdef>
 
                         <funcprototype>
                                 <funcdef>int <function>sd_notify</function></funcdef>


@@ -77,7 +77,7 @@
                 notification.</para>
 
                 <para>If the <parameter>unset_environment</parameter>
                 notification.</para>
 
                 <para>If the <parameter>unset_environment</parameter>

-                parameter is non-zero <function>sd_notify()</function>
+                parameter is non-zero, <function>sd_notify()</function>

                 will unset the <varname>$NOTIFY_SOCKET</varname>
                 environment variable before returning (regardless
                 whether the function call itself succeeded or
                 will unset the <varname>$NOTIFY_SOCKET</varname>
                 environment variable before returning (regardless
                 whether the function call itself succeeded or


@@ -87,7 +87,7 @@
                 processes.</para>
 
                 <para>The <parameter>state</parameter> parameter
                 processes.</para>
 
                 <para>The <parameter>state</parameter> parameter

-                should contain an newline-seperated list of variable
+                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, similar in style to an environment
                 block. A trailing newline is implied if none is
                 specified. The string may contain any kind of variable


@@ -104,7 +104,7 @@
                                 definition file has Type=notify
                                 set. The passed argument is a boolean
                                 "1" or "0". Since there is little
                                 definition file has Type=notify
                                 set. The passed argument is a boolean
                                 "1" or "0". Since there is little

-                                value in signalling non-readiness, the
+                                value in signaling non-readiness, the

                                 only value daemons should send is
                                 "READY=1".</para></listitem>
                         </varlistentry>
                                 only value daemons should send is
                                 "READY=1".</para></listitem>
                         </varlistentry>


@@ -151,6 +151,25 @@
                                 itself. Example:
                                 "MAINPID=4711"</para></listitem>
                         </varlistentry>
                                 itself. Example:
                                 "MAINPID=4711"</para></listitem>
                         </varlistentry>

+
+                        <varlistentry>
+                                <term>WATCHDOG=1</term>
+
+                                <listitem><para>Tells systemd to
+                                update the watchdog timestamp. This is
+                                the keep-alive ping that services need
+                                to issue in regular intervals if
+                                <varname>WatchdogSec=</varname> is
+                                enabled for it. See
+                                <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                                for details. It is recommended to send
+                                this message if the
+                                <varname>WATCHDOG_USEC=</varname>
+                                environment variable has been set for
+                                the service process, in every half the
+                                time interval that is specified in the
+                                variable.</para></listitem>
+                        </varlistentry>

                 </variablelist>
 
                 <para>It is recommended to prefix variable names that
                 </variablelist>
 
                 <para>It is recommended to prefix variable names that


@@ -166,7 +185,7 @@
                 for details.</para>
 
                 <para><function>sd_notifyf()</function> is similar to
                 for details.</para>
 
                 <para><function>sd_notifyf()</function> is similar to

-                <function>sd_notifyf()</function> but takes a
+                <function>sd_notify()</function> but takes a

                 <function>printf()</function>-like format string plus
                 arguments.</para>
         </refsect1>
                 <function>printf()</function>-like format string plus
                 arguments.</para>
         </refsect1>


@@ -178,10 +197,10 @@
                 errno-style error code. If
                 <varname>$NOTIFY_SOCKET</varname> was not set and
                 hence no status data could be sent, 0 is returned. If
                 errno-style error code. If
                 <varname>$NOTIFY_SOCKET</varname> was not set and
                 hence no status data could be sent, 0 is returned. If

-                the status was sent these functions return with a
+                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
                 positive return value. In order to support both, init
                 systems that implement this scheme and those which

-                don't, it is generally recommended to ignore the return
+                do not, it is generally recommended to ignore the return

                 value of this call.</para>
         </refsect1>
 
                 value of this call.</para>
         </refsect1>
 


@@ -198,39 +217,43 @@
 
                 <para>Internally, these functions send a single
                 datagram with the state string as payload to the
 
                 <para>Internally, these functions send a single
                 datagram with the state string as payload to the

-                AF_UNIX socket referenced in the
+                <constant>AF_UNIX</constant> socket referenced in the

                 <varname>$NOTIFY_SOCKET</varname> environment
                 variable. If the first character of
                 <varname>$NOTIFY_SOCKET</varname> environment
                 variable. If the first character of

-                <varname>$NOTIFY_SOCKET</varname> is @ the string is
+                <varname>$NOTIFY_SOCKET</varname> is <literal>@</literal>, the string is

                 understood as Linux abstract namespace socket. The
                 datagram is accompanied by the process credentials of
                 the sending daemon, using SCM_CREDENTIALS.</para>
 
                 understood as Linux abstract namespace socket. The
                 datagram is accompanied by the process credentials of
                 the sending daemon, using SCM_CREDENTIALS.</para>
 

-                <para>For details about the algorithm check the
+                <para>For details about the algorithms check the

                 liberally licensed reference implementation sources:
                 liberally licensed reference implementation sources:

-                <ulink url="http://cgit.freedesktop.org/systemd/tree/src/sd-daemon.c"/>
-                resp. <ulink
-                url="http://cgit.freedesktop.org/systemd/tree/src/sd-daemon.h"/></para>
+                <ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/libsystemd-daemon/sd-daemon.c"/>
+                and <ulink
+                url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h"/></para>

 
                 <para><function>sd_notify()</function> and
                 <function>sd_notifyf()</function> are implemented in
 
                 <para><function>sd_notify()</function> and
                 <function>sd_notifyf()</function> are implemented in

-                the reference implementation's drop-in
+                the reference implementation's

                 <filename>sd-daemon.c</filename> and
                 <filename>sd-daemon.c</filename> and

-                <filename>sd-daemon.h</filename> files. It is
-                recommended that applications consuming these APIs
-                copy the implementation into their source tree. For
+                <filename>sd-daemon.h</filename> files. These
+                interfaces are available as shared library, which can
+                be compiled and linked to with the
+                <constant>libsystemd-daemon</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+                file. Alternatively, applications consuming these APIs
+                may copy the implementation into their source tree. For

                 more details about the reference implementation see
                 more details about the reference implementation see

-                <citerefentry><refentrytitle>sd_daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry></para>
+                <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>

 
 

-                <para>If -DDISABLE_SYSTEMD is set during compilation
-                this function will always return 0 and otherwise
-                become a NOP.</para>
+                <para>If the reference implementation is used as
+                drop-in files and -DDISABLE_SYSTEMD is set during
+                compilation, these functions will always return 0 and
+                otherwise become a NOP.</para>

         </refsect1>
 
         <refsect1>
                 <title>Environment</title>
 
         </refsect1>
 
         <refsect1>
                 <title>Environment</title>
 

-                <variablelist>
+                <variablelist class='environment-variables'>

                         <varlistentry>
                                 <term><varname>$NOTIFY_SOCKET</varname></term>
 
                         <varlistentry>
                                 <term><varname>$NOTIFY_SOCKET</varname></term>
 


@@ -252,7 +275,7 @@
                         <title>Start-up Notification</title>
 
                         <para>When a daemon finished starting up, it
                         <title>Start-up Notification</title>
 
                         <para>When a daemon finished starting up, it

-                        might issue the following call call to notify
+                        might issue the following call to notify

                         the init system:</para>
 
                         <programlisting>sd_notify(0, "READY=1");</programlisting>
                         the init system:</para>
 
                         <programlisting>sd_notify(0, "READY=1");</programlisting>


@@ -286,7 +309,7 @@
                 <title>See Also</title>
                 <para>
                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                 <title>See Also</title>
                 <para>
                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

-                        <citerefentry><refentrytitle>sd_daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

                         <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                 </para>
                         <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                 </para>