mmap.2: Fix description of treatment of the hint

The current manpage reads to me as if the kernel will always pick
a free space close to the requested address, but that's not the
case:

mmap(0x600000000000, 4096, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS,
-1, 0) = 0x600000000000
mmap(0x600000000000, 4096, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS,
-1, 0) = 0x7f5042859000

You can also see this in the various implementations of
->get_unmapped_area() - if the specified address isn't available,
the kernel basically ignores the hint (apart from the 5level
paging hack).

Clarify how this works a bit.

Acked-by: Michal Hocko <mhocko@suse.com>
Signed-off-by: Jann Horn <jannh@google.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

diff --git a/man2/mmap.2 b/man2/mmap.2
index fccfb9b3e9864d2a4880ecfdcc39c28f2241e06b..dbcae59bef6280c1daa164a0384218efdf2252c5 100644 (file)
--- a/man2/mmap.2
+++ b/man2/mmap.2
@@ -71,7 +71,12 @@ If
 .I addr
 is not NULL,
 then the kernel takes it as a hint about where to place the mapping;
-on Linux, the mapping will be created at a nearby page boundary.
+on Linux, the kernel will pick a nearby page boundary (but always above
+or equal to the value specified by
+.IR /proc/sys/vm/mmap_min_addr )
+and attempt to create the mapping there.
+If another mapping already exists there, the kernel picks a new address that
+may or may not depend on the hint.
 .\" Before Linux 2.6.24, the address was rounded up to the next page
 .\" boundary; since 2.6.24, it is rounded down!
 The address of the new mapping is returned as the result of the call.