Revise the description of MAP_STACK. In particular, describe the guard

in more detail.

Reviewed by:	bcr, kib, markj
MFC after:	1 week
Differential Revision:	https://reviews.freebsd.org/D26908

1 files changed, 23 insertions, 19 deletions

diff --git a/lib/libc/sys/mmap.2 b/lib/libc/sys/mmap.2
index 7d739e000b31..4635a33e0958 100644
--- a/lib/libc/sys/mmap.2
+++ b/lib/libc/sys/mmap.2
@@ -28,7 +28,7 @@
 .\"	@(#)mmap.2	8.4 (Berkeley) 5/11/95
 .\" $FreeBSD$
 .\"
-.Dd October 21, 2020
+.Dd October 27, 2020
 .Dt MMAP 2
 .Os
 .Sh NAME
@@ -319,9 +319,30 @@ Modifications are private.
 .It Dv MAP_SHARED
 Modifications are shared.
 .It Dv MAP_STACK
+Creates both a mapped region that grows downward on demand and an
+adjoining guard that both reserves address space for the mapped region
+to grow into and limits the mapped region's growth.
+Together, the mapped region and the guard occupy
+.Fa len
+bytes of the address space.
+The guard starts at the returned address, and the mapped region ends at
+the returned address plus
+.Fa len
+bytes.
+Upon access to the guard, the mapped region automatically grows in size,
+and the guard shrinks by an equal amount.
+Essentially, the boundary between the guard and the mapped region moves
+downward so that the access falls within the enlarged mapped region.
+However, the guard will never shrink to less than the number of pages
+specified by the sysctl
+.Dv security.bsd.stack_guard_page ,
+thereby ensuring that a gap for detecting stack overflow always exists
+between the downward growing mapped region and the closest mapped region
+beneath it.
+.Pp
 .Dv MAP_STACK
 implies
-.Dv MAP_ANON ,
+.Dv MAP_ANON
 and
 .Fa offset
 of 0.
@@ -334,23 +355,6 @@ must include at least
 .Dv PROT_READ
 and
 .Dv PROT_WRITE .
-.Pp
-This option creates
-a memory region that grows to at most
-.Fa len
-bytes in size, starting from the stack top and growing down.
-The
-stack top is the starting address returned by the call, plus
-.Fa len
-bytes.
-The bottom of the stack at maximum growth is the starting
-address returned by the call.
-.Pp
-Stacks created with
-.Dv MAP_STACK
-automatically grow.
-Guards prevent inadvertent use of the regions into which those
-stacks can grow without requiring mapping the whole stack in advance.
 The size of the guard, in pages, is specified by sysctl
 .Dv security.bsd.stack_guard_page .
 .El