[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <20130709165041.GT29800@brightrain.aerifal.cx>
Date: Tue, 9 Jul 2013 12:50:41 -0400
From: Rich Felker <dalias@...ifal.cx>
To: musl@...ts.openwall.com
Cc: "Michael Kerrisk (man-pages)" <mtk.manpages@...il.com>
Subject: Re: Re: Linux manpages (was Re: Request for volunteers)
On Tue, Jul 09, 2013 at 11:42:49AM -0500, Rob Landley wrote:
> >See https://www.kernel.org/doc/man-pages/todo.html#migrate_to_kernel_source
> >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
API/ABI".
> 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
already.
> 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.
Rich
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.
