summaryrefslogtreecommitdiff
path: root/src/libsystemd/sd_notify.xml
diff options
context:
space:
mode:
authorLuke Shumaker <lukeshu@lukeshu.com>2017-05-20 17:35:06 -0400
committerLuke Shumaker <lukeshu@lukeshu.com>2017-05-20 17:35:06 -0400
commitf2f1f2472c5efc541bd53f51289ad58a86fa2d41 (patch)
tree42807ddc64ab0672744c716d9f952e5673762b9d /src/libsystemd/sd_notify.xml
parent3eed542bbc10978aa0b68a39dd3619edf7a7d90b (diff)
./tools/notsd-move
Diffstat (limited to 'src/libsystemd/sd_notify.xml')
-rw-r--r--src/libsystemd/sd_notify.xml405
1 files changed, 405 insertions, 0 deletions
diff --git a/src/libsystemd/sd_notify.xml b/src/libsystemd/sd_notify.xml
new file mode 100644
index 0000000000..94542b80b8
--- /dev/null
+++ b/src/libsystemd/sd_notify.xml
@@ -0,0 +1,405 @@
+<?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">
+
+<!--
+ This file is part of systemd.
+
+ Copyright 2010 Lennart Poettering
+
+ systemd 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
+ 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/>.
+-->
+
+<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 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 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>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>