VM_MAP_LOOKUP(9)

💖 VM_MAP_LOOKUP 💖

okay bestie, so this one lives in section 9 of the Kernel Developer's Manual — yeah, the kernel dev corner of the man pages, we're in the big leagues now 👑

✨ NAME ✨

vm_map_lookup, vm_map_lookup_done — the little duo that goes and finds the vm_object backing a given virtual region 🦋

🌸 SYNOPSIS 🌸

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

int
vm_map_lookup(vm_map_t *var_map, vm_offset_t vaddr,
    vm_prot_t fault_type, vm_map_entry_t *out_entry,
    vm_object_t *object, vm_pindex_t *pindex, vm_prot_t *out_prot,
    boolean_t *wired);

void
vm_map_lookup_done(vm_map_t map, vm_map_entry_t entry);

like. look at that signature. it's giving "seven arguments and i know exactly what each one does" 💅

🎀 DESCRIPTION 🎀

vm_map_lookup() goes snooping for the vm_object, the page index and the protection for a given virtual address vaddr, inside the map var_map — and it does all of that as if a page fault of type fault_type had just happened. hypothetical page fault, real answers. no cap ✨

and here's the thing that makes it iconic: the return values are guaranteed until vm_map_lookup_done() gets called to release the lock. so like, don't be out here trusting those values forever, bestie, that lock is held 😭

💅 IMPLEMENTATION NOTES 💅

so vm_map_lookup() grabs a read-lock on the map *var_map… and then just. doesn't let go. 🙈 it's not a red flag, it's a handoff.

that means it's your job, caller, to invoke vm_map_lookup_done() so that lock actually gets released. main character energy: you finish what the lookup started 🫶

⭐ RETURN VALUES ⭐

vm_map_lookup() returns KERN_SUCCESS, and it sets *object, *pindex, *out_prot and *out_entry to whatever's appropriate for that imaginary page fault we were talking about. slay 🎀

🔥 SEE ALSO 🔥

• vm_map(9)

👑 AUTHORS 👑

this manual page was written by Bruce M Simpson <bms@spc.org>. thank you king, we appreciate you 💜

okay that's the whole page!! this lil writeup comes to you from Debian, dated July 19, 2003, filed under VM_MAP_LOOKUP(9) — yes it's older than most of us and it still ate 💖✨🌸🦋 no notes, periodt.