From 09812eb764b440651f3ff4cb5d37bd343f800560 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Sun, 22 Dec 2013 22:14:05 +0100 Subject: sd-daemon: introduce sd_watchdog_enabled() for parsing $WATCHDOG_USEC Also, introduce a new environment variable named $WATCHDOG_PID which cotnains the PID of the process that is supposed to send the keep-alive events. This is similar how $LISTEN_FDS and $LISTEN_PID work together, and protects against confusing processes further down the process tree due to inherited environment. --- man/sd_watchdog_enabled.xml | 198 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 198 insertions(+) create mode 100644 man/sd_watchdog_enabled.xml (limited to 'man/sd_watchdog_enabled.xml') diff --git a/man/sd_watchdog_enabled.xml b/man/sd_watchdog_enabled.xml new file mode 100644 index 0000000000..e42ae430ec --- /dev/null +++ b/man/sd_watchdog_enabled.xml @@ -0,0 +1,198 @@ + + + + + + + + + sd_watchdog_enabled + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_watchdog_enabled + 3 + + + + sd_watchdog_enabled + Check whether the service manager expects watchdog keep-alive notifications from a service + + + + + #include <systemd/sd-daemon.h> + + + int sd_watchdog_enabled + int unset_environment + const uint64_t *usec + + + + + + Description + sd_watchdog_enabled() 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. + + If the unset_environment + parameter is non-zero, + sd_watchdog_enabled() will unset + the $WATCHDOG_USEC and + $WATCHDOG_PID environment variables + before returning (regardless whether the function call + itself succeeded or not). Further calls to + sd_watchdog_enabled() will then + return with zero, but the variable is no longer + inherited by child processes. + + If the usec parameter is + non-NULL sd_watchdog_enabled() + will return the timeout in µs for the watchdog + logic. The service manager will usually terminate a + service when it did 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 + sd_notify3 + with a message string of + WATCHDOG=1. + + To enable service supervision with the watchdog + logic use WatchdogSec= in service + files. See + systemd.service5 + for details. + + + + Return Value + + 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 + usec parameter is valid after + the call. + + + + Notes + + This function is provided by the reference + implementation of APIs for new-style daemons and + distributed with the systemd package. The algorithm + it implements is simple, and can easily be + reimplemented in daemons if it is important to support + this interface without using the reference + implementation. + + Internally, this functions parses the + $WATCHDOG_PID and + $WATCHDOG_USEC environment + variable. The call will ignore these variables if + $WATCHDOG_PID does containe 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. + + For details about the algorithm check the + liberally licensed reference implementation sources: + + and + + sd_watchdog_enabled() is + implemented in the reference implementation's + sd-daemon.c and + sd-daemon.h files. These + interfaces are available as shared library, which can + be compiled and linked to with the + libsystemd-daemon pkg-config1 + file. Alternatively, applications consuming these APIs + may copy the implementation into their source + tree. For more details about the reference + implementation see + sd-daemon3. + + If the reference implementation is used as + drop-in files and -DDISABLE_SYSTEMD is set during + compilation, these functions will always return 0 and + otherwise become a NOP. + + + + Environment + + + + $WATCHDOG_PID + + 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. + + + + $WATCHDOG_USEC + + 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. + + + + + + See Also + + systemd1, + sd-daemon3, + daemon7, + systemd.service5, + sd_notify3 + + + + -- cgit v1.2.3-54-g00ecf