sd_watchdog_enabled.xml revision 6a70f3aa63a3b7a6a30448c48322ad38b719cdce
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/>.
6a70f3aa63a3b7a6a30448c48322ad38b719cdceZbigniew Jędrzejewski-Szmek<refentry id="sd_watchdog_enabled"
6a70f3aa63a3b7a6a30448c48322ad38b719cdceZbigniew Jędrzejewski-Szmek 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>const uint64_t *<parameter>usec</parameter></paramdef>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering </funcprototype>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering </funcsynopsis>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering </refsynopsisdiv>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <para><function>sd_watchdog_enabled()</function> may
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering be called by a service to detect whether the service
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering manager expects regular keep-alive watchdog
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering notification events from it, and the timeout after
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering which the manager will act on the service if it did
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering not get such a notification.</para>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <para>If the <parameter>unset_environment</parameter>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering parameter is non-zero,
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <function>sd_watchdog_enabled()</function> will unset
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering the <varname>$WATCHDOG_USEC</varname> and
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <varname>$WATCHDOG_PID</varname> environment variables
494a66821815e8109afa136bd42818b85da38c09Jan Engelhardt before returning (regardless of whether the function call
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering itself succeeded or not). Further calls to
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <function>sd_watchdog_enabled()</function> will then
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering return with zero, but the variable is no longer
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering inherited by child processes.</para>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <para>If the <parameter>usec</parameter> parameter is
b040723ea412209e0edf54647fa5aa4287411507Jan Engelhardt non-NULL, <function>sd_watchdog_enabled()</function>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering will return the timeout in µs for the watchdog
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering logic. The service manager will usually terminate a
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering service when it did not get a notification message
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering within the specified time after startup and after each
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering previous message. It is recommended that a daemon
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering sends a keep-alive notification message to the service
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering manager every half of the time returned
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering 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
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <para>To enable service supervision with the watchdog
b040723ea412209e0edf54647fa5aa4287411507Jan Engelhardt logic, use <varname>WatchdogSec=</varname> in service
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
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering errno-style error code. If the service manager expects
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering watchdog keep-alive notification messages to be sent,
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering > 0 is returned, otherwise 0 is returned. Only if
b040723ea412209e0edf54647fa5aa4287411507Jan Engelhardt the return value is > 0, the
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <parameter>usec</parameter> parameter is valid after
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering the call.</para>
6a70f3aa63a3b7a6a30448c48322ad38b719cdceZbigniew Jędrzejewski-Szmek <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <para>Internally, this functions parses the
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <varname>$WATCHDOG_USEC</varname> environment
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering variable. The call will ignore these variables if
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <varname>$WATCHDOG_PID</varname> does containe the PID
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering of the current process, under the assumption that in
b040723ea412209e0edf54647fa5aa4287411507Jan Engelhardt that case, the variables were set for a different
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering 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 manager for supervised process for
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering which watchdog support is enabled, and
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering contains the PID of that process. See
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering </varlistentry>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <varlistentry>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <term><varname>$WATCHDOG_USEC</varname></term>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering manager for supervised process for
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering which watchdog support is enabled, and
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering contains the watchdog timeout in µs
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering </varlistentry>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering </variablelist>
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>