man/man2/mmap.2: CAVEATS: Document danger of mappings larger than PTRDIFF_MAX

References:
 - C99 draft: https://www.open-std.org/jtc1/sc22/wg14/www/docs/n1124.pdf
   section "6.5.6 Additive operators", paragraph 9
 - object size restriction in GCC:
   https://gcc.gnu.org/legacy-ml/gcc/2011-08/msg00221.html
 - glibc malloc restricts object size to <=PTRDIFF_MAX in
   checked_request2size() since glibc v2.30 (released in 2019, as pointed
   out by Jakub Wilk):
   https://sourceware.org/cgit/glibc/commit/?id=9bf8e29ca136094f

Signed-off-by: Jann Horn <jannh@google.com>
Message-ID: <20250429164359.2699330-1-jannh@google.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

diff --git a/man/man2/mmap.2 b/man/man2/mmap.2
index caf82210360d7fbb381def8a90965a97ce549aa2..49b5530466f2e82023b3bd1325dcc55e208e6168 100644 (file)
--- a/man/man2/mmap.2
+++ b/man/man2/mmap.2
@@ -881,6 +881,30 @@ and
 .I length
 must both be a multiple of the underlying huge page size.
 .\"
+.SH CAVEATS
+Unlike typical
+.BR malloc (3)
+implementations,
+.BR mmap ()
+does not prevent creating objects larger than
+.BR PTRDIFF_MAX .
+Objects that are larger than
+.B PTRDIFF_MAX
+only work in limited ways in C
+(in particular,
+pointer subtraction results in undefined behavior
+if the result would be bigger than
+.BR PTRDIFF_MAX ).
+On top of that,
+GCC also assumes that no object is bigger than
+.BR PTRDIFF_MAX .
+.B PTRDIFF_MAX
+is usually half of the address space size;
+so for 32-bit processes,
+it is usually
+.B 0x7fffffff
+(almost 2 GiB).
+.\"
 .SH BUGS
 On Linux, there are no guarantees like those suggested above under
 .BR MAP_NORESERVE .