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