summaryrefslogtreecommitdiff
path: root/man/sd_notify.xml
diff options
context:
space:
mode:
authorZbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>2015-02-03 21:14:13 -0500
committerZbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>2015-02-03 23:11:35 -0500
commit798d3a524ea57aaf40cb53858aaa45ec702f012d (patch)
treef9251ab7878a180d464780d514f3ea8d4599fe6e /man/sd_notify.xml
parent35888b67f77fa7a5cae0973403cb97aa30cad70c (diff)
Reindent man pages to 2ch
Diffstat (limited to 'man/sd_notify.xml')
-rw-r--r--man/sd_notify.xml754
1 files changed, 351 insertions, 403 deletions
diff --git a/man/sd_notify.xml b/man/sd_notify.xml
index b7c33da63a..87e59c9cc2 100644
--- a/man/sd_notify.xml
+++ b/man/sd_notify.xml
@@ -1,6 +1,6 @@
<?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">
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
This file is part of systemd.
@@ -22,407 +22,355 @@
-->
<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 if the 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>systemd.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 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>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", &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>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
- </para>
- </refsect1>
+ 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 if the 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>systemd.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 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>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", &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>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ </para>
+ </refsect1>
</refentry>