Adding upstream version 252.22.upstream/252.22

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 142 insertions, 0 deletions

diff --git a/man/sd_watchdog_enabled.xml b/man/sd_watchdog_enabled.xml
new file mode 100644
index 0000000..1abc2f8
--- /dev/null
+++ b/man/sd_watchdog_enabled.xml
@@ -0,0 +1,142 @@
+<?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 &lt;systemd/sd-daemon.h&gt;</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, &gt; 0 is returned, otherwise 0
+    is returned. Only if the return value is &gt; 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"/>
+
+    <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></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></listitem>
+      </varlistentry>
+    </variablelist>
+  </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>