diff options
Diffstat (limited to 'man/sd_watchdog_enabled.xml')
| -rw-r--r-- | man/sd_watchdog_enabled.xml | 152 |
1 files changed, 152 insertions, 0 deletions
diff --git a/man/sd_watchdog_enabled.xml b/man/sd_watchdog_enabled.xml new file mode 100644 index 0000000..4a6bd6f --- /dev/null +++ b/man/sd_watchdog_enabled.xml @@ -0,0 +1,152 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> + +<refentry id="sd_watchdog_enabled" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_watchdog_enabled</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_watchdog_enabled</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_watchdog_enabled</refname> + <refpurpose>Check whether the service manager expects watchdog keep-alive notifications from a service</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_watchdog_enabled</function></funcdef> + <paramdef>int <parameter>unset_environment</parameter></paramdef> + <paramdef>uint64_t *<parameter>usec</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para><function>sd_watchdog_enabled()</function> may be called by + a service to detect whether the service manager expects regular + keep-alive watchdog notification events from it, and the timeout + after which the manager will act on the service if it did not get + such a notification.</para> + + <para>If the <varname>$WATCHDOG_USEC</varname> environment + variable is set, and the <varname>$WATCHDOG_PID</varname> variable + is unset or set to the PID of the current process, the service + manager expects notifications from this process. The manager will + usually terminate a service when it does not get a notification + message within the specified time after startup and after each + previous message. It is recommended that a daemon sends a + keep-alive notification message to the service manager every half + of the time returned here. Notification messages may be sent with + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> + with a message string of <literal>WATCHDOG=1</literal>.</para> + + <para>If the <parameter>unset_environment</parameter> parameter is + non-zero, <function>sd_watchdog_enabled()</function> will unset + the <varname>$WATCHDOG_USEC</varname> and + <varname>$WATCHDOG_PID</varname> environment variables before + returning (regardless of whether the function call itself + succeeded or not). Those variables are no longer inherited by + child processes. Further calls to + <function>sd_watchdog_enabled()</function> will also return with + zero.</para> + + <para>If the <parameter>usec</parameter> parameter is non-<constant>NULL</constant>, + <function>sd_watchdog_enabled()</function> will write the timeout + in μs for the watchdog logic to it.</para> + + <para>To enable service supervision with the watchdog logic, use + <varname>WatchdogSec=</varname> in service files. See + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para> + + <para>Use + <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + to enable automatic watchdog support in + <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>-based event loops.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On failure, this call returns a negative errno-style error + code. If the service manager expects watchdog keep-alive + notification messages to be sent, > 0 is returned, otherwise 0 + is returned. Only if the return value is > 0, the + <parameter>usec</parameter> parameter is valid after the + call.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> + <xi:include href="threads-aware.xml" xpointer="getenv"/> + + <para>Internally, this function parses the + <varname>$WATCHDOG_PID</varname> and + <varname>$WATCHDOG_USEC</varname> environment variable. The call + will ignore these variables if <varname>$WATCHDOG_PID</varname> + does not contain the PID of the current process, under the + assumption that in that case, the variables were set for a + different process further up the process tree.</para> + </refsect1> + + <refsect1> + <title>Environment</title> + + <variablelist class='environment-variables'> + <varlistentry> + <term><varname>$WATCHDOG_PID</varname></term> + + <listitem><para>Set by the system manager for supervised + process for which watchdog support is enabled, and contains + the PID of that process. See above for + details.</para> + + <xi:include href="version-info.xml" xpointer="v209"/></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$WATCHDOG_USEC</varname></term> + + <listitem><para>Set by the system manager for supervised + process for which watchdog support is enabled, and contains + the watchdog timeout in μs. See above for + details.</para> + + <xi:include href="version-info.xml" xpointer="v209"/></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>History</title> + <para><function>sd_watchdog_enabled()</function> was added in version 209.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> |