sd_notify.xml revision f9378423b9758861850748aeb49ae0d3300e56e6
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering This file is part of systemd.
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering Copyright 2010 Lennart Poettering
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering systemd is free software; you can redistribute it and/or modify it
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering under the terms of the GNU General Public License as published by
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering the Free Software Foundation; either version 2 of the License, or
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering (at your option) any later version.
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering systemd is distributed in the hope that it will be useful, but
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering General Public License for more details.
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering You should have received a copy of the GNU General Public License
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <refentryinfo>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering </authorgroup>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering </refentryinfo>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <refpurpose>Notify init system about start-up completion and other daemon status changes</refpurpose>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <refsynopsisdiv>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <funcsynopsis>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <funcsynopsisinfo>#include "sd-daemon.h"</funcsynopsisinfo>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <funcprototype>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <funcdef>int <function>sd_notify</function></funcdef>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <paramdef>int <parameter>unset_environment</parameter></paramdef>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <paramdef>const char *<parameter>state</parameter></paramdef>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering </funcprototype>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <funcprototype>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <funcdef>int <function>sd_notifyf</function></funcdef>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <paramdef>int <parameter>unset_environment</parameter></paramdef>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <paramdef>const char *<parameter>format</parameter></paramdef>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering </funcprototype>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering </funcsynopsis>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering </refsynopsisdiv>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <para><function>sd_notify()</function> shall be called
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering by a daemon to notify the init system about status
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering changes. It can be used to send arbitrary information,
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering encoded in an environment-block-like string. Most
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering importantly it can be used for start-up completion
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering notification.</para>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <para>If the <parameter>unset_environment</parameter>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering parameter is non-zero <function>sd_notify()</function>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering will unset the <varname>$NOTIFY_SOCKET</varname>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering environment variable before returning (regardless
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering whether the function call itself succeeded or
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering not). Further calls to
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <function>sd_notify()</function> will then fail, but
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering the variable is no longer inherited by child
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering processes.</para>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <para>The <parameter>state</parameter> parameter
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering should contain an newline-seperated list of variable
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering assignments, similar in style to an environment
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering block. A trailing newline is implied if none is
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering specified. The string may contain any kind of variable
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering assignments, but the following shall be considered
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering well-known:</para>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <variablelist>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <varlistentry>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering that daemon startup is finished. This
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering is only used by systemd if the service
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering definition file has Type=notify
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering set. The passed argument is a boolean
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering "1" or "0". Since there is little
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering value in signalling non-readiness the
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering only value daemons should send is
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering </varlistentry>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <varlistentry>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering status string back to the init system
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering that describes the daemon state. This
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering is free-from and can be used for
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering various purposes: general state
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering feedback, fsck-like programs could
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering pass completion percentages and
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering failing programs could pass a human
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering readable error message. Example:
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering "STATUS=Completed 66% of file system
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering </varlistentry>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <varlistentry>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering errno-style error code, formatted as
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering string. Example: "ERRNO=2" for
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering </varlistentry>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <varlistentry>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering D-Bus error-style error code. Example:
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering "BUSERROR=org.freedesktop.DBus.Error.TimedOut"</para></listitem>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering </varlistentry>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <varlistentry>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering daemon, in case the init system did
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering not fork off the process
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering itself. Example:
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering </varlistentry>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering </variablelist>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <para>It is recommened to prefix variable names that
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering are not shown in the list above with
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering clashes.</para>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <para>Note that systemd will accept status data sent
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering from a daemon only if the
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <varname>NotifyAccess=</varname> option is correctly
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering set in the service definition file. See
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering for details.</para>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <para><function>sd_notifyf()</function> is similar to
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <function>sd_notifyf()</function> but takes a
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <function>printf()</function>-like format string plus
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering arguments.</para>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <para>On failure, these calls return a negative
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering errno-style error code. If
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <varname>$NOTIFY_SOCKET</varname> was not set and
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering hence no status data could be sent 0 is returned. If
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering the status was sent these functions return with a
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering positive return value. In order to support both init
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering systems that implement this scheme and those which
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering don't it is generally recommended to ignore the return
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering value of this call.</para>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <para>These functions are provided by the reference
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering implementation of APIs for new-style daemons and
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering distributed with the systemd package. The algorithms
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering they implement are simple, and can easily be
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering reimplemented in daemons if it is important to support
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering this interface without using the reference
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering implementation.</para>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <para>Internally, these functions send a single
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering datagram with the state string as payload to the
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering AF_UNIX socket referenced in the
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <varname>$NOTIFY_SOCKET</varname> environment
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering variable. If the first character of
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <varname>$NOTIFY_SOCKET</varname> is @ the string is
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering understood as Linux abstract namespace socket. The
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering datagram is accompanied by the process credentials of
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering the sending daemon, using SCM_CREDENTIALS.</para>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <para>For details about the algorithm check the
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering liberally licensed reference implementation sources:
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <ulink url="http://cgit.freedesktop.org/systemd/tree/src/sd-daemon.c"/>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering url="http://cgit.freedesktop.org/systemd/tree/src/sd-daemon.h"/></para>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <para><function>sd_notify()</function> and
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <function>sd_notifyf()</function> are implemented in
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering the reference implementation's drop-in
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <filename>sd-daemon.h</filename> files. It is
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering recommended that applications consuming these APIs
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering copy the implementation into their source tree. For
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering more details about the reference implementation see
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <citerefentry><refentrytitle>sd_daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry></para>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <para>If -DDISABLE_SYSTEMD is set during compilation
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering this function will always return 0 and otherwise
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering become a NOP.</para>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <para>When a daemon finished starting up, it
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering might issue the following call call to notify
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering the init system:</para>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <programlisting>sd_notify(0, "READY=1");</programlisting>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <title>Extended Start-up Notification</title>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <para>A daemon could send the following after
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering completing initialization:</para>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <programlisting>sd_notifyf(0, "READY=1\n"
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering "STATUS=Processing requests...\n"
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering "MAINPID=%lu",
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering (unsigned long) getpid());</programlisting>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <para>A daemon could send the following shortly before exiting, on failure</para>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <programlisting>sd_notifyf(0, "STATUS=Failed to start up: %s\n"
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering strerror(errno),
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering errno);</programlisting>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <citerefentry><refentrytitle>sd_daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>