On Tue 18 Mar 2014 16:00:21 Michael Kerrisk wrote: > You raised a question at the bottom of a bug report > (https://bugzilla.kernel.org/show_bug.cgi?id=70801#c4) > that I though might better go to the list, since I > think it merits some wider discussion: > > i'd like to have a master location to document all > this stuff at the kernel ABI level. can we do that > with the man-pages project somehow without violating > the C library API tenet? > > First though, I'd like to check: what do you mean by "all this stuff"? > Am I correct to understand your question as something like: > > Can man-pages become a place where the kernel-user-space ABI > (as distinct from the glibc wrappers on top) is consistently > and thoroughly documented? the linux-man-pages project is great at meeting the needs of the majority of developers -- those that live in userland with the C library between them and the kernel. but i think there is not an insignificant number of developers who live at the direct kernel ABI level and do not want to see any C library details at all. like the people who write C libraries, or low level debugging utilities (i.e. anyone who touches ptrace -- gdb, qemu, strace just to name a few), or kernel developers themselves, or arch porters (who live in all the aforementioned sections), or test writers (like LTP), or researchers (academic, security, etc...), or the stubbornly curious. i've worn most of these hats at some point in time and have been frustrated way more times than i can remember after trying to follow the man page for a function only to find out the kernel was slightly different. doing `man foo` is a lot easier than going into the kernel and tracking down the actual function's source (and then tracing it through all the various subsystems to see how the diff args get treated). basically i want this: http://thread.gmane.org/gmane.linux.kernel.cross-arch/21821 and i want documentation :). the linux-man-pages project is already filling the critical documentation gap and rather than bootstrap another project, i was hoping we could find some way to integrate. i understand the perfectly reasonable desire to not have to maintain multiple man pages that cover a lot of the same content (upwards of 90%) when the functions are pretty one-to-one in flags/behavior (like the openat() syscall and the openat() C library function). so maybe we need a technical solution to be able to split off the kernel-specific bits ? -mike
Attachment:
signature.asc
Description: This is a digitally signed message part.
