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