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

[Rob Landley <rob@landley.net>]

On 07/09/2013 12:28:17 AM, Michael Kerrisk (man-pages) wrote:
> >> > 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.

I note that I'm nominally the kernel Documentation maintainer. If you'd  
like a Documentation/syscall directory handed over to you in  
MAINTAINERS, I can do that. (Or Documentation/DocBook/syscall, up to  
you...)

(I don't do nearly enough with it due to lack of time, and because  
every patch series in the world has a documentation bit I get cc'd on  
and How am _I_ supposed to judge the correct locking requirements for a  
Heterodyne Death Ray so half the time I just go "You need a comma in  
'Fools I shall destroy you all!'" and then ack it. Still eats up the  
time I have to devote to that topic, most weeks.)

At some point I'd like to completely reorganize that directory so (for  
example) all the architecture directories are under "arch". But this  
involves me setting up a git tree somewhere I can upload to and send  
pull requests about, and that's just icky enough to stay well below the  
surface of my todo list...

> > Yes, that's understandable. I somewhat question why we even still  
> have
> > a "section 2" in the manual, though...
> 
> Well then, you'll be amused to hear that the discussion with the BSD
> maintainers was about whether FreeBSD (and others) should simply merge
> Sections 2 and 3. I can see arguments in favor of it, but they're not
> (to my mind) compelling. See one piece from the thread below.

A system call is a different thing than a library call, even in libc.  
The fact glibc gets them confused is a problem with glibc.

In theory there is a "clean upstream" system call set in posix, and a  
"clean upstream" libc call set in c99 and/or posix. (In practice  
there's noting like subscribing to the austin group mailing list to  
rapidly erode your faith in the upcoming Posix standard. The sausage is  
made of people! And they're _INSANE_.)

Rob