11a1589223
Files which are installed as-is (any .service and other unit files, .conf files, .policy files, etc), are left as is. My assumption is that SPDX identifiers are not yet that well known, so it's better to retain the extended header to avoid any doubt. I also kept any copyright lines. We can probably remove them, but it'd nice to obtain explicit acks from all involved authors before doing that.
159 lines
6.1 KiB
XML
159 lines
6.1 KiB
XML
<?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">
|
|
|
|
<!--
|
|
SPDX-License-Identifier: LGPL-2.1+
|
|
|
|
This file is part of systemd.
|
|
|
|
Copyright 2013 Lennart Poettering
|
|
-->
|
|
|
|
<refentry id="sd_watchdog_enabled"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
|
|
<refentryinfo>
|
|
<title>sd_watchdog_enabled</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_watchdog_enabled</refentrytitle>
|
|
<manvolnum>3</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>sd_watchdog_enabled</refname>
|
|
<refpurpose>Check whether the service manager expects watchdog keep-alive notifications from a service</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo>
|
|
|
|
<funcprototype>
|
|
<funcdef>int <function>sd_watchdog_enabled</function></funcdef>
|
|
<paramdef>int <parameter>unset_environment</parameter></paramdef>
|
|
<paramdef>uint64_t *<parameter>usec</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<para><function>sd_watchdog_enabled()</function> may be called by
|
|
a service to detect whether the service manager expects regular
|
|
keep-alive watchdog notification events from it, and the timeout
|
|
after which the manager will act on the service if it did not get
|
|
such a notification.</para>
|
|
|
|
<para>If the <varname>$WATCHDOG_USEC</varname> environment
|
|
variable is set, and the <varname>$WATCHDOG_PID</varname> variable
|
|
is unset or set to the PID of the current process, the service
|
|
manager expects notifications from this process. The manager will
|
|
usually terminate a service when it does not get a notification
|
|
message within the specified time after startup and after each
|
|
previous message. It is recommended that a daemon sends a
|
|
keep-alive notification message to the service manager every half
|
|
of the time returned here. Notification messages may be sent with
|
|
<citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
|
with a message string of <literal>WATCHDOG=1</literal>.</para>
|
|
|
|
<para>If the <parameter>unset_environment</parameter> parameter is
|
|
non-zero, <function>sd_watchdog_enabled()</function> will unset
|
|
the <varname>$WATCHDOG_USEC</varname> and
|
|
<varname>$WATCHDOG_PID</varname> environment variables before
|
|
returning (regardless of whether the function call itself
|
|
succeeded or not). Those variables are no longer inherited by
|
|
child processes. Further calls to
|
|
<function>sd_watchdog_enabled()</function> will also return with
|
|
zero.</para>
|
|
|
|
<para>If the <parameter>usec</parameter> parameter is non-NULL,
|
|
<function>sd_watchdog_enabled()</function> will write the timeout
|
|
in µs for the watchdog logic to it.</para>
|
|
|
|
<para>To enable service supervision with the watchdog logic, use
|
|
<varname>WatchdogSec=</varname> in service files. See
|
|
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
|
for details.</para>
|
|
|
|
<para>Use
|
|
<citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
|
to enable automatic watchdog support in
|
|
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>-based event loops.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>On failure, this call returns a negative errno-style error
|
|
code. If the service manager expects watchdog keep-alive
|
|
notification messages to be sent, > 0 is returned, otherwise 0
|
|
is returned. Only if the return value is > 0, the
|
|
<parameter>usec</parameter> parameter is valid after the
|
|
call.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Notes</title>
|
|
|
|
<xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
|
|
|
|
<para>Internally, this function parses the
|
|
<varname>$WATCHDOG_PID</varname> and
|
|
<varname>$WATCHDOG_USEC</varname> environment variable. The call
|
|
will ignore these variables if <varname>$WATCHDOG_PID</varname>
|
|
does not contain the PID of the current process, under the
|
|
assumption that in that case, the variables were set for a
|
|
different process further up the process tree.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Environment</title>
|
|
|
|
<variablelist class='environment-variables'>
|
|
<varlistentry>
|
|
<term><varname>$WATCHDOG_PID</varname></term>
|
|
|
|
<listitem><para>Set by the system manager for supervised
|
|
process for which watchdog support is enabled, and contains
|
|
the PID of that process. See above for
|
|
details.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>$WATCHDOG_USEC</varname></term>
|
|
|
|
<listitem><para>Set by the system manager for supervised
|
|
process for which watchdog support is enabled, and contains
|
|
the watchdog timeout in µs. See above for
|
|
details.</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</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_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|