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

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

[Jann Horn]

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

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

[Alejandro Colomar]

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

Hi Jann,

On Tue, Apr 29, 2025 at 06:43:59PM +0200, Jann Horn wrote:
> 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

Thanks!  I've applied the patch.  See some comments below.
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=7e5756fdeba1a4729f817079c64f0d87fdcdadfa>


Have a lovely day!
Alex

> ---
>  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

I've moved the paragraph to a new CAVEATS section.

> +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

I've removed 'standard', since in any C it is problematic.

Is it okay to you?  (We're still in time to amend if you prefer
something else.)

> +(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
> 

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

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

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

[Jann Horn]

On Thu, May 1, 2025 at 6:43 PM Alejandro Colomar <alx@kernel.org> wrote:
> On Tue, Apr 29, 2025 at 06:43:59PM +0200, Jann Horn wrote:
> > 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
>
> Thanks!  I've applied the patch.  See some comments below.
> <https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=7e5756fdeba1a4729f817079c64f0d87fdcdadfa>

Thanks!

> > +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
>
> I've removed 'standard', since in any C it is problematic.
>
> Is it okay to you?  (We're still in time to amend if you prefer
> something else.)

Sounds good to me.