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>