KS2007: The greater kernel ecosystem and user-space APIs [LWN.net]

KS2007: The greater kernel ecosystem and user-space APIs

Posted Sep 16, 2007 6:31 UTC (Sun) by mkerrisk (subscriber, #1978) [Link]

In the wrapper-and-syscall-nearly-identical case, you could describe the differences in a NOTE in the section 3 page.

Yes, but what I want to avoid is people having to look in two places to get all the information they need. Or looking in just one of those two places and not getting all the info that they require (and not realizing that they don't have all the information, if for example they only look in the section 2 page). Ideas are always welcome!

It just seems clumsy to have user-callable stuff documented in section 2: on other Unixes that's not what it's for.

It is not clear to me other Unix implementations always have a clear .2 / .3 divide. Lacking the source, it's not easy to be sure what is done in libc before a syscall is invoked.

KS2007: The greater kernel ecosystem and user-space APIs

Posted Sep 16, 2007 11:07 UTC (Sun) by nix (subscriber, #2304) [Link]

Er, why would people need to simultaneously know the details of the
kernel-level interface (only of interest to people writing libcs) and of
the POSIX interface (only of interest to people using libcs).

It seems to me that your division is of most use only to libc authors :/
everyone else will need either one half of the info, or the other half.

(Of course this is relevant only for the small minority of syscall/libc
calls that differ significantly, and as I said, I'm not doing the *work*,
so my opinion is worth basically nothing :) )

Solaris has a clear .2 / .3 divide: it's only that it then subdivides
section 3 into enough subsections that you're then left guessing which of
*those* your page might be in. Let's not do *that*. :)

KS2007: The greater kernel ecosystem and user-space APIs

Posted Sep 16, 2007 15:16 UTC (Sun) by mkerrisk (subscriber, #1978) [Link]

Er, why would people need to simultaneously know the details of the kernel-level interface (only of interest to people writing libcs) and of the POSIX interface (only of interest to people using libcs).

The majority audience for man pages is of course userland programmers. I suppose that 99.99% (give or take a 9) of those userland programmers use a libc, rather than invoking syscalls directly, and let's say that 99% of them use glibc, and are thus interested in the glibc interface. In terms of documenting the APIs, these are the choices I see:

Document the details of the system call in .2, and have .3 pages that note just the differences in the (g)libc API. I dislike this option, because the (userland) programmer must look at two pages to put together the information they need.
Document the details of the system call in .2, and have .3 pages that fully document the (g)libc API, reproducing all of the details that also appeared in the corresponding .2 page. I dislike this solution because of the duplication involved. Furthermore, for the many interfaces where the glibc wrapper does nothing, the .2 and .3 pages would be exactly the same.
Have .2 pages which include details of the (g)libc API, but clearly indicate those parts where the raw syscall API differs.

So far, I prefer option 3, but I realize it's not perfect, for various reasons, some of which you mention. It may be that someone comes up with a better solution than any of these three.

It seems to me that your division is of most use only to libc authors :/ everyone else will need either one half of the info, or the other half. (Of course this is relevant only for the small minority of syscall/libc calls that differ significantly, and as I said, I'm not doing the *work*, so my opinion is worth basically nothing :) )

But you're polite, and interested, so I can't help but respond ;-).

Solaris has a clear .2 / .3 divide

What I'm suggesting (and it's just a guess), is that maybe the divide on Solaris is no more real than that on Linux. Is *everything* documented in .2 on Solaris a raw syscall? Is *anything* documented in .3 in fact a syscall? I don't know the definitive answer to either question, but I wouldn't be surprised to find that the answer to both questions is "yes".

KS2007: The greater kernel ecosystem and user-space APIs

Posted Sep 16, 2007 17:10 UTC (Sun) by nix (subscriber, #2304) [Link]

Well, option 2 is implementable by having the nearly-identical subset of
section 2 and 3 manpages generated from a common source (it'd be pretty
trivial to sed out markers that indicate that `this bit is section 2 only'
and `this bit is section 3 only').

But I really will shut up now until I have actual patches implementing
this (medical crud means it may be some time, biology is best observed
from a long way away).