+<?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 elogind.
+
+ Copyright 2010 Lennart Poettering
+
+ 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.
+
+ 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 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>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 <elogind/sd-daemon.h></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>elogind.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 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>elogind.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 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>elogind.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>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", &fd, 1);</programlisting>
+ </example>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>elogind.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+
+</refentry>
~ianmdlvl / elogind.git / blobdiff