chiark / gitweb /
man: bring machinectl man page up-to-date
[elogind.git] / man / sd_notify.xml
index a7bf17f..2bf3383 100644 (file)
@@ -21,7 +21,8 @@
   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>
         <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>
                                 <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>
-                <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>
-                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
+                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
                         <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
-                                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
-                                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:
-                                "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>
 
-                                <listitem><para>If a daemon fails, the
+                                <listitem><para>If a service fails, the
                                 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>
 
-                                <listitem><para>If a daemon fails, the
+                                <listitem><para>If a service fails, the
                                 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
-                                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:
-                                "MAINPID=4711"</para></listitem>
+                                <literal>MAINPID=4711</literal></para></listitem>
                         </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>
-                                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>
+                                <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
-                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
-                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>
                 <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>
                 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
-                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>
 
-                <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
-                <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>
-
-                <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>
                         <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
                 <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
-                        the init system:</para>
+                        the service manager:</para>
 
                         <programlisting>sd_notify(0, "READY=1");</programlisting>
                 </example>
                 <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"
                 <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>
+
+                <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>
                         <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>