-<?xml version='1.0'?> <!--*-nxml-*-->
+<?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">
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
- This file is part of systemd.
+ This file is part of elogind.
Copyright 2010 Lennart Poettering
- systemd is free software; you can redistribute it and/or modify it
+ 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.
- systemd is distributed in the hope that it will be useful, but
+ 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 systemd; If not, see <http://www.gnu.org/licenses/>.
+ 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>systemd</productname>
-
- <authorgroup>
- <author>
- <contrib>Developer</contrib>
- <firstname>Lennart</firstname>
- <surname>Poettering</surname>
- <email>lennart@poettering.net</email>
- </author>
- </authorgroup>
- </refentryinfo>
-
- <refmeta>
- <refentrytitle>sd_notify</refentrytitle>
- <manvolnum>3</manvolnum>
- </refmeta>
-
- <refnamediv>
- <refname>sd_notify</refname>
- <refname>sd_notifyf</refname>
- <refpurpose>Notify service manager about start-up completion and other daemon status changes</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcsynopsisinfo>#include <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>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Description</title>
- <para><function>sd_notify()</function> shall be called
- by a daemon to notify the init system about status
- changes. It can be used to send arbitrary information,
- encoded in an environment-block-like string. Most
- importantly it can be used for start-up completion
- notification.</para>
-
- <para>If the <parameter>unset_environment</parameter>
- parameter is non-zero, <function>sd_notify()</function>
- will unset the <varname>$NOTIFY_SOCKET</varname>
- environment variable before returning (regardless 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 init system
- that daemon startup is finished. This
- is only used by systemd if the service
- definition file has Type=notify
- set. The passed argument is a boolean
- "1" or "0". Since there is little
- value in signaling non-readiness, the
- only value daemons should send is
- "READY=1".</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>STATUS=...</term>
-
- <listitem><para>Passes a single-line
- status string back to the init system
- that describes the daemon state. This
- is free-form and can be used for
- various purposes: general state
- feedback, fsck-like programs could
- pass completion percentages and
- failing programs could pass a human
- readable error message. Example:
- "STATUS=Completed 66% of file system
- check..."</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ERRNO=...</term>
-
- <listitem><para>If a daemon fails, the
- errno-style error code, formatted as
- string. Example: "ERRNO=2" for
- ENOENT.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>BUSERROR=...</term>
-
- <listitem><para>If a daemon fails, the
- D-Bus error-style error code. Example:
- "BUSERROR=org.freedesktop.DBus.Error.TimedOut"</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>MAINPID=...</term>
-
- <listitem><para>The main pid of the
- daemon, in case the init system did
- not fork off the process
- itself. Example:
- "MAINPID=4711"</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>WATCHDOG=1</term>
-
- <listitem><para>Tells systemd to
- update the watchdog timestamp. This is
- the keep-alive ping that services need
- to issue in regular intervals if
- <varname>WatchdogSec=</varname> is
- enabled for it. See
- <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- for details. It is recommended to send
- this message if the
- <varname>$WATCHDOG_PID</varname>
- environment variable has been set to
- the PID of the service process, in
- every half the time interval that is
- specified in the
- <varname>$WATCHDOG_USEC</varname>
- environment variable. See
- <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
- for details.</para></listitem>
- </varlistentry>
- </variablelist>
-
- <para>It is recommended to prefix variable names that
- are not shown in the list above with
- <varname>X_</varname> to avoid namespace
- clashes.</para>
-
- <para>Note that systemd will accept status data sent
- from a daemon only if the
- <varname>NotifyAccess=</varname> option is correctly
- set in the service definition file. See
- <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- for details.</para>
-
- <para><function>sd_notifyf()</function> is similar to
- <function>sd_notify()</function> but takes a
- <function>printf()</function>-like format string plus
- arguments.</para>
- </refsect1>
-
- <refsect1>
- <title>Return Value</title>
-
- <para>On failure, these calls return a negative
- errno-style error code. If
- <varname>$NOTIFY_SOCKET</varname> was not set and
- hence no status data could be sent, 0 is returned. If
- the status was sent, these functions return with a
- positive return value. In order to support both, init
- systems that implement this scheme and those which
- 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 daemon, 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 init system
- for supervised processes for status
- and start-up completion
- notification. This environment variable
- specifies the socket
- <function>sd_notify()</function> talks
- to. See above for details.</para></listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Examples</title>
-
- <example>
- <title>Start-up Notification</title>
-
- <para>When a daemon finished starting up, it
- might issue the following call to notify
- the init system:</para>
-
- <programlisting>sd_notify(0, "READY=1");</programlisting>
- </example>
-
- <example>
- <title>Extended Start-up Notification</title>
-
- <para>A daemon could send the following after
- completing initialization:</para>
-
- <programlisting>sd_notifyf(0, "READY=1\n"
- "STATUS=Processing requests...\n"
- "MAINPID=%lu",
- (unsigned long) getpid());</programlisting>
- </example>
-
- <example>
- <title>Error Cause Notification</title>
-
- <para>A daemon could send the following shortly before exiting, on failure</para>
-
- <programlisting>sd_notifyf(0, "STATUS=Failed to start up: %s\n"
- "ERRNO=%i",
- strerror(errno),
- errno);</programlisting>
- </example>
- </refsect1>
-
- <refsect1>
- <title>See Also</title>
- <para>
- <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <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>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>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 later be handed back using the usual file descriptor
+ passing logic at the next invocation of the service, see
+ <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This is
+ useful for implementing services that can restart after an explicit request or a crash without losing
+ state. Any open sockets and other file descriptors which should not be closed during the restart may be stored
+ this way. Application state can either be serialized to a file in <filename>/run</filename>, or better, stored
+ in a <citerefentry><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> memory
+ file descriptor. Note that the service manager will accept messages for a service only if its
+ <varname>FileDescriptorStoreMax=</varname> setting is non-zero (defaults to zero, see
+ <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If file
+ descriptors sent are pollable (see
+ <citerefentry><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>), then any
+ <constant>EPOLLHUP</constant> or <constant>EPOLLERR</constant> event seen on them will result in their
+ automatic removal from the store. 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 (pointing to the same
+ object) 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 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>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 message could be sent, 0 is returned. If the status was sent, these functions return a
+ positive value. In order to support both service managers that implement this scheme and those which do not, it is
+ generally recommended to ignore the return value of this call. Note that the return value simply indicates whether
+ the notification message was enqueued properly, it does not reflect whether the message could be processed
+ successfully. Specifically, no error is returned when a file descriptor is attempted to be stored using
+ <varname>FDSTORE=1</varname> but the service is not actually configured to permit storing of file descriptors (see
+ above).</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Notes</title>
+
+ <xi:include href="libelogind-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>
~ianmdlvl / elogind.git / blobdiff