This is the mail archive of the
mailing list for the glibc project.
[Bug manual/6887] mmap documentation bugs, perhaps also 2 functional bugs
- From: "mtk.manpages at gmail dot com" <sourceware-bugzilla at sourceware dot org>
- To: glibc-bugs at sourceware dot org
- Date: Fri, 12 Aug 2016 19:17:08 +0000
- Subject: [Bug manual/6887] mmap documentation bugs, perhaps also 2 functional bugs
- Auto-submitted: auto-generated
- References: <email@example.com/bugzilla/>
--- 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.
> 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
> 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
> which should be
> "This tells `msync' to begin synchronization, but to not wait for it to
> 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:
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
> 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
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‐
> 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.