man: bring machinectl man page up-to-date

[elogind.git] / man / sd_notify.xml

diff --git a/man/sd_notify.xml b/man/sd_notify.xml
index a7bf17f9c68b461d06a69e5f4110143f2d5aef59..2bf3383c0db38793eccfcbecdbf86796b06603dc 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,10 @@
         <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>
+                <refname>sd_pid_notify</refname>
+                <refname>sd_pid_notifyf</refname>
+                <refname>sd_pid_notify_with_fds</refname>
+                <refpurpose>Notify service manager about start-up completion and other service status changes</refpurpose>

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


@@ -64,22 +68,46 @@
                                 <paramdef>const char *<parameter>format</parameter></paramdef>
                                 <paramdef>...</paramdef>
                         </funcprototype>
                                 <paramdef>const char *<parameter>format</parameter></paramdef>
                                 <paramdef>...</paramdef>
                         </funcprototype>

+
+                        <funcprototype>
+                                <funcdef>int <function>sd_pid_notify</function></funcdef>
+                                <paramdef>pid_t <parameter>pid</parameter></paramdef>
+                                <paramdef>int <parameter>unset_environment</parameter></paramdef>
+                                <paramdef>const char *<parameter>state</parameter></paramdef>
+                        </funcprototype>
+
+                        <funcprototype>
+                                <funcdef>int <function>sd_pid_notifyf</function></funcdef>
+                                <paramdef>pid_t <parameter>pid</parameter></paramdef>
+                                <paramdef>int <parameter>unset_environment</parameter></paramdef>
+                                <paramdef>const char *<parameter>format</parameter></paramdef>
+                                <paramdef>...</paramdef>
+                        </funcprototype>
+
+                        <funcprototype>
+                                <funcdef>int <function>sd_pid_notify_with_fds</function></funcdef>
+                                <paramdef>pid_t <parameter>pid</parameter></paramdef>
+                                <paramdef>int <parameter>unset_environment</parameter></paramdef>
+                                <paramdef>const char *<parameter>state</parameter></paramdef>
+                                <paramdef>const int *<parameter>fds</parameter></paramdef>
+                                <paramdef>unsigned <parameter>n_fds</parameter></paramdef>
+                        </funcprototype>

                 </funcsynopsis>
         </refsynopsisdiv>
 
         <refsect1>
                 <title>Description</title>
                 </funcsynopsis>
         </refsynopsisdiv>
 
         <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,87 +126,156 @@
                         <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>
 
                         </varlistentry>
 
                         <varlistentry>
                                 <term>MAINPID=...</term>
 

-                                <listitem><para>The main pid of the
-                                daemon, in case the init system did
+                                <listitem><para>The main process ID (PID) of the
+                                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>
                                 <term>WATCHDOG=1</term>
 
                         </varlistentry>
 
                         <varlistentry>
                                 <term>WATCHDOG=1</term>
 

-                                <listitem><para>Tells systemd to
+                                <listitem><para>Tells the service manager 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>
                                 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>
+                                for information how to enable this
+                                functionality and
+                                <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+                                for the details of how the service can
+                                check if the the watchdog is enabled.
+                                </para></listitem>

                         </varlistentry>
                         </varlistentry>

+
+
+                        <varlistentry>
+                                <term>FDSTORE=1</term>
+
+                                <listitem><para>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
+                                <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>). This
+                                is useful for implementing service
+                                restart schemes where services
+                                serialize their state to
+                                <filename>/run</filename>, push their
+                                file descriptors to the system
+                                manager, and are then restarted,
+                                retrieving their state again via
+                                socket passing and
+                                <filename>/run</filename>. Note that
+                                the service manager will accept
+                                messages for a service only if
+                                <varname>FileDescriptorStoreMax=</varname>
+                                is set to non-zero for it (defaults to
+                                zero). See
+                                <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                                for details. Multiple arrays of file
+                                descriptors may be sent in seperate
+                                messages, in which case the arrays are
+                                combined. Note that the service
+                                manager removes duplicate file
+                                descriptors before passing them to the
+                                service. Use
+                                <function>sd_pid_notify_with_fds()</function>
+                                to send messages with
+                                <literal>FDSTORE=1</literal>, see
+                                below.</para></listitem>
+                        </varlistentry>
+

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

-                are not shown in the list above with
-                <varname>X_</varname> to avoid namespace
-                clashes.</para>
+                are not listed above with <varname>X_</varname> to
+                avoid namespace clashes.</para>

 
                 <para>Note that systemd will accept status data sent
 
                 <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>


@@ -188,6 +285,36 @@
                 <function>sd_notify()</function> but takes a
                 <function>printf()</function>-like format string plus
                 arguments.</para>
                 <function>sd_notify()</function> but takes a
                 <function>printf()</function>-like format string plus
                 arguments.</para>

+
+                <para><function>sd_pid_notify()</function> and
+                <function>sd_pid_notifyf()</function> are similar to
+                <function>sd_notify()</function> and
+                <function>sd_notifyf()</function> 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 <function>sd_notify()</function>
+                and <function>sd_notifyf()</function>.</para>
+
+                <para><function>sd_pid_notify_with_fds()</function> is
+                similar to <function>sd_pid_notify()</function> 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 <literal>FDSTORE=1</literal>
+                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 <function>sd_pid_notify()</function>,
+                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
+                <literal>FDSTORE=1</literal>) they are immediately
+                closed on reception.</para>

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


@@ -197,57 +324,27 @@
                 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
                 <constant>AF_UNIX</constant> socket referenced in the
                 <varname>$NOTIFY_SOCKET</varname> environment
                 variable. If the first character of
 
                 <para>Internally, these functions send a single
                 datagram with the state string as payload to the
                 <constant>AF_UNIX</constant> socket referenced in the
                 <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
-                <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
-                <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>
         </refsect1>
 
         <refsect1>


@@ -257,7 +354,7 @@
                         <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


@@ -274,9 +371,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>


@@ -284,7 +381,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"


@@ -296,13 +393,25 @@
                 <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",
               strerror(errno),
               errno);</programlisting>
                 </example>
 
                         <programlisting>sd_notifyf(0, "STATUS=Failed to start up: %s\n"
               "ERRNO=%i",
               strerror(errno),
               errno);</programlisting>
                 </example>

+
+                <example>
+                        <title>Store a File Descriptor in the Service Manager</title>
+
+                        <para>To store an open file descriptor in the
+                        service manager, in order to continue
+                        operation after a service restart without
+                        losing state use
+                        <literal>FDSTORE=1</literal>:</para>
+
+                        <programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1", &amp;fd, 1);</programlisting>
+                </example>

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


@@ -311,7 +420,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>