2013-12-23 01:14:05 +04:00
<?xml version='1.0'?> <!-- * - nxml - * -->
2019-03-14 16:40:58 +03:00
< !DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
2023-12-25 17:48:33 +03:00
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
2020-11-09 07:23:58 +03:00
<!-- SPDX - License - Identifier: LGPL - 2.1 - or - later -->
2013-12-23 01:14:05 +04:00
2014-02-21 07:39:26 +04:00
<refentry id= "sd_watchdog_enabled"
2015-02-04 05:14:13 +03:00
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo >
<title > sd_watchdog_enabled</title>
<productname > systemd</productname>
</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>
2020-11-12 10:58:00 +03:00
<para > If the <parameter > usec</parameter> parameter is non-<constant > NULL</constant> ,
2015-02-04 05:14:13 +03:00
<function > sd_watchdog_enabled()</function> will write the timeout
2023-06-14 11:13:08 +03:00
in μs for the watchdog logic to it.</para>
2015-02-04 05:14:13 +03:00
<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>
2015-11-20 01:38:54 +03:00
<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>
2015-02-04 05:14:13 +03:00
</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" />
2023-03-07 22:25:58 +03:00
<xi:include href= "threads-aware.xml" xpointer= "getenv" />
2015-02-04 05:14:13 +03:00
2016-11-09 19:30:10 +03:00
<para > Internally, this function parses the
2015-02-04 05:14:13 +03:00
<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
2023-08-22 19:52:36 +03:00
details.</para>
<xi:include href= "version-info.xml" xpointer= "v209" /> </listitem>
2015-02-04 05:14:13 +03:00
</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
2023-06-14 11:13:08 +03:00
the watchdog timeout in μs. See above for
2023-08-22 19:52:36 +03:00
details.</para>
<xi:include href= "version-info.xml" xpointer= "v209" /> </listitem>
2015-02-04 05:14:13 +03:00
</varlistentry>
</variablelist>
</refsect1>
2023-09-04 15:46:35 +03:00
<refsect1 >
<title > History</title>
<para > <function > sd_watchdog_enabled()</function> was added in version 209.</para>
</refsect1>
2015-02-04 05:14:13 +03:00
<refsect1 >
<title > See Also</title>
2023-12-22 21:09:32 +03:00
<para > <simplelist type= "inline" >
<member > <citerefentry > <refentrytitle > systemd</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry> </member>
<member > <citerefentry > <refentrytitle > sd-daemon</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> </member>
<member > <citerefentry > <refentrytitle > daemon</refentrytitle> <manvolnum > 7</manvolnum> </citerefentry> </member>
<member > <citerefentry > <refentrytitle > systemd.service</refentrytitle> <manvolnum > 5</manvolnum> </citerefentry> </member>
<member > <citerefentry > <refentrytitle > sd_notify</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> </member>
<member > <citerefentry > <refentrytitle > sd_event_set_watchdog</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> </member>
</simplelist> </para>
2015-02-04 05:14:13 +03:00
</refsect1>
2013-12-23 01:14:05 +04:00
</refentry>