Edit File: HOWTOHELP
The following notes are written for people who want to help with maintaining manual pages in the Linux man-pages package. See also the MAINTAINING and TODO documents in this directory. Read man-pages(7) for information about conventions that should be used in man pages for the man-pages package. Send suggestions and corrections to: mtk-manpages@gmx.net Cheers Michael Kerrisk man-pages maintainer THINGS YOU CAN DO TO HELP ========================= You can help in the following ways: -- sending in bug reports about problems in existing pages; (An alternative is to report the bug in one of the distribution-specific Bugzilla facilities, if that facility provides a mechanism to automatically forward bug reports to me. Currently, I am registered to receive man-page bug reports from the Debian bugzilla, but if other distributions provide a similar facility I may get myself registered for those; let me know.) -- writing patches that improve existing pages (see below); -- writing new pages (see below for a list of currently missing pages); -- grepping for the string FIXME in existing pages and writing a suitable patch (see below); -- asking me to add you to my distribution list for notification of new man-pages releases, and reviewing the changes that have occurred during a release (do "diff -ruN" between the directory trees for the current and previous releases); and -- suggesting improvements to this document. HOW TO CONTRIBUTE PATCHES ========================= Patches should be sent to Michael Kerrisk, mtk-manpages@gmx.net. When you submit a patch, please note the following: -- Submit a patch against the current version of the page. The current version of the man-pages package can be downloaded from ftp://ftp.win.tue.nl/pub/linux-local/manpages or: ftp://ftp.kernel.org/pub/linux/docs/manpages or mirrors: ftp://ftp.XX.kernel.org/pub/linux/docs/manpages -- Let me know how you obtained the information: was it by reading (or writing) the relevant kernel or (g)libc source code; by writing a test program (send it to me, if you want, and if it is clear and simple to use); from other documentation; from a mailing list or Usenet thread (please provide a URL if possible). -- Send patches in "diff -u" format, inline inside the mail message is usually best; if it is a very long patch then send it both inline and as an attachment. -- Send logically separate patches (e.g., for unrelated pages) as separate mails. -- In the body of the mail message, identify the manual page version against which the patch applies. -- Make sure that the mail has a suitable SUBJECT line (i.e., one that mentions the name(s) of the page(s) being patched). Don't put the manual page version in the subject line (it should already be in the body, and cluttering the subject line with a version number does not help me when filing messages...). A suitable subject line might be something like: [patch] shmop.2: add "(void *)" cast to RETURN VALUE -- If editing a page, and you find one or two white spaces at the end of an existing line, DON'T bother removing them. The reason is that in a "diff -u" patch this will make it look like there is a change when in fact nothing has changed. In most cases, these extra white spaces do no harm, so just leave them be. MANUAL PAGES IN OTHER PACKAGES ============================== Not all Linux manual pages are part of the man-pages set. In particular, most Section 1 and 8 pages come as part of some other package. The easiest way to determine which pages are part of the man-pages package is to download the latest tarball, and see if the page is present. If you want to submit a patch for a manual page that comes from another source, then you need to work out where the manual page comes from (i.e., which package) and who the maintainer of that manual page is. On an RPM-based distribution (e..g., SUSE, Red Had, Mandriva), you can do the following to find out which package owns a particular file. For example, suppose we want to find out who maintains the fstab(5) manual page: $ man -w fstab /usr/share/man/man5/fstab.5.gz $ rpm -qf /usr/share/man/man5/fstab.5.gz util-linux-2.12q-7.2 If we then look in the MAINTAINERS file in the util-linux package, we see: Maintainer: Adrian Bunk <bunk@stusta.de> Maintainer of getopt: Frodo Looijaard <frodol@dds.nl> Maintainer of simpleinit: Richard Gooch <rgooch@atnf.csiro.au> On a Debian-based distribution (e.g. Debian, Knoppix, Ubuntu) you can do the following: $ man -w fstab /usr/share/man/man5/fstab.5.gz $ dpkg -S /usr/share/man/man5/fstab.5.gz mount: /usr/share/man/man5/fstab.5.gz $ dpkg -p mount | grep Maintainer Maintainer: LaMont Jones <lamont@debian.org> Note: this gives you the Debian maintainer of the package in question, which is a good address to report to, since many packages and manual pages are modified by Debian. The maintainer of the original package can usually be found in a README in /usr/share/doc/<package-name>. Use "dpkg -L mount" to find all files from the mount package. On Gentoo, we can use the "equery belongs" command to do similar: $ equery belongs $(man -w fstab) (FIXME: add instructions for doing the equivalent of the above on distributions that use other schemes.) SECTION 9 MAN PAGES =================== These have nothing to with man-pages. They are documentation of in-kernel APIs, built from specially formatted comments in the kernel source. After installing the required software, these pages can be built from a kernel source tree using the command 'make mandocs'; see the kernel source file Documentation/HOWTO for more information. REPAIRING PAGES MARKED "FIXME" ============================== Grepping the source of the manual pages will show various places where pages are marked with the string FIXME. There is also a shell script (scripts/FIXME_list.sh) that can be used to obtain a list of FIXMEs in the manual page sources: $ cd man-pages $ sh scripts/FIXME_list.sh . The presence of a FIXME usually indicates that someone has noticed that some information on the page is incorrect or incomplete, but has not had the time/knowledge to fix the problem. (Sometimes a FIXME relates to a kernel or glibc bug report that is awaiting resolution, and it may be sufficient to check if the bug has been resolved and then provide a suitable write-up on the page.) If you know how to fix the problem, then please send a patch. However, note that some of the FIXME markings are associated with problems that are quite difficult: you need to ensure that you are knowledgeable on the relevant point(s), or you need to be willing to invest the time to become knowledgeable (by reading kernel or [g]libc source files and/or writing suitable test programs). MISSING MANUAL 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 manual 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 manual pages. -- Follow the existing formatting conventions for manual pages. Some information about formatting is provided in the "man(7)" manual page. As an example of how these conventions are employed, have a look at the "fcntl(2)" manual 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 manual page. Possible licenses include the GPL, the BSD license, or a range of other licenses, some of which can be seen in existing manual pages. -- You may find it useful to check the information in your page against the specifications in SUSv3/POSIX.1-2001 (http://www.opengroup.org/onlinepubs/009695399/toc.htm) or against manual pages on other implementations, but do not not violate the copyright on those publications by copying text from them. -- The GNU C library documents many of the functions that it provides using info(1). If you are thinking of writing a manual page for a function that is already documented in info(1) format, then ideally this page needs to present new or different information from that provided by the info(1) page (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 pages). (An alternative to consider is submitting a patch to the maintainers of the glibc documentation, if that is more appropriate.) System Calls ------------ add_key(2) (new in kernel 2.6.10) keyctl(2) (new in kernel 2.6.10) request_key(2) (new in kernel 2.6.10) See: Documentation/keys.txt Documentation/keys-request-key.txt Requires CONFIG_KEYS (and optionally CONFIG_KEYS_DEBUG_PROC_KEYS) under "Security options" restart_syscall(2) (new in kernel 2.6) kexec_load(2) (new in kernel 2.6.13) migrate_pages(2) (new in kernel 2.6.16) See Documentation/vm/page_migration preadv(2), pwritev(2) (new in ?? -- see http://www.lwn.net/Articles/164887/ ) (Perhaps these will ultimately be library functions.) set_robust_list(2) New in 2.6.17 get_robust_list(2) Information can be found in the 2.6.17 ChangeLog under "lightweight robust futexes" move_pages(2) New in 2.6.18 lutimesat(2) Likely to appear in a future kernel fallocate(2) May appear in a future kernel signalfd(2) Likely to appear around 2.6.23 (or pollfs?) See http://lwn.net/Articles/225714/ timerfd(2) Likely to appear around 2.6.22 (or pollfs?) See http://lwn.net/Articles/225714/ /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 ----------------- (See a further list of missing pages in the "undocumented(3)" manual page.) 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 $(echo $GLIBCDIR/abilist/*.abilist) | grep -v 'GLIBC' | \ awk '{print $1}' | 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 ) clock_nanosleep(3) crypt_r(3) (To be added to crypt.3) dlinfo(3) (Solaris and FreeBSD have a similar function.) dladdr1(3) dlmopen(3) (Solaris has a similar function; since glibc 2.3.4; probably to be documented in dlopen.3) etext, edata, end (variables) fdopendir(3) (since glibc 2.4) fopencookie(3) getgrouplist(3) (since glibc 2.2.4) getutmp(3) getutmpx(3) gnu_get_libc_release(3) gnu_get_libc_version(3) mallinfo(3) mallopt(3) mcheck(3), mprobe(3) memmem(3) (GNU extension) readdir_r(3) (probably as additional text in readdir.3) open_wmemstream(3) (since glibc 2.4) posix_madvise(3) sigstack(3) sigwait(3) strftime_l(3) (since glibc 2.3) strptime_l(3) (since glibc 2.3.2) tmpnam_r(3) (probably as additional text in tmpnam.3) updwtmpx(3) backtrace(3) backtrace_symbols(3) backtrace_fd(3) (There are info pages for these functions. See also page 48 of http://people.redhat.com/~drepper/tut1.ps) 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)) and fwscanf(3), swscanf(3), vfwscanf(3), vswscanf(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 manual pages are written, add SEE ALSO entries from the pages for the traditional functions to the pages describing their wide-character equivalents. 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) manual page, which gives an overview of Pthreads implementations on Linux, is designed as a base document for these manual pages. The list of required manual 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: pthread_atfork() * pthread_attr_destroy() pthread_attr_getaffinity_np() pthread_attr_getdetachstate() pthread_attr_getguardsize() pthread_attr_getinheritsched() pthread_attr_getschedparam() pthread_attr_getschedpolicy() pthread_attr_getscope() pthread_attr_getstack() pthread_attr_getstackaddr() pthread_attr_getstacksize() pthread_attr_init() pthread_attr_setaffinity_np() pthread_attr_setdetachstate() pthread_attr_setguardsize() pthread_attr_setinheritsched() pthread_attr_setschedparam() pthread_attr_setschedpolicy() pthread_attr_setscope() pthread_attr_setstack() pthread_attr_setstackaddr() pthread_attr_setstacksize() pthread_barrierattr_destroy() pthread_barrierattr_getpshared() pthread_barrierattr_init() pthread_barrierattr_setpshared() pthread_barrier_destroy() pthread_barrier_init() pthread_barrier_wait() pthread_cancel() ** pthread_cleanup_pop() ** pthread_cleanup_pop_restore_np() pthread_cleanup_push() ** pthread_cleanup_push_defer_np() pthread_condattr_destroy() pthread_condattr_getclock() pthread_condattr_getpshared() pthread_condattr_init() pthread_condattr_setclock() pthread_condattr_setpshared() pthread_cond_broadcast() ** pthread_cond_destroy() ** pthread_cond_init() ** pthread_cond_signal() ** pthread_cond_timedwait() ** pthread_cond_wait() ** pthread_create() *** pthread_detach() *** pthread_equal() *** pthread_exit() *** pthread_getaffinity_np() pthread_getattr_np() pthread_getconcurrency() pthread_getcpuclockid() pthread_getschedparam() pthread_getspecific() ** pthread_join() *** pthread_key_create() ** pthread_key_delete() ** pthread_kill() * pthread_kill_other_threads_np() pthread_mutexattr_destroy() pthread_mutexattr_getpshared() pthread_mutexattr_gettype() pthread_mutexattr_init() pthread_mutexattr_setpshared() pthread_mutexattr_settype() pthread_mutex_destroy() ** pthread_mutex_init() ** pthread_mutex_lock() ** pthread_mutex_timedlock() ** pthread_mutex_trylock() ** pthread_mutex_unlock() ** pthread_once() ** pthread_rwlockattr_destroy() pthread_rwlockattr_getkind_np() pthread_rwlockattr_getpshared() pthread_rwlockattr_init() pthread_rwlockattr_setkind_np() pthread_rwlockattr_setpshared() pthread_rwlock_destroy() pthread_rwlock_init() pthread_rwlock_rdlock() pthread_rwlock_timedrdlock() pthread_rwlock_timedwrlock() pthread_rwlock_tryrdlock() pthread_rwlock_trywrlock() pthread_rwlock_unlock() pthread_rwlock_wrlock() pthread_self() ** pthread_setaffinity_np() pthread_setcancelstate() pthread_setcanceltype() pthread_setconcurrency() pthread_setschedparam() pthread_setspecific() ** pthread_sigmask() * pthread_spin_destroy() pthread_spin_init() pthread_spin_lock() pthread_spin_trylock() pthread_spin_unlock() pthread_testcancel() ** pthread_timedjoin_np() pthread_tryjoin_np() pthread_yield() * pthread_yield_np() And new in glibc 2.4: pthread_mutex_consistent_np() pthread_mutexattr_getrobust_np() pthread_mutexattr_setrobust_np() pthread_mutexattr_getprotocol() pthread_mutexattr_setprotocol() pthread_mutexattr_getprioceiling() pthread_mutexattr_setprioceiling() pthread_mutex_getprioceiling() pthread_mutex_setprioceiling()