[PATCH man v2] mmap.2: Document danger of mappings larger than PTRDIFF_MAX

[Jann Horn <jannh@google.com>]

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
---
 man/man2/mmap.2 | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/man/man2/mmap.2 b/man/man2/mmap.2
index caf822103..4bb15699d 100644
--- a/man/man2/mmap.2
+++ b/man/man2/mmap.2
@@ -785,6 +785,25 @@ correspond to added or removed regions of the file is unspecified.
 An application can determine which pages of a mapping are
 currently resident in the buffer/page cache using
 .BR mincore (2).
+.P
+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 standard 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 0x7fffffff (almost 2 GiB).
 .\"
 .SS Using MAP_FIXED safely
 The only safe use for

base-commit: 4c4d9f0f5148caf1271394018d0f7381c1b8b400
-- 
2.49.0.901.g37484f566f-goog