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-AT-gmail.com
CC
linux-man-AT-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

System call	Since kernel	Notes
endian_switch(2)	2.6.26	POWER 6 specific; see http://thread.gmane.org/gmane.linux.ltp/5233/
perfmonctl(2)	2.4	IA-64 specific
restart_syscall(2)	2.6
add_key(2) keyctl(2) request_key(2)	2.6.10	See: Documentation/keys.txt and Documentation/keys-request-key.txt. Requires CONFIG_KEYS (and optionally CONFIG_KEYS_DEBUG_PROC_KEYS) under "Security options" Work is in progress on this page
sys_debug_setcontext(2)	2.6.11	PowerPC if CONFIG_POWERPC kernel config option is enabled
kexec_load(2)	2.6.13
migrate_pages(2)	2.6.16	See Documentation/vm/page_migration Work is in progress on this page
set_robust_list(2) get_robust_list(2)	2.6.17	Information can be found in the 2.6.17 ChangeLog under "lightweight robust futexes" See also http://lwn.net/Articles/172149/ and the kernel source file: Documentation/robust-futexes.txt.

/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 libc:


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

Function	Since glibc version	Notes
dlinfo(3)	2.3.3	Solaris and FreeBSD have a similar function.
dladdr1(3)	2.3.3
dlmopen(3)	2.3.4	Probably to be documented in dlopen(3); Solaris has a similar function.
mallinfo(3) mallopt(3)		There is out-of-date documentation in the glibc manual. Currently (glibc 2.7) the following are supported: #define M_TRIM_THRESHOLD -1 #define M_TOP_PAD -2 #define M_MMAP_THRESHOLD -3 #define M_MMAP_MAX -4 #define M_CHECK_ACTION -5 #define M_PERTURB -6
mcheck(3) mprobe(3)
posix_madvise(3)	2.2	POSIX_MADV_DONTNEED became a no-op in glibc 2.7, reflecting the fact that the underlying madvise(MADV_DONTNEED) is not consistent with POSIX semantics.
qsort_r(3)	2.8	Probably to be documented on qsort(3) page.
sigstack(3)
strftime_l(3)	2.3
strptime_l(3)	2.3.2
uselocale(3), newlocale(3), duplocale(3), freelocale(3)		These functions are in POSIX.1-2008
register_printf_function(), parse_printf_format(),	2.0	There are info pages, and <printf.h> contains useful information.
printf_size(), printf_size_info()	2.1	There are info pages, and <printf.h> contains useful information.
argp_error(3) argp_failure(3) argp_help(3) argp_parse(3) argp_program_bug_address(3) argp_program_version(3) argp_program_version_hook(3) argp_state_help(3) argp_usage(3)
posix_spawn(3) posix_spawnattr_destroy(3) posix_spawnattr_getflags(3) posix_spawnattr_getpgroup(3) posix_spawnattr_getschedparam(3) posix_spawnattr_getschedpolicy(3) posix_spawnattr_getsigdefault(3) posix_spawnattr_getsigmask(3) posix_spawnattr_init(3) posix_spawnattr_setflags(3) posix_spawnattr_setpgroup(3) posix_spawnattr_setschedparam(3) posix_spawnattr_setschedpolicy(3) posix_spawnattr_setsigdefault(3) posix_spawnattr_setsigmask(3) posix_spawn_file_actions_addclose(3) posix_spawn_file_actions_adddup2(3) posix_spawn_file_actions_addopen(3) posix_spawn_file_actions_destroy(3) posix_spawn_file_actions_init(3) posix_spawnp(3)
if_freenameindex(3) if_indextoname(3) if_nameindex(3) if_nametoindex(3)
getaddrinfo_a(3) gai_cancel(3) gai_error(3) gai_suspend(3)		libanl; since glibc 2.2.3; See http://people.redhat.com/~drepper/asynchnl.pdf
Various wide-character functions (with their traditional equivalents mentioned in parentheses)
wscanf(3) (scanf(3)) fwscanf(3) (fscanf(3)) swscanf(3) (sscanf(3)) vfwscanf(3) (vfscanf(3)) vswscanf(3) (vsscanf(3)) wcschrnul(3) (strchrnul(3)) wcscoll(3) (strcoll(3)) wcsftime(3) (strftime(3)) wcstod(3) (strtod(3)) wcstof(3) (strtof(3)) wcstold(3) (strtold(3)) wcstol(3) (atol(3)) wcstol(3) (strtol(3)) wcstoul(3) (strtoul(3)) wcstoll(3) (strtoll(3)) wcstoull(3) (strtoull(3)) wcstoq(3) (atoq(3)) wcstoq(3) (strtoq(3)) wcstouq(3) (strtouq(3)) wcswcs(3) (strstr(3)) wcsxfrm(3) (strxfrm(3))		After these man pages are written, add SEE ALSO entries from the pages for the traditional functions to the pages describing their wide-character equivalents.

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.

Function Since glibc
version Notes

pthread_atfork(3) *

pthread_attr_destroy(3) Done

pthread_attr_getaffinity_np(3) Done

pthread_attr_getdetachstate(3) Done

pthread_attr_getguardsize(3) Done

pthread_attr_getinheritsched(3) Done

pthread_attr_getschedparam(3) Done

pthread_attr_getschedpolicy(3) Done

pthread_attr_getscope(3) Done

pthread_attr_getstack(3) Done

pthread_attr_getstackaddr(3) Done

pthread_attr_getstacksize(3) Done

pthread_attr_init(3) Done

pthread_attr_setaffinity_np(3) Done

pthread_attr_setdetachstate(3) Done

pthread_attr_setguardsize(3) Done

pthread_attr_setinheritsched(3) Done

pthread_attr_setschedparam(3) Done

pthread_attr_setschedpolicy(3) Done

pthread_attr_setscope(3) Done

pthread_attr_setstack(3) Done

pthread_attr_setstackaddr(3) Done

pthread_attr_setstacksize(3) Done

pthread_barrierattr_destroy(3)

pthread_barrierattr_getpshared(3)

pthread_barrierattr_init(3)

pthread_barrierattr_setpshared(3)

pthread_barrier_destroy(3)

pthread_barrier_init(3)

pthread_barrier_wait(3)

pthread_cancel(3) Done

pthread_cleanup_pop(3) Done

pthread_cleanup_pop_restore_np(3) Done

pthread_cleanup_push(3) Done

pthread_cleanup_push_defer_np(3) Done

pthread_condattr_destroy(3)

pthread_condattr_getclock(3)

pthread_condattr_getpshared(3)

pthread_condattr_init(3)

pthread_condattr_setclock(3)

pthread_condattr_setpshared(3)

pthread_cond_broadcast(3) **

pthread_cond_destroy(3) **

pthread_cond_init(3) **

pthread_cond_signal(3) **

pthread_cond_timedwait(3) **

pthread_cond_wait(3) **

pthread_create(3) Done

pthread_detach(3) Done

pthread_equal(3) Done

pthread_exit(3) Done

pthread_getaffinity_np(3) Done

pthread_getattr_np(3) Done

pthread_getconcurrency(3)

pthread_getcpuclockid(3) Done

pthread_getschedparam(3) Done

pthread_getspecific(3) **

pthread_join(3) Done

pthread_key_create(3) **

pthread_key_delete(3) **

pthread_kill(3) Done

pthread_kill_other_threads_np(3) Done

pthread_mutexattr_destroy(3)

pthread_mutexattr_getpshared(3)

pthread_mutexattr_gettype(3)

pthread_mutexattr_init(3)

pthread_mutexattr_setpshared(3)

pthread_mutexattr_settype(3)

pthread_mutex_consistent_np(3) 2.4 POSIX.1-2008 has pthread_mutex_consistent()

pthread_mutexattr_getrobust_np(3) 2.4 POSIX.1-2008 has pthread_mutexattr_getrobust()

pthread_mutexattr_setrobust_np(3) 2.4 POSIX.1-2008 has pthread_mutexattr_setrobust()

pthread_mutexattr_getprotocol(3) 2.4

pthread_mutexattr_setprotocol(3) 2.4

pthread_mutexattr_getprioceiling(3) 2.4

pthread_mutexattr_setprioceiling(3) 2.4

pthread_mutex_getprioceiling(3) 2.4

pthread_mutex_setprioceiling(3) 2.4

pthread_mutex_destroy(3) **

pthread_mutex_init(3) **

pthread_mutex_lock(3) **

pthread_mutex_timedlock(3) **

pthread_mutex_trylock(3) **

pthread_mutex_unlock(3) **

pthread_once(3) Done

pthread_rwlockattr_destroy(3)

pthread_rwlockattr_getkind_np(3)

pthread_rwlockattr_getpshared(3)

pthread_rwlockattr_init(3)

pthread_rwlockattr_setkind_np(3)

pthread_rwlockattr_setpshared(3)

pthread_rwlock_destroy(3)

pthread_rwlock_init(3)

pthread_rwlock_rdlock(3)

pthread_rwlock_timedrdlock(3)

pthread_rwlock_timedwrlock(3)

pthread_rwlock_tryrdlock(3)

pthread_rwlock_trywrlock(3)

pthread_rwlock_unlock(3)

pthread_rwlock_wrlock(3)

pthread_self(3) Done

pthread_setaffinity_np(3) Done

pthread_setcancelstate(3) Done

pthread_setcanceltype(3) Done

pthread_setconcurrency(3) Done

pthread_setschedparam(3) Done

pthread_setschedprio(3) Done

pthread_setspecific(3) **

pthread_sigmask(3) Done

pthread_spin_destroy(3)

pthread_spin_init(3)

pthread_spin_lock(3)

pthread_spin_trylock(3)

pthread_spin_unlock(3)

pthread_testcancel(3) Done

pthread_timedjoin_np(3) Done

pthread_tryjoin_np(3) Done

pthread_yield(3) Done