PMEM2_SOURCE_PREAD_MCSAFE(3)

💖 pmem2_source_pread_mcsafe(3) — pmem2_source_pwrite_mcsafe(3) 💖

okay bestie, welcome to the PMDK Programmer's Manual ✨ you're literally about to learn how to read from and write to a source without your whole program getting bodied by a bad block. two functions, one vibe: safe I/O. let's get into it 🫶

---

🌸 NAME 🌸

pmem2_source_pread_mcsafe(), pmem2_source_pwrite_mcsafe() — read source contents or write to the source in a safe manner 💅

no cap, "in a safe manner" is doing a LOT of heavy lifting in that sentence and we're about to find out why.

---

✨ SYNOPSIS ✨

#include <libpmem2.h>

struct pmem2_source;
int pmem2_source_pread_mcsafe(struct pmem2_source *src, void *buf, size_t size,
        size_t offset);
int pmem2_source_pwrite_mcsafe(struct pmem2_source *src, void *buf, size_t size,
        size_t offset);

---

🦋 DESCRIPTION 🦋

okay so here's the tea ☕

pmem2_source_pread_mcsafe() reads size bytes from the source src, starting at offset offset, and dumps them into the buffer buf. iconic behavior. 🌈

pmem2_source_pwrite_mcsafe() goes the other direction — it writes size bytes from the buffer buf into the source src, starting at the offset offset. queen shit. 👑

now the mcsafe part, which is the whole point, and honestly? it's giving guardian angel 🧚

Both of these functions are capable of detecting bad blocks and handling the SIGBUS signal that gets thrown when you try to access a bad block. so instead of your process just getting merked by a signal, when a bad block is encountered, pmem2_source_pread_mcsafe() and pmem2_source_pwrite_mcsafe() return a corresponding error. much more chill. much more demure. 😌

how does it do that? a signal handler for the SIGBUS signal is registered using sigaction(2) for the running time of those operations. so it's like a little bodyguard that clocks in when the call starts and clocks out when it's done. 💪

⚠️ heads up bestie: this capability is limited to POSIX systems. if you're not on POSIX, this whole mcsafe moment is not happening for you. sorry. 🙈

if you wanna go deeper on bad block detection and clearing, go look at pmem2_badblock_context_new(3), pmem2_badblock_next(3) and pmem2_badblock_clear(3). the whole badblock squad. 🎀

---

💜 RETURN VALUE 💜

Both pmem2_source_pread_mcsafe() and pmem2_source_pwrite_mcsafe() return 0 on success, or a negative error code on failure. that's it. that's the whole contract. simple. clean. periodt. 💅

---

🔥 ERRORS 🔥

pmem2_source_pread_mcsafe() and pmem2_source_pwrite_mcsafe() can fail with the following errors:

• PMEM2_E_IO_FAIL — a physical I/O error occurred during the read/write operation. a possible bad block encountered. 💀 yeah, this is the one you were scared of.
• PMEM2_E_LENGTH_OUT_OF_RANGE — read/write operation size size from offset offset goes beyond the file length. you asked for bytes that simply do not exist, bestie. 😭
• PMEM2_E_SOURCE_TYPE_NOT_SUPPORTED — read/write operation doesn't support provided source. only sources created with pmem2_source_from_fd(3) is supported. so like… if your source came from anywhere else? no. not today. 🚫

and also — those operations can return all errors from the underlying pread(2), pwrite(2), sigaction(2) functions. so if you're debugging and the error code is confusing, check those manpages too. the plot thickens. 🕵️

---

🌈 SEE ALSO 🌈

pread(2), pwrite(2), ReadFile(), WriteFile(), pmem2_badblock_clear(3), pmem2_badblock_context_new(3), pmem2_badblock_next(3), pmem2_source_from_fd(3), libpmem2(7) and https://pmem.io 🫶

---

and that's the whole page, bestie!! you ate that. go forth and do safe I/O. 💖

this page is from PMDK (the PMDK Programmer's Manual, dated 2025-07-24). love that for us. mwah. 🎀💅✨