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

[Rob Landley <rob@landley.net>]

On 07/08/2013 07:18:21 PM, Michael Kerrisk wrote:
> Rich,
> > I think it's an error to have anything glibc-specific in section 2  
> of
> > the manual, which should be documenting the kernel, not userspace.
> > What would be useful in the section 2 man pages is to document where
> 
> ("useful" to who? Few users care about the naked
> syscall behavior.)

We exist. :)

Speaking of which the data blob sent to sched_{get,set}affinity() is an  
array of longs, with each processor's bit living at:

   int x = 255 & (mask[cpu/sizeof(long)] >> (8*(cpu&(sizeof(long)-1))));

I know this because I implemented taskset against the raw system call,  
and read kernel code until I found the obscure corner where this is  
actually documented, namely:

   arch/powerpc/include/asm/bitops.h

(And yes, _only_ described in that architecture, not in any of the  
others. Go figure.)

(The toybox project is not a GNU program, and does not #define  
GNU_DAMMIT to access extra magic header bits. Where necessary, it  
provides its own header definitions.)

> > the syscall is insufficient to provide POSIX semantics, which are  
> left
> > to userspace to provide. Such section 2 pages could then have
> > corresponding section 3 pages that document the library behavior.
> 
> 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?

Syscall wrappers in Section 2 make sense, it _is_ a syscall, and most  
wrappers should be NOPs. 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).

Rob