KS2007: The greater kernel ecosystem and user-space APIs
Posted Sep 13, 2007 11:14 UTC (Thu) by mkerrisk
In reply to: KS2007: The greater kernel ecosystem and user-space APIs
Parent article: KS2007: The greater kernel ecosystem and user-space APIs
[...] the man pages, as currently written, document the system call interface as presented by the C library. But the API exported directly by the kernel can be different, and often is. Which API should be documented?
There's already a scheme for this, and long has been. The syscall docs go into section 2: the docs for the C interface go into section 3.
Life is not so simple, on Linux at least (and I suspect the same is true of a number of other Unix implementatons): there is a fairly close intertwining of kernel and (g)libc interfaces. Often the glibc wrapper for a system call adds nothing, or very little, on top of the kernel interface. But sometimes the wrapper makes significant changes (e.g., does some manipulation of arguments). Where that is done, the application programmer is almost always interested in the (g)libc interface, rather than the raw kernel interface. The alternative would be two have two man pages for each system call: one in section 2 describing the raw kernel interface, and one in section 3 describing the (g)libc interface. That is kind of clumsy for the following reasons:
often the section 3 page will describe no difference from the section 2 page (i.e., the wrapper does nothing except invoke the syscall); and
in cases where the wrapper does add something to the syscall, the reader needs to read two man pages to get the full picture.
My preference (already embodied in some pages), is to describe all syscalls in section 2 pages, and, if the (g)libc wrapper provides a different behavior/interface, then document that interface in the main text of the section 2 page, and include a NOTE that describes the differences for the raw kernel interface.
to post comments)