WATCHDOG(9)

🐶 WATCHDOG(9) — the kernel dev's manual, bestie edition 💖

okay so you found the watchdog page, which lives in section 9 of the Kernel Developer's Manual ✨ (yes, the dev one, we're in the big leagues now, no cap). Sit down, grab a strawberry 🍓, and let's talk about making sure your system never just... vibes into the void forever.

✨ NAME ✨

watchdog — the software and hardware watchdog facility 🐕🦺🔥

it's giving "someone to check on you when you stop responding." main character energy, honestly.

🎀 SYNOPSIS 🎀

#include <sys/watchdog.h>

void
watchdog_fn(void *private, u_int cmd, int *error);

EVENTHANDLER_REGISTER(watchdog_list, watchdog_fn, private, 0);

EVENTHANDLER_DEREGISTER(watchdog_list, eventhandler_tag);

look at that. three lines. one function. we love a low-effort registration 💅

🌸 DESCRIPTION 🌸

okay so here's the whole vibe: to implement a watchdog in software or hardware, you literally only need to write a single function and register it on the global watchdog_list. that's it. one function. iconic behavior, truly.

that function has to look at the cmd argument and act on it like this:

• if cmd is zero, the watchdog must be disabled, and the error argument gets left untouched. do not touch it. hands off. 🙈 but — and this is the important part — if the watchdog cannot be disabled, then error must be set to EOPNOTSUPP. periodt.
• else (so, anything non-zero), the watchdog should be reset and configured to a timeout of (1 << (cmd & WD_INTERVAL)) nanoseconds or larger, and the error argument should be set to zero to signal that a watchdog has been armed. 🔥 consider it locked and loaded.
• if the watchdog cannot be configured to the proposed timeout, it must be disabled and the error argument left as is. why, you ask? to avoid hiding the arming of another watchdog. bestie we are NOT stealing someone else's spotlight 💀

real talk though: there is no specification of what the watchdog should do when it times out. none. it's giving "your call, king." but a hardware reset or similar "drastic but certain" behaviour is recommended — and honestly, if you're gonna go, go loud. 💥

🦋 SEE ALSO 🦋

• watchdog(4)

👑 AUTHORS 👑

the watchdog facility and this manual page were written by Poul-Henning Kamp <phk@FreeBSD.org>. absolute legend, we thank them for their service 🫶

and that's the whole page, bestie — go forth and register your watchdog_fn, keep those error values honest, and never leave a watchdog unarmed. iykyk 🌈

this edition came from Debian, dated February 28, 2004 — old school, but the vibes are timeless. mwah 💋