sd_watchdog_enabled.xml revision b938cb902c3b5bca807a94b277672c64d6767886
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering This file is part of systemd.
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering Copyright 2013 Lennart Poettering
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering systemd is free software; you can redistribute it and/or modify it
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering under the terms of the GNU Lesser General Public License as published by
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering the Free Software Foundation; either version 2.1 of the License, or
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering (at your option) any later version.
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering systemd is distributed in the hope that it will be useful, but
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering Lesser General Public License for more details.
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering You should have received a copy of the GNU Lesser General Public License
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering xmlns:xi="http://www.w3.org/2001/XInclude">
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <refentryinfo>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering </authorgroup>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering </refentryinfo>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <refentrytitle>sd_watchdog_enabled</refentrytitle>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <refpurpose>Check whether the service manager expects watchdog keep-alive notifications from a service</refpurpose>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <refsynopsisdiv>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <funcsynopsis>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <funcprototype>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <funcdef>int <function>sd_watchdog_enabled</function></funcdef>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <paramdef>int <parameter>unset_environment</parameter></paramdef>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering </funcprototype>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering </funcsynopsis>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering </refsynopsisdiv>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <para><function>sd_watchdog_enabled()</function> may be called by
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering a service to detect whether the service manager expects regular
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering keep-alive watchdog notification events from it, and the timeout
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering after which the manager will act on the service if it did not get
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering such a notification.</para>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <para>If the <varname>$WATCHDOG_USEC</varname> environment
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering variable is set, and the <varname>$WATCHDOG_PID</varname> variable
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering is unset or set to the PID of the current process, the service
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering manager expects notifications from this process. The manager will
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering usually terminate a service when it does not get a notification
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering message within the specified time after startup and after each
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering previous message. It is recommended that a daemon sends a
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering keep-alive notification message to the service manager every half
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering of the time returned here. Notification messages may be sent with
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering with a message string of <literal>WATCHDOG=1</literal>.</para>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <para>If the <parameter>unset_environment</parameter> parameter is
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering non-zero, <function>sd_watchdog_enabled()</function> will unset
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering the <varname>$WATCHDOG_USEC</varname> and
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <varname>$WATCHDOG_PID</varname> environment variables before
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering returning (regardless of whether the function call itself
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering succeeded or not). Those variables are no longer inherited by
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering child processes. Further calls to
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <function>sd_watchdog_enabled()</function> will also return with
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <para>If the <parameter>usec</parameter> parameter is non-NULL,
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <function>sd_watchdog_enabled()</function> will write the timeout
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering in µs for the watchdog logic to it.</para>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <para>To enable service supervision with the watchdog logic, use
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <varname>WatchdogSec=</varname> in service files. See
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering for details.</para>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <para>On failure, this call returns a negative errno-style error
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering code. If the service manager expects watchdog keep-alive
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering notification messages to be sent, > 0 is returned, otherwise 0
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering is returned. Only if the return value is > 0, the
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <parameter>usec</parameter> parameter is valid after the
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <para>Internally, this functions parses the
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <varname>$WATCHDOG_USEC</varname> environment variable. The call
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering will ignore these variables if <varname>$WATCHDOG_PID</varname>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering does not contain the PID of the current process, under the
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering assumption that in that case, the variables were set for a
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering different process further up the process tree.</para>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <variablelist class='environment-variables'>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <varlistentry>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <term><varname>$WATCHDOG_PID</varname></term>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <listitem><para>Set by the system manager for supervised
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering process for which watchdog support is enabled, and contains
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering the PID of that process. See above for
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering </varlistentry>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <varlistentry>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <term><varname>$WATCHDOG_USEC</varname></term>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <listitem><para>Set by the system manager for supervised
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering process for which watchdog support is enabled, and contains
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering the watchdog timeout in µs See above for
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering </varlistentry>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering </variablelist>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <para>The watchdog functionality and the
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <varname>$WATCHDOG_USEC</varname> variable were added in
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering systemd-41.</para>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <para><function>sd_watchdog_enabled()</function> function was
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering added in systemd-209. Since that version, the
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <varname>$WATCHDOG_PID</varname> variable is also set.</para>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>