PMEM2_MAP_NEW(3)

✨ pmem2_map_new(3) ✨ — the PMDK Programmer's Manual's cutest little mapping maker 💖

okay bestie, sit down, hydrate, because we're about to make a mapping in your virtual address space and it's genuinely giving main character energy 🫶

---

🌸 NAME 🌸

pmem2_map_new() — creates a mapping ✨

---

🎀 SYNOPSIS 🎀

#include <libpmem2.h>

struct pmem2_config;
struct pmem2_source;
struct pmem2_map;
int pmem2_map_new(struct pmem2_map **map_ptr, const struct pmem2_config *config,
        const struct pmem2_source *source);

---

💅 DESCRIPTION 💅

So the pmem2_map_new() function creates a brand new mapping in the virtual address space of the calling process. iconic behavior fr fr. to pull this off it needs two things: a configuration config of the mapping, and the data source source. that's the duo. the it-girl and her bestie 💖

Optionally, the mapping can be created at the offset of the virtual memory reservation set in the configuration config. see pmem2_config_set_vm_reservation(3) for details 👑

For a mapping to succeed, the config structure must have the granularity parameter set to the appropriate level. no granularity, no mapping, periodt. see pmem2_config_set_required_store_granularity(3) and libpmem2(7) for more details 🌈

If pmem2_map_new() succeeds in creating a new mapping, it instantiates a new *struct pmem2_map* object describing the mapping. the pointer to this freshly created object gets stored in the user-provided variable you passed via the map_ptr pointer. slay ✨ If the mapping fails, the variable pointed by map_ptr will contain a NULL value and an appropriate error value will be returned. for a list of possible return values please see RETURN VALUE 💀

⚠️ every single struct pmem2_map object created via pmem2_map_new() has to be destroyed using the pmem2_map_delete() function. like, it's not optional, it's a lifestyle. for details please see pmem2_map_delete(3). don't leave your mappings orphaned bestie 😭

---

💜 RETURN VALUE 💜

pmem2_map_new() returns 0 on success or a negative error code on failure. that's it, that's the vibe check 🎀

---

🔥 ERRORS 🔥

pmem2_map_new() can fail with the following errors:

• PMEM2_E_GRANULARITY_NOT_SET — the store granularity for the mapping was not set in the provided config structure. please see pmem2_config_set_required_store_granularity(3) and libpmem2(7). you forgot the granularity bestie, we've all been there 🙈
• PMEM2_E_MAP_RANGE — offset + length is too big to represent it using size_t data type. too much. unhinged amounts of range 😭
• PMEM2_E_MAP_RANGE — end of the mapping (offset + length) is outside of the file. the file is too small. tiny file, big dreams 💀
• PMEM2_E_SOURCE_EMPTY — mapped file has size equal to 0. nothing there. empty. ghosted 🫥
• PMEM2_E_MAPPING_EXISTS — if the object exists before the function call. it was already there, no cap 👀
• PMEM2_E_OFFSET_UNALIGNED — argument unaligned, offset is not a multiple of the alignment required for specific *source. please see pmem2_source_alignment(3) ✨
• PMEM2_E_LENGTH_UNALIGNED — argument unaligned, length is not a multiple of the alignment required for specific *source. please see pmem2_source_alignment(3) ✨
• PMEM2_E_SRC_DEVDAX_PRIVATE — device DAX mapped with MAP_PRIVATE. nope, not doing that 💅
• PMEM2_E_ADDRESS_UNALIGNED — when mapping device DAX to a virtual memory reservation and the base mapping address (reservation address + reservation offset) is not aligned to the device DAX granularity. please see pmem2_config_set_vm_reservation(3) 🎀
• PMEM2_E_ADDRESS_UNALIGNED — when mapping to a virtual memory reservation and the region for the mapping exceeds reservation size. please see pmem2_config_set_vm_reservation(3) 🎀
• PMEM2_E_NOSUPP — when config-provided protection flags combination is not supported. that combo? not on the menu 🚫
• PMEM2_E_NO_ACCESS — there is a conflict between mapping protection and file opening mode. they're beefing 😤

It can also return -EACCES, -EAGAIN, -EBADF, -ENFILE, -ENODEV, -ENOMEM, -EPERM, -ETXTBSY from the underlying mmap(2) function. It is used with and without MAP_ANONYMOUS 🌈

-EACCES may be returned only if the file descriptor points to an append-only file 👑

It can also return all errors from the underlying pmem2_source_size() and pmem2_source_alignment() functions.

---

🦋 SEE ALSO 🦋

mmap(2), open(3), pmem2_config_set_required_store_granularity(3), pmem2_source_alignment(3), pmem2_source_from_fd(3), pmem2_source_size(3), pmem2_map_delete(3), pmem2_config_set_vm_reservation(3), libpmem2(7) and <https://pmem.io> 💖

---

okay that's the whole page bestie, you ate that 🫶 this was the PMDK Programmer's Manual, PMDK - version, dated 2025-07-24 — go forth and map responsibly, and remember: delete your mappings, hydrate, and stan libpmem2 💅✨🎀