diff options
Diffstat (limited to 'static/netbsd/man7/stack.7')
| -rw-r--r-- | static/netbsd/man7/stack.7 | 293 |
1 files changed, 293 insertions, 0 deletions
diff --git a/static/netbsd/man7/stack.7 b/static/netbsd/man7/stack.7 new file mode 100644 index 00000000..86c2fa0b --- /dev/null +++ b/static/netbsd/man7/stack.7 @@ -0,0 +1,293 @@ +.\" $NetBSD: stack.7,v 1.8 2026/04/23 20:09:46 uwe Exp $ +.\" +.\" Copyright (c) 2023 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 23, 2026 +.Dt STACK 7 +.Os +.Sh NAME +.Nm stack +.Nd layout of program execution stack memory +.Sh DESCRIPTION +When executing a program, with the +.Xr execve 2 +or +.Xr posix_spawn 3 +families of system calls, +.Nx +reserves a region in the new program image's virtual address space for +the +.Em stack , +which stores return addresses and local variables for nested procedure +calls in program execution. +Similarly, threads created with +.Xr pthread_create 3 +have regions allocated for per-thread stacks. +.Pp +The stack grows from the +.Em base , +where information of the outermost procedure call is stored, fixed at +program start, to the +.Em stack pointer , +a +.Tn CPU +register that points to information used by the current procedure call, +varying during execution as procedures are called. +.Pp +On most architectures, the stack base is at higher-numbered virtual +addresses and the stack pointer is at lower-numbered virtual addresses +\(em on these architectures, +.Em the stack grows down . +On some other architectures, notably +.Tn HP PA-RISC +.Pq Sq hppa , +the stack base is at lower-numbered virtual addresses and the stack +pointer is at higher-numbered virtual addresses, so on those +architectures +.Em the stack grows up . +.Pp +In the kernel, the C preprocessor macro +.Dv __HAVE_MACHINE_STACK_GROWS_UP +is defined in +.In machine/types.h +on architectures where the stack grows up. +.Ss Main thread +For single-threaded programs, and for the main thread of multi-threaded +programs, +.Nx +reserves virtual addresses as follows on architectures where the stack +grows +.Em down : +.Bd -literal -offset indent ++--------------------+ USRSTACK +| ASLR stack gap | ++--------------------+ stack base +| accessible pages | +| . | +| . | <-- stack pointer +| . | (varies during execution) +| V | ++--------------------+ (stack base) - (soft stack rlimit) +| inaccessible pages | ++--------------------+ (stack base) - (hard stack rlimit) +| guard/redzone | ++--------------------+ USRSTACK - MAXSSIZ +.Ed +.Pp +On architectures where the stack grows +.Em up , +the layout is: +.Bd -literal -offset indent ++--------------------+ USRSTACK + MAXSSIZ +| guard/redzone | ++--------------------+ (stack base) + (hard stack rlimit) +| inaccessible pages | ++--------------------+ (stack base) + (soft stack rlimit) +| \(ha | +| . | <-- stack pointer +| . | (varies during execution) +| . | +| accessible pages | ++--------------------+ stack base +| ASLR stack gap | ++--------------------+ USRSTACK +.Ed +.Bl -bullet +.It +The +.Em stack guard +is allocated so that any access \(em read, write, or execute \(em will +deliver +.Dv SIGSEGV +to the process. +This serves to detect stack overflow and crash rather than silently +overwrite other memory in the program's virtual address space. +The size of the stack guard is tuned by the +.Li vm.guard_size +.Xr sysctl 7 +knob. +.Pp +The stack guard is also sometimes known as the +.Sq redzone +or +.Sq red zone , +although the term +.Sq red zone +is also sometimes used to mean a fixed space +.Em above +the stack pointer (in the direction of stack growth) that the system +guarantees it will not overwrite when calling a signal handler in the +.Tn ABI +of some architectures; see also +.Xr sigaltstack 2 +to specify an alternate stack base for the kernel to use when invoking +signal handlers on signal delivery. +.It +The +.Em inaccessible pages +of the stack region are allocated so that any access will also deliver +.Dv SIGSEGV +to the process, but they can be made accessible by changing the soft +stack rlimit with +.Xr setrlimit 2 . +.It +The +.Em accessible pages +of the stack region are allocated with read/write access permitted, and +are used to store the actual data in the program stack. +.It +When +.Tn PaX ASLR , +address space layout randomization, is enabled, the +.Em stack gap +is an +.Em unallocated +space of a size chosen unpredictably at random at program startup time. +When +.Tn PaX ASLR +is disabled, the stack gap is empty. +.El +.Pp +All of the boundaries \(em +.Dv USRSTACK , +the stack base, and the boundaries between the accessible, +inaccessible, and guard pages \(em are page-aligned, or rounded to be +page-aligned even if the rlimits are not themselves page-aligned, +rounding so that the sizes of the regions do not exceed the rlimits. +.Pp +The stack base is exposed to programs via the +.Dv AT_STACKBASE +.Xr elf 5 +auxiliary info vector entry. +.Pp +The per-architecture constants +.Dv USRSTACK +and +.Dv MAXSSIZ +are defined in +.In machine/vmparam.h . +.Ss Non-main threads +Threads created with +.Xr pthread_create 3 +have stacks allocated at dynamically chosen addresses outside the main +thread's stack region by default, and their stacks cannot be resized +after creation. +On architectures where the stack grows +.Em down , +the layout is: +.Bd -literal -offset indent ++--------------------+ stack base = stackaddr + stacksize +| stack | +| . | +| . | <-- stack pointer +| . | (varies during execution) +| V | ++--------------------+ stackaddr +| guard/redzone | ++--------------------+ stackaddr - guardsize +.Ed +.Pp +On architectures where the stack grows +.Em up , +the layout is: +.Bd -literal -offset indent ++--------------------+ stackaddr + stacksize + guardsize +| guard/redzone | ++--------------------+ stackaddr + stacksize +| \(ha | +| . | <-- stack pointer +| . | (varies during execution) +| . | +| stack | ++--------------------+ stack base = stackaddr +.Ed +.Pp +The parameters stackaddr, stacksize, and guardsize can be obtained from +an existing thread using +.Xr pthread_getattr_np 3 , +.Xr pthread_attr_getguardsize 3 , +and the +.Xr pthread_attr_getstack 3 +family of functions. +.Pp +When creating a thread, the stack can be manually allocated and the +parameters can be set using +.Xr pthread_attr_setguardsize 3 +and the +.Xr pthread_attr_setstack 3 +family of functions. +However, the stack parameters cannot be changed after thread creation. +The default guard size is tuned by the +.Li vm.thread_guard_size +.Xr sysctl 7 +knob. +.Pp +For the main thread, +.Xr pthread_getattr_np 3 +returns a +.Em snapshot +of the parameters as they existed at program startup, so that stackaddr +and stacksize reflect the current accessible pages of the stack, and +guardsize is the value of the +.Li vm.guard_size +.Xr sysctl 7 +knob at the time of program startup. +.Po +Note that this means the +.Xr pthread 3 +view of the main thread's stack guard may not coincide with the actual +stack guard \(em it may overlap with, or lie entirely in, the +inaccessible pages of the stack reserved on program start. +.Pc +However, if the program changes its soft stack rlimit with +.Xr setrlimit 2 , +this snapshot may become stale. +.Sh SEE ALSO +.Xr execve 2 , +.Xr mmap 2 , +.Xr mprotect 2 , +.Xr sigaltstack 2 , +.Xr ucontext 2 , +.Xr posix_spawn 3 , +.Xr pthread 3 , +.Xr security 7 , +.Xr sysctl 7 , +.Xr paxctl 8 +.Sh BUGS +.Tn PaX ASLR +doesn't actually guarantee an accessible stack reservation of length +equal to the soft stack rlimit \(em owing to a bug (XXX which PR +number?), +.Nx +may sometimes reserve less space than the soft rlimit, in which case +the accessible pages of the stack cannot be extended. +.Pp +There is a race between the kernel's access of +.Li vm.guard_size +at exec time, and userland's access of +.Li vm.guard_size +in +.Xr pthread 3 +initialization. |