man-pages-3.32 is released

I've uploaded man-pages-3.32 into the release directory (or view the online pages). The most notable changes in man-pages-3.32 are as follows:

• The readv(2) page adds documentation of the preadv() and pwritev() system calls.
• The getrlimit(2) page adds an example of the use of the recently added prlimit() system call.
• A new phread_sigqueue(3) page documents the pthread_sigqueue() library function.

The Linux Programming Interface is released

I'm happy to announce that my book, The Linux Programming Interface (TLPI), is now available. TLPI is a detailed guide and reference for system programming on Linux and UNIX systems, 1552 pages in length, with 115 diagrams, 88 tables, nearly 200 example programs, and over 200 exercises.

The TLPI web site contains the detailed table of contents (PDF or HTML), preface, sample chapters, and index for download. It also provides complete source code for the book (both as a tarball for download and browsable as individual files online). You can find a detailed description of TLPI on the web site here.

A few reviews (all extremely positive) have already appeared. You can find pointers to reviews here.

For information on ordering (a nice way to support the work of the man-pages maintainer!), look here.

(Post updated 2010-11-20, to fix a typo and add a detail to the description.)

man-pages-3.31 is released

I've uploaded man-pages-3.31 into the release directory (or view the online pages). This is a fairly small release. The most notable changes in man-pages-3.31 are as follows:

• The getrlimit(2) man page adds documentation of the prlimit() system call, which was new in Linux 2.6.36.
• The inotify(7) man page adds documentation of the IN_EXCL_UNLINK flag, also new in Linux 2.6.36.
  

System call credential checking (a tale of inconsistency)

While looking at the new prlimit() system call in Linux 2.6.36, I surveyed the various system calls that allow one process to change the operation or attributes of another (arbitrary) process. In general, these system calls require either that the caller is privileged (i.e., has some capability) or that there is a match between the credentials (user or group IDs) of the calling process and the target process.

There's a great deal of inconsistency. As at 2.6.36, here's what we have (in the following, uid means the real UID of the caller, euid means the effective UID, and suid means the saved set-user-ID; a similar convention applies for the group IDs--thus gid, egid, sgid; and a "t-" prefix means the corresponding credentials of the target process):

• setpriority(), sched_setscheduler(), sched_setparam(), sched_setaffinity(): CAP_SYS_NICE || euid == t-uid || euid == t-euid. This is sane: you can make changes to another process if you have the right capability or you own the process--that is, you (i.e., here "you" means the UID currently operated via the effective UID) can change the attributes of a process that was originally created by you (euid == t-uid) or one that has assumed (via the set-user-ID mechanism) your identity (euid == t-euid). POSIX specifies that the checks for setpriority() are uid == t-euid || euid == t-euid; the Linux semantics are arguably saner (and are consistent with historical BSD behavior). POSIX specifies sched_setscheduler() and sched_setparam() but does not specify their permission-checking semantics.
  
• ioprio_set(): CAP_SYS_NICE || uid == t-uid || euid == t-uid. The caller is privileged, or the caller's real or effective UID matches the target process's UID. There's no obvious reason for the inconsistency with setpriority().
• migrate_pages(), move_pages(): CAP_SYS_NICE || uid == t-uid || uid == t-suid || euid == t-uid || euid == t-suid. Like setpriority(), but you can also make changes if your real UID matches target credentials. Again, there's no obvious reason for the inconsistency with setpriority().
• kill(), killpg(): CAP_KILL || uid == t-uid || uid == t-suid || euid == t-uid euid == t-suid. The UID-matching semantics are as required by POSIX: the real or effective UID of the caller must match the real or saved set-user-ID of the target.
  
• prlimit(): CAP_SYS_RESOURCE || (uid == t-uid && uid == t-euid && uid == t-suid) && (gid == t-gid && gid == t-guid && gid == t-sgid). Now we start to get into strange territory. Using CAP_SYS_RESOURCE makes sense, because CAP_SYS_RESOURCE is used for the privilege checks in the setrlimit() system call. However, requiring that all of the UIDs of the target match the real UID of the caller is quite inconsistent with any of the other APIs. Adding an analogous check for the group IDs further compounds the inconsistency.

One thing to note: the behavior of most of the Linux-specific system calls (i.e., ioprio_set(), move_pages(), migrate_pages(), and prlimit()) was documented only after the implementation, which I'd argue was a contributing factor to the inconsistencies described above.

man-pages-3.30 is released

I've uploaded man-pages-3.30 into the release directory (or view the online pages). The most notable changes in man-pages-3.30 are as follows:

• A new kexec_load(2) man page documents the kexec_load() system call. Thanks to Andi Kleen.
  
• A new lio_listio(3) page documents the lio_listio() library function.
  
• The reboot(2) page adds documentation of the LINUX_REBOOT_KEXEC command.
• The unshare(2) page adds documentation of CLONE_NEWIPC, CLONE_NEWNET, CLONE_SYSVSEM, and CLONE_NEWUTS.
• Various consistency fixes were made across a wide range of pages.
  

man-pages-3.29 is released

I've uploaded man-pages-3.29 into the release directory (or view the online pages). The most notable changes in man-pages-3.29 are as follows:

• A new subpage_prot(2) system call documents an ARM-specific system call for setting sub-page protections
• A new aio_init(3) page documents the aio_init() library function.
• The posix_fadvise(2) page adds documentation of the ARM-specific arm_fadvise64_64() system call.
• The sync_file_range(2) page adds documentation of the architecture-specific sync_file_range(2) system call.
• The psignal(3) page adds documentation of the psiginfo() library function.
• The ip(7) page adds descriptions of the IP_RECVORIGDSTADDR, IP_TRANSPARENT, and IP_FREEBIND socket options.
• The unix(7) page adds documentation for the autobind feature and fixes the description of abstract socket names.
  
  

man-pages-3.28 is released

I've uploaded man-pages-3.28 into the release directory (or view the online pages). The most notable changes in man-pages-3.28 are as follows:

• A new getaddrinfo_a(3) page documents the getaddrinfo_a(3), gai_suspend(3), gai_cancel(3), and gai_error(3) library functions. Thanks to Petr Baudis.
• A new aio(7) page provides an overview of the POSIX asynchronous I/O API.
• Various improvements were made to the section 3 pages describing the POSIX asynchronous I/O API: aio_cancel(3), aio_error(3), aio_fsync(3), aio_read(3), aio_return(3), aio_suspend(3) and aio_write(3).
  
• The exec(3) page adds documentation for the execvpe(3) library function.
• Continuing the work of man-pages-3.27, information about feature test macro requirements was improved in various pages.
  

man-pages-3.27 is released

I've uploaded man-pages-3.27 into the release directory (or view the online pages). The most notable changes in man-pages-3.27 are as follows:

• The feature test macro requirements in a large number of pages were updated, either to incorporate changes in recent glibc releases, to fix errors in existing pages, or to add requirements to pages that did not previously document them.
• A new sigevent(7) page documents the sigevent structure that is used by several APIs that provide asynchronous notification. This page was created by extracting out the generic material on sigevent from the timer_create(2) and mq_notify(3) pages. Thanks to Petr Baudis.
• Additional information and an example program were added to the insque(3) page.
• The rand(3) page was expanded, and an example program added.
• The ip(7) manual page adds documentation of the IP_NODEFRAG socket option (new in Linux 2.6.36)
  

I'll be at Linux Kongress

I'll be at the upcoming Linux Kongress, 23-24 September, in Nuremberg, Germany. All going well, I'll be there with copies of my book, The Linux Programming Interface, which I should receive in the coming week. Get in touch with me at mtk-AT-man7.org, if you'll be at the conference and would like to see a copy of the book.

man-pages-3.26 is released

I've uploaded man-pages-3.26 into the release directory (or view the online pages). Mostly, this release consists of minor changes to existing pages. The notable changes in man-pages-3.26 are as follows:

• The eventfd(2) page adds documentation of the EFD_SEMAPHORE flag (new in Linux 2.6.30).
• The tzfile(5) manual page adds documentation of version 2 format timezone files.

Coming soon: The Linux Programming Interface

My book, The Linux Programming Interface, is now just a few days away from leaving the printer. (Most likely, people in the US who order online now will see the book before I even get a copy here in Germany.)

I've built out the content of the book web site with further information about the book, including:

• The table of contents, preface, and index from the book.
• A downloadable sample chapter from the book.
• Complete source code, browsable as individual web pages.
• Source code tarballs containing all of the examples from the book.
  
  

man-pages-3.25 is released

I've uploaded man-pages-3.25 into the release directory (or view the online pages). The most notable changes in man-pages-3.25 are the following:

• A new migrate_pages(2) manual page, written by Andi Kleen, documenting the migrate_pages() system call (added to Linux back in kernel 2.6.16).
  
• A major update of the quotactl(2) manual page. This update incorporates material from the version of this page (mostly written by Jan Kara) that was in the quota-tools package, and also adds new material by me. The quotactl(2) manual page that was in quota-tools has been dropped from that package, so that there is now a single canonical quotactl(2) page--the one in man-pages.
  
• The mkstemp(3) manual page adds descriptions of the mkstemps() and mkostemps() library functions, which were added to glibc in version 2.11.
  
• The fcntl(2) man page adds descriptions of the F_SETPIPE_SZ and F_GETPIPE_SZ operations, which are new in Linux 2.6.35.
  
• The madvise(2) manual page adds descriptions of the following operations: MADV_HWPOISON (new in kernel 2.6.32), MADV_MERGEABLE and MADV_UNMERGEABLE (new in Linux 2.6.32), and MADV_SOFT_OFFLINE (new in Linux 2.6.33).
  
• The prctl(2) manual page adds descriptions of the hardware poison operations (PR_MCE_KILL and PR_MCE_KILL_GET) added in kernel 2.6.32.
  
• The sched_setscheduler(2) manual page adds a description of the SCHED_RESET_ON_FORK flag, which was new in kernel 2.6.32.
  
• The umount(2) manual page adds a description of UMOUNT_NOFOLLOW (new in kernel 2.6.34).
  
• The socket(7) manual page adds descriptions of the read-only socket operations SO_DOMAIN and SO_PROTOCOL, both new in kernel 2.6.32.
  

Book progress

Production of my book, The Linux Programming Interface, which provides a detailed description of Linux and UNIX system programming, has stretched out longer than I and No Starch Press were hoping, but by now we're getting close to the end: the book should appear in June (I'll post more precise dates on my other blog as we get closer to publication date).

In the meantime, I've made the first steps toward building out a web site for the book. Most notably, I've started putting some sample some sample code from the book online. Take a look here to see the code from Chapters 3 to 12, and send me comments at mtk AT man7.org, if you want.

And, we finalized the cover (and, evidently, the subtitle) for the book:



Updated 1 May 2010, to correct email address.

man-pages-3.24 is released

I've uploaded man-pages-3.24 into the release directory (or view the online pages). The most notable changes in man-pages-3.24 are the following:

• The addition of three pages by David Howells describing the kernel key management facility: add_key(2), request_key(2), and keyctl(2). (These pages were formerly part of the keyutils package.)
• The fcntl(2) manual pages adds documention of F_SETOWN_EX and F_GETOWN_EX, which are new in Linux 2.6.32.
• Minor changes to many other pages.