[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-Id: <1373388169.27613.31@driftwood>
Date: Tue, 09 Jul 2013 11:42:49 -0500
From: Rob Landley <rob@...dley.net>
To: musl@...ts.openwall.com
Cc: Rich Felker <dalias@...ifal.cx>, musl@...ts.openwall.com,
"Michael Kerrisk (man-pages)" <mtk.manpages@...il.com>
Subject: Re: Re: Linux manpages (was Re: Request for
volunteers)
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
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.
