Linux man-pages

LinuxCon Europe

2011-10-20T18:26:00.001+02:00

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

2011-10-04T19:11:00.002+02:00

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.

A git repository for man-pages can be found on github. You can clone the repository with the command:

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

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

2011-09-23T08:05:00.006+02:00

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.

A git repository for man-pages can be found on github. You can clone the repository with the command:

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

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

2011-09-20T12:17:00.002+02:00

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.

A git repository for man-pages can be found on github. You can clone the repository with the command:

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

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

2011-09-20T08:34:00.009+02:00

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

2010-12-05T15:03:00.001+01:00

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

2010-11-17T21:45:00.001+01:00

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

2010-11-14T16:37:00.001+01:00

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)

2010-11-07T08:40:00.005+01:00

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

2010-11-01T19:10:00.001+01:00

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

2010-10-20T13:19:00.001+02:00

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

2010-10-11T09:08:00.001+02:00

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

2010-09-22T19:01:00.001+02:00

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

2010-09-12T16:55:00.003+02:00

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

2010-09-10T21:37:00.002+02:00

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

2010-08-30T18:29:00.002+02:00

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

2010-06-26T15:59:00.001+02:00

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

2010-04-14T23:01:00.002+02:00

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

2010-02-27T16:40:00.002+01:00

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.

man-pages-3.23 release; my book progresses

2009-10-03T07:45:00.003+02:00

I've uploaded man-pages-3.23 into the release directory (or view the online pages). This release consists entirely of fixes to existing pages.

Meanwhile, progress continues on my book providing a detailed description of Linux and Unix system programming. We now have a title: The Linux Programming Interface. I've also posted the detailed table of contents of chapters 1 to 42. (Full list of chapters here; draft preface here.)

See you at LCA 2010!

2009-09-28T14:04:00.001+02:00

One of my proposals got accepted for LCA 2010, in Wellington, New Zealand! As usual, there look to be lots of interesting papers at LCA. I'm presenting a tutorial on writing secure privileged programs, which will draw heavily on Chapter 38 of my book.

What to call my book?

2009-09-10T19:54:00.003+02:00

We (me, my publisher) are still trying to work out what to call my (lengthy) system programming book. On my other blog, I'm asking for opinions from potential readers. If you'd like to help me name my book, please have a read of that blog post and send me a vote!

System programming book now half-way through copyediting

2009-09-06T09:35:00.001+02:00

My book on Lunux/Unix system programming is now more than half-way through copyediting, so I've posted the detailed table of contents of the first 33 chapters. (For an overview of the book, look here, and to see the brief table of contents--chapter names only--look here.)

We're still on schedule for the book to be published in the first half of 2010 (by No Starch Press). Ongoing progress towards publication is regularly updated at blog.man7.org.

Please keep telling people about the book and the blog!

A different story: my book

2009-07-27T22:30:00.000+02:00

For quite a long time now, I've been working on a book that covers much the same topic area as man-pages; that is, the Linux/Unix kernel-userland interface (system calls, /proc, and so on) and C library (glibc) functions.

The book is going to be comprehensive: it runs to around 1500 pages (exactly how long will depend on typesetting and page layout, which are just getting started), has 64 chapters, 116 diagrams, 85 tables, and around 250 example programs. It will be published in the first half of 2010 by No Starch Press. You can read about its ongoing progress towards publication in my other blog at blog.man7.org. To get an overview of what the book is about, read this post, and to see the table of contents of the book, read this post.

And of course, please tell people about the book!

man-pages-3.22 is released

2009-07-25T20:38:00.001+02:00

After a long gap without a release, I've uploaded man-pages-3.22 into the release directory (or view the online pages). This release consists entirely of fixes to existing pages.

man-pages-3.21 is released

2009-04-20T20:01:00.001+02:00

A few days ago, I uploaded man-pages-3.21 into the release directory (or view the online pages). Notable changes in man-pages-3.21 are:

A new pthread_setconcurrency(3) page documents pthread_setconcurrency() and pthread_getconcurrency().
A new pthread_yield(3) page documents pthread_yield().
The feature_test_macro(7) page adds information on the changes that glibc 2.10 makes for alignment with POSIX.1-2008, and adds an example program that can be used to display the feature test macros that are implicitly defined by particular glibc versions and as a consequence of explicitly setting macros.

Living with options, Los Gatos

man-pages-3.20 is released

2009-03-30T23:45:00.000+02:00

I've uploaded man-pages-3.20 into the release directory (or view the online pages). Notable changes in man-pages-3.20 are:

The addition of cpuid(4) and msr(4) device man pages (thanks to Andi Kleen)
Numerous fixes to other pages.

Te whare karakia i Onuku, Ōtautahi

man-pages-3.19 is released

2009-02-25T03:17:00.001+01:00

I've uploaded man-pages-3.19 into the release directory (or view the online pages). The most notable change in man-pages-3.19 is the addition of four pages describing the POSIX interval timers API: timer_create(2), timer_settime(2), timer_getoverrun(2), and timer_delete(2).

man-pages-3.18 is released

2009-02-11T01:47:00.003+01:00

I've uploaded man-pages-3.18 (my one hundredth release as maintainer!) into the release directory (or view the online pages). Notable changes in man-pages-3.18 are:

4 new pages describing character sets: armscii-8(7), iso_8859-11(7), iso_8859-4(7), and iso _8859-6(7). Thanks once again to Lefteris Dimitroulakis for contributing!

A new pthread_kill(3) page documents pthread_kill().

A new pthread_kill_other_threads_np(3) page documents pthread_kill_other_threads_np().

A new pthread_sigmask(3) page documents pthread_sigmask().

The clock_getres(2) page was moved from Section 3 to Section 2 (since the interfaces it describes really are system calls, not library functions), and adds a description of CLOCK_MONOTONIC_RAW, new in 2.6.28.

Some bugs were fixed in select_tut(2) and many changes and tidy-ups were made to the text.

linux.conf.au 2010 in Wellington

2009-01-23T21:34:00.002+01:00

For it's 11th time out, linux.conf.au returns to New Zealand again in 2010. (YAY!!) Congratulations to the successful bidders from Wellington! The conference will run from Monday 18 January to Saturday 23 January. The organizers' website is http://www.penguinsvisiting.org.nz/.

Speaking at LCA 2009

2009-01-20T04:52:00.004+01:00

Late notice (but that's all I got)... I'll be speaking at LCA 2009 in Hobart, Australia, on 22 Jan, considering what happens when kernel and userland don't talk.

Update: my presentation slides can be found here.

man-pages-3.17 is released

2009-01-19T06:32:00.001+01:00

I've uploaded man-pages-3.17 into the release directory (or view the online pages). Notable changes in man-pages-3.17 are:

A new endian(3) page documents functions added in glibc 2.9 that convert between host byte order and little- and big-endian order: htobe16(), htole16(), be16toh(), le16toh(), htobe32(), htole32(), be32toh(), le32toh(), htobe64(), htole64(), be64toh(), and le64toh().

A new getifaddrs(3) page documents the getifaddrs() and freeifaddrs() library functions.

8 new pages describe various character sets: cp1251(7), iso-8859-10(7), iso_8859-13(7), iso_8859-14(7), iso_8859-3(7), iso_8859-5(7), iso_8859-8(7), and koi8-u(7). Thanks to Lefteris Dimitroulakis for contributing these!

And various smaller changes in many other pages.

Tasmanian Devil

man-pages-3.16 is released

2009-01-12T23:05:00.000+01:00

I've uploaded man-pages-3.16 into the release directory (or view the online pages). Notable changes in man-pages-3.16 are:

A new pthread_getcpuclockid(3) page documents pthread_getcpuclockid().
A new libc(7) page provides an overview of the standard C library implementations on Linux.
A new rtld-audit(7) page provides an overview of the dynamic linker auditing API (modeled on the Solaris API): the functions la_version(), la_objsearch(), la_activity(), la_objopen(), la_objclose(), la_preinit(), la_symbind(), la_pltenter(), and la_pltexit().
The ld.so(8) page adds documentation of the LD_AUDIT and LD_POINTER_GUARD environment variables.

See you at LCA 2009

2009-01-06T18:56:00.006+01:00

It's too much fun to miss, so I finally made the booking... I'm going to LCA 2009 (19-24 Jan), in Hobart, Australia!

man-pages-3.15 is released

2008-12-05T23:30:00.002+01:00

I've uploaded man-pages-3.15 into the release directory (or view the online pages). Notable changes in man-pages-3.15 are:

A new makedev(3) page documents the makedev(), major(), and minor() macros used to manipulate device IDs.
A new pthread_cleanup_push_defer_np(3) page documents pthread_cleanup_push_defer_np() and pthread_cleanup_pop_restore_np().
The accept(2) page adds documentation of the new accept4() system call (coming in Linux 2.6.28)
The fmemopen(3) page adds a description of open_wmemstream(3).
The tcp(7) page adds a description of the use of the MSG_TRUNC flag for retrieving data from a TCP socket.
Many updates to the atexit(3) page.
Updates to many other pages

Special thanks to Petr Baudis for a lot of patches that went into this release.

Caballito del diablo ("Devil's little horse")

Linux Foundation fellowship, 6 months in

2008-12-03T11:50:00.005+01:00

Not quite 6 months since I started the Linux Foundation fellowship, it's time to analyze and reflect on what has (or hasn't) been accomplished.

Some statistics

I took over maintainership of man-pages at the start of November 2004, with the first release being man-pages-2.00. From then until the fellowship started in the middle of May this year (a period of 185 weeks), I probably spent between 0 and 2.5 days a week on man-pages, most of it done as private, volunteer work. (For a period of around a year, I probably managed up about half day a week as part of my day job; thanks Google!) I'd guess it was a bit better than day a week on average (let's say 1.25 days), and we could roughly estimate that as the equivalent of 45 working weeks.

Since the fellowship started, I've worked for about 25 weeks on man-pages; that is, somewhat more than half of the estimated time that I spent on man-pages in the preceding 3.5 years. The first release during my tenure of the fellowship was man-pages-2.80, and since then there have been 15 more (man-pages-3.00 through man-pages-3.14).

What I'm expecting is that the limiting factor in the progress of man-pages is the availability of my time. If I get to work at around four times the rate I did before, then we should see a corresponding increase in the progress of man-pages. Very roughly, in the last 6 months, progress should have been somewhat more than 50% of what it was in the previous 3.5 years.So here's a first comparison:

Period	Number of releases
Pre-fellowship	80
During fellowship	16

Well, that doesn't look so good. But there's no question that there's more work going on for each release nowadays. Here's another simple statistic, derived from the commit logs:

Period	Number of commits
Pre-fellowship	3610
During fellowship	1852

Commits in the last 6 months were nearly 50% of the total during the previous 3.5 years. That seems roughly in line with expectations, and supports the theory that there's a lot more work going into each man-pages release nowadays. Of course, commits vary a lot in size, ranging from a spelling fix, to a complete new page, and going through to some of the enormous global formatting fixes that took place in the man-pages-2.* series, so this is a very rough measure. (One of the commits cleaning up source files layout in man-pages-2.47 had a diff size of more than 60000 lines(!). There were many other large formatting commits in the man-pages-2.*, which is why trying to compare the volume of diffs before and during the fellowship doesn't produce a useful metric.)Another rough measure is how many man pages were added to the set over time:

Period	Number of new pages added
Pre-fellowship	93
During fellowship	56

Again, that's roughly in line with expectations, with the number of pages added during the fellowship being somewhat more than 50% of the previous period.

But where did the new pages come from?

Period	By mtk	By others	By mtk + other(s)	Imports
Pre-fellowship	52	22	13	6
During fellowship	50	4	1	1

"mtk" is me. "Other(s)" is someone else. "Imports" are pages under a free license that I scooped up from some other source (e.g., found on the net, in a distro, or in BSD).

On the negative side, I wrote the vast majority of new pages that have been added so far during the fellowship. On the positive side, Paul Jackson contributed the single biggest page, cpuset(7), which became the fourth largest page in man-pages. (Also worth noting: in the man-pages-2.* releases, a total of 28 pages were deleted, mainly obsolete pages in Section 1.) In fact, I had hoped to be able to get even more pages written, but other tasks, such as testing, API review, and kernel patches have also taken up a significant fraction of my time during the fellowship. When considered as a (calendar) monthly rate, contributions of new pages by others are, unfortunately, essentially unchanged since before the fellowship.

So, progress towards improving contributions by others, at least in terms of new pages, has not been good. However, my gut feeling has been that more people are actually contributing to man-pages than before: the fact that there is a full-time maintainer means people are rather more likely to send bug reports, suggestions, and patches for existing pages. Here's a statistic that bears it out:

Period	Average contributors/week
Pre-fellowship	2.8
During fellowship	5.9

This was calculated by summing the number of contributors in each of the change logs in all of the releases over the two periods and then dividing by the number of calendar weeks in each period (185 and 28 respectively). 5.9 contributors per week is still much lower than I'd like, but my feeling is that the rate has increased steadily over the time of the fellowship, so that the current rate is already higher than 5.9, and set to increase further. (Another factor that may also have helped boost the number of reports is that in December 2007 I started adding a COLOPHON to each man page describing how to report bugs, and this change would have filtered into distribution CDs a few months later.)

Timeliness of documentation

Things have defintely got better during the fellowship. Most additions and changes to the kernel-userland interface during the time of the fellowship have been documented in man-pages pretty much as they occur. (This contrasts with earlier times, where interface changes have sometimes been followed only months (or in extreme cases years) later by man page updates.) Most notably, Ulrich Drepper's new system calls in Linux 2.6.27 saw man pages go out a few days after the release of that kernel.

Testing and bug reporting

I've done a fair bit of this over the course of the fellowship. Most new system calls and system call extensions got tested by me before they hit mainline. This uncovered a few bugs which were then fixed. The biggest single piece of work here was for the utimensat(2) system call, producing a test suite (later integrated into LTP), along with patches that fixed the 5 or so bugs in the interface (details here).

Many existing glibc functions also got tested as I updated the man pages for them. Most notably, updates to the man pages produced about 35 bug reports related to error reporting by the math functions. The addition of man pages for various pthreads functions has also been accompanied by a lot of testing, and a half dozen or so bug reports.

API design review

Most new system calls and system call extensions got reviewed before going into mainline. (My record on other kernel interfaces, such as /proc files, was a more spotty though.) Among other things, this resulted in a redesign of the proposed extension of the accept() system call (originally proposed as paccept(), with a signal set argument whose necessity was dubious, later revised to accept4(), which should appear in kernel 2.6.28).

Miscellaneous

A summary of other man-pages work that I've done during the time of the fellowship:

man-pages moved from a private Subversion repository to a public git repository on kernel.org.

In general, I'm blogging a bit more actively nowadays, and in addition to posts summarizing releases, there have been longer posts on topics such as: problems with kernel-userland interface design and implementation; the state of error reporting for glibc's math functions; and a few articles describing or summarizing Linux kernel-userland interface changes.

After my presentation at LPC for the kernel-userland interface track, I finally got round to an idea I'd been considering for a while: creating the linux-api mailing list. The rationale for the list is that all patches that cause API/ABI changes should be CCed to the list, so that the many parties who are interested in API/ABI changes (e.g., man-pages, LSB, libc developers, kernel developers, testers such as the folk at LTP, and of course userland developers) can get an idea of what's going on. Most people still don't read Documentation/SubmitChecklist, to know they should be using this list, so I try to regularly chase people to use it (and some others also help in that regard), and by now at least some people do so without prompting.

I've helped out LSB on a number of occasions, filing a few bug reports against the spec, but also helping out by writing man pages for functions that they wanted to specify that were currently undocumented (see, e.g., here and here). This resulted in new man pages such as getprotoent_r(3), getservent_r(3), getnetent_r(3), and pthread_getattr_np().

I continue to respond to many bug reports in the manpages and manpages-dev components of Debian's bug tracking system. This has mutual benefits: on the one hand, although I'm not actually a member of Debian, I'm by far the most active fixer of their bug reports; on the other hand, most Debian bug reports for man pages really apply to the upstream pages (I ignore the ones that don't), and so the reports provide a valuable source of pointers to things that need fixing in man-pages. A big thank you to Debian users, who produce far more (and more useful) man-pages bug reports than all of the other distributions put together!

Working on man-pages led me to find various deficiencies in POSIX.1 specifications, resulting in around a half dozen bug reports to the Austin group.

Mariposa

Publish Post

man-pages-3.14 is released

2008-11-25T22:40:00.000+01:00

I've uploaded man-pages-3.14 into the release directo ry (or view the online pages). Notable changes in man-pages-3.14 are:

A new CPU_SET(3) page documents the CPU_* macros used for manipulating CPU sets (the cpu_set_t data structure used by sched_setaffinity(2), pthread_attr_setaffinity_np(3), and pthread_setaffinity_np(3)).
More man pages for POSIX threads library functions: 5 new pages documenting 8 functions

pthread_attr_setinheritsched(3) (includes documentation of pthread_attr_getinheritsched())
pthread_cancel(3)
pthread_cleanup_push(3) (includes documentation of pthread_cleanup_pop())
pthread_setcancelstate(3) (includes documentation of pthread_setcanceltype())
pthread_testcancel(3)

clone(2) adds documentation of the CLONE_NEWNET, CLONE_NEWUTS, CLONE_NEWPID, and CLONE_IPC flags.
mmap(2) adds documentation of the MAP_STACK flag.
arp(7) adds documentation of a few preously undocumented /proc files.
icmp(7) adds documentation of a few previously undocumented /proc files.
tcp(7) adds documentation of many previously undocumented /proc files.
udp(7) adds documentation of a few previously undocumented /proc files.
pthreads(7) adds lists of functions that POSIX.1 specifies are and may be cancellation points.

Lagarto

man-pages-3.13 is released

2008-11-07T14:27:00.003+01:00

I've uploaded man-pages-3.13 into the release directo ry (or view the online pages). Notable changes in man-pages-3.13 are:

More man pages for POSIX threads library functions: 6 new pages documenting 11 functions.
- pthread_attr_setaffinity_np(3) (includes documentation of pthread_attr_getaffinity_np(3))
- pthread_attr_setschedparam(3) (includes documentation of pthread_attr_getschedparam(3))
- pthread_attr_setschedpolicy(3) (includes documentation of pthread_attr_getschedpolicy(3))
- pthread_setaffinity_np(3) (includes documentation of pthread_getaffinity_np(3))
- pthread_setschedparam(3) (includes documentation of pthread_getschedparam(3))
- pthread_setschedprio(3)
Various fixes and improvements to the example program in epoll(7).

Saltamontes, intentando evitarme

Recent changes in file descriptor system calls

2008-10-30T16:26:00.011+01:00

In recent Linux kernels, especially 2.6.27, a number of system calls have changed, or new versions of existing system calls have been added, to allow more control over the file descriptors created by those system calls. (Most of this work has been done by Ulrich Drepper.) These changes have taken the form of either adding new bits to the flags bit-mask argument of an existing system call, if it had such an argument, or creating a new version of the system call that adds an extra flags argument. In most cases, two new flags have been added: a close-on-exec flag, and a non-blocking flag, which we describe shortly.

The changes are summarized in the table below. In this table, the Kernel column indicates the kernel version where the change occurred, and the Glibc column indicates the version of glibc that adds the corresponding wrapper functions and/or header file definitions. (Note: glibc 2.9 is not yet released.)

Interface	Changes	Kernel	Glibc	Notes
open(2)	New flag: O_CLOEXEC	2.6.23	2.7	Flag also supported for openat(2). These syscalls already supported O_NONBLOCK.
fcntl(2)	New flag: F_DUPFD_CLOEXEC	2.6.24	2.7	Performs a similar task to dup3(2)
recvmsg(2)	New flag: MSG_CMSG_CLOEXEC	2.6.23	2.7	-
dup3(2)	New syscall, like dup2(2), but adds flags argument (O_CLOEXEC)	2.6.27	2.9	Requires new glibc interface
pipe2(2)	New syscall, like pipe(2), but adds flags argument: O_CLOEXEC, O_NONBLOCK	2.6.27	2.9	Requires new glibc interface
socket(2)	New flags in type argument: SOCK_CLOEXEC, SOCK_NONBLOCK	2.6.27	2.9	-
socketpair(2)	New flags in type argument: SOCK_CLOEXEC, SOCK_NONBLOCK	2.6.27	2.9	-
epoll_create1(2)	New syscall, like epoll_create(2), but adds flags argument: EPOLL_CLOEXEC; the new system call drops epoll_create()'s obsolete size argument	2.6.27	2.9	Requires new glibc interface
inotify_init1(2)	New syscall, like inotify_init(2), but adds flags argument: IN_CLOEXEC, IN_NONBLOCK	2.6.27	2.9	Requires new glibc interface
eventfd2(2)	New syscall, like eventfd(2), but adds flags argument: EFD_CLOEXEC, EFD_NONBLOCK	2.6.27	2.9	The glibc eventfd() wrapper already allowed a flags argument, so no new wrapper is required
signalfd4(2)	New syscall, like signalfd(2), but adds flags argument: SFD_CLOEXEC, SFD_NONBLOCK	2.6.27	2.9	The glibc signalfd() wrapper already allowed a flags argument, so no new wrapper is required
timerfd_create(2)	New flags: TFD_CLOEXEC, TFD_NONBLOCK	2.6.27	2.9	-

A proposed analogous change for accept(2), paccept(), supporting flags SOCK_CLOEXEC and SOCK_NONBLOCK and treatment of a signal mask argument like pselect(2), was debated and then spent some time in limbo, but has recently re-emerged in a somewhat modified form, accept4() (which was in fact the original proposal), that will probably go into Linux 2.6.28 or 2.6.29.

Perhaps one day there might even be an analogous change for mq_notify(3), since (on Linux, but not on most other systems) a message queue descriptor is really just a file descriptor.

The close-on-exec flag (*_CLOEXEC)

The addition of a close-on-exec flag was the primary motivator for the system call changes. Specifying this flag causes the file descriptor created by the system call to automatically have its close-on-exec flag set. (This flag causes the file descriptor to automatically be closed if the process does a successful execve(2).)

Before the existence of this flag, it was possible to change the close-on-exec flag of a file descriptor after it has been created, using the fcntl(2) F_GETFL and F_SETFL operations. The fact that this required two additional system calls was not so problematic as the fact that the need for multiple (non-atomic) steps to set the flag on a new file descriptor meant that there were certain race conditions that could lead to races in multithreaded programs where one thread was trying to set a file descriptor's close-on-exec flag at the same time as another thread was performing a fork() plus execve(). Ulrich Drepper explains the resulting security issues in more detail.

The non-blocking flag (*_NONBLOCK)

The *_NONBLOCK flag causes the non-blocking flag to be set on the open file description associated with the new file descriptor. (For a discussion of the relationship of a file descriptor to an open file description, see the open(2) man page.)

Unlike the *_CLOEXEC flag, the *_NONBLOCK flag exists merely as a convenience: it saves two system call operations (fcntl(2) F_GETFL and F_SETFL) if we want to immediately set the non-blocking flag when opening a file descriptor.

Note that there deliberately is no *_NONBLOCK flag for dup3(2). This would not be sensible, since the new file descriptor shares an open file description with the old file descriptor.

There is also deliberately no *_NONBLOCK flag for epoll_create1(2), since equivalent functionality can be obtained with a zero timeout.

Other flags?

The flags argument added for the new system calls allows for other kinds of functionality to be added to these system calls in the future.

Future standards?

Ulrich Drepper already did some work on getting some of these interface changes into the POSIX.1-2008 standard, which includes specifications of the O_CLOEXEC flag for open() and the F_DUPFD_CLOEXEC operation for fcntl(). In the future, some the other changes may also make their way into the standard.

A note on the new system call names

The numbers in the names of the new system calls refer to the number of arguments that each system call has. This is an extension of a convention that was used for some existing Unix system calls, notably dup2(2), wait3(2), and wait4(2). Note that while the wrapper function for signalfd(2) has three arguments, the underlying signalfd4() system call really does have four arguments, as described in the man page. (However, this suggests that, in the end, this naming scheme might not have been the best choice.)

man-pages-3.12 is released

2008-10-30T03:28:00.010+01:00

I've uploaded man-pages-3.12 into the release directory (or view the online pages). Notable changes in man-pages-3.12 are:

Documentation is added for a set of new and changed system calls (which will be the subject of a future post) that extend the functionality of existing system calls that work with file descriptors. (The changes occurred in kernel 2.6.27.) The new and modified system calls add flags that allow the close-on-exec file descriptor flag to be set, and the non-blocking file status to be set on a file description, as the file is opened. The modified pages are:

dup(2) adds a description of the new dup3() system call.
epoll_create(2) adds a description of the new epoll_create1() system call.
eventfd(2) adds a description of the new eventfd2() system call.
inotify_init(2) adds a description of the new inotify_init1() system call.
pipe(2) adds a description of the new pipe2() system call.
signalfd(2) adds a description of the new signalfd4() system call.
socket(2) and socketpair(2) add a description of the new SOCK_CLOEXEC and SOCK_NONBLOCK flags.
timerfd_create(2) adds a description of the new TFD_CLOEXEC and TFD_NONBLOCK flags.

A start has been made on providing man pages for the POSIX threads library functions: 15 new pages documenting 23 functions.
- pthread_attr_init(3) (includes documentation of pthread_attr_destroy(3))
- pthread_attr_setdetachstate(3) (includes documentation of pthread_attr_getdetachstate(3))
- pthread_attr_setguardsize(3) (includes documentation of pthread_attr_getguardsize(3))
- pthread_attr_setscope(3) (includes documentation of pthread_attr_getscope(3))
- pthread_attr_setstacki(3) (includes documentation of pthread_attr_getstack(3))
- pthread_attr_setstackaddr(3) (includes documentation of pthread_attr_getstackaddr(3))
- pthread_attr_setstacksize(3) (includes documentation of pthread_attr_getstacksize(3))
- pthread_create(3)
- pthread_detach(3)
- pthread_equal(3)
- pthread_exit(3)
- pthread_getattr_np(3)
- pthread_join(3)
- pthread_self(3)
- pthread_tryjoin_np(3) (includes documentation of pthread_timedjoin_np(3))
Many details were added to, or fixed in, ld.so(8).

El jardín de la casa

man-pages-3.11 is released

2008-10-07T11:30:00.001+02:00

I've uploaded man-pages-3.11 into the release directory (or view the online pages). Notable changes in man-pages-3.11 are:

A new umount(2) page has been created by splitting the umount() and umount2() material out of the old mount(2) page.
The mount(2) page adds a description of per-process namespaces.
Various fixes and improvements in getdents(2), including the addition of an example program.
Many improvements and additions in signal(7), the page that provides an overview of signals on Linux.
Numerous fixes to many other pages.

man-pages-3.10 is released

2008-09-24T11:04:00.002+02:00

I've uploaded man-pages-3.10 into the release directory (or view the online pages). This is a fairly light release; conferences, and learning and changing my workflow for git have take a bit of time lately. Notable changes in man-pages-3.10 are:

The clone(2) and getpid(2) pages add some notes and details of the consequences of the PID caching performed by glibc's getpid() wrapper function.
Various changes to services(5), including removing various out-of-date pieces of text.

git update

2008-09-18T17:14:00.002+02:00

I updated my previous post, mainly to add the details required to import subversion tags into git. If you cloned the repository that I put up at kernel.org about a week ago, you'll need to re-clone. (Sorry!)

The timing has been good. Primed and ready to start learning more about git, I got to join a sizable crowd at the Linux Plumbers Conference to see Linus giving a highly informative and entertaining tutorial on git.

man-pages goes git (at last!)

2008-09-11T10:44:00.041+02:00

[Update: 19 Sep 2008: when I first attempted the git import, I didn't import the subversion tags into git. I've updated and expanded this post to include the required details to do that.]

When I inherited man-pages, there was no version control system (VCS) in use. To help myself keep track of changes, I've been running a private subversion repository since I took over as maintainer (i.e., since man-pages-2.00), but I never got round to hosting it on a public server so that people could pull from it (requests for such a facility were only occasional). Instead, people wanting to send patches would just grab the latest tarball from the downloads directory, patch the required source file, and email me the patch.

Somewhat more frequent requests for a public repository, and the fact that the Linux world is nowadays mostly oriented around the git distributed version control system, have gradually created a pressure to change things. So, I'm taking baby steps towards using git for man-pages. Here goes...

Importing from subversion to git

I found the Simplistic Complexity blog's simple instructions on subversion-to-git migration quite useful (though it didn't supply all of the details I needed for importing subversion tags).

My subversion repository had a somewhat non-standard layout, which affected the options (see the git svn init command below) that I needed to do an import that included my subversion tags. (Thanks to various people on the git mailing list who helped me find the right way to do things, especially Björn Steinbrink and Michael Gruber.) The following subversion commands give an idea of the layout:

$ svn list file:///home/mtk/man-pages-rep
branches/
tags/
trunk/
$ svn list file:///home/mtk/man-pages-rep/trunk
man-pages/
$ svn list file:///home/mtk/man-pages-rep/trunk/man-pages
Changes
Changes.old
Makefile
README
...
man7/
man8/
scripts/
$ svn list file:///home/mtk/man-pages-rep/tags
man-pages-2.00/
man-pages-2.01/
...
man-pages-3.08/
man-pages-3.09/
$ svn list file:///home/mtk/man-pages-rep/tags
man-pages-2.00
man-pages-2.01
...
man-pages-3.08
man-pages-3.09
$ svn list file:///home/mtk/man-pages-rep/tags/man-pages-2.00
man-pages
$ svn list file:///home/mtk/man-pages-rep/tags/man-pages-2.01
man-pages
[and so on]
$ svn list file:///home/mtk/man-pages-rep/branches
$
[i.e., no branches, since this has been a linear svn repo.]

Set up an empty, temporary git repository, in the process informing git about the location of the subversion repository from which the import should be done:

$ cd $HOME
$ mkdir man-pages-git-tmp
$ cd man-pages-git-tmp
$ git svn init file:///home/mtk/man-pages-rep/ \
                    -T trunk/man-pages \
                    -b branches/*/man-pages
                    -t tags/*/man-pages
                    --no-metadata
Initialized empty Git repository in .git/

Tell git about the names of users in the subversion commit logs. Because the subversion repository was private (I just took other people's emailed input and made changes as required), I'm the only user. That means that the historical information in the repository will be bogus, suggesting that I'm responsible for all of the nearly 5000 commits to the repository, when it's probably more like 75%. My apologies to everyone else. Something like the true story for man-pages 2.00 through to 3.09 can be found here.

$ cat > ~/users.txt
mtk = Michael Kerrisk
^D
$ git config svn.authorsfile ~/users.txt

Do the import:

$ time git svn fetch
[...]
        M Changes
r4917 = 93a6e8f9ee5d0710a084425548775348389e2900 (git-svn)
Checking out files: 100% (1925/1925), done.
Checked out HEAD:
  file:///home/mtk/man-pages-rep/trunk/man-pages r4917

real 70m24.850s
user 14m46.571s
sys 22m29.852s

And yes, I definitely need some faster hardware...

At this point, git branch -a showed that I had imported the subversion tags into git. But the tags still need to be turned into proper git tags. This requires a command for each tag, which can be automated in a script. (Thanks to Heikki Orsila who pointed out to me that this step was required, and who supplied the script.)

$ cat git-svn-tags.sh
#!/bin/sh
#
git branch -a | grep tags/ | while read tag ; do
  tagname=$(echo $tag | cut -d/ -f2)
  commit=$(git rev-parse $tag)
  res=$(git log master | grep "^commit $commit")
  if test -z "$res" ; then
      # take the parent commit for the tag commit (found in master)
      commit=$(git rev-parse $tag^)
  fi
  echo $tagname $commit
  git tag -a $tagname $commit -m "This is $tagname"
done

$ sh ~/git-svn-tags.sh
man-pages-2.00 105a35bc69bd3088d69f5d3c94d22e6595e223d2
man-pages-2.01 972a9aee950d4df97cc1f81147b64fe52007dfc7
...
man-pages-3.08 5c8cbdc1b2c9b5a1ebb8626361ea01cb73965636
man-pages-3.09 81468e1308f643ffd5718809379c074ff75dc311
$ git tag -l
man-pages-2.00
man-pages-2.01
...
man-pages-3.08
man-pages-3.09

Clone the temporary repository, to produce a clean repository from which any lingering cruft that was used to support git svn has been removed:

$ git clone man-pages-git-tmp man-pages-git
Initialized empty Git repository in /home/mtk/man-pages-git/.git/
0 blocks

And then run a garbage collection to clean up any remaining unneeded files, and otherwise improve the efficiency of the repository:

$ git gc
Counting objects: 36341, done.
Compressing objects: 100% (12059/12059), done.
Writing objects: 100% (36341/36341), done.
Total 36341 (delta 29117), reused 29623 (delta 23595)

Hosting the git repository on kernel.org

The public git repository is to be hosted on kernel.org. Quite a while back the admins there already set up a location for a man-pages git repository. Jeremy Kerr kindly held my hand through the hurdles of the initial set up.

On kernel.org, the admins assigned man-pages a repository location of /pub/scm/docs/man-pages. So, let's create an empty repository there:

$ ssh mtk@master.kernel.org
mtk@master.kernel.org's password:
[mtk@hera man-pages]$ cd /pub/scm/docs/man-pages
[mtk@hera man-pages]$ git init
[mtk@hera man-pages]$ mv .git/ man-pages.git
[mtk@hera man-pages]$ exit

Back on my local machine, modify the git repository's config file so that I can write simple git push commands to push changes onto the kernel.org repository

$ cat >> ~/man-pages-git/.git/config
[remote "kernel.org"]
        url = ssh://master.kernel.org/pub/scm/docs/man-pages/man-pages.git
        push = +refs/heads/master:refs/heads/master

And then do the push to kernel.org:

$ cd $HOME/man-pages-git
$ git push kernel.org
mtk@master.kernel.org's password:
Counting objects: 36341, done.
Compressing objects: 100% (12059/12059), done.
Writing objects: 100% (36341/36341), 8.62 MiB 681 KiB/s, done.
Total 36341 (delta 29117), reused 29623 (delta 23595)
To ssh://master.kernel.org/pub/scm/docs/man-pages/man-pages.git
 * [new branch] master -> master

Log into kernel.org and give the repository a public description:

$ ssh mtk@master.kernel.org
mtk@master.kernel.org's password:
[mtk@hera man-pages]$ cat > /pub/scm/docs/man-pages/man-pages.git/description
Man pages for Linux kernel and glibc APIs
^D
[mtk@hera man-pages]$ exit

And then we have the repository visible and ready for use at http://git.kernel.org/, and you can clone it using the following command:

$ git clone git://git.kernel.org/pub/scm/docs/man-pages/man-pages.git

PS In case it's not clear: only use git to submit changes to man-pages if that's your preference. It's still possible to submit patches the good old-fashioned way, by grabbing the latest release (tarballs will continue to be released as usual every week or two), editing the required source file(s), and sending me a diff -u patch by email.

man-pages-3.09 is released

2008-09-10T15:55:00.006+02:00

I've uploaded man-pages-3.09 into the release directory (or view the online pages). Notable changes in man-pages-3.09 are:

A new fopencookie(3) page, documents a library function that allows a custom implementation of a stdio stream.
A new networks(5) page (adopted from Debian) documents the /etc/networks file.
Feature test macro requirements were added or fixed for various pages.
Many parts of the hsearch(3) man page were fixed and rewritten.

Dan Jacobson remarked that people who read the COLOPHON at the end of each man page may have a kernel or glibc bug to report, rather than a man-pages bug report, but that following the URL in the COLOPHON only leads to a page describing how to report documentation bugs. So, I wrote a new page giving some pointers about reporting kernel and glibc bugs, and that page is linked from the man-pages reporting bugs page.

Fast fertig auf da Wiesn

man-pages-3.08 is released

2008-08-27T15:22:00.005+02:00

I've uploaded man-pages-3.08 into the release directory (or view the online pages). Notable changes in man-pages-3.08 are:

A new numa(7) page gives an overview of the Linux NUMA interfaces.
A new getnetent_r(3) page documents getnetent_r(), getnetbyname_r(), and getnetbyaddr_r(), the reentrant equivalents of getnetent(), getnetbyname(), and getnetbyaddr().
A new getprotoent_r(3) page documents getprotoent_r(), getprotobyname_r(), and getprotobynumber_r(), the reentrant equivalents of getprotoent(), getprotobyname(), and getprotobynumber().
A new getrpcent_r(3) page documents getrpcent_r(), getrpcbyname_r(), and
getrpcbynumber_r(), the reentrant equivalents of getrpcent(), getrpcbyname(), and getrpcbynumber().
A new getservent_r(3) page documents documents getservent_r(), getservbyname_r(), and getservbyport_r(), the reentrant equivalents of getservent(), getservbyname(), and getservbyport().
Further updates related to changes in the recently approved POSIX.1-2008 standard.

Speaking at LPC

2008-08-15T05:09:00.005+02:00

My paper for Linux Plumbers Conference (16-19 September, Portland, OR) got accepted :-). I'll be considering the question: Who owns the interface?

man-pages-3.07 is released

2008-08-12T14:33:00.009+02:00

I've uploaded man-pages-3.07 into the release directory (or view the online pages). Notable changes in man-pages-3.07 are:

A new move_pages(2) page, written by Christoph Lameter, documents the move_pages() system call. This page was formerly part of the numactl package, but has been revised and moved into man-pages (its natural home, since it is a kernel interface).
A new clock_getcpuclockid(3) page describes the clock_getcpuclockid() library function.
A new udplite(7) page, written by Gerrit Renker, documents the Linux implementation (since kernel 2.6.20) of the UDP-Lite transport layer protocol.
The proc(5) man page adds a description of the /proc/PID/numa_maps file.
Various updates and improvements by Lee Schermerhorn for the mbind(2), get_mempolicy(2), and set_mempolicy(2) pages.
Following on from last week's big update to the math man pages, there are a few more changes to these pages. Most notably, where error-reporting details have differed (from glibc 2.8) in earlier versions of glibc, the differences have been noted in the man pages. Currently, the details have been extended back until glibc 2.3.2, but I hope to extend them back further, when I can get test results. If you want to help, look here.
On 24 July, the Governing Board of The Open Group approved the 2008 revisions of POSIX.1. Among other things, POSIX.1-2008 marks some previously specified functions as obsolete, and drops the specifications of some other functions altogether. The manual pages have been updated to reflect all of these changes. (The standard should be published in final form after approval by the IEEE, but in the meantime you can get access to the draft by joining the Austin group.)
VERSIONS sections have been added to the man pages of many library functions to indicate the glibc version where the function first appeared.

Grünegg Fenster

Translating man-pages

2008-08-08T11:41:00.011+02:00

Lately, I've gotten a few requests for information about how to translate man-pages into other languages.

First off, I should say that I have never translated man-pages. But I have communicated with a few people who do. So these are my current thoughts...

Do you really want to do this? Before you answer this, consider the following:

man-pages contains the documentation of the Linux and glibc programming APIs (i.e., pages in Sections 2, 3, 4, 5, and 7). Is this the set of man pages that your group of language speakers most need? If, for example, you are more interested in translating pages for end users, then you might want instead to translate pages in the coreutils package. (More generally, if you want to find out which package a particular man page belongs to, take a look here.)
How big is the target audience? Your target audience is primarily programmers. What proportion of them aren't able to read English well enough to read man pages, and therefore would benefit from a translation? Is that group big enough to warrant the effort of a translation? Or is there perhaps a better place where you can invest your time in working on Linux?
How much time do you have? There are currently around 850 pages in man-pages, amounting to perhaps 2000 pages of printed text. My guess is that this amounts to one to two person years of translation work. In other words, you'll need to have a team of translators, if you intend to complete the translation in any reasonable time.
What is your longer term commitment? man-pages is a moving target: starting a couple of months ago, I'm now working full time on man-pages, and I make a release every week or so. The French translator estimates that there is around two days' work for him translating each release. Now, I may not be working full time on man-pages forever, and therefore the required translation effort may decrease some day, but the point remains that there is a significant ongoing effort required to keep a translation up to date and useful.

The size of the translation effort should not be underestimated. It is because it is so large that to date there has been only one complete and up-to-date translation: the French translation. (For a while, there was a fairly full German translation, but it seems to have languished for a few years now.) The state of the French translation has largely been down to the extraordinary work of two people: Christophe Blaess, and more recently, Alain Portal. (In fact, there are nowadays two French translations which cooperate to some extent: the Debian distribution has a team doing a French translation of man-pages.) But nowadays even the French translator(s) have started to feel the strain resulting from the recent increase in my output.

If you decide you really want to do a translation (and think very carefully before you do decide that!), then I have a few thoughts on how you go about it.

Tools: I have no real recommendations here (since I never translated man-pages). But it's worth mentioning that the Debian French translators use po4a, and see it as very beneficial for their work, especially for facilitating the work of a team of translators.

Other than that, I'd say that you need to:

Estimate the time required to translate the 850 pages in man-pages, and decide if you have the necessary number translators who have sufficient time to complete the work.
Divide the work up so that your translators can work independently on translations. I suggest you divide the pages up into small, related parcels. For example, the POSIX message queue pages (mq_*) could be a parcel translated by a single translator, or the math man pages could be a parcel translated by a single translator, etc.
Come up with a review plan, so that each translation by one member of your team is reviewed by at least one other member.
Devise a glossary of terminology, so that you all translate English technical terms ("e.g., shared memory segment") into the same terms in the target language.
Plan for ongoing maintenance, so that as the English man pages are updated, then the translated pages are also updated. Don't underestimate the amount of this work!

My suggestion is that if you go forward with a translation project, then:

Pick a particular man-pages release -- let's say man-pages-3.x -- and translate all of the pages in that version.
When that is completed, you can then update your translation with all of the changes that have occurred in the English original since release man-pages-3.x. I keep fairly detailed changelogs which should assist you during this phase of the work.

I suggest doing things this way since I estimate that trying to do a translation while simultaneously trying to keep up with changes in already translated pages would just prove too difficult. You might decide otherwise.

And finally... did I mention that you should think long and hard before embarking on a translation of man-pages?

[12 Aug 08: minor updates, to point out exactly which sections are in man-pages, and to suggest more appropriate pages to translate, if targeting end users.]

Help request: testing of math function error reporting

2008-08-06T11:00:00.000+02:00

As I mentioned in my previous post, as of man-pages-3.06, the math man pages now describe the error-reporting behavior of the math functions as at glibc 2.8. I'd like to extend those descriptions to cover differences in older glibc versions. In order to do that, I've written some scripts to check the error-reporting behavior of the math functions, and I'd like to run them on as many different versions of glibc as possible.

If you'd like to help, and you have an x86 system with an older glibc (look at the version number in the first line of output produced by the command /lib/libc.so.6), run the script in this tarball (see the README file inside the tarball for details), and send me the resulting log file (email to mtk.manpages AT gmail.com).

Math functions and error reporting

2008-08-06T10:45:00.014+02:00

Math functions are different from most other library functions in the kinds of errors that they report, and in the way that they report errors. Broadly speaking, a math function can fail for one of the following reasons:

Domain error: an argument to the function was outside the range for which the function was defined. For example, the call sqrt(-1.0) gives a domain error because a negative number does not have (real) square root. When a domain error occurs, a math function typicall returns a NaN (not-a-number).
Pole error: the function result is an exact infinity. For example log(0.0) is negative infinity. When a pole error occurs, most math functions return the floating-point representation of positive or negative infinity, as appropriate (i.e., HUGE_VAL or -HUGE_VAL for functions returning a double).
Range error (overflow): an overflow occurs if the function result is too large to be represented as a floating-point number. For example, exp(1e10) produces a number too large to represent in a double. When an overflow occurs, most math functions return the floating-point representation of positive or negative infinity, as appropriate (i.e., HUGE_VAL or -HUGE_VAL for functions returning a double).
Range error (underflow): an underflow occurs if the function result is so small that it can't be represented as a (normalized) floating-point number. For example, exp(-1e10) produces a number too large to represent in a double. When an underflow occurs, a math function usually either returns a (signed) zero, or a subnormal value, as appropriate.

(More details can be found in the math_error(7) man page.)

Many library functions report an error by returning a NULL pointer or an integer -1. Neither of these mechanisms would be suitable for math functions: these functions usually return a floating-point value, and -1 is in many cases a valid successful return. For this reasons, the C99 and POSIX.1-2001 standards define two other mechanisms by which math functions can report errors.

The first of the error-reporting mechanisms is to use the traditional errno variable. We set the errno to zero before the call, and if it has a non-zero value after the call, then an error occurred. On error, errno is set as follows:

Domain error: EDOM

Pole error: ERANGE

Overflow: ERANGE

Underflow: ERANGE

(These settings do of course make it hard to distinguish the last three types of errors.)

The other error-reporting mechanism is exceptions. For each of the errors described above, the system raises an exception, and the fetestexcept() library function can be used to check whether an exception occurred. In order to use this mechanism we do the following:

Call feclearexcept(FE_ALL_EXCEPT) to clear any existing exceptions.

Call the math library function.

Call fetestexcept(FE_INVALID FE_DIVBYZERO FE_OVERFLOW FE_UNDERFLOW).

If the math function was successful, then fetestexcept() returns 0. If an error occurred while calling the math function, then fetestexcept() returns a bit mask indicating the error. In this bit mask, exactly one of FE_INVALID, FE_DIVBYZERO, FE_OVERFLOW, or FE_UNDERFLOW will be set. The exceptions raised for each error are:

Domain error: invalid exception (FE_INVALID)

Pole error: divide-by-zero exception (FE_DIVBYZERO)

Overflow: overflow exception (FE_OVERFLOW)

Underflow: underflow exception (FE_UNDERFLOW)

C99 and POSIX.1-2001 require an implementation to support at least one of the error-reporting mechanisms for all math functions, and allow both to be supported. The standards specify an identifier, math_errhandling, that an implementation should set to indicate which mechanisms are supported. If (math_errhandling & MATH_ERRNO) is non-zero, then errno is set to indicate errors. If (math_errhandling & MATH_EXCEPT) is non-zero ,then exceptions are raised on errors.

The CONFORMANCE file in the glibc sources has long explained that:

Implementing MATH_ERRNO, MATH_ERREXCEPT and math_errhandling in needs compiler support: see
http://sources.redhat.com/ml/libc-hacker/2000-06/msg00008.html
http://sources.redhat.com/ml/libc-hacker/2000-06/msg00014.html
http://sources.redhat.com/ml/libc-hacker/2000-06/msg00015.html

But to date this support has not arrived. In any case, this support is a somewhat moot point, since it transpires that neither of the mechanisms is supported by all of the math functions in glibc: most (but not all) support exceptions, many support both exceptions and errno, a few support errno but not exceptions, and one or two functions support neither mechanism. To make things even worse, the man pages didn't fully and correctly describe the details for each math function. Since man-pages-3.06, the details should now be accurate, at least for glibc 2.8.

Ideally, all of the glibc math functions would support both mechanisms, so that programs that depend on either mechanism could be happily ported to Linux. With that idea in mind, I went through and tested the error-reporting behavior for each math function, and filed a series of bug reports that document deviations from that ideal.

In order to get an overview, the table below summarizes the situation for all of the math functions as at glibc 2.8. The third and fourth columns indicate whether errno is correctly set and an exception is raised for each error case.

Function	Expected error	errno set correctly?	Exception correctly raised?	Notes
acos(+-inf)	domain	y	y	-
acosh(x<1)	domain	y	y	-
asin(+-inf)	domain	y	y	-
asinh()	-	-	-	No errors occur
atan()	-	-	-	No errors occur
atan2()	-	-	-	No errors occur
atanh(+-1)	pole	n	y	errno is set to EDOM (should be ERANGE)
atanh(x>1)	domain	y	y	-
cbrt()	-	-	-	No errors occur
ceil()	-	-	-	No errors occur
cos(+-inf)	domain	n	y	-
cosh(+-large)	overflow	y	y	e.g., cosh(DBL_MAX)
erf(+-small)	underflow	n	y	For subnormal x
erfc(x)	underflow	n	y	Result underflows but produces representable (i.e., subnormal) result; e.g., erfc(27)
exp(+large)	overflow	y	y	-
exp(-large)	underflow	y	y	-
exp10(+large)	overflow	y	y	GNU extension, but inconsistent with exp()
exp10(-large)	underflow	n	y	GNU extension, but inconsistent with exp()
exp2(+large)	overflow	y	y	-
exp2(-large)	underflow	y	y	-
expm1(+large)	overflow	n	y	-
fabs()	-	-	-	No errors occur
fdim()	overflow	n	y	e.g., fdim(DBL_MAX, -DBL_MAX)
floor()	-	-	-	No errors occur
fma()	domain	n	y	Various causes, e.g., one of x or y is an infinity and the other is 0.
fma()	overflow	n	y	e.g., fma(DBL_MAX, DBL_MAX, 0)
fma()	underflow	n	y	e.g., fma(DBL_MIN, DBL_MIN, 0)
fmax()	-	-	-	No errors occur
fmin()	-	-	-	No errors occur
fmod(+-inf,y)	domain	n	y	-
fmod(x,0)	domain	y	y	-
hypot()	overflow	y	y	e.g., hypot(DBL_MAX, DBL_MAX)
hypot()	underflow	n	y	e.g., if both arguments are small subnormal numbers
ilogb(+-inf)	domain	n	n	Does correctly return INT_MAX
ilogb(0)	domain	n	y	Does correctly return FP_ILOGB0
ilogb(nan)	domain	n	y	Does correctly return FP_ILOGBNAN
j0()	underflow	y	n	e.g., j0(DBL_MAX)
j1()	underflow	y	n	-
jn()	underflow	y	n	-
ldexp(x, +large-exp)	overflow	y	y	-
ldexp(x, -large-exp)	underflow	y	y	-
lgamma()	overflow	y	y	e.g., lgamma(DBL_MAX)
lgamma()	pole	n	y	Occurs when x is a non-positive integer; errno is set to EDOM (should be ERANGE)
llrint()	domain	n	y	x is NaN, infinity, or too large to store in a long long
llround()	domain	n	y	x is NaN, infinity, or too large to store in a long long
log(0)	pole	y	y	-
log(x<0)	domain	y	y	-
log10(0)	pole	y	y	-
log10(x<0)	domain	y	y	-
log1p(-1)	pole	n	y	-
log1p(x<-1)	domain	n	y	-
log2(0)	pole	y	y	-
log2(x<0)	domain	y	y	-
logb(0)	pole	n	y	-
lrint()	domain	n	y	x is NaN, infinity, or too large to store in a long
lround()	domain	n	y	x is NaN, infinity, or too large to store in a long
nearbyint()	-	-	-	No errors occur
nextafter()	overflow	n	y	e.g., nextafter(DBL_MAX, +inf)
nextafter()	underflow	n	y	e.g., nextafter(DBL_MIN, 0);
nexttoward()	overflow	n	y	e.g., nexttoward(DBL_MAX, +inf)
nexttoward()	underflow	n	y	e.g., nexttoward(DBL_MIN, 0);
pow(0, -y)	pole (0, neg)	n	y	errno is set to EDOM (should be ERANGE)
pow(x,y)	overflow	y	y	Suitable values to cause overflow (e.g., pow(2, 1e100))
pow(x,y)	underflow	y	y	Suitable values to cause underflow (e.g., pow(2, -1e100)
pow(x<0,>	domain	y	y	-
remainder(+-inf,y)	domain	n	y	-
remainder(x,0)	domain	y	y	-
remquo(+-inf,y)	domain	n	y	-
remquo(x,0)	domain	n	y	-
rint()	-	-	-	No errors occur
round()	-	-	-	No errors occur
scalb()	overflow	n	y	e.g., scalb(DBL_MAX, 200)
scalb()	underflow	n	y	e.g., scalb(DBL_MAX, -200)
scalb(0,+inf)	domain	n	y	-
scalbln()	overflow	n	y	e.g., scalbln(DBL_MAX, 200)
scalbln()	underflow	n	y	e.g., scalbln(DBL_MAX, -200)
scalbn()	overflow	n	y	e.g., scalbn(DBL_MAX, 200)
scalbn()	underflow	n	y	e.g., scalbn(DBL_MAX, -200)
sin(+-inf)	domain	n	y	-
sinh(+-large)	overflow	y	-	e.g., sinh(DBL_MAX)
sqrt(x<0)	domain	y	y	-
tan(+-inf)	domain	n	y	-
tan(pi/2)	overflow	-	-	No test possible, since the best approximation of pi/2 in double precision only yields a tan() value of 1.633e16.
tanh()	-	-	-	No errors occur
tgamma()	underflow	n	y	Occurs for ranges of x values between negative integers, e.g., tgamma(-10000.5)
tgamma(+-0)	pole	y	y	-
tgamma(+large)	overflow	y	y	-
tgamma(-inf)	domain	n	y	Note the difference from tgamma(x<0)
tgamma(x<0)	domain	y	y	For finite x
trunc()	-	-	-	No errors occur
y0()	overflow	-	-	Not possible to overflow with double
y0()	underflow	y	n	e.g., y0(DBL_MAX)
y0(0)	pole	n	n	errno is set to EDOM (should be ERANGE)
y0(x<0)	domain	y	y	-
y1()	overflow	-	-	Not possible to overflow with double
y1()	underflow	y	n	e.g., y1(DBL_MAX)
y1(0)	pole	n	n	errno is set to EDOM (should be ERANGE)
y1(x<0)	domain	y	y	-
yn()	overflow	n	y	e.g., yn(1000, DBL_MIN)
yn()	underflow	y	n	e.g., yn(10, DBL_MAX)
yn(0)	pole	n	n	errno is set to EDOM (should be ERANGE)
yn(x<0)	domain	y	y	-

man-pages-3.06 is released

2008-08-05T15:38:00.012+02:00

I've uploaded man-pages-3.06 into the release directory (or view the online pages). The main changes in man-pages-3.06 are updates to around 65 math pages. The changes are broadly as follows:

RETURN VALUE: in many cases, the math pages lacked descriptions of the return value when the function arguments are special cases such as +0, -0, NaN (not-a-number), +infinity, -infinity, etc. This has been fixed. I carried out tests on glibc 2.8 to ensure that the behavior of all of these functions matches the RETURN VALUE descriptions (and the POSIX.1-2001 requirements).
BUGS: a BUGS sections was added to a few pages to document deviations from from expected behavior.
ERRORS: many pages lacked a clear (or indeed any) description of how errno is set on error and what exception is raised for each error. This has been fixed. The ERRORS sections are now generally headed up as per the POSIX.1 way of doing things, describing Pole, Range, and Domain errors, as applicable. I carried out tests on glibc 2.8 to ensure that all of these functions match the ERRORS descriptions. Deviations from POSIX.1-2001 requirements have been filed as glibc bug reports, and noted in the man pages. (The pages now describe the situation for ERRORS as at glibc 2.8. I may eventually try and extend the text with descriptions of changes in older versions of glibc; watch for a post on that subject in the next days, when I'll describe my test scripts.)
Fixed feature test macros (FTMs). Often, the FTM requirements for the float and long double versions of a math function are different from the requirements for the double version. Each math page now shows the correct FTM requirements for all three versions of the function(s) it describes. This may have required either a change to the existing FTM text (if the requirements for the double function were already described), or the addition of an FTM description to a SYNOPSIS where one was not previously present (typically because the double version of the function does not require any FTMs to be defined). A few outright errors in the documentation of FTM requirements were also fixed.
CONFORMING TO: in many cases, POSIX.1-2001 was not mentioned. Where a function is specified in POSIX.1-2001, this is now noted. Also, statements about what other standards a function conforms to were generally clarified. (The wording about which functions conformed to C99 was previously often done as an add-on sentence; now it is made part of the first sentence of the CONFORMING TO section, along with mention of POSIX.1-2001.)

While making all of the above changes, I split out some logically separate material from existing pages to create three new pages: erfc(3) (formerly part of erf(3)), scalbln(3) (formerly part of scalb(3)), and y0(3) (formerly part of j0(3)).

P.S. One point that is still not covered in any page is the circumstances that generate inexact (FE_INEXACT) floating-point exceptions. (The details for these exceptions are not specified in POSIX.1-2001, and I haven't gone looking for the standards that describe the details.) If anyone has thoughts on what needs to be done about this, I'm open to ideas.

Grünegg

Handling bug reports explicitly

2008-07-28T11:41:00.003+02:00

(Thoughts after a recent mail conversation...)

As a project maintainer, when you handle reports it's helpful to all concerned, but most especially you, if you are as explicit as possible when handling bug reports. In other words, explain to the reporter exactly what you did to fix the problem they reported, and why you did it. (This might be as simple as saying you applied a patch written by the reporter, or showing the patch you wrote and applied, but usually that's not enough.) If you did nothing, explain why. If the report was made by email to a list, then make sure you CC the list with your explanation. If the report was via a bug-reporting facility, then make sure that your explanation goes into the facility.

This helps you because:

It provides a historical record that will help you remember later what you did and why, and allow others to go back and find that information.
It encourages your good bug reporters to make future reports, because they can see that their reports make a difference.
It will help your bad bug reporters make better reports in the future.
Perhaps most importantly... You'll always make mistakes (misunderstand the report, make the wrong fix, etc.): if you let as many people as possible (the reporter, readers of the mailing list to which the bug report was written, followers of traffic on the bug reporting facility) know as precisely as possible what you did, then you give them all a chance to spot your mistake. I've had (far too) many of my mistakes spotted by others by explicitly explaining what I've done. (People could always find out what you did by hunting down diffs in a source repository, or a tarball, or whatever, but the effort involved means that many people won't do that.)

It helps others because:

The reporter of the bug knows how their problem got fixed.
If you are an upstream package maintainer, it will help downstream maintainers know what you did and why.
If you are a downstream package maintainer, it will help the upstream maintainer know what you did and why, which will help them decide whether to integrate your downstream changes upstream.

man-pages-3.05 is released

2008-07-23T15:25:00.009+02:00

I've uploaded man-pages-3.05 into the release directory (or view the online pages). Notable changes in man-pages-3.05 are:

A new math_error(7) page describes how to diagnose errors when calling math functions.
A new matherr(3) page describes the older SVID-specified mechanism for diagnosing errors from math functions.

There are a few other minor changes, but this week's release is indeed smaller than usual. That's because I'm working on pending changes to almost all of the math man pages to improve: the discussion of return values, treatment of special values (+0, -0, infinities, NaN), and error diagnostics; the accuracy of the description of feature test macro requirements; and various other details. Expect a (very) big release next week.

Blick auf die Grünegg, Konolfingen

Capabilities have fully arrived, finally

2008-07-16T13:55:00.000+02:00

Linux 2.6.26 is out, which means that a complete Linux capabilities implementation has finally arrived, since we now have:

The ability to attach capability sets to files (added in 2.6.24), so that a process can acquire capabilities during an execve(2).
A CAP_SETPCAP capability with the proper semantics (since 2.6.25).
A per-thread capability bounding set (added in 2.6.25).
The per-thread securebits flags (added in 2.6.26), which can be used to restrict a thread and its children to a pure capabilities-only environment (i.e., one in which there is no special treatment of UID 0).

All of the details are provided in the recently revised capabilities(7) man page. A couple of other useful places to look for information on capabilities are Serge Hallyn's article, POSIX file capabilities: Parceling the power of root, and Chris Friedhoff's page on capabilities.

man-pages-3.04 is released

2008-07-16T13:52:00.006+02:00

I've uploaded man-pages-3.04 into the release directory (or view the online pages). Notable changes in man-pages-3.04 are:

A new utimensat(2) page describes the utimensat() system call (new in kernel 2.6.22, fixed in 2.6.26) and the futimens() library function.
A new end(3) page describes the end, etext, and edata variables.
The capget(2) page was updated by Andrew Morgan, in line with changes in Linux capabilities in kernels 2.6.24, 2.6.25, and 2.6.26.
The capabilities(7) page adds discussion of: file capabilities (new in Linux 2.6.24), the per-thread capability bounding set (new in Linux 2.6.25); the changed semantics for CAP_SETPCAP (Linux 2.6.25); per-thread securebits flags (new in Linux 2.6.26); three new capabilities, CAP_MAC_ADMIN, CAP_MAC_OVERRIDE, CAP_SETFCAP (Linux 2.6.25); historical CAP_SETPCAP semantics; the rules governing changes to capability sets; and the rationale for the inheritable set and capability bounding set. There were also many other more minor changes to this page. Thanks to Serge Hallyn for his contributions here.
The getrusage(2) page adds a description of the RUSAGE_THREAD option, which is new in Linux 2.6.26.
Many changes were made to the prctl(2) page, including adding documentation of: PR_CAPBSET_READ and PR_CAPBSET_DROP (thanks to Serge Hallyn); PR_GET_TSC and PR_SET_TSC (thanks to Erik Bosman); PR_SET_SECCOMP and PR_GET_SECCOMP; and PR_SET_SECUREBITS and PR_GET_SECUREBITS.
The proc(5) page adds documentation of /proc/config.gz (new in kernel 2.6); /proc/sys/vm/oom_kill_allocating_task (new in Linux 2.6.24); /proc/sys/vm/oom_dump_tasks (new in Linux 2.6.25); and /proc/sys/vm/panic_on_oom (new in Linux 2.6.18).
The getopt(3) page adds details on the use of optind for restarting an argument list scan.
The memchr(3) page adds a description of rawmemchr().
There were also very many minor content and and minor and major formatting fixes, many of them triggered by the around 70 mailed reports that I received from the Alain Portal, the French translator of man-pages. (Alain also provided dozens of reports that led to fixes in man-pages-3.03.) Thanks Alain!

man-pages-3.03 is released

2008-07-08T08:00:00.000+02:00

I've uploaded man-pages-3.03 into the release directory (or view the online pages). Notable changes in man-pages-3.03 are:

A new cpuset(7) page, written by Paul Jackson, describes the cpuset file system, the mechanism introduced in Linux 2.6.12 for confining processes to designated processors and nodes. This enormous page becomes the fourth largest in man-pages. Thanks for a great contribution Paul!

A new getcpu(2) page, written by Andi Kleen, to document the getcpu(2) system call, introduced in Linux 2.6.19.

A new sched_getcpu(3) page documents a glibc wrapper for getcpu(2).

The readdir(3) page adds a description of readdir_r(3), the reentrant analog of readdir(3).

The signal(7) page adds a section on system call restarting (SA_RESTART), and describes the aberrant Linux behavior whereby a stop signal plus SIGCONT can interrupt some system calls, even if no signal handler has been established.

man-pages-3.02 is released

2008-07-02T19:57:00.008+02:00

I've uploaded man-pages-3.02 into the release directory (or view the online pages).

Notable changes in man-pages-3.02 are:

A new clock_nanosleep(2) page, describing the system call introduced in kernel 2.6.

A rewritten getgrouplist(3) page, which provides additional information and an example program.

A new getutmp(3) page documenting the getutmp(3) and getutmpx(3) functions.

A new gnu_get_libc_version(3) page documenting get_gnu_libc_version(3) and get_gnu_libc_release(3).

A new sigwait(3) page dopcumenting the sigwait(3) library function.

A new shm_overview(7) page providing an overview of the POSIX shared memory API.

Additional information in the sigreturn(2) man page.

Additons and updates to various pages describing the login accounting APIs, including: a new getutmp(3) page documenting the getutmp(3) and getutmpx(3) functions; and various improvements in the getutent(3) and utmp(5) pages.

What's wrong with kernel-userland interface development?

2008-06-30T14:30:00.025+02:00

So I came to write the man pages for utimensat() and futimens(), interfaces that are specified in the upcoming POSIX.1 revision, and recently added to Linux (kernel 2.6.22, glibc 2.6), and it's a familiar story: bugs, and yet more bugs.

This case is a little worse than usual (the gory details are below), but hardly exceptional: it was a similar story with other recent APIs, such as splice(), signalf(), and the timerfd API (the last of which was ultimately redesigned after some pushing by me). In each case, an interface that was already released in a stable kernel turned out to have easy-to-find bugs when I came to document and test it. All that was required was to come up with something like a reasonable written specification (i.e., a man page), and then start testing against that specification.

The following seems (to me) like a reasonable development model for new kernel userland APIs:

Write a more or less complete design specification (preferably something like a man page, which I'm more than happy to edit and review at this stage in the process), and perhaps even code up an initial version of the interface.

Get review comments about the design; revise the design if necessary.

Implement something like a final version of the interface.

Test the interface. Preferably: test in collaboration with other people who had nothing to do with the implementation (they will think about the interface in different ways from the implementer). If it's sensible to do so (and usually it is), produce a test suite to check the correctness of as many operational cases of the interface as possible (and then send that suite to the Linux Test Project).

Write the interface documentation (i.e., a man page) for userland programmers, and send it to me for editing and review. (If you do this smart, then you can just recycle the work from the first step.)

Get the interface accepted into mainline.

However, as far as I can see, the actual development model for kernel-userland interfaces seems to work something like this:

Code up the new interface.

Post the code to LKML, explaining that "I tested it, and it works", and, maybe, include some brief documentation of the interface.

Often, someone looks at the code and suggests some fixes. Usually, no one else does any testing.

Code gets accepted into mainline.

Usually, some few dot releases later: someone (often me) who had nothing to do with the earlier steps writes the man page.

Often, some few dot releases later: find and fix all of the bugs (e.g., in the case of utimensat(), released for 2.6.22, the fixes will only make it into 2.6.26 at the earliest).

Occasionally, some few dot releases later: realize that the interface could have been better designed, but it's too late now to change it, because we can't break the ABI.

Most kernel-userland interfaces are seeing far too little testing before release. This hurts because:

Userland programmers end up dealing with kernel bugs they shouldn't have to deal with. (When this happens often, it can damage the reputation of the Linux kernel-userland interface, and userland programmers may become wary of adopting new interfaces, which can further delay any kind of real-world testing and adoption of the interface.)

Code that uses new interfaces may have to special case for ABI bugs that were present in the first few kernel releases that contained the bug.

Similarly, many kernel-userland interfaces could do with more design review as well. This can hurt even more than interfaces released with bugs, since, once an interface is released, it is at least difficult, but often impossible to modify the design, since doing so would break the kernel-userland ABI. (With timerfd, we got lucky: the interface was in any case broken by a bug, which gave a more or less blank slate for a redesign.) As a result, userland programmers usually just have to live with the bad design.

I'll have more time for testing and review nowadays, and hopefully I'll catch more problems before they are released into stable kernels, but there's certainly more than one person can do. And, as described above, there is a culture problem when it comes to adding kernel-userland interfaces on Linux. The question is whether the culture can be changed. (And here its worth repeating a point that I often make: one could perhaps try and blame individual developers for buggy interfaces, but that doesn't really get to the core issue (everyone is going to write bugs): the real problem is the process by which kernel-userland interface changes are accepted into the kernel.)

The Gory Details

For those who are interested, here are the problems I found with utimensat() and futimens(), explained by annotating the current draft of the man page.

SYNOPSIS
    #include <sys/stat.h>
 
    int utimensat(int dirfd, const char *pathname,
                  const struct timespec times[2], int flags);
 
    int futimens(int fd, const struct timespec times[2]);
 
DESCRIPTION
    utimensat() and futimens() update  the  timestamps  of  a
    file  with nanosecond precision.  This contrasts with the
    historical utime(2) and utimes(2), which permit only sec-
    ond and microsecond precision, respectively, when setting
    file timestamps.

This is the first of the advantages of the new interfaces: greater precision for setting timestamps. (The next revision of POSIX.1 specifies nanosecond file timestamps, and extends stat(2) to allow their retrieval. File system support is needed, and can't necessarily be retrofitted to some older file systems. Currently, Linux supports nanosecond timestamps on XFS, JFS, and ext4.)

    With utimensat() the file is specified via  the  pathname
    given in pathname.  With futimens() the file whose times-
    tamps are to be updated is specified  via  an  open  file
    descriptor, fd.
 
    For  both calls, the new file timestamps are specified in
    the array times: times[0] specifies the new "last  access
    time" (atime); times[1] specifies the new "last modifica-
    tion time" (mtime).  Each of the elements of times speci-
    fies  a  time  in seconds and nanoseconds since the Epoch
    (00:00:00, 1 Jan 1970, UTC), in a structure of  the  fol-
    lowing form:
 
        struct timespec {
            time_t tv_sec;        /* seconds */
            long   tv_nsec;       /* nanoseconds */
        };
 
    If  the  tv_nsec  field of one of the timespec structures
    has the special value UTIME_NOW, then  the  corresponding
    file  timestamp  is  set  to  the  current  time.  If the
    tv_nsec field of one of the timespec structures  has  the
    special  value  UTIME_OMIT,  then  the corresponding file
    timestamp is left unchanged.  In both of these cases, the
    value of the corresponding tv_sec field is ignored.

These are the other advantages of the new interfaces.

With utime(2) and utimes(2), to change just one of the timestamps, we must make a call to stat(2) to retrieve the current timestamps, use one of the timestamps to initialize the times element that we don't want to change, and then call utimensat() with the desired value for the other timestamp. This can be subject to race conditions: if another process updates the file timestamps between the two calls, then that update will be lost. UTIME_OMIT allows us to avoid this problem.

UTIME_NOW exists mainly as a convenience: it allows us to avoid fetching the current time (using gettimeofday(2) or similar) in order to set a file timestamp to "now".

    If  times  is  NULL,  then both timestamps are set to the
    current time.
 
Permissions requirements
    To set both file timestamps to the  current  time  (i.e.,
    times is NULL, or both tv_nsec fields specify UTIME_NOW),
    either:
 
    1. the caller must have write access to the file;
 
    2. the caller's effective user ID must match the owner of
       the file; or
 
    3. the caller must have appropriate privileges.
 
    To  make any change other than setting both timestamps to
    the current time (i.e.,  times  is  not  NULL,  and  both
    tv_nsec  fields are not UTIME_NOW and both tv_nsec fields
    are not UTIME_OMIT), either condition 2 or 3  above  must
    apply.
 
    If  both tv_nsec fields are specified as UTIME_OMIT, then
    no file ownership or permission checks are performed, and
    the  file  timestamps  are  not modified, but other error
    conditions may still be detected.
 
utimensat() specifics
    [Details of dirfd and flags arguments omitted.]

For details of the dirfd argument, see openat(2).

RETURN VALUE
    On success, utimensat()  and  futimens()  return  0.   On
    error,  -1  is  returned and errno is set to indicate the
    error.
 
ERRORS
    [Various other errors that are irrelevant  to  this  post
    have been omitted.]
 
    EACCES times   is   NULL,  or  both  tv_nsec  values  are
           UTIME_NOW, but the effective effective ID  of  the
           caller  does  not match the owner of the file, the
           caller does not have write access to the file, and
           the caller is not privileged (Linux: does not have
           either  the  CAP_FOWNER  or  the  CAP_DAC_OVERRIDE
           capability).
 
    EACCES times   is   NULL,  or  both  tv_nsec  values  are
           UTIME_NOW, and the file is marked immutable.
 
    EPERM  The caller attempted to change one or both  times-
           tamps  to  a value other than the current time, or
           to change one of the  timestamps  to  the  current
           time  while leaving the other timestamp unchanged,
           (i.e., times is not NULL, both tv_nsec fields  are
           not  UTIME_NOW,  and  both  tv_nsec fields are not
           UTIME_OMIT) but the  caller's  effective  user  ID
           does  not  match the owner of file, and the caller
           is  not  privileged  (Linux:  does  not  have  the
           CAP_FOWNER capability).
 
    EPERM  times  is not NULL, and the file is marked append-
           only or immutable.
 
NOTES
    On Linux, futimens() is a library function implemented on
    top of the utimensat() system call.  To support this, the
    Linux utimensat() system call implements  a  non-standard
    feature:  if pathname is NULL, then the system call modi-
    fies the timestamps of the open file referred to  by  the
    file  descriptor  dirfd  (which  may refer to any type of
    file).  Using this feature, the call  futimens(fd, times)
    is implemented as:
 
        utimensat(fd, NULL, times, 0);
 
BUGS
    Several  bugs  afflict utimensat() and futimens() on ker-
    nels before 2.6.??.

Really, there should have been a test suite to go along with the initial implementation. There wasn't, unfortunately, so I wrote one (later revised a little before it went to LTP) whose results can be seen here.

I've posted patches to fix all of the bugs, and Andrew Morton has accepted them into -mm, and from there, they seem to have gone upstream to Al Viro. It's just a question of when they will get pushed into mainline. It'd be nice if they make it into 2.6.26, but maybe they won't, since it is already getting very late in the -rc cycle. (Update, 6 Jul 08: the patches have gone into -rc9.)

                         These bugs  are  either  non-confor-
    mances  with the POSIX.1 draft specification or inconsis-
    tencies with historical Linux behavior.
 
    * POSIX.1 specifies that if one of the tv_nsec fields has
      the  value  UTIME_NOW  or UTIME_OMIT, then the value of
      the  corresponding  tv_sec  field  should  be  ignored.
      Instead,  the  value of the tv_sec field is required to
      be 0 (or the error EINVAL results).

This was a simple and obvious divergence from the specification.

    * Various bugs mean that for the purposes  of  permission
      checking, the case where both tv_nsec fields are set to
      UTIME_NOW isn't always treated the same  as  specifying
      times  as NULL, and the case where one tv_nsec value is
      UTIME_NOW and the other is UTIME_OMIT isn't treated the
      same  as  specifying  times as a pointer to a structure
      containing arbitrary time values.  As a result, in some
      cases:  a)  file timestamps can be updated by a process
      that shouldn't have permission to perform  updates;  b)
      file  timestamps  can't  be  updated  by a process that
      should have permission to perform updates; and  c)  the
      wrong errno value is returned in case of an error.

There are multiple error cases here:

If one of the tv_nsec fields is UTIME_OMIT and the other is UTIME_NOW, then the error EPERM should occur if the process's effective user ID does not match the file owner and the process is not privileged. Instead, the call successfully changes one of the timestamps.
If the file is not writable by the effective user ID of the process and the process's effective user ID does not match the file owner and the process is not privileged, and times is NULL, then the error EACCES results. This error should also occur if times points to a structure in which both tv_nsec fields are UTIME_NOW. Instead the call succeeds.
If a file is marked as append-only (see chattr(1)), then Linux traditionally (i.e., utime(2), utimes(2)), permits a NULL times argument to be used in order to update both timestamps to the current time. For consistency, utimensat() and futimens() should also produce the same result when given a times argument that points to a structure in which both tv_nsec fields are UTIME_NOW. Instead, the call fails with the error EPERM.
If a file is marked as immutable (see chattr(1)), then Linux traditionally (i.e., utime(2), utimes(2)), gives an EACCES error if times is NULL. For consistency, utimensat() and futimens() should also produce the same result when given a times that points to a structure in which both tv_nsec fields are UTIME_NOW. Instead, the call fails with the error EPERM.

    * POSIX.1  says  that  a process that has write access to
      the file can make a call with times as  NULL,  or  with
      times  pointing  to  a  structure in which both tv_nsec
      fields are UTIME_NOW,  in  order  to  update  the  both
      timestamps  to  the  current time.  However, futimens()
      instead checks whether the  access  mode  of  the  file
      descriptor  allows  writing.

This means that a process with a file descriptor that allows writing could change the timestamps of a file for which it does not have write permission; conversely, a process with a read-only file descriptor won't be able to update the timestamps of a file, even if it has write permission on the file.

man-pages-3.01 is released

2008-06-25T16:56:00.013+02:00

I've uploaded man-pages-3.01 into the release directory (or view the online pages).

Notable changes in man-pages-3.01 are:

A new hostname(7) page (based on the FreeBSD page) describing hostname resolution.
A new symlink(7) page (heavily modified from the original FreeBSD page) describing symbolic links.
A rewritten acct(5) page providing much more detail on the information written to the process accounting file.
The getrlimit(2) page adds a description of RLIMIT_RTTIME limit, new in Linux 2.6.25.
The mkstemp(3) page adds a description of mkostemp(), new in glibc 2.7.
The core(5) page adds a description (and an example program for) of the core_pattern pipe syntax, which appeared in Linux 2.6.19, and documents /proc/PID/coredump_filter, new in kernel 2.6.23.
The proc(5) page adds details for a number of previously undocumented /proc interfaces, including /proc/PID/oom_score, /proc/PID/oom_adj, /proc/PID/limits, /proc/PID/fdinfo/*, /proc/PID/mountinfo, /proc/PID/mountstats, and /proc/PID/status.
The time(7) page enhances the discussion of jiffies, and adds a section on high-resolution timers.
The unix(7) page adds a clear description of the three types of address that can appear in the sockaddr_un structure: pathname, unnamed, and abstract.
Many other pages saw significant changes, including brk(2), chmod(2), chown(2), nanosleep(2), open(2), sched_setscheduler(2), syscalls(2), ftime(3), getaddrinfo(3), inet(3), inet_pton(3), scanf(3), strerror(3), random(4), and locale(5).

man-pages-3.00 is released

2008-06-17T12:36:00.008+02:00

I've uploaded man-pages-3.00 into the release directory (or view the online pages). Notable changes in man-pages-3.00 are:

The POSIX man pages (man pages sections 0p, 1p, 3p) are now split out into a separate package, which can be downloaded here. This makes sense because the POSIX pages are logically separate: they are copies of specifications from the POSIX.1 standard (to be precise, we are currently redistributing pages from the 2003 Technical Corrigendum 1), that we have kindly been given permission to publish by the IEEE and The Open Group. Furthermore, the POSIX pages are only updated rarely (e.g., occasional formatting fixes, and periodic updates when a new version of the standard is released, such as the revision due to appear later this year), so there is no need to redistribute them with each release of man-pages.

After Stuart Brady noted that the quotes around single-quoted characters were not formatted well in UTF-8 output, I've globally replaced the characters used in the source files for quoting in man-pages in order to try and produce better formatted output for both ASCII and UTF-8 xterms, and also to bring greater consistency in general to the use of single and double quotes in the pages. This may not be the final word on the subject, but at least things should be somewhat improved.

man-pages is now supported

2008-06-09T10:35:00.009+02:00

Last month I started on what is, for the moment, my dream job: man-pages finally has a paid, full-time maintainer, thanks to a fellowship from the Linux Foundation. For the foreseeable future, that means I'll be working on:

Documenting every new Linux kernel-userland (and glibc) API, and every API change, that is released into the mainline kernel, ideally before actual release. (That's the ideal, but there's a quite a backlog, so I'm not going to achieve the ideal immediately.)

Testing new APIs, again ideally before they are released into the mainline kernel, and probably doing some light bug fixing while I'm at it.

Design review of new kernel-userland APIs.

And of course accepting patches and dealing with bug reports for existing man pages.

Other than that, I'll be helping out with in-kernel documentation (the /Documentation directory) by providing editorial, review, and possibly other assistance.

When I find time, I'll try to post a longer job description (but have a look here in the meantime). In the meantime, I'm looking forward to going to the Linux Plumbers Conference, September 17-19, in Portland, OR, USA, where there is currently a planned track on kernel-userland APIs.

man-pages-2.80 and man-pages-fr-2.80.0 are released

2008-06-06T15:18:00.019+02:00

The Linux man-pages maintainer, Michael Kerrisk, and the maintainer of the French translation of man-pages, Alain Portal, proudly announce the simultaneous release of man-pages-2.80 in English original and French translation.

The English version can be downloaded from the usual release directory (or viewed online at the usual location).

The French translation can be downloaded from http://manpagesfr.free.fr/download.html, or viewed online at http://manpagesfr.free.fr/consulter.html.

There is long list of changes in man-pages-2.80. Among the more notable changes are the following:

A new random_r(3) page describes random_r(3), srandom_r(3), initstate_r(3), and setstate_r(3), the reentrant equivalents of random(3), srandom(3), initstate(3), and setstate(3).
getpriority(2) adds text describing the punchier effect of nice values since kernel 2.6.23.
mmap(2) describes improvements for the support of MAP_POPULATE in kernel 2.6.23.
sched_setscheduler(2) adds a description of the SCHED_IDLE policy, new in 2.6.23.
futimes(3) adds a description of lutimes(3), which was added in glibc 2.6
credentials(7) adds some text describing how NPTL maintains the same UIDs and GIDs for all threads in a process, even though the Linux kernel allows each thread to have distinct credentials.
inotify(7) documents the SIGIO support that was added for inotify in kernel 2.6.25.
standards(7) adds a description of the upcoming POSIX.1 revision.
A large number of consistency and formatting fix-ups were made to many pages.

man-pages-2.79 is released

2008-03-03T14:33:00.003+01:00

I've uploaded man-pages-2.79 into the release directory (or view the online pages).

Notable changes in man-pages-2.79 are:

a new page describing the timerfd API (timerfd_create(2), timerfd_settime(2), timerfd_gettime(2)), which is new in kernel 2.6.25
various additions and improvements to the syslog(2) page (thanks in part to Jeremy Kerr)
many clarifications and additions to the epoll.7 page (with help from Davide Libenzi and Chris Heath)

man-pages-2.78 is released

2008-02-12T16:00:00.001+01:00

I've uploaded man-pages-2.78 into the release directory (or view the online pages).

Notable changes in man-pages-2.78 are new pages describing the eventfd(2) and signalfd(2) system calls, and a substantial addition to open(2) by Greg Banks describing the semantics and use of O_DIRECT.

man-pages-2.77 is released

2008-01-31T14:44:00.000+01:00

I've uploaded man-pages-2.77 into the release directory (or view the online version, which now includes facilities for searching the pages).

Look here for a list of changes in this release.

man-pages-2.76 is released

2008-01-14T13:42:00.000+01:00

I've uploaded man-pages-2.76 into the release directory (or view the online pages).

Changes include rewrites of (parts of) the gettid(2), pipe(2), and umask(2) pages.

man-pages-2.75 and man-pages-fr-2.75.0 are released

2008-01-08T17:18:00.000+01:00

The Linux man-pages maintainer, Michael Kerrisk, and the maintainer of the French translation of man-pages, Alain Portal, proudly announce the simultaneous release of man-pages-2.75 in English original and French translation.

The English version can be downloaded from the usual release directory (or view the online pages).

The French translation can be downloaded from http://manpagesfr.free.fr/download.html. The translated French pages are viewable online, along with some translated man pages from other projects, at http://manpagesfr.free.fr/consulter.html. Comments and suggestions for the French translation can be sent to manpagesfr AT free DOT fr.

A huge thanks to Alain, who has over the last two and a half years made a terrific effort to bring the French translation fully up to date with the English original.

man-pages-fr-2.74.0 est sorti

2007-12-29T16:09:00.000+01:00

Back in June 2005, a few months after I became the man-pages maintainer, Alain Portal took over the French translation, which had long been maintained by Christophe Blaess (author of Programmation Système en C sous Linux, a nice book on Linux system programming). At that time, the current French translation (1.58) was trailing the English original (2.03) by about 16 releases, and Alain was determined to catch up by creating one-to-one releases for each of the original English release tarballs. I tried to dissuade him from that course, arguing that it might be less work to simply jump forward to translating the current English version. Luckily, he did not listen to me. He proceeded with his plan, creating French translations that corresponded exactly with the original English releases. Along the way he reported countless formatting and wording errors, and many confused pieces of text in the original English pages, which I then corrected upstream.

87 releases later, Alain has caught up with the current English release: yesterday man-pages-fr-2.74.0 was released, and can be downloaded from the usual location. It's a wonderful achievement, and incredibly valuable for francophones all over the world -- thanks Alain!

man-pages-2.74 is released

2007-12-20T13:43:00.000+01:00

I've uploaded man-pages-2.74, almost certainly the last release this year, into the release directory (or view the online pages).

Changes include many formatting fixes, and a description of an ugly bug in times(2).

man-pages-2.73 is released

2007-12-14T17:20:00.000+01:00

Pádraig Brady prompted me to try to make the online pages look a bit better.
As a result I've uploaded man-pages-2.73 into the release directory, and uploaded a new version of the HTML pages. (The actual changes in man-pages-2.73 are quite small, and consist mainly of formatting fixes.)

man-pages-2.71 and man-pages-2.72 are released

2007-12-14T10:28:00.000+01:00

I've uploaded man-pages-2.71 and man-pages-2.72 into the release directory (or view the online pages).

The most notable of the changes in man-pages-2.71 is the replacement of mdoc macros by man macros in 9 pages that used the former macros. This means that the only pages that still use mdoc macros are mdoc(7) and mdoc.samples(7).

Notable changes in man-pages-2.72 are a rewrite of the abort(3) man page and very many formatting fixes suggested by Alain Portal, maintainer of the French translation of man-pages.

Meanwhile, the timerfd saga goes on, after I tried using the draft timerfd_create(2) man page as a test spec.

man-pages-2.70 released

2007-12-06T11:02:00.001+01:00

I've uploaded man-pages-2.70 into the release directory (or view the online pages). The changes in this release consist mainly of formatting and consistency fixes.

man-pages-2.69 released

2007-12-03T17:17:00.001+01:00

I've uploaded man-pages-2.69 into the release directory. Among the changes are various fixes by J. Bruce Fields in the fcntl(2) page, many improvements and updates by Jeremy Kerr for spu_run(2), spu_create(2), and spufs(7), and many small fixes to various pages suggested by Alain Portal and Maxime Vaudequin, and whitespace fix-ups to improve the appearance of a large number of the POSIX (*.[013]p) pages.

man-pages website and mailing list

2007-11-24T09:45:00.000+01:00

man-pages now has a website. The website includes information about reporting bugs and otherwise contributing to man-pages, and also contains the online pages from the latest release.

There is also a mailing list for discussions related to man-pages. The posting address is linux-man@vger.kernel.org. (You do not need to be subscribed to the list to post to it.) To subscribe to the list, send a message to majordomo@vger.kernel.org, with the body:

subscribe linux-man

An archive of the messages to this list is available on gmane.

man-pages-2.68 released

2007-11-23T11:38:00.001+01:00

Earlier this week I uploaded man-pages-2.68 into the release directory. Among the changes are a new _syscall(2) page, and substantially written intro(2) and intro(3) pages.

man-pages-2.67 released

2007-10-23T09:53:00.000+02:00

Yesterday I uploaded man-pages-2.67 into the release directory. The changes in this release are primarily formatting fixes, and the addition of a PROLOG section to the 1p and 3p (POSIX) pages giving a clear indication that these are POSIX man pages (so as to prevent readers wrongly understanding that they are looking at a description of Linux behavior).

Work in progress

2007-10-14T14:52:00.001+02:00

A few days ago, I released man-pages-2.66, which included the page that David Chinner wrote for fallocate(2), a new system call in Linux 2.6.23. Work on man-pages-2.67 is done, and I'll upload it soon; meanwhile, I'm working on man-pages-2.68, and also working on a website for man-pages.

Getting started

2007-10-14T14:13:00.000+02:00

So this is the first of a series of irregular posts about my work on the Linux man-pages project, and related topics, like kernel-userland API testing and API design review. (I did a talk on the latter topics at LinuxConf Europe 2007, and Jon Corbet was kind enough to do a sympathetic write-up on lwn.net. I also covered some of the same ground at the 2007 Linux kernel summit.)