LIBPMEM2_UNSAFE_SHUTDOWN(7)

✨ NAME ✨

libpmem2_unsafe_shutdown — the libpmem2 tea on unsafe shutdown 💅

So bestie, this page is straight out of the PMDK Programmer's Manual, and it's here to spill everything about unsafe shutdowns. Buckle up. 🎀

---

🌸 DESCRIPTION 🌸

Okay so picture this: on systems with persistent memory support, there's this thing called a power-fail protected domain</> — it's basically a lil squad of resources, and if the power just dies, the platform is gonna flush that data to the persistent medium. And data sitting on the persistent medium? It survives power cycles. It's giving main character energy, fr fr. 👑

The hardware pinky-promises to flush everything in the power-fail protected domain over to the persistent medium. But nothing is infallible bestie, and Persistent Memory hardware can expose a monotonically increasing unsafe shutdown counter (that's USC for short, iykyk) — and it goes up by one every single time a failure of that whole mechanism gets detected. Which means software can actually find out when a running app got interrupted by a power failure that led to an unsafe shutdown. And why do we care? Because undiscovered unsafe shutdowns might cause silent data corruption. Not the vibe. 😭

Note: an unsafe shutdown can corrupt data stored on a device, in a file, in a set of files, and even a mapping that only spans part of a file. For simplicity's sake, all of those cases get called file down below. Periodt.

---

💖 UNSAFE SHUTDOWN DETECTION 💖

So how does software clock an unsafe shutdown? By watching for any change between the unsafe shutdown count value across application startups. Any change at all can be a lil hint that an unsafe shutdown happened. 🕵️‍♀️

Apps can build a whole detection mechanism by storing the USC they pulled from pmem2_source_device_usc(3) into Persistent Memory. Then, on the next startups, that stored value has to get compared against a freshly retrieved one. Slay.

But — and this is the plot twist — that detection method can result in false-positives. If you move the file over to different Persistent Memory devices that might have different USC values, boom, you get a fake unsafe shutdown detection. Rude. 🙈

Also, relying on the USC value alone could make you detect unsafe shutdown events that literally had no chance of impacting the data your app uses — like, say, when nothing is actively using the file. Irrelevant queen.

Apps can dodge the false-positives that come with moving the file by storing device identification (grabbed via pmem2_source_device_id(3)) right alongside the USC. That way the software can check whether the underlying device changed, and reinitialize the stored USC whenever it did. 💅

And that second behavior — detecting possibly irrelevant unsafe shutdown events — if you don't want it, you can prevent it by storing a flag saying whether the file is in use, alongside all the rest of the relevant info.

The application should use pmem2_deep_flush(3) when it's storing any data related to unsafe shutdown detection, for higher reliability. Why? Because that helps make sure the detection mechanism isn't reliant on the correct functioning of the very same hardware features it's supposed to be safeguarding. Iconic circular-dependency avoidance. ✨

General-purpose software should not assume the USC is present on the platform, and should instead appropriately handle any PMEM2_E_NOSUPP it runs into. Do otherwise and you might make your software unnecessarily restrictive about the hardware it supports, and you'd prevent stuff like testing on emulated PMEM. Don't be that girl. 🫶

---

🌈 SEE ALSO 🌈

• pmem2_deep_flush(3)
• pmem2_persist_fn(3)
• pmem2_source_device_id(3)
• pmem2_source_device_usc(3)
• https://pmem.io

---

Okay bestie that's the whole page, no cap. This came to you from the PMDK crew, dated 2025-07-24 — go forth and never let a silent data corruption catch you slipping. 💖✨🎀🦋