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