chiark / gitweb /
fs-util: add flags parameter to chase_symlinks()
[elogind.git] / man / sd_notify.xml
index b7c33da63af35f44b8dc8b504a3f1720543ae670..f2710b6ab3d07caa015e0efd3701ef7a18c64069 100644 (file)
-<?xml version='1.0'?> <!--*-nxml-*-->
+<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 
 <!--
-  This file is part of systemd.
+  This file is part of elogind.
 
   Copyright 2010 Lennart Poettering
 
-  systemd is free software; you can redistribute it and/or modify it
+  elogind is free software; you can redistribute it and/or modify it
   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
+  elogind 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
   Lesser General Public License for more details.
 
   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 elogind; If not, see <http://www.gnu.org/licenses/>.
 -->
 
 <refentry id="sd_notify"
-        xmlns:xi="http://www.w3.org/2001/XInclude">
-
-        <refentryinfo>
-                <title>sd_notify</title>
-                <productname>systemd</productname>
-
-                <authorgroup>
-                        <author>
-                                <contrib>Developer</contrib>
-                                <firstname>Lennart</firstname>
-                                <surname>Poettering</surname>
-                                <email>lennart@poettering.net</email>
-                        </author>
-                </authorgroup>
-        </refentryinfo>
-
-        <refmeta>
-                <refentrytitle>sd_notify</refentrytitle>
-                <manvolnum>3</manvolnum>
-        </refmeta>
-
-        <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>
-
-        <refsynopsisdiv>
-                <funcsynopsis>
-                        <funcsynopsisinfo>#include &lt;systemd/sd-daemon.h&gt;</funcsynopsisinfo>
-
-                        <funcprototype>
-                                <funcdef>int <function>sd_notify</function></funcdef>
-                                <paramdef>int <parameter>unset_environment</parameter></paramdef>
-                                <paramdef>const char *<parameter>state</parameter></paramdef>
-                        </funcprototype>
-
-                        <funcprototype>
-                                <funcdef>int <function>sd_notifyf</function></funcdef>
-                                <paramdef>int <parameter>unset_environment</parameter></paramdef>
-                                <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> 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>
-                will unset the <varname>$NOTIFY_SOCKET</varname>
-                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
-                the variable is no longer inherited by child
-                processes.</para>
-
-                <para>The <parameter>state</parameter> parameter
-                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, but the following shall be considered
-                well-known:</para>
-
-                <variablelist>
-                        <varlistentry>
-                                <term>READY=1</term>
-
-                                <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
-                                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:
-                                <literal>STATUS=Completed 66% of file
-                                system
-                                check...</literal></para></listitem>
-                        </varlistentry>
-
-                        <varlistentry>
-                                <term>ERRNO=...</term>
-
-                                <listitem><para>If a service fails, the
-                                errno-style error code, formatted as
-                                string. Example: <literal>ERRNO=2</literal> for
-                                ENOENT.</para></listitem>
-                        </varlistentry>
-
-                        <varlistentry>
-                                <term>BUSERROR=...</term>
-
-                                <listitem><para>If a service fails, the
-                                D-Bus error-style error code. Example:
-                                <literal>BUSERROR=org.freedesktop.DBus.Error.TimedOut</literal></para></listitem>
-                        </varlistentry>
-
-                        <varlistentry>
-                                <term>MAINPID=...</term>
-
-                                <listitem><para>The main process ID (PID) of the
-                                service, in case the service manager did
-                                not fork off the process
-                                itself. Example:
-                                <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 separate
-                                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 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
-                <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_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>
-                <title>Return Value</title>
-
-                <para>On failure, these calls return a negative
-                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
-                positive return value. In order to support both, init
-                systems that implement this scheme and those which
-                do not, it is generally recommended to ignore the return
-                value of this call.</para>
-        </refsect1>
-
-        <refsect1>
-                <title>Notes</title>
-
-                <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 <literal>@</literal>, the string is
-                understood as Linux abstract namespace socket. The
-                datagram is accompanied by the process credentials of
-                the sending service, using SCM_CREDENTIALS.</para>
-        </refsect1>
-
-        <refsect1>
-                <title>Environment</title>
-
-                <variablelist class='environment-variables'>
-                        <varlistentry>
-                                <term><varname>$NOTIFY_SOCKET</varname></term>
-
-                                <listitem><para>Set by the service manager
-                                for supervised processes for status
-                                and start-up completion
-                                notification. This environment variable
-                                specifies the socket
-                                <function>sd_notify()</function> talks
-                                to. See above for details.</para></listitem>
-                        </varlistentry>
-                </variablelist>
-        </refsect1>
-
-        <refsect1>
-                <title>Examples</title>
-
-                <example>
-                        <title>Start-up Notification</title>
-
-                        <para>When a service finished starting up, it
-                        might issue the following call to notify
-                        the service manager:</para>
-
-                        <programlisting>sd_notify(0, "READY=1");</programlisting>
-                </example>
-
-                <example>
-                        <title>Extended Start-up Notification</title>
-
-                        <para>A service could send the following after
-                        completing initialization:</para>
-
-                        <programlisting>sd_notifyf(0, "READY=1\n"
-              "STATUS=Processing requests...\n"
-              "MAINPID=%lu",
-              (unsigned long) getpid());</programlisting>
-                </example>
-
-                <example>
-                        <title>Error Cause Notification</title>
-
-                        <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>
-                <title>See Also</title>
-                <para>
-                        <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>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-                </para>
-        </refsect1>
+  xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>sd_notify</title>
+    <productname>elogind</productname>
+
+    <authorgroup>
+      <author>
+        <contrib>Developer</contrib>
+        <firstname>Lennart</firstname>
+        <surname>Poettering</surname>
+        <email>lennart@poettering.net</email>
+      </author>
+    </authorgroup>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd_notify</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <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>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;elogind/sd-daemon.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>int <function>sd_notify</function></funcdef>
+        <paramdef>int <parameter>unset_environment</parameter></paramdef>
+        <paramdef>const char *<parameter>state</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_notifyf</function></funcdef>
+        <paramdef>int <parameter>unset_environment</parameter></paramdef>
+        <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> 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> will unset the
+    <varname>$NOTIFY_SOCKET</varname> 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 the variable
+    is no longer inherited by child processes.</para>
+
+    <para>The <parameter>state</parameter> parameter 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, but the following shall be considered
+    well-known:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>READY=1</term>
+
+        <listitem><para>Tells the service manager that service startup
+        is finished. This is only used by elogind 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 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: <literal>STATUS=Completed 66% of file
+        system check...</literal></para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>ERRNO=...</term>
+
+        <listitem><para>If a service fails, the errno-style error
+        code, formatted as string. Example: <literal>ERRNO=2</literal>
+        for ENOENT.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>BUSERROR=...</term>
+
+        <listitem><para>If a service fails, the D-Bus error-style
+        error code. Example:
+        <literal>BUSERROR=org.freedesktop.DBus.Error.TimedOut</literal></para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>MAINPID=...</term>
+
+        <listitem><para>The main process ID (PID) of the service, in
+        case the service manager did not fork off the process itself.
+        Example: <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 whether 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 will 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>).
+        File descriptors must be pollable, see
+        <citerefentry><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
+        Multiple arrays of file descriptors may be sent in separate 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>
+        <term>FDNAME=...</term>
+
+        <listitem><para>When used in combination with
+        <varname>FDSTORE=1</varname>, specifies a name for the
+        submitted file descriptors. This name is passed to the service
+        during activation, and may be queried using
+        <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>. File
+        descriptors submitted without this field set, will implicitly
+        get the name <literal>stored</literal> assigned. Note that, if
+        multiple file descriptors are submitted at once, the specified
+        name will be assigned to all of them. In order to assign
+        different names to submitted file descriptors, submit them in
+        separate invocations of
+        <function>sd_pid_notify_with_fds()</function>. The name may
+        consist of any ASCII character, but must not contain control
+        characters or <literal>:</literal>. It may not be longer than
+        255 characters. If a submitted name does not follow these
+        restrictions, it is ignored.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>WATCHDOG_USEC=...</term>
+
+        <listitem><para>Reset <varname>watchdog_usec</varname> value during runtime.
+        Notice that this is not available when using <function>sd_event_set_watchdog()</function>
+        or <function>sd_watchdog_enabled()</function>.
+        Example : <literal>WATCHDOG_USEC=20000000</literal></para></listitem>
+      </varlistentry>
+
+    </variablelist>
+
+    <para>It is recommended to prefix variable names that are not
+    listed above with <varname>X_</varname> to avoid namespace
+    clashes.</para>
+
+    <para>Note that elogind will accept status data sent 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
+    <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>
+    <title>Return Value</title>
+
+    <para>On failure, these calls return a negative 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 positive return value. In
+    order to support both, init systems that implement this scheme and
+    those which do not, it is generally recommended to ignore the
+    return value of this call.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Notes</title>
+
+    <xi:include href="libelogind-pkgconfig.xml" xpointer="pkgconfig-text"/>
+
+    <para>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 <literal>@</literal>, the
+    string is understood as Linux abstract namespace socket. The
+    datagram is accompanied by the process credentials of the sending
+    service, using SCM_CREDENTIALS.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Environment</title>
+
+    <variablelist class='environment-variables'>
+      <varlistentry>
+        <term><varname>$NOTIFY_SOCKET</varname></term>
+
+        <listitem><para>Set by the service manager for supervised
+        processes for status and start-up completion notification.
+        This environment variable specifies the socket
+        <function>sd_notify()</function> talks to. See above for
+        details.</para></listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>Examples</title>
+
+    <example>
+      <title>Start-up Notification</title>
+
+      <para>When a service finished starting up, it might issue the
+      following call to notify the service manager:</para>
+
+      <programlisting>sd_notify(0, "READY=1");</programlisting>
+    </example>
+
+    <example>
+      <title>Extended Start-up Notification</title>
+
+      <para>A service could send the following after completing
+      initialization:</para>
+
+      <programlisting>sd_notifyf(0, "READY=1\n"
+        "STATUS=Processing requests...\n"
+        "MAINPID=%lu",
+        (unsigned long) getpid());</programlisting>
+    </example>
+
+    <example>
+      <title>Error Cause Notification</title>
+
+      <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\nFDNAME=foobar", &amp;fd, 1);</programlisting>
+    </example>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para>
+      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    </para>
+  </refsect1>
 
 </refentry>