SHUTDOWNHOOK_ESTABLISH(9)

✨ SHUTDOWNHOOK_ESTABLISH ✨

okay so bestie, welcome to the shutdownhook_establish page from the Kernel Developer's Manual (section 9, kernel land, we love her) 💅 this one's all about adding and removing shutdown hooks — the little callbacks that fire right before the kernel dips out.

---

🌸 NAME 🌸

shutdownhook_establish, shutdownhook_disestablish — add or remove a shutdown hook

lowkey the whole personality of this page in one line, we love a clear name section 🫶

---

🎀 SYNOPSIS 🎀

void *
shutdownhook_establish(void (*fn)(void *), void *arg);

void
shutdownhook_disestablish(void *cookie);

literally the entire API, right there. two functions, no cap ✨

---

🦋 DESCRIPTION 🦋

okay so first things first, and I need you to hear me: the shutdownhook_establish API is deprecated. not me delivering bad news in the first sentence 😭 she's iconic but she's retired, periodt.

The shutdownhook_establish() function adds fn to the list of hooks invoked by doshutdownhooks(9) at shutdown. when it gets called, your hook function fn will be passed arg as its only argument. that's it, that's the whole vibe — one arg, no surprises 💖

The shutdownhook_disestablish() function removes the hook described by the opaque pointer cookie from the list of hooks to be invoked at shutdown. now, if cookie is invalid, the result of shutdownhook_disestablish() is undefined — so like, please don't do that, bestie 🙈 undefined behaviour is not the cute kind of chaos.

Shutdown hooks should be used to perform one-time activities that must happen immediately before the kernel exits. main character energy: they show up once, right at the end, and then they're gone 👑

but here's the tea — because of the environment in which they run, shutdown hooks cannot rely on many system services (including file systems, and timeouts and other interrupt-driven services), or even basic system integrity (because the system could be rebooting after a crash). so like, the whole world might be on fire and your hook still has to do its thing 💀 plan accordingly.

---

⭐ RETURN VALUES ⭐

If successful, shutdownhook_establish() returns an opaque pointer describing the newly-established shutdown hook. Otherwise, it returns NULL. that's the whole return section, we ate and left no crumbs 🍓

---

🌈 EXAMPLES 🌈

It may be appropriate to use a shutdown hook to disable a device that does direct memory access, so that the device will not try to access memory while the system is rebooting. very much "bestie please stop touching things while we're mid-reboot" energy ✨

It may be appropriate to use a shutdown hook to inform watchdog timer hardware that the operating system is no longer running. like leaving a little note that says "hey, I'm out, don't panic" 🎀

---

👑 SEE ALSO 👑

• doshutdownhooks(9)

the one and only reference, and honestly she's the whole reason we're here 🫶

---

💀 BUGS 💀

The names are clumsy, at best. fr fr, they said it themselves, and honestly? we respect the honesty 😭

---

that's the page, bestie! 💜 this one came from the Debian crew, dated May 14, 2009 — so yeah, she's been serving deprecated-but-iconic since before some of us could read, and we're still obsessed. go forth and shut down responsibly 🌸✨