chiark / gitweb /
man: mention XDG_CONFIG_HOME in systemd.unit
[elogind.git] / man / sd_watchdog_enabled.xml
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">
4
5 <!--
6   This file is part of systemd.
7
8   Copyright 2013 Lennart Poettering
9
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.
14
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.
19
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/>.
22 -->
23
24 <refentry id="sd_watchdog_enabled"
25         xmlns:xi="http://www.w3.org/2001/XInclude">
26
27         <refentryinfo>
28                 <title>sd_watchdog_enabled</title>
29                 <productname>systemd</productname>
30
31                 <authorgroup>
32                         <author>
33                                 <contrib>Developer</contrib>
34                                 <firstname>Lennart</firstname>
35                                 <surname>Poettering</surname>
36                                 <email>lennart@poettering.net</email>
37                         </author>
38                 </authorgroup>
39         </refentryinfo>
40
41         <refmeta>
42                 <refentrytitle>sd_watchdog_enabled</refentrytitle>
43                 <manvolnum>3</manvolnum>
44         </refmeta>
45
46         <refnamediv>
47                 <refname>sd_watchdog_enabled</refname>
48                 <refpurpose>Check whether the service manager expects watchdog keep-alive notifications from a service</refpurpose>
49         </refnamediv>
50
51         <refsynopsisdiv>
52                 <funcsynopsis>
53                         <funcsynopsisinfo>#include &lt;systemd/sd-daemon.h&gt;</funcsynopsisinfo>
54
55                         <funcprototype>
56                                 <funcdef>int <function>sd_watchdog_enabled</function></funcdef>
57                                 <paramdef>int <parameter>unset_environment</parameter></paramdef>
58                                 <paramdef>const uint64_t *<parameter>usec</parameter></paramdef>
59                         </funcprototype>
60                 </funcsynopsis>
61         </refsynopsisdiv>
62
63         <refsect1>
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>
71
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>
82
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>
96
97                 <para>To enable service supervision with the watchdog
98                 logic, use <varname>WatchdogSec=</varname> in service
99                 files. See
100                 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
101                 for details.</para>
102         </refsect1>
103
104         <refsect1>
105                 <title>Return Value</title>
106
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                 &gt; 0 is returned, otherwise 0 is returned. Only if
111                 the return value is &gt; 0, the
112                 <parameter>usec</parameter> parameter is valid after
113                 the call.</para>
114         </refsect1>
115
116         <refsect1>
117                 <title>Notes</title>
118
119                 <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
120
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>
129
130         </refsect1>
131
132         <refsect1>
133                 <title>Environment</title>
134
135                 <variablelist class='environment-variables'>
136                         <varlistentry>
137                                 <term><varname>$WATCHDOG_PID</varname></term>
138
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>
144                         </varlistentry>
145
146                         <varlistentry>
147                                 <term><varname>$WATCHDOG_USEC</varname></term>
148
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
153                                 See above for
154                                 details.</para></listitem>
155                         </varlistentry>
156                 </variablelist>
157         </refsect1>
158
159         <refsect1>
160                 <title>See Also</title>
161                 <para>
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>
167                 </para>
168         </refsect1>
169
170 </refentry>