-<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-
-<!--
- SPDX-License-Identifier: LGPL-2.1+
-
- 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/>.
--->
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
<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>
<refname>sd_pid_notify</refname>
<refname>sd_pid_notifyf</refname>
<refname>sd_pid_notify_with_fds</refname>
+ <refname>sd_notify_barrier</refname>
<refpurpose>Notify service manager about start-up completion and other service status changes</refpurpose>
</refnamediv>
<paramdef>const int *<parameter>fds</parameter></paramdef>
<paramdef>unsigned <parameter>n_fds</parameter></paramdef>
</funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_notify_barrier</function></funcdef>
+ <paramdef>int <parameter>unset_environment</parameter></paramdef>
+ <paramdef>uint64_t <parameter>timeout</parameter></paramdef>
+ </funcprototype>
</funcsynopsis>
</refsynopsisdiv>
watchdog is enabled. </para></listitem>
</varlistentry>
+ <varlistentry>
+ <term>WATCHDOG=trigger</term>
+
+ <listitem><para>Tells the service manager that the service detected an internal error that should be handled by
+ the configured watchdog options. This will trigger the same behaviour as if <varname>WatchdogSec=</varname> is
+ enabled and the service did not send <literal>WATCHDOG=1</literal> in time. Note that
+ <varname>WatchdogSec=</varname> does not need to be enabled for <literal>WATCHDOG=trigger</literal> to trigger
+ the watchdog action. See
+ <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
+ information about the watchdog behavior. </para></listitem>
+ </varlistentry>
+
<varlistentry>
<term>WATCHDOG_USEC=…</term>
Example : <literal>WATCHDOG_USEC=20000000</literal></para></listitem>
</varlistentry>
+ <varlistentry>
+ <term>EXTEND_TIMEOUT_USEC=…</term>
+
+ <listitem><para>Tells the service manager to extend the startup, runtime or shutdown service timeout
+ corresponding the current state. The value specified is a time in microseconds during which the service must
+ send a new message. A service timeout will occur if the message isn't received, but only if the runtime of the
+ current state is beyond the original maximum times of <varname>TimeoutStartSec=</varname>, <varname>RuntimeMaxSec=</varname>,
+ and <varname>TimeoutStopSec=</varname>.
+ See <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for effects on the service timeouts.</para></listitem>
+ </varlistentry>
+
<varlistentry>
<term>FDSTORE=1</term>
<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
+ 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>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If
+ <varname>FDPOLL=0</varname> is not set and the 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
submitted name does not follow these restrictions, it is ignored.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term>FDPOLL=0</term>
+
+ <listitem><para>When used in combination with <varname>FDSTORE=1</varname>, disables polling of the stored
+ file descriptors regardless of whether or not they are pollable. As this option disables automatic cleanup
+ of the stored file descriptors on EPOLLERR and EPOLLHUP, care must be taken to ensure proper manual cleanup.
+ Use of this option is not generally recommended except for when automatic cleanup has unwanted behavior such
+ as prematurely discarding file descriptors from the store.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>BARRIER=1</term>
+
+ <listitem><para>Tells the service manager that the client is explicitly requesting synchronization by means of
+ closing the file descriptor sent with this command. The service manager guarantees that the processing of a <varname>
+ BARRIER=1</varname> command will only happen after all previous notification messages sent before this command
+ have been processed. Hence, this command accompanied with a single file descriptor can be used to synchronize
+ against reception of all previous status messages. Note that this command cannot be mixed with other notifications,
+ and has to be sent in a separate message to the service manager, otherwise all assignments will be ignored. Note that
+ sending 0 or more than 1 file descriptor with this command is a violation of the protocol.</para></listitem>
+ </varlistentry>
</variablelist>
<para>It is recommended to prefix variable names that are not
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>Hence, to eliminate all race conditions involving lookup of the client's unit and attribution of notifications
+ to units correctly, <function>sd_notify_barrier()</function> may be used. This call acts as a synchronization point
+ and ensures all notifications sent before this call have been picked up by the service manager when it returns
+ successfully. Use of <function>sd_notify_barrier()</function> is needed for clients which are not invoked by the
+ service manager, otherwise this synchronization mechanism is unnecessary for attribution of notifications to the
+ unit.</para>
+
<para><function>sd_notifyf()</function> is similar to
<function>sd_notify()</function> but takes a
<function>printf()</function>-like format string plus
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>
+
+ <para><function>sd_notify_barrier()</function> allows the caller to
+ synchronize against reception of previously sent notification messages
+ and uses the <literal>BARRIER=1</literal> command. It takes a relative
+ <varname>timeout</varname> value in microseconds which is passed to
+ <citerefentry><refentrytitle>ppoll</refentrytitle><manvolnum>2</manvolnum>
+ </citerefentry>. A value of UINT64_MAX is interpreted as infinite timeout.
+ </para>
</refsect1>
<refsect1>
<programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1\nFDNAME=foobar", &fd, 1);</programlisting>
</example>
+
+ <example>
+ <title>Eliminating race conditions</title>
+
+ <para>When the client sending the notifications is not spawned
+ by the service manager, it may exit too quickly and the service
+ manager may fail to attribute them correctly to the unit. To
+ prevent such races, use <function>sd_notify_barrier()</function>
+ to synchronize against reception of all notifications sent before
+ this call is made.</para>
+
+ <programlisting>sd_notify(0, "READY=1");
+ /* set timeout to 5 seconds */
+ sd_notify_barrier(0, 5 * 1000000);
+ </programlisting>
+ </example>
</refsect1>
<refsect1>
projects / thirdparty / systemd.git / blobdiff