1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 This file is part of systemd.
8 Copyright 2013 Lennart Poettering
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
24 <refentry id="sd_watchdog_enabled">
27 <title>sd_watchdog_enabled</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>sd_watchdog_enabled</refentrytitle>
42 <manvolnum>3</manvolnum>
46 <refname>sd_watchdog_enabled</refname>
47 <refpurpose>Check whether the service manager expects watchdog keep-alive notifications from a service</refpurpose>
52 <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo>
55 <funcdef>int <function>sd_watchdog_enabled</function></funcdef>
56 <paramdef>int <parameter>unset_environment</parameter></paramdef>
57 <paramdef>const uint64_t *<parameter>usec</parameter></paramdef>
63 <title>Description</title>
64 <para><function>sd_watchdog_enabled()</function> may
65 be called by a service to detect whether the service
66 manager expects regular keep-alive watchdog
67 notification events from it, and the timeout after
68 which the manager will act on the service if it did
69 not get such a notification.</para>
71 <para>If the <parameter>unset_environment</parameter>
72 parameter is non-zero,
73 <function>sd_watchdog_enabled()</function> will unset
74 the <varname>$WATCHDOG_USEC</varname> and
75 <varname>$WATCHDOG_PID</varname> environment variables
76 before returning (regardless of whether the function call
77 itself succeeded or not). Further calls to
78 <function>sd_watchdog_enabled()</function> will then
79 return with zero, but the variable is no longer
80 inherited by child processes.</para>
82 <para>If the <parameter>usec</parameter> parameter is
83 non-NULL, <function>sd_watchdog_enabled()</function>
84 will return the timeout in µs for the watchdog
85 logic. The service manager will usually terminate a
86 service when it did not get a notification message
87 within the specified time after startup and after each
88 previous message. It is recommended that a daemon
89 sends a keep-alive notification message to the service
90 manager every half of the time returned
91 here. Notification messages may be sent with
92 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
93 with a message string of
94 <literal>WATCHDOG=1</literal>.</para>
96 <para>To enable service supervision with the watchdog
97 logic, use <varname>WatchdogSec=</varname> in service
99 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
104 <title>Return Value</title>
106 <para>On failure, this call returns a negative
107 errno-style error code. If the service manager expects
108 watchdog keep-alive notification messages to be sent,
109 > 0 is returned, otherwise 0 is returned. Only if
110 the return value is > 0, the
111 <parameter>usec</parameter> parameter is valid after
118 <para>These APIs are implemented as a shared library,
119 which can be compiled and linked to with the
120 <constant>libsystemd</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
123 <para>Internally, this functions parses the
124 <varname>$WATCHDOG_PID</varname> and
125 <varname>$WATCHDOG_USEC</varname> environment
126 variable. The call will ignore these variables if
127 <varname>$WATCHDOG_PID</varname> does containe the PID
128 of the current process, under the assumption that in
129 that case, the variables were set for a different
130 process further up the process tree.</para>
135 <title>Environment</title>
137 <variablelist class='environment-variables'>
139 <term><varname>$WATCHDOG_PID</varname></term>
141 <listitem><para>Set by the system
142 manager for supervised process for
143 which watchdog support is enabled, and
144 contains the PID of that process. See
145 above for details.</para></listitem>
149 <term><varname>$WATCHDOG_USEC</varname></term>
151 <listitem><para>Set by the system
152 manager for supervised process for
153 which watchdog support is enabled, and
154 contains the watchdog timeout in µs
156 details.</para></listitem>
162 <title>See Also</title>
164 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
165 <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
166 <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
167 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
168 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>