share/man/man9/vm_map_stack.9

   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 January 11, 2013
  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
  47 The
  48 .Fn vm_map_stack
  49 function maps a process stack for a new process image.
  50 The stack is mapped
  51 .Fa addrbos
  52 in
  53 .Fa map ,
  54 with a maximum size of
  55 .Fa max_ssize .
  56 Copy-on-write flags passed in
  57 .Fa cow
  58 are also applied to the new mapping.
  59 Protection bits are supplied by
  60 .Fa prot
  61 and
  62 .Fa max .
  63 .Pp
  64 It is typically called by
  65 .Xr execve 2 .
  66 .Pp
  67 The
  68 .Fn vm_map_growstack
  69 function is responsible for growing a stack for the process
  70 .Fa p
  71 to the desired address
  72 .Fa addr ,
  73 similar to the legacy
  74 .Xr sbrk 2
  75 call.
  76 .Sh IMPLEMENTATION NOTES
  77 The
  78 .Fn vm_map_stack
  79 function calls
  80 .Xr vm_map_insert 9
  81 to create its mappings.
  82 .Pp
  83 The
  84 .Fn vm_map_stack
  85 and
  86 .Fn vm_map_growstack
  87 functions acquire the process lock on
  88 .Fa p
  89 for the duration of the call.
  90 .Sh RETURN VALUES
  91 The
  92 .Fn vm_map_stack
  93 function returns
  94 .Dv KERN_SUCCESS
  95 if the mapping was allocated successfully.
  96 .Pp
  97 Otherwise,
  98 if mapping the stack would exceed the process's VMEM resource limit,
  99 or if the specified bottom-of-stack address is out of range for the map,
 100 or if there is already a mapping at the address which would result,
 101 or if
 102 .Fa max_ssize
 103 could not be accommodated within the current mapping,
 104 .Dv KERN_NO_SPACE
 105 is returned.
 106 .Pp
 107 Other possible return values for this function are documented in
 108 .Xr vm_map_insert 9 .
 109 .Pp
 110 The
 111 .Fn vm_map_growstack
 112 function returns
 113 .Dv KERN_SUCCESS
 114 if
 115 .Fa addr
 116 is already mapped, or if the stack was grown successfully.
 117 .Pp
 118 It also returns
 119 .Dv KERN_SUCCESS
 120 if
 121 .Fa addr
 122 is outside the stack range; this is done in order to preserve
 123 compatibility with the deprecated
 124 .Fn grow
 125 function 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
 131 This manual page was written by
 132 .An Bruce M Simpson Aq bms@spc.org .