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 elogind.
   7   SPDX-License-Identifier: LGPL-2.1+
   8
   9
  10   Copyright 2013 Lennart Poettering
  11
  12   elogind is free software; you can redistribute it and/or modify it
  13   under the terms of the GNU Lesser General Public License as published by
  14   the Free Software Foundation; either version 2.1 of the License, or
  15   (at your option) any later version.
  16
  17   elogind is distributed in the hope that it will be useful, but
  18   WITHOUT ANY WARRANTY; without even the implied warranty of
  19   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  20   Lesser General Public License for more details.
  21
  22   You should have received a copy of the GNU Lesser General Public License
  23   along with elogind; If not, see <http://www.gnu.org/licenses/>.
  24 -->
  25
  26 <refentry id="sd_watchdog_enabled"
  27   xmlns:xi="http://www.w3.org/2001/XInclude">
  28
  29   <refentryinfo>
  30     <title>sd_watchdog_enabled</title>
  31     <productname>elogind</productname>
  32
  33     <authorgroup>
  34       <author>
  35         <contrib>Developer</contrib>
  36         <firstname>Lennart</firstname>
  37         <surname>Poettering</surname>
  38         <email>lennart@poettering.net</email>
  39       </author>
  40     </authorgroup>
  41   </refentryinfo>
  42
  43   <refmeta>
  44     <refentrytitle>sd_watchdog_enabled</refentrytitle>
  45     <manvolnum>3</manvolnum>
  46   </refmeta>
  47
  48   <refnamediv>
  49     <refname>sd_watchdog_enabled</refname>
  50     <refpurpose>Check whether the service manager expects watchdog keep-alive notifications from a service</refpurpose>
  51   </refnamediv>
  52
  53   <refsynopsisdiv>
  54     <funcsynopsis>
  55       <funcsynopsisinfo>#include &lt;elogind/sd-daemon.h&gt;</funcsynopsisinfo>
  56
  57       <funcprototype>
  58         <funcdef>int <function>sd_watchdog_enabled</function></funcdef>
  59         <paramdef>int <parameter>unset_environment</parameter></paramdef>
  60         <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
  61       </funcprototype>
  62     </funcsynopsis>
  63   </refsynopsisdiv>
  64
  65   <refsect1>
  66     <title>Description</title>
  67     <para><function>sd_watchdog_enabled()</function> may be called by
  68     a service to detect whether the service manager expects regular
  69     keep-alive watchdog notification events from it, and the timeout
  70     after which the manager will act on the service if it did not get
  71     such a notification.</para>
  72
  73     <para>If the <varname>$WATCHDOG_USEC</varname> environment
  74     variable is set, and the <varname>$WATCHDOG_PID</varname> variable
  75     is unset or set to the PID of the current process, the service
  76     manager expects notifications from this process. The manager will
  77     usually terminate a service when it does not get a notification
  78     message within the specified time after startup and after each
  79     previous message. It is recommended that a daemon sends a
  80     keep-alive notification message to the service manager every half
  81     of the time returned here. Notification messages may be sent with
  82     <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  83     with a message string of <literal>WATCHDOG=1</literal>.</para>
  84
  85     <para>If the <parameter>unset_environment</parameter> parameter is
  86     non-zero, <function>sd_watchdog_enabled()</function> will unset
  87     the <varname>$WATCHDOG_USEC</varname> and
  88     <varname>$WATCHDOG_PID</varname> environment variables before
  89     returning (regardless of whether the function call itself
  90     succeeded or not). Those variables are no longer inherited by
  91     child processes. Further calls to
  92     <function>sd_watchdog_enabled()</function> will also return with
  93     zero.</para>
  94
  95     <para>If the <parameter>usec</parameter> parameter is non-NULL,
  96     <function>sd_watchdog_enabled()</function> will write the timeout
  97     in µs for the watchdog logic to it.</para>
  98
  99     <para>To enable service supervision with the watchdog logic, use
 100     <varname>WatchdogSec=</varname> in service files. See
 101     <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 102     for details.</para>
 103
 104     <para>Use
 105     <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 106     to enable automatic watchdog support in
 107     <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>-based event loops.</para>
 108   </refsect1>
 109
 110   <refsect1>
 111     <title>Return Value</title>
 112
 113     <para>On failure, this call returns a negative errno-style error
 114     code. If the service manager expects watchdog keep-alive
 115     notification messages to be sent, &gt; 0 is returned, otherwise 0
 116     is returned. Only if the return value is &gt; 0, the
 117     <parameter>usec</parameter> parameter is valid after the
 118     call.</para>
 119   </refsect1>
 120
 121   <refsect1>
 122     <title>Notes</title>
 123
 124     <xi:include href="libelogind-pkgconfig.xml" xpointer="pkgconfig-text"/>
 125
 126     <para>Internally, this function parses the
 127     <varname>$WATCHDOG_PID</varname> and
 128     <varname>$WATCHDOG_USEC</varname> environment variable. The call
 129     will ignore these variables if <varname>$WATCHDOG_PID</varname>
 130     does not contain the PID of the current process, under the
 131     assumption that in that case, the variables were set for a
 132     different process further up the process tree.</para>
 133   </refsect1>
 134
 135   <refsect1>
 136     <title>Environment</title>
 137
 138     <variablelist class='environment-variables'>
 139       <varlistentry>
 140         <term><varname>$WATCHDOG_PID</varname></term>
 141
 142         <listitem><para>Set by the system manager for supervised
 143         process for which watchdog support is enabled, and contains
 144         the PID of that process. See above for
 145         details.</para></listitem>
 146       </varlistentry>
 147
 148       <varlistentry>
 149         <term><varname>$WATCHDOG_USEC</varname></term>
 150
 151         <listitem><para>Set by the system manager for supervised
 152         process for which watchdog support is enabled, and contains
 153         the watchdog timeout in µs. 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       <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 168     </para>
 169   </refsect1>
 170
 171 </refentry>