VM_MAP_WIRE(9)

💜 vm_map_wire — bestie's guide to pinning pages down (kernel developer's manual, section 9)

okay so real talk, this page is vm_map_wire and vm_map_unwire — the two functions that manage page wiring inside a virtual memory map. it's giving "i'm gonna make sure these pages cannot leave" energy and honestly? iconic. ✨

---

🌸 NAME 🌸

vm_map_wire, vm_map_unwire — manage page wiring within a virtual memory map 🫶

---

🎀 SYNOPSIS 🎀

like always, you gotta bring the right headers to the party first, no cap:

#include <sys/param.h>
#include <vm/vm.h>
#include <vm/vm_map.h>

then the functions themselves, here's the whole fit:

int
vm_map_wire(vm_map_t map, vm_offset_t start, vm_offset_t end,
    int flags);

int
vm_map_unwire(vm_map_t map, vm_offset_t start, vm_offset_t end,
    int flags);

---

🦋 DESCRIPTION 🦋

so vm_map_wire() is the main character here 💅 — its whole job is wiring up the pages in the range between start and end inside the map map. and what does "wired" even mean? it means those pages are locked into physical memory, and they may not be paged out as long as their wire count stays above zero. periodt. 🔒

then vm_map_unwire() does the corresponding unwire operation — the reverse vibe, the undoing, the "okay you can breathe now" moment. 🧚

the flags argument is a bit mask, made of these flags right here:

• if the VM_MAP_WIRE_USER flag is set, the function operates within user address space 👑
• if the VM_MAP_WIRE_HOLESOK flag is set, it may operate upon an arbitrary range within the address space of map 🕳️✨
• if you actually want a contiguous range, you should explicitly express your intent by specifying the VM_MAP_WIRE_NOHOLES flag — say it with your chest, bestie 📣

---

🌈 IMPLEMENTATION NOTES 🌈

both functions are gonna try to grab a lock on the map using vm_map_lock(9), and they hold onto it for the whole duration of the call. like, the entire time. 🫰

and if they detect MAP_ENTRY_IN_TRANSITION, they'll call vm_map_unlock_and_wait(9) until the map becomes available again — just politely waiting in the group chat until it's their turn 😭

⚠️ important vibe check: the map could have changed during that window, because somebody else was holding it. so if you're consuming this interface, you should be checking for that condition using the return values down below. don't skip this, fr fr 💀

---

⭐ RETURN VALUES ⭐

vm_map_wire() and vm_map_unwire() have identical return values — twins, matching outfits, the whole thing 👯

• KERN_SUCCESS — returned if all the pages within the range were [un]wired successfully 🎉 slay
• KERN_INVALID_ADDRESS — returned otherwise: if the specified range was not valid, or if the map changed while the MAP_ENTRY_IN_TRANSITION flag was set 🚩

---

🔥 SEE ALSO 🔥

• mlockall(2)
• munlockall(2)
• vm_map(9)

go read those too, iykyk 📚

---

💖 AUTHORS 💖

this manual page was written by Bruce M Simpson <bms@spc.org> — ty for your service king 🫡👑

---

and that's the whole page bestie, no notes 💅

sign-off szn: this one came from Debian, dated July 19, 2003 — a whole vintage moment, honestly kinda nostalgic 🎀✨ mwah, go wire some pages responsibly 🦋💜