Bug 42892 - Man page bug for mmap2(2)
Man page bug for mmap2(2)
Status: RESOLVED CODE_FIX
Product: Documentation
Classification: Unclassified
Component: man-pages
All Linux
: P1 normal
Assigned To: Michael Kerrisk
:
Depends on:
Blocks:
  Show dependency treegraph
 
Reported: 2012-03-09 03:13 UTC by Kevin
Modified: 2012-04-16 03:58 UTC (History)
1 user (show)

See Also:
Kernel Version:
Tree: Mainline
Regression: No


Attachments
Program to discover partitions that got lost. (2.41 KB, text/x-csrc)
2012-03-09 03:13 UTC, Kevin
Details

Description Kevin 2012-03-09 03:13:58 UTC
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.
Comment 1 Kevin 2012-03-09 15:14:06 UTC
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."
Comment 2 Michael Kerrisk 2012-04-14 20:57:31 UTC
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...
Comment 3 Kevin 2012-04-15 23:20:07 UTC
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
Comment 4 Michael Kerrisk 2012-04-16 03:58:04 UTC
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.

Note You need to log in before you can comment on or make changes to this bug.