The Linux man-pages project lives on the boundary between two worlds that are not always mutually intelligible: the kernel and user-space programs. One subgoal of that project is to allow the two worlds to hold mutually intelligible conversations. Living on this boundary–testing, reviewing, and documenting the APIs–provides some interesting perspectives on the kernel-user-space interface. In this session, I’ll briefly outline some of the problems that I’ve observed in the design and implementation of kernel-user-space APIs and then look at some of the challenges faced by the man-pages project. (Several of these challenges are faced by other projects that also live at the boundary, such as C libraries, strace, fuzz testers, and various testing projects.) One problem of special interest for me is “the problem of discovery”: how do we even know if the interface has changed, where “change” can range, at one end, from the introduction of a bug, through the addition of a new flag in a system call, and and at, the other end, to the addition of a new system call or /proc file? (In some unfortunate cases, kernel developers do not even realize they’ve made such changes.) Related to “the problem of discovery” is “the problem of the feedback loop”: when (how long) does it take us to discover changes to the interface? I’ll also like to look at (and solicit ideas for) possible solutions to these problems; in particular, to talk about what–from a user-space perspective–the perfect kernel commit message looks like.
Michael Kerrisk, Linux man-pages
[slideshare id=66781629&doc=kr2016-man-pages-discovery-feedback-and-commit-messages-161005203507]