Once upon an API...
Back in 1997, a new system call, prctl(), was added to the Linux kernel. By now that API does many (arguably, too many) different things to a process. But to begin with, it provided just one feature: the ability to allow a child process to request that the kernel sends it a signal when its parent dies (in other words, the converse of the traditional UNIX SIGCHILD signal that is sent to a parent process when one of its children dies). At first, the PR_SET_PDEATHSIG feature seems quite simple. However, when one examines its interactions with various other UNIX and Linux API features, such as threads, signals, and exec, the semantics of this feature turn out to be at times both complex and surprising. Some of those semantics were certainly unintended, and are bizarre enough that, as the Linux man-pages maintainer, I fear documenting them. By looking in detail at this specific example, I’ll explore various pitfalls and lessons we can learn when designing APIs, philosophize a little on the question of who "owns" an API when it comes to defining the semantics of that API, and consider some strategies that can improve the API design process.
Michael Kerrisk is a programmer, writer, and trainer who has a passion for investigating and explaining software systems. He is the author of "The Linux Programming Interface", a widely acclaimed book on Linux (and UNIX) system programming. He has been actively involved in the Linux development community since 2000, operating mainly in the area of testing, design review, and documentation of kernel-user-space interfaces. Since 2004, he has maintained the Linux "man-pages"
project, which provides the primary documentation for Linux system calls and C library functions. Michael is a New Zealander, living in Munich, Germany, from where he operates a training business (man7.org) providing low-level Linux programming courses in Europe, North America, and occasionally further afield.