SD_WATCHDOG_ENABLED(3)

💖 NAME 💖

sd_watchdog_enabled — okay so this is the little function that checks whether the service manager is out here expecting watchdog keep-alive notifications from your service 👀✨ (like, is it watching you, bestie, or is it chill)

---

🌸 SYNOPSIS 🌸

#include <systemd/sd-daemon.h>

int sd_watchdog_enabled(int unset_environment, uint64_t *usec);

---

🎀 DESCRIPTION 🎀

okay so sd_watchdog_enabled() is what a service calls to find out two things: first, whether the service manager expects regular keep-alive watchdog notification events from it, and second, the timeout after which the manager will act on the service if it didn't get one of those notifications. two-for-one, we love to see it 💅

here's the vibe check logic, no cap: if the $WATCHDOG_USEC environment variable is set, and the $WATCHDOG_PID variable is unset or set to the PID of the current process, then the service manager expects notifications from this process. and when it doesn't get a notification message within the specified time after startup, and after each previous message? the manager will usually terminate a service. so yeah, lowkey high stakes 😭

the recommendation is that a daemon sends a keep-alive notification message to the service manager every half of the time returned here. literally just set a timer for half of it and you're golden 🫶 notification messages may be sent with sd_notify(3) using a message string of "WATCHDOG=1".

now about unset_environment: if this parameter is non-zero, sd_watchdog_enabled() will unset the $WATCHDOG_USEC and $WATCHDOG_PID environment variables before returning — and yes, that's regardless of whether the function call itself succeeded or not, so don't go thinking it skips the cleanup when things go sideways. those variables are no longer inherited by child processes after that. and further calls to sd_watchdog_enabled() will also return with zero. gone, gone, periodt.

if the usec parameter is non-NULL, sd_watchdog_enabled() will write the timeout in μs for the watchdog logic into it. cute little number for you ✨

to enable service supervision with the watchdog logic, use WatchdogSec= in service files — see systemd.service(5) for the details, iykyk.

and if you want automatic watchdog support in sd-event(3)-based event loops, use sd_event_set_watchdog(3). the event loop handles it, you just vibe 🌈

---

⭐ 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. and listen — only if the return value is > 0 is the usec parameter valid after the call. so check the return value first, bestie, don't just go reading usec whenever you feel like it 💀

---

💅 NOTES 💅

the functions described here are available as a shared library, which can be compiled against and linked to with the libsystemd pkg-config(1) file. standard, iconic, you know the drill.

the code described here uses getenv(3), which is declared to be not multi-thread-safe. meaning the code calling the functions described here must not call setenv(3) from a parallel thread. it's recommended to only do calls to setenv() from an early phase of the program when no other threads have been started. yes this is a real caveat, be normal about it 🧚

internally, this function parses the $WATCHDOG_PID and $WATCHDOG_USEC environment variables. the call will ignore these variables if $WATCHDOG_PID doesn't contain the PID of the current process — the assumption being that in that case the variables were set for a different process further up the process tree. so like, not your business, not your watchdog 🦋

---

🦋 ENVIRONMENT 🦋

• $WATCHDOG_PID — set by the system manager for a supervised process for which watchdog support is enabled, and it contains the PID of that process. see above for the details 👆 Added in version 209.
• $WATCHDOG_USEC — set by the system manager for a supervised process for which watchdog support is enabled, and it contains the watchdog timeout in μs. see above for the details 👆 Added in version 209.

---

🌈 HISTORY 🌈

sd_watchdog_enabled() was added in version 209. a classic, an icon, a legend 👑

---

👑 SEE ALSO 👑

systemd(1), sd-daemon(3), daemon(7), systemd.service(5), sd_notify(3), sd_event_set_watchdog(3)

---

and that's the whole page, bestie 🎀 this was SD_WATCHDOG_ENABLED(3) from systemd 261.3 — go forth and send your WATCHDOG=1 on time, mwah 💖