chiark / gitweb /
check for _POSIX_C_SOURCE instead of __USE_POSIX*
[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 elogind.
7
8   Copyright 2013 Lennart Poettering
9
10   elogind 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   elogind 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 elogind; 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>elogind</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;elogind/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
102     <para>Use
103     <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
104     to enable automatic watchdog support in
105     <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>-based event loops.</para>
106   </refsect1>
107
108   <refsect1>
109     <title>Return Value</title>
110
111     <para>On failure, this call returns a negative errno-style error
112     code. If the service manager expects watchdog keep-alive
113     notification messages to be sent, &gt; 0 is returned, otherwise 0
114     is returned. Only if the return value is &gt; 0, the
115     <parameter>usec</parameter> parameter is valid after the
116     call.</para>
117   </refsect1>
118
119   <refsect1>
120     <title>Notes</title>
121
122     <xi:include href="libelogind-pkgconfig.xml" xpointer="pkgconfig-text"/>
123
124     <para>Internally, this function parses the
125     <varname>$WATCHDOG_PID</varname> and
126     <varname>$WATCHDOG_USEC</varname> environment variable. The call
127     will ignore these variables if <varname>$WATCHDOG_PID</varname>
128     does not contain the PID of the current process, under the
129     assumption that in that case, the variables were set for a
130     different process further up the process tree.</para>
131   </refsect1>
132
133   <refsect1>
134     <title>Environment</title>
135
136     <variablelist class='environment-variables'>
137       <varlistentry>
138         <term><varname>$WATCHDOG_PID</varname></term>
139
140         <listitem><para>Set by the system manager for supervised
141         process for which watchdog support is enabled, and contains
142         the PID of that process. See above for
143         details.</para></listitem>
144       </varlistentry>
145
146       <varlistentry>
147         <term><varname>$WATCHDOG_USEC</varname></term>
148
149         <listitem><para>Set by the system manager for supervised
150         process for which watchdog support is enabled, and contains
151         the watchdog timeout in µs. See above for
152         details.</para></listitem>
153       </varlistentry>
154     </variablelist>
155   </refsect1>
156
157   <refsect1>
158     <title>See Also</title>
159     <para>
160       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
161       <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
162       <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
163       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
164       <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
165       <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
166     </para>
167   </refsect1>
168
169 </refentry>