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