man: use the escape for "-" in example instead of space.

[elogind.git] / man / sd_notify.xml

diff --git a/man/sd_notify.xml b/man/sd_notify.xml
index 75edeeadf39f2c98f65d1f6779e73be1c7b3487d..fbb882dfd2c0e0c0f177232b6e293c361fa88ee4 100644 (file)
--- a/man/sd_notify.xml
+++ b/man/sd_notify.xml
@@ -21,7 +21,8 @@
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 

-<refentry id="sd_notify">
+<refentry id="sd_notify"
+        xmlns:xi="http://www.w3.org/2001/XInclude">

 
         <refentryinfo>
                 <title>sd_notify</title>
 
         <refentryinfo>
                 <title>sd_notify</title>


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

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

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


@@ -69,17 +70,17 @@
 
         <refsect1>
                 <title>Description</title>
 
         <refsect1>
                 <title>Description</title>

-                <para><function>sd_notify()</function> shall be called
-                by a daemon to notify the init system about status
-                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.</para>
+                <para><function>sd_notify()</function> 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.</para>

 
                 <para>If the <parameter>unset_environment</parameter>
 
                 <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>
                 will unset the <varname>$NOTIFY_SOCKET</varname>

-                environment variable before returning (regardless
+                environment variable before returning (regardless of

                 whether the function call itself succeeded or
                 not). Further calls to
                 <function>sd_notify()</function> will then fail, but
                 whether the function call itself succeeded or
                 not). Further calls to
                 <function>sd_notify()</function> will then fail, but


@@ -98,58 +99,87 @@
                         <varlistentry>
                                 <term>READY=1</term>
 
                         <varlistentry>
                                 <term>READY=1</term>
 

-                                <listitem><para>Tells the init system
-                                that daemon startup is finished. This
-                                is only used by systemd if the service
-                                definition file has Type=notify
-                                set. The passed argument is a boolean
-                                "1" or "0". Since there is little
+                                <listitem><para>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
                                 value in signaling non-readiness, the

-                                only value daemons should send is
-                                "READY=1".</para></listitem>
+                                only value services should send is
+                                <literal>READY=1</literal>
+                                (i.e. <literal>READY=0</literal> is
+                                not defined).</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term>RELOADING=1</term>
+
+                                <listitem><para>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
+                                <literal>READY=1</literal>
+                                notification when it completed
+                                reloading its
+                                configuration.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term>STOPPING=1</term>
+
+                                <listitem><para>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.</para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                                 <term>STATUS=...</term>
 
                                 <listitem><para>Passes a single-line
                         </varlistentry>
 
                         <varlistentry>
                                 <term>STATUS=...</term>
 
                                 <listitem><para>Passes a single-line

-                                status string back to the init system
-                                that describes the daemon state. This
+                                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:
                                 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:

-                                "STATUS=Completed 66% of file system
-                                check..."</para></listitem>
+                                <literal>STATUS=Completed 66% of file
+                                system
+                                check...</literal></para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                                 <term>ERRNO=...</term>
 
                         </varlistentry>
 
                         <varlistentry>
                                 <term>ERRNO=...</term>
 

-                                <listitem><para>If a daemon fails, the
+                                <listitem><para>If a service fails, the

                                 errno-style error code, formatted as
                                 errno-style error code, formatted as

-                                string. Example: "ERRNO=2" for
+                                string. Example: <literal>ERRNO=2</literal> for

                                 ENOENT.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
                                 <term>BUSERROR=...</term>
 
                                 ENOENT.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
                                 <term>BUSERROR=...</term>
 

-                                <listitem><para>If a daemon fails, the
+                                <listitem><para>If a service fails, the

                                 D-Bus error-style error code. Example:
                                 D-Bus error-style error code. Example:

-                                "BUSERROR=org.freedesktop.DBus.Error.TimedOut"</para></listitem>
+                                <literal>BUSERROR=org.freedesktop.DBus.Error.TimedOut</literal></para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                                 <term>MAINPID=...</term>
 
                                 <listitem><para>The main pid of the
                         </varlistentry>
 
                         <varlistentry>
                                 <term>MAINPID=...</term>
 
                                 <listitem><para>The main pid of the

-                                daemon, in case the init system did
+                                service, in case the service manager did

                                 not fork off the process
                                 itself. Example:
                                 not fork off the process
                                 itself. Example:

-                                "MAINPID=4711"</para></listitem>
+                                <literal>MAINPID=4711</literal></para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>


@@ -164,11 +194,15 @@
                                 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                                 for details. It is recommended to send
                                 this message if the
                                 <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>
+                                <varname>$WATCHDOG_PID</varname>
+                                environment variable has been set to
+                                the PID of the service process, in
+                                every half the time interval that is
+                                specified in the
+                                <varname>$WATCHDOG_USEC</varname>
+                                environment variable. See
+                                <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+                                for details.</para></listitem>

                         </varlistentry>
                 </variablelist>
 
                         </varlistentry>
                 </variablelist>
 


@@ -178,7 +212,7 @@
                 clashes.</para>
 
                 <para>Note that systemd will accept status data sent
                 clashes.</para>
 
                 <para>Note that systemd will accept status data sent

-                from a daemon only if the
+                from a service only if the

                 <varname>NotifyAccess=</varname> option is correctly
                 set in the service definition file. See
                 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                 <varname>NotifyAccess=</varname> option is correctly
                 set in the service definition file. See
                 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>


@@ -197,68 +231,37 @@
                 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>
 
         <refsect1>
                 <title>Notes</title>
 
                 value of this call.</para>
         </refsect1>
 
         <refsect1>
                 <title>Notes</title>
 

-                <para>These functions are provided by the reference
-                implementation of APIs for new-style daemons and
-                distributed with the systemd package. The algorithms
-                they implement are simple, and can easily be
-                reimplemented in daemons if it is important to support
-                this interface without using the reference
-                implementation.</para>
+                <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>

 
                 <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
                 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 algorithms check the
-                liberally licensed reference implementation sources:
-                <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
-                the reference implementation's
-                <filename>sd-daemon.c</filename> and
-                <filename>sd-daemon.h</filename> files. These
-                interfaces are available as shared library, which can
-                be compiled and linked to with the
-                <literal>libsystemd-daemon</literal>
-                <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
-                <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</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>
+                the sending service, using SCM_CREDENTIALS.</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>
 

-                                <listitem><para>Set by the init system
+                                <listitem><para>Set by the service manager

                                 for supervised processes for status
                                 and start-up completion
                                 notification. This environment variable
                                 for supervised processes for status
                                 and start-up completion
                                 notification. This environment variable


@@ -275,9 +278,9 @@
                 <example>
                         <title>Start-up Notification</title>
 
                 <example>
                         <title>Start-up Notification</title>
 

-                        <para>When a daemon finished starting up, it
+                        <para>When a service finished starting up, it

                         might issue the following call to notify
                         might issue the following call to notify

-                        the init system:</para>
+                        the service manager:</para>

 
                         <programlisting>sd_notify(0, "READY=1");</programlisting>
                 </example>
 
                         <programlisting>sd_notify(0, "READY=1");</programlisting>
                 </example>


@@ -285,7 +288,7 @@
                 <example>
                         <title>Extended Start-up Notification</title>
 
                 <example>
                         <title>Extended Start-up Notification</title>
 

-                        <para>A daemon could send the following after
+                        <para>A service could send the following after

                         completing initialization:</para>
 
                         <programlisting>sd_notifyf(0, "READY=1\n"
                         completing initialization:</para>
 
                         <programlisting>sd_notifyf(0, "READY=1\n"


@@ -297,7 +300,7 @@
                 <example>
                         <title>Error Cause Notification</title>
 
                 <example>
                         <title>Error Cause Notification</title>
 

-                        <para>A daemon could send the following shortly before exiting, on failure</para>
+                        <para>A service could send the following shortly before exiting, on failure</para>

 
                         <programlisting>sd_notifyf(0, "STATUS=Failed to start up: %s\n"
               "ERRNO=%i",
 
                         <programlisting>sd_notifyf(0, "STATUS=Failed to start up: %s\n"
               "ERRNO=%i",


@@ -312,7 +315,8 @@
                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</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>
+                        <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>

                 </para>
         </refsect1>
 
                 </para>
         </refsect1>