Manual pages that are missing from Linux man-pages

Below is a list of pages that I would like to see in the man-pages set. If you are thinking of writing one or more of these pages, then:

• It might be wise to let me know in advance, just in case someone else has started working on the page, or a related page. I may also be able point you at useful sources of information for the man page.
  
  
• You need to have a reasonably high degree of understanding of the topic, or be prepared to invest the time (e.g., reading source code, writing test programs) to gain that understanding. Writing test programs is important: quite a few kernel and glibc bugs have been uncovered while writing test programs during the preparation of man pages.
  
  
• Follow the existing formatting conventions for man pages. Some information about formatting is provided in the man(7) and man-pages(7) man pages. As an example of how these conventions are employed, have a look at the fcntl(2)
man page and read its source file (man2/fcntl.2).


• The page must be submitted under some sort of license that permits the page to be freely redistributed and modified. Include that license or a reference to it, in the source code of the man page. For a list of preferred free licenses, look here.
  
  
• Say how you obtained the information in the page: was it by reading (or writing) the relevant kernel or (g)libc source code; by writing a test program (send it with the patch, if you want, and if it is clear and simple to use); from a standards document; from other documentation; from a mailing list or Usenet thread (please provide a URL if possible)?
  
  
• Send the page (inline, not as an attachment) to

  mtk.manpages@gmail.com

  CC

  linux-man@vger.kernel.org

  and CC any other interested parties, including any people that you know of who might be suitable reviewers for the page.
  
  
• The GNU C library documents many of the functions that it provides using info(1). Since many programmers prefer documentation in man format, this does not preclude writing a manual page for functions that are already documented using info(1). Ideally, the manual page would include at least as much information as is included in the info(1) page, and also include details that are typically not covered in info(1) pages, for example, historical information about how the function has changed across various glibc versions, or variations in operation across C libraries; such information is often not present in info(1) pages). (An alternative to consider is submitting a patch to the maintainers of the glibc documentation, if that is more appropriate.)

System Calls

/sys file system

There is no man page for the /sys file system: there probably should be a sys(5) page similar to proc(5). The kernel source file Documentation/filesystems/sysfs.txt provides a starting point for this page.

Library Functions

A list of undocumented (GNU) C library functions is given below. Searches like the following are likely to suggest other functions that need to be documented:

MPDIR=~/man-pages       # Directory containing uncompressed man-pages
GLIBCDIR=/SOME_DIR      # Directory containing glibc tree

for f in  $(cat $(find $GLIBCDIR -name Versions |
                egrep -v '/(hurd|mach)/') |
        egrep -v '({|}|^%)' |
        sed -e 's/#.*//' |
        tr ';' '\012' |
        sed 's/^  *//' |
        grep -v '^[_.]' |
        sort -u); do
    if ! test -f "$MPDIR/man3/$f.3" > /dev/null 2>&1 &&
                ! test -f "$MPDIR/man2/$f.2" > /dev/null 2>&1 ; then
        echo $f;
    fi
done

Alternatively, one can look at the text symbols exported by a particular library (unless the library symbols have been stripped), to see if there is a corresponding man page. Here, an example using libm:

nm -D /lib/libm.so.6 | sed -re '/^[0-9a-f]* T /!d; s///; /^_/d' | 
	xargs whatis | sed -ne 's/: nothing appropriate\.$//p' | sort -u

In many cases, the interfaces listed below were found using such scripts, and it hasn't been checked whether these are obsolete interfaces that may better be not documented.

The POSIX Threads API

And last, but far from least, the POSIX threads API. Note that there is an existing, outdated set of pages supplied with glibc that document the old LinuxThreads implementation. (These pages are written under a license that allows re-use, so some material that they contain could be used in new pages.)

What is required is a set of pages that document the complete API, describing details where LinuxThreads and NPTL diverge from the standard. The existing pthreads(7) man page, which gives an overview of Pthreads implementations on Linux, is designed as a background document for these man pages.

The list of required man pages is long (related functions can be grouped on a single page); those marked with more asterisks are probably the most desirable to get done first.