[PATCH] man/man2/mmap.2: Further document MAP_GROWSDOWN

[PATCH] man/man2/mmap.2: Further document MAP_GROWSDOWN

[Ben Kallus]

Makes 2 corrections to the page:
1. mmap(MAP_GROWSDOWN) returns the base address of the returned
   mapping; not one page lower than that.
2. When growing a MAP_GROWSDOWN mapping, the kernel doesn't require that
   the faulting access be within the guard page. Instead, it just needs
   to be beneath the mapping, and not within `stack_guard_gap` of the
   next lower mapping. By default, `stack_guard_gap` is 256.
---
 man/man2/mmap.2 | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/man/man2/mmap.2 b/man/man2/mmap.2
index 093b0caf1..be2b21ccc 100644
--- a/man/man2/mmap.2
+++ b/man/man2/mmap.2
@@ -274,13 +274,11 @@ should check the returned address against the requested address.
 This flag is used for stacks.
 It indicates to the kernel virtual memory system that the mapping
 should extend downward in memory.
-The return address is one page lower than the memory area that is
-actually created in the process's virtual address space.
-Touching an address in the "guard" page below the mapping will cause
-the mapping to grow by a page.
-This growth can be repeated until the mapping grows to within a
-page of the high end of the next lower mapping,
-at which point touching the "guard" page will result in a
+Accessing an address in the pages below the mapping will cause the mapping
+to grow to accommodate the access.
+This growth can be repeated until the mapping grows to within
+256 pages of the high end of the next lower mapping, at which point touching
+below the mapping will result in a
 .B SIGSEGV
 signal.
 .TP
-- 
2.52.0

Re: [PATCH] man/man2/mmap.2: Further document MAP_GROWSDOWN

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 3093 bytes --]

Hi Ben,

On 2026-01-26T13:13:04-0500, Ben Kallus wrote:
> Makes 2 corrections to the page:
> 1. mmap(MAP_GROWSDOWN) returns the base address of the returned
>    mapping; not one page lower than that.
> 2. When growing a MAP_GROWSDOWN mapping, the kernel doesn't require that
>    the faulting access be within the guard page. Instead, it just needs
>    to be beneath the mapping, and not within `stack_guard_gap` of the
>    next lower mapping. By default, `stack_guard_gap` is 256.

Would you mind separating this into two patches?  Or do you think this
is better as a single one?

> ---

Would you mind signing the patch?

$ tail CONTRIBUTING.d/patches/description 
    Trailer
	Sign your patch with "Signed-off-by:".  Read about the
	"Developer's Certificate of Origin" at
	<https://www.kernel.org/doc/Documentation/process/submitting-patches.rst>.
	When appropriate, other tags documented in that file, such as
	"Reported-by:", "Reviewed-by:", "Acked-by:", and "Suggested-by:"
	can be added to the patch.  We use "Co-authored-by:" instead of
	"Co-developed-by:".  Example:

		Signed-off-by: Alejandro Colomar <alx@kernel.org>

>  man/man2/mmap.2 | 12 +++++-------
>  1 file changed, 5 insertions(+), 7 deletions(-)
> 
> diff --git a/man/man2/mmap.2 b/man/man2/mmap.2
> index 093b0caf1..be2b21ccc 100644
> --- a/man/man2/mmap.2
> +++ b/man/man2/mmap.2
> @@ -274,13 +274,11 @@ should check the returned address against the requested address.
>  This flag is used for stacks.
>  It indicates to the kernel virtual memory system that the mapping
>  should extend downward in memory.
> -The return address is one page lower than the memory area that is
> -actually created in the process's virtual address space.
> -Touching an address in the "guard" page below the mapping will cause
> -the mapping to grow by a page.
> -This growth can be repeated until the mapping grows to within a
> -page of the high end of the next lower mapping,
> -at which point touching the "guard" page will result in a
> +Accessing an address in the pages below the mapping will cause the mapping
> +to grow to accommodate the access.

Please use semantic newlines.  See man-pages(7).

$ MANWIDTH=72 man man-pages | awk '/Use semantic newlines/,/^$/'
   Use semantic newlines
     In the source of a manual page, new sentences should be started on
     new lines, long sentences should be split  into  lines  at  clause
     breaks  (commas,  semicolons, colons, and so on), and long clauses
     should be split at phrase boundaries.  This convention,  sometimes
     known as "semantic newlines", makes it easier to see the effect of
     patches, which often operate at the level of individual sentences,
     clauses, or phrases.


Have a lovely day!
Alex

> +This growth can be repeated until the mapping grows to within
> +256 pages of the high end of the next lower mapping, at which point touching
> +below the mapping will result in a
>  .B SIGSEGV
>  signal.
>  .TP
> -- 
> 2.52.0
> 

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] man/man2/mmap.2: Further document MAP_GROWSDOWN

[Ben Kallus]

Hi Alex,

Thanks for the feedback. Broke this up into 2 patches as you
suggested. First patch incoming.
-Ben