chiark / gitweb /
~ianmdlvl / elogind.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
util: make http url validity checks more generic, and move them to util.c
[elogind.git] / man / sd_notify.xml
diff --git a/man/sd_notify.xml b/man/sd_notify.xml
index 7c1d982d855e4f37654ce653f9fd600bac7cdcfe..2bf3383c0db38793eccfcbecdbf86796b06603dc 100644 (file)
--- a/man/sd_notify.xml
+++ b/man/sd_notify.xml
@@ -8,20 +8,21 @@
   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/>.
 -->
 
-<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,12 +46,15 @@
         <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>
+                <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>
                 <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>
@@ -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
@@ -87,7 +115,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
@@ -98,77 +126,195 @@
                         <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
-                                value in signalling non-readiness, the
-                                only value daemons should send is
-                                "READY=1".</para></listitem>
+                                <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 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>
+
+                                <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 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>
                         </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>
                 for details.</para>
 
                 <para><function>sd_notifyf()</function> is similar to
                 <varname>NotifyAccess=</varname> option is correctly
                 set in the service definition file. See
                 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                 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>
                 <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>
@@ -178,63 +324,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 algorithm check the
-                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>
-
-                <para><function>sd_notify()</function> and
-                <function>sd_notifyf()</function> are implemented in
-                the reference implementation's drop-in
-                <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
-                more details about the reference implementation see
-                <citerefentry><refentrytitle>sd_daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry></para>
-
-                <para>If -DDISABLE_SYSTEMD is set during compilation
-                this function 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
@@ -251,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>
@@ -261,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"
@@ -273,22 +393,35 @@
                 <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>
                 <title>See Also</title>
                 <para>
                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
         </refsect1>
 
         <refsect1>
                 <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>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>
 
Unnamed repository; edit this file 'description' to name the repository.