summaryrefslogtreecommitdiff
path: root/man/sd_notify.xml
diff options
context:
space:
mode:
Diffstat (limited to 'man/sd_notify.xml')
-rw-r--r--man/sd_notify.xml319
1 files changed, 319 insertions, 0 deletions
diff --git a/man/sd_notify.xml b/man/sd_notify.xml
new file mode 100644
index 0000000000..75edeeadf3
--- /dev/null
+++ b/man/sd_notify.xml
@@ -0,0 +1,319 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!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">
+
+ <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>
+ <refpurpose>Notify service manager about start-up completion and other daemon 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>
+ </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>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
+ 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 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 signaling non-readiness, the
+ only value daemons should send is
+ "READY=1".</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>STATUS=...</term>
+
+ <listitem><para>Passes a single-line
+ status string back to the init system
+ that describes the daemon state. This
+ 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>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ERRNO=...</term>
+
+ <listitem><para>If a daemon fails, the
+ errno-style error code, formatted as
+ string. Example: "ERRNO=2" for
+ ENOENT.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>BUSERROR=...</term>
+
+ <listitem><para>If a daemon fails, the
+ D-Bus error-style error code. Example:
+ "BUSERROR=org.freedesktop.DBus.Error.TimedOut"</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>MAINPID=...</term>
+
+ <listitem><para>The main pid of the
+ daemon, in case the init system did
+ not fork off the process
+ itself. Example:
+ "MAINPID=4711"</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>WATCHDOG=1</term>
+
+ <listitem><para>Tells systemd to
+ update the watchdog timestamp. This is
+ the keep-alive ping that services need
+ to issue in regular intervals if
+ <varname>WatchdogSec=</varname> is
+ enabled for it. See
+ <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details. It is recommended to send
+ this message if the
+ <varname>WATCHDOG_USEC=</varname>
+ environment variable has been set for
+ the service process, in every half the
+ time interval that is specified in the
+ variable.</para></listitem>
+ </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>
+
+ <para>Note that systemd will accept status data sent
+ from a daemon 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>
+ </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
+ don't, it is generally recommended to ignore the return
+ value of this call.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Notes</title>
+
+ <para>These functions are provided by the reference
+ implementation of APIs for new-style daemons and
+ distributed with the systemd package. The algorithms
+ they implement are simple, and can easily be
+ reimplemented in daemons if it is important to support
+ this interface without using the reference
+ implementation.</para>
+
+ <para>Internally, these functions send a single
+ datagram with the state string as payload to the
+ AF_UNIX socket referenced in the
+ <varname>$NOTIFY_SOCKET</varname> environment
+ variable. If the first character of
+ <varname>$NOTIFY_SOCKET</varname> is @ the string is
+ understood as Linux abstract namespace socket. The
+ datagram is accompanied by the process credentials of
+ the sending daemon, using SCM_CREDENTIALS.</para>
+
+ <para>For details about the algorithms check the
+ liberally licensed reference implementation sources:
+ <ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/libsystemd-daemon/sd-daemon.c"/>
+ and <ulink
+ url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h"/></para>
+
+ <para><function>sd_notify()</function> and
+ <function>sd_notifyf()</function> are implemented in
+ the reference implementation's
+ <filename>sd-daemon.c</filename> and
+ <filename>sd-daemon.h</filename> files. These
+ interfaces are available as shared library, which can
+ be compiled and linked to with the
+ <literal>libsystemd-daemon</literal>
+ <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ file. Alternatively, applications consuming these APIs
+ may copy the implementation into their source tree. For
+ more details about the reference implementation see
+ <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+
+ <para>If the reference implementation is used as
+ drop-in files and -DDISABLE_SYSTEMD is set during
+ compilation these functions will always return 0 and
+ otherwise become a NOP.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Environment</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>$NOTIFY_SOCKET</varname></term>
+
+ <listitem><para>Set by the init system
+ 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 daemon finished starting up, it
+ might issue the following call to notify
+ the init system:</para>
+
+ <programlisting>sd_notify(0, "READY=1");</programlisting>
+ </example>
+
+ <example>
+ <title>Extended Start-up Notification</title>
+
+ <para>A daemon 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 daemon 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>
+ </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>
+ </para>
+ </refsect1>
+
+</refentry>