[Bug manual/6887] mmap documentation bugs, perhaps also 2 functional bugs

["mtk.manpages at gmail dot com" <sourceware-bugzilla at sourceware dot org>]

https://sourceware.org/bugzilla/show_bug.cgi?id=6887

--- Comment #4 from Michael Kerrisk <mtk.manpages at gmail dot com> ---
(In reply to Adhemerval Zanella from comment #3)
> I would suggest to next time when open bugs against kernel interfaces to
> specify which architecture and kernel version the issues were observed. The
> mmap interface has some arch-specific implementation and behaviours (for
> instance MAP_32BIT on x86).
> 
> About the questionings:
> 
> * opening file rw and mmapping it w
>   causes segfault at first write to a mapped memory location.
>   (functional bug, therefore documentation bug until it is fixed).
> 
>   I did not observed in my testing system (x86_64 4.4.0-31-generic) and if
> it is happening it is clearly a kernel issue.

I also could not reproduce this.

> * opening file w and mmapping it w causes mmap error 'permission denied',
>   which is not mentioned in documentation
>   (rather it is said that i may GET more permissions than i asked for).
> 
>   Again this is clearly a kernel issue if it is really happening.

In the mmap(2) man page, there is mention of this case under the EACCES error

MAP_SHARED  was  requested and PROT_WRITE is set, but fd is
              not open in read/write (O_RDWR)  mode.
> 
> * trying to read from an empty file generates a 'bus error',
>   terminating process,
>   which is not mentioned in documentation.
> 
>   This is a implementation detail which is covered by POSIX:
> 
>   "An implementation may generate SIGBUS signals when a reference would
> cause an error in the mapped object, such as out-of-space condition." 
> 
>   And it is currently covered by manual as:

(Here, Adhemerval, you refer to the mmap(2) man page, but I believe the Siward
was reporting documentation bugs against the glibc manual, which is rather less
complete than the mmap(2) man page.

> "ERRORS
> 
>   [...]
> 
>   SIGBUS Attempted  access  to  a portion of the buffer that does not
> correspond to the file (for example, beyond the end of the file, including
> the case where another process has truncated the file)."
> 
> * when mmapping an empty file, mmap() returns a valid address,
>   but reading from this address causes a segfault.
>   (functional bug, therefore documentation bug until fixed).
> 
>   This is the same issue as before.
> 
> * compiler didn't find O_READ ,
>   though fcntl.h was #included,
>   and both __USE_GNU and _GNU_SOURCE were #defined.
>   (working around by using O_RDONLY is trivial, but it is a documentation
> bug)
> 
>   O_READ is GNU-specific identifier only used on GNU/Hurd.  GLIBC on Linux
> only defines the POSIX name O_RDONLY.
> 
> * description of mremap says that it returns -1 on error,
>   but this is not possible since it's returntype is void* .
> 
>   The manual states "On error, the value MAP_FAILED (that is, (void *) -1)".
> 
> * description of MS_ASYNC says
>   "This tells `msync' to begin synchronization, but not to wait for it to
> complete."
>    which should be
>    "This tells `msync' to begin synchronization, but to not wait for it to
> complete."
>    because it is confusing.
>    (never mind whether it is official english ; it is braindamage.)

Again, I think that Siward was reporting a bug against the glibc manual, which
does indeed still contain the text:

     'MS_ASYNC'

          This tells 'msync' to begin the synchronization, but not to
          wait for it to complete.

>   The text has changed and it does not contain this wording any more.
> 
> * description of MAP_SHARED says
>   "This specifies that writes to region will be written back to file."
>    but it is valid (or at least it works) to use MAP_SHARED with MAP_ANON,
>    in which case there is no file to write back to.
>    Perhaps in this case MAP_SHARED controls whether other processes see
> changed
> content ?
> 
>    It currenty states that "Share  this mapping.  Updates to the mapping are
> visible to other processes that map this file, and are carried through to
> the underlying file.  (To precisely control when updates are carried through
> to the underlying file requires the use of msync(2).)"

So the text here could be a little more precise in mmap(2). I changed it to

       MAP_SHARED
              Share this mapping.  Updates to the mapping are visible  to
              other  processes  mapping the same region, and (in the case
              of file-backed mappings) are carried through to the  under‐
              lying file.

Cheers,

Michael

> 
> So mostly of the mentioned issues are currently documented and some are just
> user errors. I will close this bug.

-- 
You are receiving this mail because:
You are on the CC list for the bug.