Linux man-pages:   home   ||   git | readme | contributing | conventions   |   mailing list | archives   |   releases | book | online pages

Maintaining Linux man-pages

The current man-pages maintainer is (since 2004) Michael Kerrisk (mtk.manpages@gmail.com; blog); starting in 2020, Alejandro Colomar (alx.manpages@gmail.com) has joined as comaintainer.

This page provides some tips on how to maintain the Linux man-pages project (also useful for anyone who wants to help with work on man-pages).

Read some man pages

Read at least the following:

All of these pages are relevant for maintaining man-pages. Some of them are part of packages other than man-pages.

Get the source code

History matters. The man-pages project documents not just the current state of the Linux kernel and glibc APIs, but also how they have changed over time.

Once upon a time, man-pages also used to document Linux libc details (libc4, libc5), but Linux libc started disappearing in the late 1990s (see here and here for some details), and there is no longer any need to keep documenting its peculiarities.

Kernel source code

You can find nearly every kernel release ever made at https://www.kernel.org/.

You can get a copy of Linus' Git tree (i.e., the current development tree) using this command:

$ git clone https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
Thereafter, just update the copy using git pull.

For browsing the kernel source code, the Elixir Cross Referencer can be useful. (Online browsable versions of various free kernels can be found at http://fxr.watson.org/.)

Glibc source code

A lot of glibc tarballs can be found at https://ftp.gnu.org/gnu/glibc/. Many older tarballs can be found at https://www.win.tue.nl/~aeb/ftpdocs/linux-local/libc.archive/. A copy of the latest glibc development tree can be obtained via git:

git clone git://sourceware.org/git/glibc.git 

Other source code

Sometimes it can be useful to grep through random source code to see what uses a certain API and how. For example, one could unpack all of the source code of a distribution and then grep that code. Download locations for source code: Fedora; OpenSUSE.

Keeping up

One of the biggest challenges is keeping up to date with changes in the kernel and glibc. There are a few ways to do this. This section lists some of the most useful ways.

Websites

These websites are useful because they in part include attempts by others to summarize changes to the Linux kernel.

Linux API mailing list

The linux-api mailing list (linux-api@vger.kernel.org) discusses changes that affect the Linux programming interface (API or ABI). In theory, all patches that change the interface should be CCed to this list. To subscribe, send a message containing the following body to majordomo@vger.kernel.org:

    subscribe linux-api 

An archive of this list can be found on lore.kernel.org.

Keeping up—some other possibilities

Below are some other ways of trying to discover changes in the kernel and glibc. There's way too much information here to track (in particular, it's pretty much impossible to track all of of the mailing lists), but the list below serves as a reminder of some places where useful information could be found.

Looking ahead: linux-next

The linux-next tree is the holding area for patches aimed at the next kernel merge window. It can be useful to track what's going on there, in order to get some idea of upcoming changes to the kernel. (Some notes on working with linux-next.)

Git

If you are looking for a specific kernel commit, or a commit log message containing a particular string, then searching Linus' Git tree can be useful.

Mailing lists

Linux Kernel (LKML)

This list (linux-kernel@vger.kernel.org) contains patches, bug reports, and general discussions about the kernel. To subscribe, send a message containing the following body to majordomo@vger.kernel.org:

    subscribe linux-kernel 

The problem with this list is that the volume is extremely high, so keeping close track of it all would require a lot of time.

vger.kernel.org/ provides the locations of a few searchable archives of this mailing list, and of course there is an archive at lore.kernel.org.

Linux Kernel Announce

This low-volume list (linux-kernel-announce@vger.kernel.org) announces releases of new versions of various kernel branches, including release candidates for the mainline kernel and new -mm kernels. To subscribe, send a message containing the following body to majordomo@vger.kernel.org:

    subscribe linux-kernel-announce 

netdev

The netdev list (netdev@vger.kernel.org) is the list used by the developers of the Linux networking subsystem.

To subscribe, send a message containing the following body to majordomo@vger.kernel.org:

    subscribe netdev 

Archives of this list can be found on lore and marc.

Linux Test Project (LTP)

The LTP produces test suites for the Linux kernel. Subscribe to the discussion list here. There are list archives here.

Kernel Newbies

This list (kernelnewbies@kernelnewbies.org) be useful for asking questions on aspects of the kernel source that you don't understand.

To subscribe, send a message containing the following body to listar@nl.linux.org:

    subscribe kernelnewbies 

Archives of this list can be found on lore and marc. See the kernelnewbies website for more information.

libc-announce

This list (libc-announce@sourceware.org) announces each glibc release. Subscribe by sending an email to libc-announce-subscribe@sourceware.org or visiting this page. There is a list archive here.

libc-alpha

This list (libc-alpha@sourceware.org) is the development list for glibc. Subscribe by sending an email to libc-alpha-subscribe@sourceware.org or visiting this page. There is a list archive here.

libc-help

This list (libc-help@sourceware.org) is for asking general questions and getting help on glibc. Subscribe by sending an email to libc-help-subscribe@sourceware.org or visiting this page. There is a list archive here.

Glibc releases

The following is useful to get a rough idea of what symbols are new or changed in various glibc releases -- execute it at the root of a glibc tree:

    cat  $(find . -name 'Versions' |
    egrep -v '/(s390|alpha|sparc|hurd|sh4|bsd|ia64|powerpc|x86_64)') |
	    sed -n '/GLIBC/,/}/p' | sed 's/#.*//'| tr ';' '\012' |
	    sed 's/^ *//' | sed 's/ *$//' | sed '/^$/d' |
	    grep -v '^_' |
	    awk '{ if ($1 ~ "^GLIBC_2.*") {
	             tag = $1
	           } else if ($1 ~ "^[a-z].*") {
	             printf "%-32s %s\n", $1, tag
	         }
	    }' |
	    sort -u
    

Kernel bugzilla

The kernel.org bugzilla can be used to report man-pages bugs. The list of unresolved bugs in the bugzilla can be seen here.

Also useful: How to use bugzilla.kernel.org.

Distribution-specific bug tracking systems

Debian

Debian makes it easy for upstream maintainers to subscribe to bug reports for man pages. To do this, visit https://packages.qa.debian.org/ and look for the Debian source packages manpages.

A current list of Debian bug reports for man-pages can be viewed here. The Debian manpages patch tracker is here.

Debian even provides an email interface that allows an upstream maintainer to manipulate Debian bug reports (using the "tags" command; see https://www.debian.org/Bugs/server-control).

The Debian developer/upstream-centric view of manpages can be seen here.

Every now and then it may be worth reviewing the Debian downstream diff patches applied to man-pages, to see if there's anything they should have pushed upstream, but didn't. Have a look at the diff patches that are available by following the "unstable" release links at https://packages.debian.org/manpages and https://packages.debian.org/manpages-dev, and downloading the Debian tarballs. Or look at the web patchtracker.

The following mail address reaches people with an interest in man pages at Debian: manpages@packages.debian.org.

Ubuntu

Ubuntu uses Launchpad for manpages (bugs, package) and manpages-posix (bugs, package). There are links on the "bugs" pages to allow subscribing to bug reports.

Red Hat

Red Hat provides a man-pages bugzilla component.

URL for Fedora package: https://koji.fedoraproject.org/koji/packageinfo?packageID=401. From there, you can reach the RPM files, and unpack them to see the diffs from upstream, using:

    rpm2cpio foo.rpm | cpio -idmv --no-absolute-filenames 

Downstream Git repo for Red Hat patches:

    git clone https://src.fedoraproject.org/rpms/man-pages.git

Fedora

It is possible to subscribe to Fedora man-pages bug reports, as follows:

Testing new features

Test programs

Writing test programs (in C) is an essential part of writing man pages. It verifies the author's understanding of what is being documented and also finds bugs in the kernel and glibc. In some cases, example programs are also suitable for inclusion in the man pages themselves.

Testing new kernel features

To follow the development curve closely, try building and testing release candidate ("rc") kernels; the release candidates are tagged in the Git repository. After building and installing the kernel, write programs to test new features. Since the declarations of new system calls probably won't yet be in your (g)libc, the use of syscall(2) may be required; see the syscall(2) man page.

Testing new glibc features

For information on building and testing glibc releases, see Appendix C Installing the GNU C Library in the glibc manual, Frequently Asked Questions about the GNU C Library on the glibc wiki, and especially Carlos O'Donell's Testing a glibc build page on the glibc wiki.

All the world is not Linux

It is not enough to document what Linux does. Programmers writing portable applications need to know about places where Linux differs from other UNIX implementations, and about places where it doesn't adhere to standards.

Test programs

If in doubt about portability, write a test program and run it on a few other systems. As a starting point, testing say Solaris, FreeBSD, and HP-UX is likely to reveal most of the range of differences that occur on other implementations. Bonus points for testing on other BSDs, on AIX, etc.

Standards

Join the Austin group. (Membership is free.)

Get electronic copies of current and past UNIX standards, especially the POSIX.1-2008/SUSv4 standard, available in PDF format to members of the Austin group, and browsable online. Note also that section 3p of the man pages includes pages containing the specifications for all functions in POSIX.1 (e.g., try man 3p stat).

Other standards to look out for are SUSv1, SUSv2, and the SVID (System V Interface Definition), all of which are available in electronic form.

And get the C programming language standards.

And have a look at the LSB.

Read man pages for other systems

It can be useful to check the manual pages from other UNIX systems to see what differences there are from Linux. The FreeBSD project website displays manual pages for a range of UNIX implementations; look here.

Glibc info

Sometimes there is useful information to be found in the info(1) documentation for a particular function (if the info documentation exists...). Always worth checking.

Header files on other implementations

It can be handy to have a set of /usr/include trees from various other implementations. Grepping all of these trees can give some clues about interfaces that are/aren't present on other UNIX implementations.

Source code

The source code of some other UNIX implementations is available, and useful to study in order to determine undocumented details of behaviour on those systems.

The FreeBSD source code is available via Git mirror at https://github.com/freebsd/freebsd.

Get set up on kernel.org infrastructure

Look here.

Making man-pages releases

Uploading files

Release tarballs are made available at https://www.kernel.org/pub/linux/docs/man-pages/. Files are uploaded using kup. Look here.

man-pages website

The man-pages website resides at https://www.kernel.org/doc/man-pages/.

The Git repository for the website is at https://git.kernel.org/pub/scm/docs/man-pages/website.git/. Publication of new versions of the website are done by publishing an annotated tag and pushing to the repo.

Release notifications

Reporting kernel and glibc bugs

Testing kernel and glibc features while writing man pages will inevitably uncover bugs, which ideally should be reported.

For the kernel, the most effective way to report bugs (e.g., in a new system call) is typically to send an email to the developers of the API with a CC to LKML (linux-kernel@vger.kernel.org) or another relevant list. Alternatively, you can try making a bug report in the kernel bugzilla.

For information about reporting glibc bugs (including errors in the glibc info(1) documentation), see https://sourceware.org/glibc/wiki/FilingBugs.

Some history

The man-pages project was begun in 1993 by Rik Faith, who created releases 1.0 through to 1.5 (February 1995).

Rik Faith was succeeded by Andries Brouwer (aeb), who continued in the role for more than nine years, creating releases 1.6 (June 1995) through to 1.70 (October 2004).

The current maintainer, Michael Kerrisk (mtk), took over in November 2004, starting with release 2.00.