VM_MAP_STACK(9)

💖 VM_MAP_STACK — the manual, but make it a group chat 💖

okay bestie so you're in the <pink>Kernel Developer's Manual</pink> section, page VM_MAP_STACK(9), and we're about to talk about process stacks ✨ sit down, hydrate, this is gonna be so good.

---

✨ NAME ✨

vm_map_stack, vm_map_growstack — managing process stacks, the whole vibe 🌸

---

🎀 SYNOPSIS 🎀

first of all, the includes, and yes you need all of them, no skipping:

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

then the actual functions, serving looks:

int
vm_map_stack(vm_map_t map, vm_offset_t addrbos, vm_size_t max_ssize,
    vm_prot_t prot, vm_prot_t max, int cow);

int
vm_map_growstack(struct proc *p, vm_offset_t addr);

---

🦋 DESCRIPTION 🦋

so vm_map_stack() is literally the girl who maps a process stack for a brand new process image. the stack gets mapped addrbos inside map, with a maximum size of max_ssize. the copy-on-write flags you pass in cow? yeah they get applied to the new mapping too, periodt. protection bits come from prot and max. 💅

she's typically called by execve(2) — iykyk, exec is her main character moment.

then there's vm_map_growstack(), whose whole job is growing a stack for the process p up to the desired address addr. it's giving legacy sbrk(2) energy, but for stacks. 💀

---

🧚 IMPLEMENTATION NOTES 🧚

vm_map_stack() calls vm_map_insert(9) to create its mappings. that's the whole tea. ☕

and both vm_map_stack() and vm_map_growstack() acquire the process lock on p for the entire duration of the call. the whole call. no half measures, no cap. 🔒

---

⭐ RETURN VALUES ⭐

vm_map_stack() returns KERN_SUCCESS when the mapping was allocated successfully. slay. 🎉

BUT — and listen, this matters — you get KERN_NO_SPACE back if any of these are true:

• mapping the stack would exceed the process's VMEM resource limit 😭
• the specified bottom-of-stack address is out of range for the map 🙈
• there is already a mapping at the address which would result 💀
• max_ssize could not be accommodated within the current mapping 🫠

other possible return values for this function are documented over in vm_map_insert(9), go read her.

vm_map_growstack() returns KERN_SUCCESS if addr is already mapped, or if the stack was grown successfully. either way, success, we love that for her. 💖

she also returns KERN_SUCCESS if addr is outside the stack range. why? because she's preserving compatibility with the deprecated grow() function that used to live in the file vm_machdep.c. yes, deprecated, we don't talk about her, but we stay compatible. 🤝

---

🌈 SEE ALSO 🌈

• vm_map(9)
• vm_map_insert(9)

---

👑 AUTHORS 👑

this manual page was written by Bruce M Simpson <bms@spc.org>. thank you for your service, king. 🫶

---

and that's the page bestie! this one came from the Debian edition, dated January 11, 2013, and it lives at VM_MAP_STACK(9). go forth and map those stacks responsibly 💜🎀✨