LinuxCon Europe

I'll be at LinuxCon Europe, 26-28 October, in Prague, Czech Republic. (In fact, I arrive already on Monday, 24 October.) I'll have a few copies of my book, The Linux Programming Interface, with me for sale. If you want to buy a copy (signed even, if you want!), drop me a mail (mtk AT man7.org).

man-pages-3.35 is released

I've released man-pages-3.35. For the moment, the various pieces of the release remain at different locations than usual. The browsable online pages can be found on man7.org; the release tarball is available here on kernel.org.

A git repository for man-pages can be found on github kernel.org.

The most notable changes in man-pages-3.35 are as follows:

• A new recvmmsg(2) page (written by Andi Kleen and me) documents the recvmmsg() system call that was added to Linux back in version 2.6.32.
• A new setns(2) page (written by Eric Biederman) documents the setns() system call that was added in Linux 3.0.
• Various global edits to improve the consistency of terminology used in the man pages.

man-pages-3.34 is released

I've released man-pages-3.34. Again, because of the problems at kernel.org, the various pieces of the release are at different locations than usual (and possibly some of these locations may become permanent). The browsable online pages can be found on man7.org; the release tarball is available here on kernel.org.

A git repository for man-pages can be found on github kernel.org.

The most notable changes in man-pages-3.34 are as follows:

• A new rt_sigqueueinfo(2) documents the rt_sigqueueinfo() and rt_tgsigqueueinfo() system calls. At the same time, the sigqueue() man page was moved from Section 2 to Section 3, since the interface it documents really is a library function (layered on top of rt_sigqueueinfo()).
• New man pages for the cciss(4) and hpsa(4) drivers. Thanks to Stephen Cameron.
• The fstatat(2) man page adds documentation of the AT_NO_AUTOMOUNT flag added in Linux 2.6.38.
• The lseek(2) man page adds documentation of the SEEK_HOLE and SEEK_DATA commands scheduled for the upcoming Linux 3.1. (These commands allow a program to map file holes.)
• The madvise(2) man page adds documentation of the MADV_HUGEPAGE and MADV_NOHUGEPAGE commands added in Linux 2.6.38.
• The feature_test_macros(7) man page adds documentation of the _ISOC95_SOURCE macro added in glibc 2.12

man-pages-3.33 is released

After a long gap, I've released man-pages-3.33. Given the ongoing problems at kernel.org, the various pieces of the release are at different locations than usual (and possibly some of these locations may become permanent). The browsable online pages can be found on man7.org; the release tarball is available here on kernel.org.

A git repository for man-pages can be found on github kernel.org.

The most notable changes in man-pages-3.33 are as follows:

• The sync(2) page adds documentation of the syncfs() system call that was added in Linux 2.6.39.
• The syscalls(2) has been updated to be current as at Linux 3.1.
• The syslog(2) page adds documentation of the CAP_SYSLOG capability added in Linux 2.6.37.

In addition, various fixes were made in many other pages.

Relocated git repository for man-pages

[Note (Mar 2014): the info in the post below is historical. The man-pages git repo long ago returned to kernel.org, see https://www.kernel.org/doc/man-pages/download.html.]

Since kernel.org remains down, I've set up a man-pages git repo on github, at https://github.com/mkerrisk/man-pages. To clone the repo:

  git clone git@github.com:mkerrisk/man-pages.git

I'm undecided yet, but this may become the permanent location of the upstream repository.

Update 2011-10-04: as a couple of people pointed out (and as I noted in some later posts), the better commands for cloning the repo would be:

  git clone git://github.com/mkerrisk/man-pages.git

or:

  git clone https://github.com/mkerrisk/man-pages.git

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.