PMEM2_BADBLOCK_CONTEXT_NEW(3)

💖 pmem2_badblock_context_new(), pmem2_badblock_context_delete() 💖

okay bestie, so this is from the PMDK Programmer's Manual and it's literally all about making and unmaking a lil context so you can go find and yeet bad blocks. two functions, one mission, let's get into it 🫶

---

✨ SYNOPSIS ✨

#include <libpmem2.h>

struct pmem2_source;
struct pmem2_badblock_context;

int pmem2_badblock_context_new(
        struct pmem2_badblock_context **bbctx,
        const struct pmem2_source *src);

void pmem2_badblock_context_delete(
        struct pmem2_badblock_context **bbctx);

---

🌸 DESCRIPTION 🌸

So pmem2_badblock_context_new() is the one that spins up a brand new (opaque, mysterious, main-character) bad block context structure called pmem2_badblock_context. what's it for? it's the lil handle you use to read and clear bad blocks, courtesy of pmem2_badblock_next() and pmem2_badblock_clear(). it hands the context back to you through the pointer at *bbctx. slay ✨

this fresh context gets initialized with values read from the source you pass in as the first argument (src). periodt.

now, what even is a bad block, bestie? a bad block is an uncorrectable media error — a chunk of storage media that's either inaccessible or unwritable because of permanent physical damage. and here's the scary part 😭: with memory-mapped I/O, if a process tries to touch (read or write) that corrupted block, it gets terminated by the SIGBUS signal. no warning, no vibe check, just gone. 💀

then there's pmem2_badblock_context_delete(), the cleanup queen. she frees the *bbctx that pmem2_badblock_context_new() gave you and sets *bbctx to NULL. and if *bbctx is already NULL? she does absolutely nothing. no operation, no drama, no notes. 💅

---

⭐ RETURN VALUE ⭐

• pmem2_badblock_context_new() — returns 0 on success, or a negative error code if it's not feeling it today 😔
• pmem2_badblock_context_new() — sets *bbctx to NULL when it fails, so you're never left holding a fake one 🫶
• pmem2_badblock_context_delete() — returns literally nothing. void. silent. iconic.

---

🔥 ERRORS 🔥

pmem2_badblock_context_new() can fail with any of these, and ngl there's a lot of them:

• PMEM2_E_INVALID_FILE_TYPE — src is not a regular file nor a character device. wrong vibe entirely 🙈
• PMEM2_E_DAX_REGION_NOT_FOUND — cannot find a DAX region for the given src. she's lost in the sauce 😭
• PMEM2_E_CANNOT_READ_BOUNDS — cannot read offset or size of the namespace of the given src. the numbers said no 💀
• PMEM2_E_NOSUPP — when the OS does not support this functionality. the operating system said "not my era" 🚫
• -ENOMEM — out of memory. brain empty, no thoughts, no RAM 😵
• -errno — set by failing ndctl_new, while trying to create a new ndctl context.
• -errno — set by failing fstat(2), while trying to validate the file descriptor of src.
• -errno — set by failing realpath(3), while trying to get the canonicalized absolute sysfs pathname of DAX device given in src.
• -errno — set by failing open(2), while trying to open the FSDAX device matching with the src.
• -errno — set by failing read(2), while trying to read from the FSDAX device matching with the src.
• -errno — set by failing ndctl_region_get_resource, while reading an offset of the region of the given src.
• -errno — set by failing fiemap ioctl(2), while reading file extents of the given src.

ok so the pattern here is: a bunch of system calls can flop and each one just hands you its own -errno. check your errno, bestie, it's telling you everything 👑

---

👑 SEE ALSO 👑

pmem2_badblock_next(3), pmem2_badblock_clear(3), libpmem2(7) and https://pmem.io

go read those next, i promise they're giving the same energy 💜

---

mwah 💋 this page is brought to you by PMDK, dated 2025-07-24 — that's the whole source/version + date situation, and yes, she ate. go clear some bad blocks, bestie, you got this 🦋✨