Doubts about mmap(2)

Doubts about mmap(2)

[Alex Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1503 bytes --]

Hi!

I believe mmap(2) is confusing (see the emboldened parts):

DESCRIPTION
        mmap()  creates  a  new mapping in the virtual address space of
        the calling process.  **The starting address for the new  mapping
        is specified in addr.**  The length argument specifies the length
        of the mapping (which must be greater than 0).

        If addr is NULL, then the kernel chooses the (page‐aligned) ad‐
        dress at which to create the mapping; this is the most portable
        method  of  creating  a new mapping.  **If addr is not NULL, then
        the kernel takes it as a hint about where to place the mapping;
        on Linux, the kernel will pick a nearby page boundary** (but  al‐
        ways    above    or   equal   to   the   value   specified   by
        /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.
        The address of the new mapping is returned as the result of the
        call.


The first emboldened sentence contradicts the second.  It's not the
starting address, but just a hint to find a nearby (>=) starting
address.  How about saying this?:

     A hint for the starting address for the new mapping is specified in
     addr.

Cheers,
Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

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

Re: Doubts about mmap(2)

[Alex Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1851 bytes --]

On 5/18/23 10:53, Alex Colomar wrote:
> Hi!
> 
> I believe mmap(2) is confusing (see the emboldened parts):
> 
> DESCRIPTION
>         mmap()  creates  a  new mapping in the virtual address space of
>         the calling process.  **The starting address for the new  mapping
>         is specified in addr.**  The length argument specifies the length
>         of the mapping (which must be greater than 0).
> 
>         If addr is NULL, then the kernel chooses the (page‐aligned) ad‐
>         dress at which to create the mapping; this is the most portable
>         method  of  creating  a new mapping.  **If addr is not NULL, then
>         the kernel takes it as a hint about where to place the mapping;
>         on Linux, the kernel will pick a nearby page boundary** (but  al‐
>         ways    above    or   equal   to   the   value   specified   by
>         /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.
>         The address of the new mapping is returned as the result of the
>         call.
> 
> 
> The first emboldened sentence contradicts the second.  It's not the
> starting address, but just a hint to find a nearby (>=) starting

I was a bit wrong there.  It's >= mmap_min_addr, not >= hint.  But the
suggestion below holds.

> address.  How about saying this?:
> 
>      A hint for the starting address for the new mapping is specified in
>      addr.
> 
> Cheers,
> Alex
> 

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


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

Re: Doubts about mmap(2)

[Oskari Pirhonen]

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

On Thu, May 18, 2023 at 11:03:14 +0200, Alex Colomar wrote:
> On 5/18/23 10:53, Alex Colomar wrote:
> > Hi!
> > 
> > I believe mmap(2) is confusing (see the emboldened parts):
> > 
> > DESCRIPTION
> >         mmap()  creates  a  new mapping in the virtual address space of
> >         the calling process.  **The starting address for the new  mapping
> >         is specified in addr.**  The length argument specifies the length
> >         of the mapping (which must be greater than 0).
> > 
> >         If addr is NULL, then the kernel chooses the (page‐aligned) ad‐
> >         dress at which to create the mapping; this is the most portable
> >         method  of  creating  a new mapping.  **If addr is not NULL, then
> >         the kernel takes it as a hint about where to place the mapping;
> >         on Linux, the kernel will pick a nearby page boundary** (but  al‐
> >         ways    above    or   equal   to   the   value   specified   by
> >         /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.
> >         The address of the new mapping is returned as the result of the
> >         call.
> > 
> > 
> > The first emboldened sentence contradicts the second.  It's not the
> > starting address, but just a hint to find a nearby (>=) starting
> 
> I was a bit wrong there.  It's >= mmap_min_addr, not >= hint.  But the
> suggestion below holds.
> 
> > address.  How about saying this?:
> > 
> >      A hint for the starting address for the new mapping is specified in
> >      addr.
> > 

I think describing the default behavior first is a good idea. If a user
needs an exact address they can read further for MAP_FIXED/_NOREPLACE
(and the potential footguns involved).

- Oskari

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