man/sd_notify.xml - systemd-stable - Rivoreo Source Code Repositories

 <?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>Note that <function>sd_notify()</function> notifications may be attributed to units correctly only if either
     the sending process is still around at the time PID 1 processes the message, or if the sending process is
     explicitly runtime-tracked by the service manager. The latter is the case if the service manager originally forked
     off the process, i.e. on all processes that match <varname>NotifyAccess=</varname><option>main</option> or
     <varname>NotifyAccess=</varname><option>exec</option>. Conversely, if an auxiliary process of the unit sends an
     <function>sd_notify()</function> message and immediately exits, the service manager might not be able to properly
     attribute the message to the unit, and thus will ignore it, even if
     <varname>NotifyAccess=</varname><option>all</option> is set for it.</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>
	<?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 <systemd/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 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>Note that <function>sd_notify()</function> notifications may be attributed to units correctly only if either
	the sending process is still around at the time PID 1 processes the message, or if the sending process is
	explicitly runtime-tracked by the service manager. The latter is the case if the service manager originally forked
	off the process, i.e. on all processes that match <varname>NotifyAccess=</varname><option>main</option> or
	<varname>NotifyAccess=</varname><option>exec</option>. Conversely, if an auxiliary process of the unit sends an
	<function>sd_notify()</function> message and immediately exits, the service manager might not be able to properly
	attribute the message to the unit, and thus will ignore it, even if
	<varname>NotifyAccess=</varname><option>all</option> is set for it.</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", &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>