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