PMEM2_VM_RESERVATION_MAP_FIND_FIRST(3)

💖 PMEM2_VM_RESERVATION_MAP_FIND(3) 💖

okay bestie, sit down, hydrate, and let me tell you about the cutest lil squad of functions in the PMDK Programmer's Manual, section 3. their whole job? finding mappings in a virtual memory reservation. searching for the mapping located at the desirable location, if you will. and honestly? they ate. 🫶

---

✨ NAME ✨

pmem2_vm_reservation_map_find(), pmem2_vm_reservation_map_find_prev(), pmem2_vm_reservation_map_find_next(), pmem2_vm_reservation_map_find_first() and pmem2_vm_reservation_map_find_last() — search for the mapping located at the desirable location 🔍

---

🌸 SYNOPSIS 🌸

#include <libpmem2.h>

struct pmem2_map;
struct pmem2_vm_reservation;
int pmem2_vm_reservation_map_find(struct pmem2_vm_reservation *rsv,
        size_t reserv_offset, size_t len, struct pmem2_map **map_ptr);
int pmem2_vm_reservation_map_find_prev(struct pmem2_vm_reservation *rsv,
        struct pmem2_map *map, struct pmem2_map **prev_map);
int pmem2_vm_reservation_map_find_next(struct pmem2_vm_reservation *rsv,
        struct pmem2_map *map, struct pmem2_map **next_map);
int pmem2_vm_reservation_map_find_first(struct pmem2_vm_reservation *rsv,
        struct pmem2_map **first_map);
int pmem2_vm_reservation_map_find_last(struct pmem2_vm_reservation *rsv,
        struct pmem2_map **last_map);

like, five whole functions. a whole friend group. no cap. 💅

---

🦋 DESCRIPTION 🦋

so here's the lore, bestie. mappings get inserted into the virtual memory reservation in the order of their virtual address space location. the first mapping is the earliest mapping in the virtual address space contained in a reservation, and the last mapping is, well, the last one. main character energy for the earliest one, honestly. ✨

• pmem2_vm_reservation_map_find() — searches for the earliest mapping stored in the virtual memory reservation that intersects with the interval defined by the reserv_offset and len variables, and hands it back to you through the map_ptr variable. 🎀
• pmem2_vm_reservation_map_find_prev() — searches for the map previous to the provided map, and returns it via the provided prev_map variable. ⬅️
• pmem2_vm_reservation_map_find_next() — searches for the map next after the provided map, and returns it via the next_map variable. ➡️
• pmem2_vm_reservation_map_find_first() — searches for the first map in the reservation, and returns it via the provided first_map variable. 👑
• pmem2_vm_reservation_map_find_last() — searches for the last map in the reservation, and returns it via the provided last_map variable. 🏁

---

🎀 RETURN VALUE 🎀

pmem2_vm_reservation_map_find(), pmem2_vm_reservation_map_find_prev(), pmem2_vm_reservation_map_find_next(), pmem2_vm_reservation_map_find_first() and pmem2_vm_reservation_map_find_last() return 0 on success, or a negative error on failure.

on success it passes an address to the found mapping via the user provided map pointer variable. otherwise, when no mapping was found, it passes a NULL value. it's giving "found nothing, bestie" 😭

---

💀 ERRORS 💀

the whole squad — pmem2_vm_reservation_map_find(), pmem2_vm_reservation_map_find_prev(), pmem2_vm_reservation_map_find_next(), pmem2_vm_reservation_map_find_first() and pmem2_vm_reservation_map_find_last() — can fail with the following errors:

• PMEM2_E_MAPPING_NOT_FOUND — no mapping found at the desirable location of the reservation 🙈

---

🌈 SEE ALSO 🌈

• libpmem2(7)
• and https://pmem.io

---

reminder bestie: mappings live in address-space order inside the reservation, so "first" = earliest and "last" = latest. don't come for me, that's literally what the page says. 🧚

---

and that's the tea, fr fr. this iconic little page came to you from the PMDK crew, dated 2025-07-24, and it is now officially over. go find your mappings, bestie. slay. 💖✨🎀🦋🌸💅🫶🔥👑⭐