PMEM2_VM_RESERVATION_SHRINK(3)

💖 pmem2_vm_reservation_extend(3), pmem2_vm_reservation_shrink(3) 💖

okay so bestie, we're in the PMDK Programmer's Manual today and we are talking about growing and shrinking your virtual memory reservation. no cap, this is the glow-up and the downsize of the reservation world 🦋

---

✨ NAME ✨

pmem2_vm_reservation_extend(), pmem2_vm_reservation_shrink() — the two functions that extend and shrink an existing virtual memory reservation. it's giving personal trainer for memory. 💪

---

🌸 SYNOPSIS 🌸

#include <libpmem2.h>

struct pmem2_vm_reservation;
int pmem2_vm_reservation_extend(struct pmem2_vm_reservation *rsv, size_t size);
int pmem2_vm_reservation_shrink(struct pmem2_vm_reservation *rsv, size_t offset,
        size_t size);

---

🎀 DESCRIPTION 🎀

so, pmem2_vm_reservation_extend() takes an existing virtual memory reservation and extends it by the given size. for this to actually work, size has to be aligned to an appropriate allocation granularity — the universe (and the allocator) does not accept unaligned chaos, periodt. ✨

if pmem2_vm_reservation_extend() succeeds in extending a reservation, it hands you a placeholder virtual memory range that starts from an address at the end of the old reservation. and the best part? mappings made to the reservation before extending are preserved. nothing lost, everything gained, we love to see it 🫶

then we have pmem2_vm_reservation_shrink(), which shrinks the reservation by a region specified by offset into the reservation and the size. for this one to succeed, both the size and offset variables have to be aligned to an appropriate allocation granularity. also the region formed by offset and size has to belong to the reservation, has to be empty, and it needs to cover the beginning or the end of the reservation. and listen — shrinking a reservation from the middle? not supported. shrinking the whole reservation? also not supported. it's giving "no, you can't just delete the middle of the sandwich" 🥪💀

if pmem2_vm_reservation_shrink() succeeds in shrinking a reservation, it releases the placeholder virtual memory range that was designated by the offset and size variables. mappings made to the reservation before shrinking are preserved. iconic. 👑

and if either of those functions fails, the reservation will be left as it was and an appropriate error value will be returned. no half-done mess, no drama, the reservation stays exactly how it woke up. 🙈

---

⭐ RETURN VALUE ⭐

both pmem2_vm_reservation_extend() and pmem2_vm_reservation_shrink() return 0 on success, or a negative error code on failure. simple as that, fr fr.

---

🔥 ERRORS 🔥

💅 pmem2_vm_reservation_extend() can fail with:

• PMEM2_E_MAPPING_EXISTS — the range that the reservation would be extended by is already occupied by an existing mapping. someone else is literally already sitting there. 😭

it can also return -EAGAIN, -ENOMEM from the underlying mmap(2) function.

💅 pmem2_vm_reservation_shrink() can fail with:

• PMEM2_E_OFFSET_UNALIGNED — the provided offset isn't aligned to an appropriate allocation granularity. alignment vibes check: failed. 💀
• PMEM2_E_LENGTH_UNALIGNED — the provided size isn't aligned to an appropriate allocation granularity. same energy, different variable. 🫠
• PMEM2_E_OFFSET_OUT_OF_RANGE — the provided offset is out of the reservation range available to be shrunk.
• PMEM2_E_LENGTH_OUT_OF_RANGE — the provided size is out of the reservation range available to be shrunk.
• PMEM2_E_NOSUPP — the interval designated by the offset and size variables covers only the middle or the whole reservation range. (see above: no middle-shrinking, no whole-shrinking, we said what we said 🚫)
• PMEM2_VM_RESERVATION_NOT_EMPTY — the interval designated by the offset and size variable is not empty.

it can also return -EAGAIN and -ENOMEM from the underlying munmap(2) function.

lowkey important: those -EAGAIN and -ENOMEM ones aren't this library's own errors, they come straight from the underlying syscalls, iykyk.

---

🌈 SEE ALSO 🌈

• pmem2_vm_reservation_new(3)
• pmem2_config_set_vm_reservation(3)
• libpmem2(7)
• <https://pmem.io> — no wait, just: https://pmem.io ✨

---

and that's the whole page bestie, you ate it up 💖

this little love letter comes from the PMDK Programmer's Manual, dated 2025-07-24 — mwah, go extend something responsibly. 💅🎀🦋