1.\" 2.\" Copyright (c) 2003 Bruce M Simpson <bms@spc.org> 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.Dd January 11, 2013 27.Dt VM_MAP_STACK 9 28.Os 29.Sh NAME 30.Nm vm_map_stack , 31.Nm vm_map_growstack 32.Nd manage process stacks 33.Sh SYNOPSIS 34.In sys/param.h 35.In vm/vm.h 36.In vm/vm_map.h 37.Ft int 38.Fo vm_map_stack 39.Fa "vm_map_t map" "vm_offset_t addrbos" "vm_size_t max_ssize" "vm_prot_t prot" 40.Fa "vm_prot_t max" "int cow" 41.Fc 42.Ft int 43.Fn vm_map_growstack "struct proc *p" "vm_offset_t addr" 44.Sh DESCRIPTION 45The 46.Fn vm_map_stack 47function maps a process stack for a new process image. 48The stack is mapped 49.Fa addrbos 50in 51.Fa map , 52with a maximum size of 53.Fa max_ssize . 54Copy-on-write flags passed in 55.Fa cow 56are also applied to the new mapping. 57Protection bits are supplied by 58.Fa prot 59and 60.Fa max . 61.Pp 62It is typically called by 63.Xr execve 2 . 64.Pp 65The 66.Fn vm_map_growstack 67function is responsible for growing a stack for the process 68.Fa p 69to the desired address 70.Fa addr , 71similar to the legacy 72.Xr sbrk 2 73call. 74.Sh IMPLEMENTATION NOTES 75The 76.Fn vm_map_stack 77function calls 78.Xr vm_map_insert 9 79to create its mappings. 80.Pp 81The 82.Fn vm_map_stack 83and 84.Fn vm_map_growstack 85functions acquire the process lock on 86.Fa p 87for the duration of the call. 88.Sh RETURN VALUES 89The 90.Fn vm_map_stack 91function returns 92.Dv KERN_SUCCESS 93if the mapping was allocated successfully. 94.Pp 95Otherwise, 96if mapping the stack would exceed the process's VMEM resource limit, 97or if the specified bottom-of-stack address is out of range for the map, 98or if there is already a mapping at the address which would result, 99or if 100.Fa max_ssize 101could not be accommodated within the current mapping, 102.Dv KERN_NO_SPACE 103is returned. 104.Pp 105Other possible return values for this function are documented in 106.Xr vm_map_insert 9 . 107.Pp 108The 109.Fn vm_map_growstack 110function returns 111.Dv KERN_SUCCESS 112if 113.Fa addr 114is already mapped, or if the stack was grown successfully. 115.Pp 116It also returns 117.Dv KERN_SUCCESS 118if 119.Fa addr 120is outside the stack range; this is done in order to preserve 121compatibility with the deprecated 122.Fn grow 123function previously located in the file 124.Pa vm_machdep.c . 125.Sh SEE ALSO 126.Xr vm_map 9 , 127.Xr vm_map_insert 9 128.Sh AUTHORS 129This manual page was written by 130.An Bruce M Simpson Aq Mt bms@spc.org . 131