X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsd_notify.xml;h=2bf3383c0db38793eccfcbecdbf86796b06603dc;hp=35f6f71ab37b00a6919e6912bd00e4ed4b648cc3;hb=a354329f724d6ce913d2ccffb2be8f3327a67faa;hpb=75399049653f2d5e22032da70cf96f20d7b4d9a6

diff --git a/man/sd_notify.xml b/man/sd_notify.xml
index 35f6f71ab..2bf3383c0 100644
--- a/man/sd_notify.xml
+++ b/man/sd_notify.xml
@@ -46,6 +46,9 @@
         <refnamediv>
                 <refname>sd_notify</refname>
                 <refname>sd_notifyf</refname>
+                <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>
 
@@ -65,6 +68,30 @@
                                 <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>
 
@@ -175,7 +202,7 @@
                         <varlistentry>
                                 <term>MAINPID=...</term>
 
-                                <listitem><para>The main pid of the
+                                <listitem><para>The main process ID (PID) of the
                                 service, in case the service manager did
                                 not fork off the process
                                 itself. Example:
@@ -185,7 +212,7 @@
                         <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
@@ -199,12 +226,53 @@
                                 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 service only if the
@@ -217,6 +285,36 @@
                 <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>
@@ -295,13 +393,25 @@
                 <example>
                         <title>Error Cause Notification</title>
 
-                        <para>A service 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>