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"
25 xmlns:xi="http://www.w3.org/2001/XInclude">
28 <title>sd_watchdog_enabled</title>
29 <productname>systemd</productname>
33 <contrib>Developer</contrib>
34 <firstname>Lennart</firstname>
35 <surname>Poettering</surname>
36 <email>lennart@poettering.net</email>
42 <refentrytitle>sd_watchdog_enabled</refentrytitle>
43 <manvolnum>3</manvolnum>
47 <refname>sd_watchdog_enabled</refname>
48 <refpurpose>Check whether the service manager expects watchdog keep-alive notifications from a service</refpurpose>
53 <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo>
56 <funcdef>int <function>sd_watchdog_enabled</function></funcdef>
57 <paramdef>int <parameter>unset_environment</parameter></paramdef>
58 <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
64 <title>Description</title>
65 <para><function>sd_watchdog_enabled()</function> may
66 be called by a service to detect whether the service
67 manager expects regular keep-alive watchdog
68 notification events from it, and the timeout after
69 which the manager will act on the service if it did
70 not get such a notification.</para>
72 <para>If the <parameter>unset_environment</parameter>
73 parameter is non-zero,
74 <function>sd_watchdog_enabled()</function> will unset
75 the <varname>$WATCHDOG_USEC</varname> and
76 <varname>$WATCHDOG_PID</varname> environment variables
77 before returning (regardless of whether the function call
78 itself succeeded or not). Further calls to
79 <function>sd_watchdog_enabled()</function> will then
80 return with zero, but the variable is no longer
81 inherited by child processes.</para>
83 <para>If the <parameter>usec</parameter> parameter is
84 non-NULL, <function>sd_watchdog_enabled()</function>
85 will return the timeout in µs for the watchdog
86 logic. The service manager will usually terminate a
87 service when it did not get a notification message
88 within the specified time after startup and after each
89 previous message. It is recommended that a daemon
90 sends a keep-alive notification message to the service
91 manager every half of the time returned
92 here. Notification messages may be sent with
93 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
94 with a message string of
95 <literal>WATCHDOG=1</literal>.</para>
97 <para>To enable service supervision with the watchdog
98 logic, use <varname>WatchdogSec=</varname> in service
100 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
105 <title>Return Value</title>
107 <para>On failure, this call returns a negative
108 errno-style error code. If the service manager expects
109 watchdog keep-alive notification messages to be sent,
110 > 0 is returned, otherwise 0 is returned. Only if
111 the return value is > 0, the
112 <parameter>usec</parameter> parameter is valid after
119 <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
121 <para>Internally, this functions parses the
122 <varname>$WATCHDOG_PID</varname> and
123 <varname>$WATCHDOG_USEC</varname> environment
124 variable. The call will ignore these variables if
125 <varname>$WATCHDOG_PID</varname> does containe the PID
126 of the current process, under the assumption that in
127 that case, the variables were set for a different
128 process further up the process tree.</para>
133 <title>Environment</title>
135 <variablelist class='environment-variables'>
137 <term><varname>$WATCHDOG_PID</varname></term>
139 <listitem><para>Set by the system
140 manager for supervised process for
141 which watchdog support is enabled, and
142 contains the PID of that process. See
143 above for details.</para></listitem>
147 <term><varname>$WATCHDOG_USEC</varname></term>
149 <listitem><para>Set by the system
150 manager for supervised process for
151 which watchdog support is enabled, and
152 contains the watchdog timeout in µs
154 details.</para></listitem>
160 <title>See Also</title>
162 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
163 <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
164 <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
165 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
166 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>