PMEM2_VM_RESERVATION_DELETE(3)

💖 pmem2_vm_reservation_new(), pmem2_vm_reservation_delete() 💖

okay bestie, sit down, hydrate, because we're talking about the PMDK Programmer's Manual today and this one is a whole mood. it's pmem2_vm_reservation_new() and pmem2_vm_reservation_delete() — the create-or-delete duo for an instance of virtual memory reservation. yes they're two functions in one manpage. they're a package deal. iconic behavior honestly. 👑

---

✨ NAME ✨

pmem2_vm_reservation_new(), pmem2_vm_reservation_delete() — creates or deletes an instance of virtual memory reservation

---

🌸 SYNOPSIS 🌸

#include <libpmem2.h>

struct pmem2_vm_reservation;
int pmem2_vm_reservation_new(struct pmem2_vm_reservation **rsv_ptr,
        void *addr, size_t size);
int pmem2_vm_reservation_delete(struct pmem2_vm_reservation **rsv_ptr);

like. look at that. two little ints and a struct. adorable. 🎀

---

🦋 DESCRIPTION 🦋

so pmem2_vm_reservation_new() creates a brand new blank mapping in the virtual address space of the calling process. it's giving... empty canvas energy. the reservation is basically a placeholder of a given size, and it's the spot where sources can be mapped later. main character of the address space fr fr. ✨

for the function to actually succeed (vibe check passed, no cap):

• addr must be either aligned to an appropriate allocation granularity or NULL
• size always has to be aligned to an appropriate OS allocation granularity

like, always always. not negotiable. 💅

the libpmem2(7) library picks the largest page alignment for the reservation based on size. and here's the tea: if that chosen alignment is different from the OS allocation granularity, then the underlying size of the reservation can be bigger than the value presented to the user. surprise! 🫶

lowkey important: the largest page alignment functionality is limited to POSIX systems. if you're not on POSIX, that part is not your moment. 🙈

if pmem2_vm_reservation_new() succeeds in creating a reservation, it instantiates a new struct pmem2_vm_reservation object describing the reservation. the pointer to this object gets stored in the user-provided variable via the rsv_ptr pointer. you handed it the pointer, it filled the pointer. teamwork. 🤝

if the function fails, an appropriate error value will be returned. for a list of possible return values please see RETURN VALUE. (spoiler: it's below. keep scrolling bestie.) 😭

after you instantiate an object via the pmem2_vm_reservation_new() function, it may be disposed of using the pmem2_vm_reservation_delete() function. new then delete. the circle of life. 🌈

now pmem2_vm_reservation_delete() destroys the object describing the reservation and unmaps the virtual memory region the *struct pmem2_vm_reservation** had assigned during the initialization. so it's not just deleting the vibe, it's cleaning up the actual memory region. she does it all. 💅

⚠️ for the delete function to succeed, it is required that the reservation passed via the rsv_ptr pointer does not contain any mappings. empty reservation only. if there's stuff still mapped in there, she will not be deleting it, periodt.

---

💜 RETURN VALUE 💜

the pmem2_vm_reservation_new() and pmem2_vm_reservation_delete() functions return 0 on success or a negative error code on failure.

the function returns 0 on success or a negative error code on failure.

(yes, both of those lines are in here. i don't make the rules, i just relay them faithfully. 🍓)

---

🔥 ERRORS 🔥

the pmem2_vm_reservation_new() function can fail with the following errors:

• PMEM2_E_ADDRESS_UNALIGNED — argument addr is not aligned to the appropriate allocation granularity. she's crooked, she's declined. 😭
• PMEM2_E_MAPPING_EXISTS — mapping already exists in the range (addr, addr + size). occupied! no vacancy! 💀

it can also return -EAGAIN, -ENOMEM from the underlying mmap(2) function and -ENOMEM in case of insufficient memory to allocate an instance of struct pmem2_vm_reservation.

the pmem2_vm_reservation_delete() function can fail with the following errors:

• PMEM2_E_RESERVATION_NOT_EMPTY — reservation contains mappings. told you. she checked. the mappings are still there. she's not touching it. 🙈

it can also return errors from the underlying munmap(2) function.

---

🌟 SEE ALSO 🌟

• pmem2_config_set_vm_reservation(3)
• libpmem2(7)
• https://pmem.io

---

and that's the whole page bestie, you ate it, you understood it, you're basically a pmem2 reservation girlie now. 👑

PMDK — 2025-07-24 🎀 that's the source, the version and the date, mwah, go forth and reserve responsibly 💖✨🦋