WATCHDOG(4)

🐕💖 WATCHDOG — kernel interfaces manual 💖🐕

okay so bestie, buckle up, this is the watchdog(4) page from the kernel interfaces manual and it's genuinely so good. no cap.

---

✨ NAME ✨

watchdog — hardware and software watchdog 🐶

---

🎀 SYNOPSIS 🎀

#include <sys/watchdog.h>

---

🦋 DESCRIPTION 🦋

So the watchdog facility is literally what you use to control hardware and software watchdogs. It's giving "someone please notice if I stop responding" energy and honestly? iconic.

The device /dev/fido supports several optional ioctl(2) calls for configuration, and it responds to a single operational ioctl call, WDIOCPATPAT. That one takes a single argument which represents a timeout value — specified as a power of two nanoseconds — or-ed with a flag that selects active or passive control of the watchdog.

• WD_ACTIVE — says the watchdog will be kept from timing out from userland, for instance by the watchdogd(8) daemon. 💅
• WD_PASSIVE — says the watchdog will be kept from timing out from the kernel.

The WDIOCPATPAT ioctl(2) call will return success if just one of the available watchdog(9) implementations supports setting the timeout to the specified timeout. That means at least one watchdog is armed. 🫡 By default, this will be a hardware watchdog if one is present, but if no hardware watchdog is able to process the request, a default software watchdog is enabled. And if the call fails — for instance if none of the watchdog(9) implementations support the timeout length — then all watchdogs are disabled and must be explicitly re-enabled. 😭

To disable the watchdogs pass WD_TO_NEVER. If disarming the watchdog(s) failed, an error is returned. The watchdog might still be armed! 💀

---

🔧 the optional configuration ioctls 🔧

Here they are, listed with the type of the parameter each one uses. Examples of their use can be found in watchdogd(8).

• WDIOC_SETTIMEOUT int — set/reset the timer ⏰
• WDIOC_GETTIMEOUT int — get total timeout
• WDIOC_GETTIMELEFT int — get time left
• WDIOC_GETPRETIMEOUT int — get the pre-timeout
• WDIOC_SETPRETIMEOUT int — set the pre-timeout
• WDIOC_SETPRETIMEOUTACT int — Set the action when a pre-timeout occurs (see WD_SOFT_* below).
• WDIOC_SETSOFT int — Use an internal software watchdog instead of hardware. There is also an external software watchdog, which is used by default if no hardware watchdog was attached.
• WDIOC_SETSOFTTIMEOUTACT int — Set the action whan a soft timeout occurs. (yes bestie, "whan". we love her. we're not fixing her. 💅)

---

🌸 the actions 🌸

The actions that may be specified for the pre-timeout or the internal software watchdog are listed here. Multiple actions can be specified by ORing values together.

• WD_SOFT_PANIC — panic 😱
• WD_SOFT_DDB — enter debugger 🐛
• WD_SOFT_LOG — log(9)
• WD_SOFT_PRINT — printf(9)

---

👑 RETURN VALUES 👑

The WDIOCPATPAT ioctl returns zero on success and non-zero on failure.

• [EOPNOTSUPP] — No watchdog present in the kernel, or none of the watchdogs supports the requested timeout value (timeout value other than 0).
• [EOPNOTSUPP] — Watchdog could not be disabled (timeout value of 0).
• [EINVAL] — Invalid flag combination passed.

The configuration ioctl operations return zero on success and non-zero on failure. ✨

---

🔥 EXAMPLES 🔥

      #include <paths.h>
      #include <sys/watchdog.h>

      #define WDPATH  "/dev/" _PATH_WATCHDOG
      int wdfd = -1;

      static void
      wd_init(void)
      {
              wdfd = open(WDPATH, O_RDWR);
              if (wdfd == -1)
                      err(1, WDPATH);
      }
      static void
      wd_reset(u_int timeout)
      {
              if (ioctl(wdfd, WDIOCPATPAT, &timeout) == -1)
                      err(1, "WDIOCPATPAT");
      }

      /* in main() */
      wd_init();
      wd_reset(WD_ACTIVE|WD_TO_8SEC);
      /* potential freeze point */
      wd_reset(WD_TO_NEVER);

Enables a watchdog to recover from a potentially freezing piece of code. 🧊➡️🔥

---

And then this, in your kernel config:

options SW_WATCHDOG

forces a software watchdog in the kernel to be configured even if a hardware watchdog is configured, dropping to KDB or panicking when firing, depending on the KDB and KDB_UNATTENDED kernel configuration options. 😌

---

🌈 SEE ALSO 🌈

watchdogd(8), watchdog(9)

---

⭐ HISTORY ⭐

The watchdog code first appeared in FreeBSD 5.1. a whole era. 🫶

---

💜 AUTHORS 💜

The watchdog facility was written by Poul-Henning Kamp <phk@FreeBSD.org>. The software watchdog code and this manual page were written by Sean Kelly <smkelly@FreeBSD.org>. Some contributions were made by Jeff Roberson <jeff@FreeBSD.org>. legends only, honestly.

---

🙈 BUGS 🙈

The WD_PASSIVE option has not yet been implemented. it's giving "coming soon" but make it 2003. 😭

---

okay that's the whole page bestie, you ate it. this is from the Debian build, dated January 2, 2018 — go forth and arm your watchdogs, ily, mwah 💋✨🎀