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 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>This function is provided by the reference
 119                 implementation of APIs for new-style daemons and
 120                 distributed with the systemd package. The algorithm
 121                 it implements is simple, and can easily be
 122                 reimplemented in daemons if it is important to support
 123                 this interface without using the reference
 124                 implementation.</para>
 125
 126                 <para>Internally, this functions parses the
 127                 <varname>$WATCHDOG_PID</varname> and
 128                 <varname>$WATCHDOG_USEC</varname> environment
 129                 variable. The call will ignore these variables if
 130                 <varname>$WATCHDOG_PID</varname> does containe the PID
 131                 of the current process, under the assumption that in
 132                 that case the variables were set for a different
 133                 process further up the process tree.</para>
 134
 135                 <para>For details about the algorithm check the
 136                 liberally licensed reference implementation sources:
 137                 <ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/libsystemd-daemon/sd-daemon.c"/>
 138                 and <ulink
 139                 url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h"/></para>
 140
 141                 <para><function>sd_watchdog_enabled()</function> is
 142                 implemented in the reference implementation's
 143                 <filename>sd-daemon.c</filename> and
 144                 <filename>sd-daemon.h</filename> files. These
 145                 interfaces are available as shared library, which can
 146                 be compiled and linked to with the
 147                 <constant>libsystemd-daemon</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 148                 file. Alternatively, applications consuming these APIs
 149                 may copy the implementation into their source
 150                 tree. For more details about the reference
 151                 implementation see
 152                 <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 153
 154                 <para>If the reference implementation is used as
 155                 drop-in files and -DDISABLE_SYSTEMD is set during
 156                 compilation, these functions will always return 0 and
 157                 otherwise become a NOP.</para>
 158         </refsect1>
 159
 160         <refsect1>
 161                 <title>Environment</title>
 162
 163                 <variablelist class='environment-variables'>
 164                         <varlistentry>
 165                                 <term><varname>$WATCHDOG_PID</varname></term>
 166
 167                                 <listitem><para>Set by the system
 168                                 manager for supervised process for
 169                                 which watchdog support is enabled, and
 170                                 contains the PID of that process. See
 171                                 above for details.</para></listitem>
 172                         </varlistentry>
 173
 174                         <varlistentry>
 175                                 <term><varname>$WATCHDOG_USEC</varname></term>
 176
 177                                 <listitem><para>Set by the system
 178                                 manager for supervised process for
 179                                 which watchdog support is enabled, and
 180                                 contains the watchdog timeout in µs
 181                                 See above for
 182                                 details.</para></listitem>
 183                         </varlistentry>
 184                 </variablelist>
 185         </refsect1>
 186
 187         <refsect1>
 188                 <title>See Also</title>
 189                 <para>
 190                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 191                         <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 192                         <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 193                         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 194                         <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 195                 </para>
 196         </refsect1>
 197
 198 </refentry>