Follow @Openwall on Twitter for new release announcements and other news
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Date: Tue, 9 Jul 2013 12:50:41 -0400
From: Rich Felker <>
Cc: "Michael Kerrisk (man-pages)" <>
Subject: Re: Re: Linux manpages (was Re: Request for volunteers)

On Tue, Jul 09, 2013 at 11:42:49AM -0500, Rob Landley wrote:
> >See
> >I think it would be a retrograde step to split syscall pages into
> >Sections 2 and 3. Users want to get the documentation in one place.
> >Note that the approach in man-pages (consolidating info on the syscall
> >plus any libc additions in one page) is not unique to Linux. From some
> >(offlist) discussions with the BSD man pages maintainers, it appears
> >that at least some (all?) of the BSDs do the same.
> Document what the syscall does, and then have wrapper behavior
> listed in the "deviant glibc-specific perversions" section?

Usually the difference between sections 2 and 3 is not "deviant
glibc-specific perversions" but "workarounds for kernel bugs that
won't be fixed because of the policy of maintaining stable syscall

> Syscall wrappers in Section 2 make sense, it _is_ a syscall, and
> most wrappers should be NOPs.

None of the ones that are cancellation points can be pure wrappers. If
nothing else, they must handle cancellation. That covers a big chunk

> The objection is not documenting what
> the actual syscall does (when you can call it via syscall(), or get
> the raw behavior when using klibc).

I agree it would be useful to have this information, but with limited
resources and the issue of confusing developers who get section 2 by
default then have to look again in section 3 for the man page they
actually wanted, I can see where it's probably preferable to maintain
the status quo, leaving the 2/3 split based on the historical
expectation of whether the function was a "syscall" or "library
function", and documenting Linux syscall deviations from the public
interface as part of the combined man page.


Powered by blists - more mailing lists

Confused about mailing lists and their use? Read about mailing lists on Wikipedia and check out these guidelines on proper formatting of your messages.