VM_MAP_PROTECT(9)

💅 VM_MAP_PROTECT(9) 💅

okay so bestie, welcome to the Kernel Developer's Manual corner of the internet — this is the page for vm_map_protect, and honestly? it's giving gatekeeper-of-memory-permissions and we're obsessed 🎀

---

✨ NAME ✨

vm_map_protect — apply protection bits to a virtual memory region 🛡️

---

🌸 SYNOPSIS 🌸

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

int
vm_map_protect(vm_map_t map, vm_offset_t start, vm_offset_t end,
    vm_prot_t new_prot, vm_prot_t new_maxprot, int flags);

---

💖 DESCRIPTION 💖

so the vm_map_protect() function sets the protection bits and the maximum protection bits of the address region bounded by start and end within the map map. that's the whole vibe. it's like a glow-up but for permissions 💅

if the flags argument has the VM_MAP_PROTECT_SET_PROT bit set, then the effective protection gets set to new_prot. slay.

if the flags argument has the VM_MAP_PROTECT_SET_MAXPROT bit set, then the maximum protection gets set to new_maxprot. and heads up: protection bits not included in new_maxprot will be cleared from existing entries. it's not a maybe-clearing, it's a definitely-clearing 😭

the values specified by new_prot and new_maxprot are not allowed to include any protection bits that aren't set in the existing max_protection on every entry within the range. like, every single entry. the operation will fail if this condition is violated. the classic example: this is what prevents upgrading a shared mapping of a read-only file from read-only to read-write. read-only means read-only, no cap 🚫

and the specified range must not contain sub-maps. none. zero. don't even try it 🙈

---

🧚 IMPLEMENTATION NOTES 🧚

the function acquires a lock on the map for the duration, by calling vm_map_lock(9). locking her down, as she should be 🔒

also, any in-progress wiring operation on the map that affects the specified range will cause vm_map_protect to sleep, waiting for completion. not a nap, just a little resty until the wiring situation resolves itself 😴

---

👑 RETURN VALUES 👑

• KERN_SUCCESS — the specified protection bits were set successfully ✨
• KERN_INVALID_ARGUMENT — a sub-map entry was encountered in the range,
• KERN_PROTECTION_FAILURE — the value of new_prot or new_maxprot exceed max_protection for an entry within the range.
• KERN_PROTECTION_FAILURE — the map does not allow simultaneous setting of write and execute permissions, but new_prot has both VM_PROT_WRITE and VM_PROT_EXECUTE set.
• KERN_RESOURCE_SHORTAGE — a copy-on-write mapping is transitioned from read-only to read-write, and not enough swap space is available to back the copied pages. oof, out of room 💀
• KERN_OUT_OF_BOUNDS — both new protection and new maximum protection updates were requested, but the specified new_prot is not a subset of new_maxprot. bestie those don't nest, pick better 🫶

---

🌈 SEE ALSO 🌈

• vm_map(9)

---

⭐ AUTHORS ⭐

this manual page was written by Bruce M Simpson <bms@spc.org> — king behavior, we thank him for his service 👑

---

so yeah, that's the whole page 💜 this one came to you from Debian, dated January 23, 2021, filed under VM_MAP_PROTECT(9) — that's a wrap, bestie, go protect some memory responsibly 🦋🍓