Bug 42892
| Summary: | Man page bug for mmap2(2) | ||
|---|---|---|---|
| Product: | Documentation | Reporter: | Kevin (kevinogorman4) |
| Component: | man-pages | Assignee: | Michael Kerrisk (mtk.manpages) |
| Status: | RESOLVED CODE_FIX | ||
| Severity: | normal | CC: | mtk.manpages |
| Priority: | P1 | ||
| Hardware: | All | ||
| OS: | Linux | ||
| Kernel Version: | Subsystem: | ||
| Regression: | No | Bisected commit-id: | |
| Attachments: | Program to discover partitions that got lost. | ||
It occurs to me that perhaps glue code is intentionally missing, and this system call is to be used internally for library authors. If this is the case, then it seems to me the man page should look more like getdents(2) and a few others, with the description beginning "This is not the function you are interested in." See the NOTES section:
NOTES
Nowadays, the glibc mmap() wrapper function invokes this
system call rather than the mmap(2) system call.
I don't think any fix is really needed...
I disagree. Even if the mmap() wrapper uses mmap2(), the "not what you're looking for" is appropriate, and used elsewhere in similar circumstances. This call occurs in the man pages of all users who have man pages at all, but is a red herring. Attempts to use it will fail. Documentation should prevent that sort of thing when it's this easy to do. Most of the section 2 stuff is about the wrappers around system calls, not the calls themselves. The ones about the raw calls are the ones that carry that "not what you're looking for" language on some systems. It could have saved me one days' work and I'm just one person. I doubt it would cost you that much time to make it right. It also happens that the mmap() wrapper does not access the full capability of the mmap2 system call, and thinking of large volumes was the reason I tried to use it. Of course that's not a documentation issue other than that the presence of this man page invited me to try it. I don't feel qualified to change the status, but I beg you to reconsider and make the minor Hello Kevin, Re-reading your earlier notes, now I get your point. Sorry that it took me qa moment. I've added this sentence at the start of the page: +This is probably not the system call you are interested; instead, see +.BR mmap (2), +which describes the glibc wrapper function that invokes this system call. and made one or two other small adjustments to the text. Thanks for persisting until I got your point. |
Created attachment 72559 [details] Program to discover partitions that got lost. Using the mmap2(2) man page to write code results in an error, possibly because of missing includes. In any event, no definition of mmap2 is seen when I use gcc -E. The result is compilation without a prototype. It happens that compilation succeeds, but linking fails for lack of a library containing mmap2. This is Ubuntu 11.04, kernel 2.6.38, and man page dated 2008-04-22, from release 3.27 of the man-pages project. Source code is attached. It's a single source file, intended to be a program to discover partitions that got lost. It is incomplete and may be buggy, but I cannot debug this version until mmap2 works for me. It looks to me as if there needs to be two things added to the synopsis: a cc line showing a non glibc library. a #include line showing an additional header.