VM_MAP_STACK(9)

📦 version 15.1, in freebsd 14.5, freebsd 15.1

💖 VM_MAP_STACK(9) 💖

okay bestie, welcome to the vm_map_stack man page — that's section 9 of the Kernel Developer's Manual, iykyk, the one where we talk about how the kernel manages process stacks. this is your girl's guide, fr fr. grab a strawberry 🍓 and let's go.

✨ NAME ✨

vm_map_stack, vm_map_growstack — manage process stacks

🌸 SYNOPSIS 🌸

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

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, the vm_map_stack() function is the main character here — it maps a process stack for a brand new process image, slay. the stack gets mapped at addrbos inside map, with a maximum size of max_ssize. the copy-on-write flags you pass in cow get applied to the new mapping too, cute. and the protection bits come from prot and max. 💅

it's typically called by execve(2) — like, that's its whole moment.

meanwhile vm_map_growstack() is the one responsible for growing a stack for the process p up to the desired address addr, similar to the legacy sbrk(2) call. very "your stack but bigger" energy. 🦋

🧚 IMPLEMENTATION NOTES 🧚

  • the vm_map_stack() function calls vm_map_insert(9) to create its mappings. teamwork, honestly.
  • the vm_map_stack() and vm_map_growstack() functions acquire the process lock on p for the duration of the call. 🔒
lowkey important: that process lock stays held the whole time. no cap.

⭐ RETURN VALUES ⭐

the vm_map_stack() function returns KERN_SUCCESS if the mapping was allocated successfully. periodt. 🎉

otherwise, you get KERN_NO_SPACE back if any of these happen, and honestly there's a few:

  • if mapping the stack would exceed the process's VMEM resource limit 😭
  • or if the specified bottom-of-stack address is out of range for the map
  • or if there is already a mapping at the address which would result
  • or if 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 that one too bestie, it's giving essential lore.

the vm_map_growstack() function returns KERN_SUCCESS if addr is already mapped, or if the stack was grown successfully.

it also returns KERN_SUCCESS if addr is outside the stack range. and yeah, that sounds kinda weird, so here's why: this is done in order to preserve compatibility with the deprecated grow() function previously located in the file vm_machdep.c. legacy behavior holding on for dear life, we respect it. 💀

🔥 SEE ALSO 🔥

💜 AUTHORS 💜

this manual page was written by Bruce M Simpson <bms@spc.org>. legend behavior, honestly. 🫶

and that's the whole vibe check, bestie — this page came from Debian, dated January 11, 2013. old money. iconic. no notes. 🌈💖

📦 where this page comes from