[PATCH] man/man2/mmap.2: Document that MAP_GROWSDOWN doesn't affect mmap return value.

[PATCH] man/man2/mmap.2: Document that MAP_GROWSDOWN doesn't affect mmap return value.

[Ben Kallus]

The man page states that the MAP_GROWSDOWN flag causes the kernel to return an
address one page lower than the mapping created. This is not true; the kernel
returns the base address of the mapping created, just as it does when
MAP_GROWSDOWN is not passed. This can be confirmed by inspecting
/proc/self/maps after making a gd mapping, and comparing it to the returned
value from mmap.
---
 man/man2/mmap.2 | 2 --
 1 file changed, 2 deletions(-)

diff --git a/man/man2/mmap.2 b/man/man2/mmap.2
index 09e7933d3..20b94c243 100644
--- a/man/man2/mmap.2
+++ b/man/man2/mmap.2
@@ -276,8 +276,6 @@ 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
-- 
2.53.0

Re: [PATCH] man/man2/mmap.2: Document that MAP_GROWSDOWN doesn't affect mmap return value.

[Alejandro Colomar]

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

Hi Ben,

Sorry for the delay in the review.

On 2026-02-23T11:02:19-0500, Ben Kallus wrote:
> The man page states that the MAP_GROWSDOWN flag causes the kernel to return an
> address one page lower than the mapping created. This is not true; the kernel
> returns the base address of the mapping created, just as it does when
> MAP_GROWSDOWN is not passed. This can be confirmed by inspecting
> /proc/self/maps after making a gd mapping, and comparing it to the returned
> value from mmap.

Okay, the patch looks good to me.  However, would you mind showing
a minimal C program that demonstrates the behavior?

Also, that text was added in the commit
176b1a76 (2016-11-21; "mmap.2: Add (much) more detail on MAP_GROWSDOWN")
If that commit was wrong (and thus the kernel has never behaved like
that), we should have the following tag in the commit message:

Fixes: 176b1a76 (2016-11-21; "mmap.2: Add (much) more detail on MAP_GROWSDOWN")

And if it was correct but the kernel has changed behavior, it would be
interesting to document when that happened (if we know).


Have a lovely day!
Alex

> ---
>  man/man2/mmap.2 | 2 --
>  1 file changed, 2 deletions(-)
> 
> diff --git a/man/man2/mmap.2 b/man/man2/mmap.2
> index 09e7933d3..20b94c243 100644
> --- a/man/man2/mmap.2
> +++ b/man/man2/mmap.2
> @@ -276,8 +276,6 @@ 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
> -- 
> 2.53.0
> 

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

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

Re: [PATCH] man/man2/mmap.2: Document that MAP_GROWSDOWN doesn't affect mmap return value.

[Ben Kallus]

Thanks for the feedback.

> Okay, the patch looks good to me.  However, would you mind showing
> a minimal C program that demonstrates the behavior?

Sure. Here's one:

#include <stdio.h>    // for printf, putchar, fopen, fgetc
#include <sys/mman.h> // for MAP_*, PROT_*, mmap
int main(void) {
  printf("mmap return value: %p\n",
         mmap(nullptr, 1 /* rounds up to page */, PROT_READ | PROT_WRITE,
              MAP_ANONYMOUS | MAP_PRIVATE | MAP_GROWSDOWN, -1, 0));
  FILE *const f = fopen("/proc/self/maps", "r");
  while (1) {
    int const c = fgetc(f);
    if (c < 0) {
      break;
    }
    putchar(c);
  }
}

If you run this, you'll see that the value returned from mmap is the
lowest address in one of the mappings from /proc/self/maps.

Reading/writing into this mapping works the way you'd expect. (I
tested this in gdb.)

> And if it was correct but the kernel has changed behavior, it would be
> interesting to document when that happened (if we know).

I don't have access to any older kernels at the moment. I'll set up
some VMs later today and check this.


-Ben

Re: [PATCH] man/man2/mmap.2: Document that MAP_GROWSDOWN doesn't affect mmap return value.

[Ben Kallus]

> And if it was correct but the kernel has changed behavior, it would be
> interesting to document when that happened (if we know).

I just tested this on Linux 2.6.26, and the MAP_GROWSDOWN flag worked
the same way then as it does now. My guess is that the behavior
described in the man page was never correct; it would have been a
large breaking change fom the kernel to modify the behavior of one of
the mmap flags.

I'll resubmit the patch with the updated commit message.

[PATCH] man/man2/mmap.2: Document that MAP_GROWSDOWN doesn't affect mmap return value.

[Ben Kallus]

The man page states that the MAP_GROWSDOWN flag causes the kernel to return an
address one page lower than the mapping created. This is not true; the kernel
returns the base address of the mapping created, just as it does when
MAP_GROWSDOWN is not passed. This can be confirmed by inspecting
/proc/self/maps after making a gd mapping, and comparing it to the returned
value from mmap.

Fixes: 176b1a76 (2016-11-21; "mmap.2: Add (much) more detail on MAP_GROWSDOWN")

Signed-off-by: Ben Kallus <benjamin.p.kallus.gr@dartmouth.edu>
---
 man/man2/mmap.2 | 2 --
 1 file changed, 2 deletions(-)

diff --git a/man/man2/mmap.2 b/man/man2/mmap.2
index 09e7933d3..20b94c243 100644
--- a/man/man2/mmap.2
+++ b/man/man2/mmap.2
@@ -276,8 +276,6 @@ 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
-- 
2.53.0

Re: [PATCH] man/man2/mmap.2: Document that MAP_GROWSDOWN doesn't affect mmap return value.

[Alejandro Colomar]

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

Hi Ben,

> Subject: Re: [PATCH] man/man2/mmap.2: Document that MAP_GROWSDOWN
> doesn't affect mmap return value.

Please include patch version in the [] prefix.  See
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING.d/patches/subject#n37>.

Also, please send In-Reply-To previous iterations.  See
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING.d/patches/sendmail#n17>

And ideally, include a range-diff that compares the patch against the
previous iteration.  See
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING.d/patches/range-diff>.

On 2026-03-17T17:46:52-0400, Ben Kallus wrote:
> The man page states that the MAP_GROWSDOWN flag causes the kernel to return an
> address one page lower than the mapping created. This is not true; the kernel

Please use two spaces after period.  See
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING.d/patches/description#n44>.

> returns the base address of the mapping created, just as it does when
> MAP_GROWSDOWN is not passed. This can be confirmed by inspecting
> /proc/self/maps after making a gd mapping, and comparing it to the returned
> value from mmap.

Please include in the commit message the example program you sent in the
previous thread about this patch.

> Fixes: 176b1a76 (2016-11-21; "mmap.2: Add (much) more detail on MAP_GROWSDOWN")
> 
> Signed-off-by: Ben Kallus <benjamin.p.kallus.gr@dartmouth.edu>

Please no blank lines between Fixes and SoB.  The trailer should be a
single block.


Have a lovely night!
Alex

> ---
>  man/man2/mmap.2 | 2 --
>  1 file changed, 2 deletions(-)
> 
> diff --git a/man/man2/mmap.2 b/man/man2/mmap.2
> index 09e7933d3..20b94c243 100644
> --- a/man/man2/mmap.2
> +++ b/man/man2/mmap.2
> @@ -276,8 +276,6 @@ 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
> -- 
> 2.53.0
> 
> 

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

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