sd_watchdog_enabled.xml revision 494a66821815e8109afa136bd42818b85da38c09
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 <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
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering 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
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering 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
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering the return value is > 0 the
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <parameter>usec</parameter> parameter is valid after
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering the call.</para>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <para>This function is provided by the reference
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering implementation of APIs for new-style daemons and
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering distributed with the systemd package. The algorithm
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering it implements is simple, and can easily be
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering reimplemented in daemons if it is important to support
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering this interface without using the reference
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering implementation.</para>
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
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering that case the variables were set for a different
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering process further up the process tree.</para>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <para>For details about the algorithm check the
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering liberally licensed reference implementation sources:
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/libsystemd-daemon/sd-daemon.c"/>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h"/></para>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <para><function>sd_watchdog_enabled()</function> is
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering implemented in the reference implementation's
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <filename>sd-daemon.h</filename> files. These
494a66821815e8109afa136bd42818b85da38c09Jan Engelhardt interfaces are available as a shared library, which can
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering be compiled and linked to with the
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <constant>libsystemd-daemon</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering file. Alternatively, applications consuming these APIs
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering may copy the implementation into their source
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering tree. For more details about the reference
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering implementation see
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <para>If the reference implementation is used as
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering drop-in files and -DDISABLE_SYSTEMD is set during
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering compilation, these functions will always return 0 and
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering otherwise become a NOP.</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>