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.\" $FreeBSD$ 27.\" 28.Dd July 19, 2003 29.Dt VM_MAP_STACK 9 30.Os 31.Sh NAME 32.Nm vm_map_stack , 33.Nm vm_map_growstack 34.Nd manage process stacks 35.Sh SYNOPSIS 36.In sys/param.h 37.In vm/vm.h 38.In vm/vm_map.h 39.Ft int 40.Fo vm_map_stack 41.Fa "vm_map_t map" "vm_offset_t addrbos" "vm_size_t max_ssize" "vm_prot_t prot" 42.Fa "vm_prot_t max" "int cow" 43.Fc 44.Ft int 45.Fn vm_map_growstack "struct proc *p" "vm_offset_t addr" 46.Sh DESCRIPTION 47The 48.Fn vm_map_stack 49function maps a process stack for a new process image. 50The stack is mapped 51.Fa addrbos 52in 53.Fa map , 54with a maximum size of 55.Fa max_ssize . 56Copy-on-write flags passed in 57.Fa cow 58are also applied to the new mapping. 59Protection bits are supplied by 60.Fa prot 61and 62.Fa max . 63.Pp 64It is typically called by 65.Xr execve 2 . 66.Pp 67The 68.Fn vm_map_growstack 69function is responsible for growing a stack for the process 70.Fa p 71to the desired address 72.Fa addr , 73similar to the legacy 74.Xr sbrk 2 75call. 76.Sh IMPLEMENTATION NOTES 77The 78.Fn vm_map_stack 79function calls 80.Xr vm_map_insert 9 81to create its mappings. 82.Pp 83The 84.Fn vm_map_growstack 85function acquires the 86.Va Giant 87lock, and the process lock on 88.Fa p , 89for the duration of the call. 90.Sh RETURN VALUES 91The 92.Fn vm_map_stack 93function returns 94.Dv KERN_SUCCESS 95if the mapping was allocated successfully. 96.Pp 97Otherwise, 98if mapping the stack would exceed the process's VMEM resource limit, 99or if the specified bottom-of-stack address is out of range for the map, 100or if there is already a mapping at the address which would result, 101or if 102.Fa max_ssize 103could not be accommodated within the current mapping, 104.Dv KERN_NO_SPACE 105is returned. 106.Pp 107Other possible return values for this function are documented in 108.Xr vm_map_insert 9 . 109.Pp 110The 111.Fn vm_map_growstack 112function returns 113.Dv KERN_SUCCESS 114if 115.Fa addr 116is already mapped, or if the stack was grown successfully. 117.Pp 118It also returns 119.Dv KERN_SUCCESS 120if 121.Fa addr 122is outside the stack range; this is done in order to preserve 123compatibility with the deprecated 124.Fn grow 125function previously located in the file 126.Pa vm_machdep.c . 127.Sh SEE ALSO 128.Xr vm_map 9 , 129.Xr vm_map_insert 9 130.Sh AUTHORS 131This manual page was written by 132.An Bruce M Simpson Aq bms@spc.org . 133