Man-pages: discovery, feedback loops, and the perfect kernel commit message

Session information has not yet been published for this event.

Refereed Presentation
Scheduled: Friday, November 4, 2016 from 2:00 – 2:45pm in Sweeney F

One Line Summary

How do we discover API changes, test and document them, and make sure they are publicized to everyone, including end users, as far in advance, and as widely, as possible?


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 talk, 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.

Presentation Materials



  • Michael_kerrisk

    Michael Kerrisk

    Linux man-pages project


    Michael Kerrisk is the author of The Linux Programming Interface, a widely acclaimed book on Linux (and UNIX) system programming. His primary involvement with Linux is in testing, design review, and documentation of kernel-user-space interfaces. After 12 years, 16k commits, 173 releases, and over 370 manual pages written or cowritten, he is still the maintainer of the Linux man-pages project. Michael is a New Zealander, living in Munich, Germany.

Leave a private comment to organizers about this proposal