818bf54632
This part of the copyright blurb stems from the GPL use recommendations: https://www.gnu.org/licenses/gpl-howto.en.html The concept appears to originate in times where version control was per file, instead of per tree, and was a way to glue the files together. Ultimately, we nowadays don't live in that world anymore, and this information is entirely useless anyway, as people are very welcome to copy these files into any projects they like, and they shouldn't have to change bits that are part of our copyright header for that. hence, let's just get rid of this old cruft, and shorten our codebase a bit.
157 lines
6 KiB
XML
157 lines
6 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+
|
|
|
|
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>
|