]> git.proxmox.com Git - systemd.git/blob - man/sd_watchdog_enabled.xml
Enable seccomp support on powerpc, ppc64el, and s390x
[systemd.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>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 be called by
66 a service to detect whether the service manager expects regular
67 keep-alive watchdog notification events from it, and the timeout
68 after which the manager will act on the service if it did not get
69 such a notification.</para>
70
71 <para>If the <varname>$WATCHDOG_USEC</varname> environment
72 variable is set, and the <varname>$WATCHDOG_PID</varname> variable
73 is unset or set to the PID of the current process, the service
74 manager expects notifications from this process. The manager will
75 usually terminate a service when it does not get a notification
76 message within the specified time after startup and after each
77 previous message. It is recommended that a daemon sends a
78 keep-alive notification message to the service manager every half
79 of the time returned here. Notification messages may be sent with
80 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
81 with a message string of <literal>WATCHDOG=1</literal>.</para>
82
83 <para>If the <parameter>unset_environment</parameter> parameter is
84 non-zero, <function>sd_watchdog_enabled()</function> will unset
85 the <varname>$WATCHDOG_USEC</varname> and
86 <varname>$WATCHDOG_PID</varname> environment variables before
87 returning (regardless of whether the function call itself
88 succeeded or not). Those variables are no longer inherited by
89 child processes. Further calls to
90 <function>sd_watchdog_enabled()</function> will also return with
91 zero.</para>
92
93 <para>If the <parameter>usec</parameter> parameter is non-NULL,
94 <function>sd_watchdog_enabled()</function> will write the timeout
95 in µs for the watchdog logic to it.</para>
96
97 <para>To enable service supervision with the watchdog logic, use
98 <varname>WatchdogSec=</varname> in service 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 errno-style error
107 code. If the service manager expects watchdog keep-alive
108 notification messages to be sent, &gt; 0 is returned, otherwise 0
109 is returned. Only if the return value is &gt; 0, the
110 <parameter>usec</parameter> parameter is valid after the
111 call.</para>
112 </refsect1>
113
114 <refsect1>
115 <title>Notes</title>
116
117 <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
118
119 <para>Internally, this functions parses the
120 <varname>$WATCHDOG_PID</varname> and
121 <varname>$WATCHDOG_USEC</varname> environment variable. The call
122 will ignore these variables if <varname>$WATCHDOG_PID</varname>
123 does not contain the PID of the current process, under the
124 assumption that in that case, the variables were set for a
125 different process further up the process tree.</para>
126 </refsect1>
127
128 <refsect1>
129 <title>Environment</title>
130
131 <variablelist class='environment-variables'>
132 <varlistentry>
133 <term><varname>$WATCHDOG_PID</varname></term>
134
135 <listitem><para>Set by the system manager for supervised
136 process for which watchdog support is enabled, and contains
137 the PID of that process. See above for
138 details.</para></listitem>
139 </varlistentry>
140
141 <varlistentry>
142 <term><varname>$WATCHDOG_USEC</varname></term>
143
144 <listitem><para>Set by the system manager for supervised
145 process for which watchdog support is enabled, and contains
146 the watchdog timeout in µs See above for
147 details.</para></listitem>
148 </varlistentry>
149 </variablelist>
150 </refsect1>
151
152 <refsect1>
153 <title>History</title>
154
155 <para>The watchdog functionality and the
156 <varname>$WATCHDOG_USEC</varname> variable were added in
157 systemd-41.</para>
158
159 <para><function>sd_watchdog_enabled()</function> function was
160 added in systemd-209. Since that version, the
161 <varname>$WATCHDOG_PID</varname> variable is also set.</para>
162 </refsect1>
163
164 <refsect1>
165 <title>See Also</title>
166 <para>
167 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
168 <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
169 <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
170 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
171 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
172 </para>
173 </refsect1>
174
175 </refentry>