Re: Re: Linux manpages (was Re: [musl] Request for volunteers)

[Rich Felker <dalias@aerifal.cx>]

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