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>These APIs are implemented as a shared library,
 119                 which can be compiled and linked to with the
 120                 <constant>libsystemd</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 121                 file.</para>
 122
 123                 <para>Internally, this functions parses the
 124                 <varname>$WATCHDOG_PID</varname> and
 125                 <varname>$WATCHDOG_USEC</varname> environment
 126                 variable. The call will ignore these variables if
 127                 <varname>$WATCHDOG_PID</varname> does containe the PID
 128                 of the current process, under the assumption that in
 129                 that case, the variables were set for a different
 130                 process further up the process tree.</para>
 131
 132         </refsect1>
 133
 134         <refsect1>
 135                 <title>Environment</title>
 136
 137                 <variablelist class='environment-variables'>
 138                         <varlistentry>
 139                                 <term><varname>$WATCHDOG_PID</varname></term>
 140
 141                                 <listitem><para>Set by the system
 142                                 manager for supervised process for
 143                                 which watchdog support is enabled, and
 144                                 contains the PID of that process. See
 145                                 above for details.</para></listitem>
 146                         </varlistentry>
 147
 148                         <varlistentry>
 149                                 <term><varname>$WATCHDOG_USEC</varname></term>
 150
 151                                 <listitem><para>Set by the system
 152                                 manager for supervised process for
 153                                 which watchdog support is enabled, and
 154                                 contains the watchdog timeout in µs
 155                                 See above for
 156                                 details.</para></listitem>
 157                         </varlistentry>
 158                 </variablelist>
 159         </refsect1>
 160
 161         <refsect1>
 162                 <title>See Also</title>
 163                 <para>
 164                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 165                         <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 166                         <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 167                         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 168                         <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 169                 </para>
 170         </refsect1>
 171
 172 </refentry>