PMEM2_MAP_FROM_EXISTING(3)

💖 pmem2_map_from_existing 💖

okay bestie, welcome to the PMDK Programmer's Manual 🌸 — this one's about pmem2_map_from_existing(), and fr fr it's the glow-up your existing mapping deserves ✨

---

🌈 NAME 🌈

pmem2_map_from_existing() — creates a pmem2_map object from an existing mapping 💅

---

🎀 SYNOPSIS 🎀

#include <libpmem2.h>

int pmem2_map_from_existing(struct pmem2_map **map, const struct pmem2_source *src,
    void *addr, size_t len, enum pmem2_granularity gran);

---

✨ DESCRIPTION ✨

so basically, pmem2_map_from_existing() hands you back a brand new *struct pmem2_map for a mapping you already brought to the party 🫶 like, the user provides the mapping, and this function is the one that wraps it up cute.

the whole point? it lets you use the libpmem2(7) API without having to call pmem2_map_new(3) to map a file. no cap. 🙈

your mapping is defined by addr and len — those two are the vibe check for what region we're talking about. you also have to specify the underlying file as src, and you gotta define the granularity of this mapping with gran. lowkey important.

for the deets on granularity, go peek at pmem2_config_set_required_store_granularity(3) and libpmem2(7) — they spill the tea ☕

⚠️ real talk, don't skip this one: for a pmem2_map object created by the pmem2_map_from_existing(3) function, pmem2_map_delete(3) will only destroy the object — it will not unmap the mapping this object describes. it's giving "I'll clean my room" but only the object part. 💀 the mapping itself stays mapped, bestie.

---

🔥 RETURN VALUE 🔥

pmem2_map_from_existing() returns 0 when it succeeds 🎉 or a negative error code on failure 😭

---

💜 ERRORS 💜

pmem2_map_from_existing() can fail with the following errors:

• PMEM2_E_MAPPING_EXISTS — when the contiguous region (addr, addr + len) is already registered by libpmem2 🙅♀️ like, girl, that spot is taken.

it can also return -ENOMEM from the underlying malloc(2) function 🍓

---

👑 SEE ALSO 👑

malloc(2), pmem2_map_delete(3), pmem2_map_new(3), pmem2_source_from_fd(3), libpmem2(7) and https://pmem.io 🌈

---

okay that's the whole page, bestie, you ate that 🎀 this was the PMDK era, dated 2025-07-24 — go forth and map responsibly, mwah 💖🦋