Module Name: src
Committed By: martin
Date: Sat Dec 9 13:13:49 UTC 2023
Modified Files:
src/distrib/sets/lists/man [netbsd-10]: mi
src/share/man/man7 [netbsd-10]: Makefile
Added Files:
src/share/man/man7 [netbsd-10]: stack.7
Log Message:
Pull up following revision(s) (requested by riastradh in ticket #486):
distrib/sets/lists/man/mi: revision 1.1767
share/man/man7/Makefile: revision 1.38
share/man/man7/Makefile: revision 1.39
share/man/man7/stack.7: revision 1.1
share/man/man7/stack.7: revision 1.2
share/man/man7/stack.7: revision 1.3
share/man/man7/stack.7: revision 1.4
share/man/man7/stack.7: revision 1.5
share/man/man7/stack.7: revision 1.6
share/man/man7/Makefile: Split MAN on separate lines, and sort.
Makes sorting and merging changes easier.
No functional change intended.
Preparing for a new stack(7) in the service of PR pkg/57708.
stack(7): New man page.
Should help with PR pkg/57708.
stack(7): Clarify thread stack guard vs program stack guard.
Just in case this confuses anyone dealing with PR pkg/57708.
stack(7): Clarify some wording and diagrams.
PR pkg/57708
stack(7): Consistently say `(in)accessible pages', not `... stack'.
PR pkg/57708
share/man/man7/Makefile: Hook stack.7
stack(7): Minor clarifications and wording tweaks.
Suggested by pgoyette@ and uwe@.
PR pkg/57708
stack(7): Fix diagram of non-main thread stacks.
Had stackaddr (pthread_attr_setstack parameter, lowest-numbered
virtual address of stack region) confused with stack base (where the
stack grows from, which is the highest-numbered virtual address on
machines where stack grows down).
PR pkg/57708
To generate a diff of this commit:
cvs rdiff -u -r1.1757.2.5 -r1.1757.2.6 src/distrib/sets/lists/man/mi
cvs rdiff -u -r1.36 -r1.36.6.1 src/share/man/man7/Makefile
cvs rdiff -u -r0 -r1.6.2.2 src/share/man/man7/stack.7
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/distrib/sets/lists/man/mi
diff -u src/distrib/sets/lists/man/mi:1.1757.2.5 src/distrib/sets/lists/man/mi:1.1757.2.6
--- src/distrib/sets/lists/man/mi:1.1757.2.5 Sun Oct 8 13:19:33 2023
+++ src/distrib/sets/lists/man/mi Sat Dec 9 13:13:48 2023
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.1757.2.5 2023/10/08 13:19:33 martin Exp $
+# $NetBSD: mi,v 1.1757.2.6 2023/12/09 13:13:48 martin Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
#
@@ -2539,6 +2539,7 @@
./usr/share/man/cat7/setuid.0 man-reference-catman .cat
./usr/share/man/cat7/signal.0 man-reference-catman .cat
./usr/share/man/cat7/src.0 man-reference-catman .cat
+./usr/share/man/cat7/stack.0 man-reference-catman .cat
./usr/share/man/cat7/sticky.0 man-reference-catman .cat
./usr/share/man/cat7/symlink.0 man-reference-catman .cat
./usr/share/man/cat7/sysctl.0 man-reference-catman .cat
@@ -5828,6 +5829,7 @@
./usr/share/man/html7/setuid.html man-reference-htmlman html
./usr/share/man/html7/signal.html man-reference-htmlman html
./usr/share/man/html7/src.html man-reference-htmlman html
+./usr/share/man/html7/stack.html man-reference-htmlman html
./usr/share/man/html7/sticky.html man-reference-htmlman html
./usr/share/man/html7/symlink.html man-reference-htmlman html
./usr/share/man/html7/sysctl.html man-reference-htmlman html
@@ -9094,6 +9096,7 @@
./usr/share/man/man7/setuid.7 man-reference-man .man
./usr/share/man/man7/signal.7 man-reference-man .man
./usr/share/man/man7/src.7 man-reference-man .man
+./usr/share/man/man7/stack.7 man-reference-man .man
./usr/share/man/man7/sticky.7 man-reference-man .man
./usr/share/man/man7/symlink.7 man-reference-man .man
./usr/share/man/man7/sysctl.7 man-reference-man .man
Index: src/share/man/man7/Makefile
diff -u src/share/man/man7/Makefile:1.36 src/share/man/man7/Makefile:1.36.6.1
--- src/share/man/man7/Makefile:1.36 Sun Jan 10 23:24:26 2021
+++ src/share/man/man7/Makefile Sat Dec 9 13:13:49 2023
@@ -1,16 +1,39 @@
-# $NetBSD: Makefile,v 1.36 2021/01/10 23:24:26 riastradh Exp $
+# $NetBSD: Makefile,v 1.36.6.1 2023/12/09 13:13:49 martin Exp $
# @(#)Makefile 8.1 (Berkeley) 6/5/93
.include <bsd.init.mk>
# missing: eqnchar.7 man.7 ms.7 term.7
-MAN= ascii.7 c.7 entropy.7 environ.7 glob.7 groups.7 hier.7 hostname.7 \
- intro.7 \
- kernel_sanitizers.7 mailaddr.7 module.7 nls.7 operator.7 orders.7 \
- pkgsrc.7 release.7 \
- rfc6056.7 security.7 script.7 setuid.7 signal.7 src.7 sticky.7 \
- symlink.7 sysctl.7 tests.7 users.7
+MAN+= ascii.7
+MAN+= c.7
+MAN+= entropy.7
+MAN+= environ.7
+MAN+= glob.7
+MAN+= groups.7
+MAN+= hier.7
+MAN+= hostname.7
+MAN+= intro.7
+MAN+= kernel_sanitizers.7
+MAN+= mailaddr.7
+MAN+= module.7
+MAN+= nls.7
+MAN+= operator.7
+MAN+= orders.7
+MAN+= pkgsrc.7
+MAN+= release.7
+MAN+= rfc6056.7
+MAN+= script.7
+MAN+= security.7
+MAN+= setuid.7
+MAN+= signal.7
+MAN+= src.7
+MAN+= stack.7
+MAN+= sticky.7
+MAN+= symlink.7
+MAN+= sysctl.7
+MAN+= tests.7
+MAN+= users.7
CLEANFILES= tests.7
.if ${MKKYUA} != "no"
Added files:
Index: src/share/man/man7/stack.7
diff -u /dev/null src/share/man/man7/stack.7:1.6.2.2
--- /dev/null Sat Dec 9 13:13:49 2023
+++ src/share/man/man7/stack.7 Sat Dec 9 13:13:49 2023
@@ -0,0 +1,282 @@
+.\" $NetBSD: stack.7,v 1.6.2.2 2023/12/09 13:13:49 martin 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 November 23, 2023
+.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 down:
+.Bd -literal
++--------------------+ USRSTACK
+| stack gap |
++--------------------+ stack base
+| accessible pages |
+| . |
+| . | <-- stack pointer (varies during execution)
+| . |
++--------------------+ (stack base) - (soft stack rlimit)
+| inaccessible pages |
++--------------------+ (stack base) - (hard stack rlimit)
+| guard/redzone |
++--------------------+ USRSTACK - MAXSSIZ
+.Ed
+.Pp
+On architectures where the stack grows up, the layout is:
+.Bd -literal
++--------------------+ USRSTACK + MAXSSIZ
+| guard/redzone |
++--------------------+ (stack base) + (hard stack rlimit)
+| inaccessible pages |
++--------------------+ (stack base) + (soft stack rlimit)
+| . |
+| . | <-- stack pointer (varies during execution)
+| . |
+| accessible pages |
++--------------------+ stack base
+| 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 down, the layout is:
+.Bd -literal
++--------------------+ stack base = stackaddr + stacksize + guardsize
+| stack |
+| . |
+| . | <-- stack pointer (varies during execution)
+| . |
++--------------------+ stackaddr
+| guard/redzone |
++--------------------+ stackaddr - guardsize
+.Ed
+.Pp
+On architectures where the stack grows up, the layout is:
+.Bd -literal
++--------------------+ stackaddr + stacksize + guardsize
+| guard/redzone |
++--------------------+ stackaddr + stacksize
+| . |
+| . | <-- 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.
