[PATCH man] 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()
---
I'm not sure if we can reasonably do anything about this in the kernel,
given that the kernel does not really have any idea of what userspace
object sizes look like, or whether userspace even wants C semantics.
But we can at least document it...

@man-pages maintainer: Please wait a few days before applying this;
I imagine there might be some discussion about this.

 man/man2/mmap.2 | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/man/man2/mmap.2 b/man/man2/mmap.2
index caf822103..9cb7dacf3 100644
--- a/man/man2/mmap.2
+++ b/man/man2/mmap.2
@@ -785,6 +785,23 @@ 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
+.B 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
+.B PTRDIFF_MAX).
+On top of that, GCC also assumes that no object is bigger than
+.B 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.504.g3bcea36a83-goog