svn commit: r367087 - head/lib/libc/sys

[Alan Cox]

Author: alc
Date: Tue Oct 27 18:08:33 2020
New Revision: 367087
URL: https://svnweb.freebsd.org/changeset/base/367087

Log:
  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

Modified:
  head/lib/libc/sys/mmap.2

Modified: head/lib/libc/sys/mmap.2
==============================================================================
--- head/lib/libc/sys/mmap.2	Tue Oct 27 17:25:40 2020	(r367086)
+++ head/lib/libc/sys/mmap.2	Tue Oct 27 18:08:33 2020	(r367087)
@@ -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