-<?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">
<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
+ 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
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
+ percentages and failing programs could pass a human-readable
error message. Example: <literal>STATUS=Completed 66% of file
system check...</literal></para></listitem>
</varlistentry>
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>logind.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ <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
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>logind.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ <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
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
<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>logind.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details.</para>
<para><function>sd_notifyf()</function> is similar 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
+ 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>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>
+ losing state, use <literal>FDSTORE=1</literal>:</para>
- <programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1", &fd, 1);</programlisting>
+ <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>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+ <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>logind.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
</para>
</refsect1>