KS2007: The greater kernel ecosystem and user-space APIs

Posted Sep 16, 2007 15:16 UTC (Sun) by michaelk (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:

1. 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.
2. 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.
3. 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".