chiark / gitweb /
machined: optionally, allow registration of pre-existing units (scopes
[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
26         <refentryinfo>
27                 <title>sd_watchdog_enabled</title>
28                 <productname>systemd</productname>
29
30                 <authorgroup>
31                         <author>
32                                 <contrib>Developer</contrib>
33                                 <firstname>Lennart</firstname>
34                                 <surname>Poettering</surname>
35                                 <email>lennart@poettering.net</email>
36                         </author>
37                 </authorgroup>
38         </refentryinfo>
39
40         <refmeta>
41                 <refentrytitle>sd_watchdog_enabled</refentrytitle>
42                 <manvolnum>3</manvolnum>
43         </refmeta>
44
45         <refnamediv>
46                 <refname>sd_watchdog_enabled</refname>
47                 <refpurpose>Check whether the service manager expects watchdog keep-alive notifications from a service</refpurpose>
48         </refnamediv>
49
50         <refsynopsisdiv>
51                 <funcsynopsis>
52                         <funcsynopsisinfo>#include &lt;systemd/sd-daemon.h&gt;</funcsynopsisinfo>
53
54                         <funcprototype>
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>
58                         </funcprototype>
59                 </funcsynopsis>
60         </refsynopsisdiv>
61
62         <refsect1>
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>
70
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>
81
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>
95
96                 <para>To enable service supervision with the watchdog
97                 logic, use <varname>WatchdogSec=</varname> in service
98                 files. See
99                 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
100                 for details.</para>
101         </refsect1>
102
103         <refsect1>
104                 <title>Return Value</title>
105
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                 &gt; 0 is returned, otherwise 0 is returned. Only if
110                 the return value is &gt; 0, the
111                 <parameter>usec</parameter> parameter is valid after
112                 the call.</para>
113         </refsect1>
114
115         <refsect1>
116                 <title>Notes</title>
117
118                 <para>This function is provided by the reference
119                 implementation of APIs for new-style daemons and
120                 distributed with the systemd package. The algorithm
121                 it implements is simple, and can easily be
122                 reimplemented in daemons if it is important to support
123                 this interface without using the reference
124                 implementation.</para>
125
126                 <para>Internally, this functions parses the
127                 <varname>$WATCHDOG_PID</varname> and
128                 <varname>$WATCHDOG_USEC</varname> environment
129                 variable. The call will ignore these variables if
130                 <varname>$WATCHDOG_PID</varname> does containe the PID
131                 of the current process, under the assumption that in
132                 that case, the variables were set for a different
133                 process further up the process tree.</para>
134
135                 <para>For details about the algorithm, check the
136                 liberally licensed reference implementation sources:
137                 <ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/libsystemd-daemon/sd-daemon.c"/>
138                 and <ulink
139                 url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h"/></para>
140
141                 <para><function>sd_watchdog_enabled()</function> is
142                 implemented in the reference implementation's
143                 <filename>sd-daemon.c</filename> and
144                 <filename>sd-daemon.h</filename> files. These
145                 interfaces are available as a shared library, which can
146                 be compiled and linked to with the
147                 <constant>libsystemd-daemon</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
148                 file. Alternatively, applications consuming these APIs
149                 may copy the implementation into their source
150                 tree. For more details about the reference
151                 implementation, see
152                 <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
153
154                 <para>If the reference implementation is used as
155                 drop-in files and -DDISABLE_SYSTEMD is set during
156                 compilation, these functions will always return 0 and
157                 otherwise become a NOP.</para>
158         </refsect1>
159
160         <refsect1>
161                 <title>Environment</title>
162
163                 <variablelist class='environment-variables'>
164                         <varlistentry>
165                                 <term><varname>$WATCHDOG_PID</varname></term>
166
167                                 <listitem><para>Set by the system
168                                 manager for supervised process for
169                                 which watchdog support is enabled, and
170                                 contains the PID of that process. See
171                                 above for details.</para></listitem>
172                         </varlistentry>
173
174                         <varlistentry>
175                                 <term><varname>$WATCHDOG_USEC</varname></term>
176
177                                 <listitem><para>Set by the system
178                                 manager for supervised process for
179                                 which watchdog support is enabled, and
180                                 contains the watchdog timeout in µs
181                                 See above for
182                                 details.</para></listitem>
183                         </varlistentry>
184                 </variablelist>
185         </refsect1>
186
187         <refsect1>
188                 <title>See Also</title>
189                 <para>
190                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
191                         <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
192                         <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
193                         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
194                         <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
195                 </para>
196         </refsect1>
197
198 </refentry>