| The following notes are written for people who want to help with |
| maintaining manual pages in the man-pages package. |
| |
| |
| 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 |
| |
| |
| 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, 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. |
| |
| (FIXME: add instructions for doing the equivalent of the above on |
| distributions that use other schemes.) |
| |
| |
| REPAIRING PAGES MARKED "FIXME" |
| ============================== |
| |
| Grepping the source of the manual pages will show various places where |
| pages are marked with the string FIXME. This 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 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 many 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). |
| |
| |
| CONVENTIONS FOR MANUAL PAGE LAYOUT |
| ================================== |
| |
| Please keep source code line length <= 72 characters wherever possible. |
| This helps avoid line-wrapping in some mail clients when patches are |
| submitted inline. |
| |
| New sentences are generally best started on new lines. This makes |
| it easier to see the effect of patches, which often operate at the |
| level of individual sentences. |
| |
| |
| EXAMPLE PROGRAMS |
| ================ |
| |
| New manual pages, or patches to existing manual pages, can include |
| example programs demonstrating how to use a system call or library |
| function. However, note the following: |
| |
| -- Example programs should be written in C. |
| |
| -- An example program is only necessary and useful if it demonstrates |
| something beyond what can easily be provided in a textual |
| description of the interface. An example program that does nothing |
| other than call an interface usually serves little purpose. |
| |
| -- Example programs should be fairly short. |
| |
| -- Example programs should do error checking after system calls and |
| library function calls. |
| |
| -- Where possible and appropriate, example programs should allow |
| experimentation, by varying their behaviour based on inputs |
| (ideally from command-line arguments, or alternatively, via |
| input read by the program). |
| |
| Example programs should be laid out according to Kernighan and |
| Ritchie, with a few concessions: |
| |
| -- 4-space indents are preferred, in unusual cases, 2-space indents |
| may be okay. (Avoid the use of TAB characters in source code!) |
| |
| -- In the interests of keeping a program short, compressing |
| error-handling code as follows is acceptable: |
| |
| if (func(...) == -1) |
| { perror("func"); exit(EXIT_FAILURE); } |
| |
| For some some examples of what example programs should look like, see |
| the wait.2 and pipe.2 manual pages. |
| |
| |
| 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. |
| |
| -- 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 |
| 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) |
| keyctl(2) |
| request_key(2) |
| |
| delete_module(2) |
| init_module(2) |
| create_module(2) (Present up to and including kernel 2.4, absent in 2.6) |
| query_module(2) (Present up to and including kernel 2.4, absent in 2.6) |
| |
| ioprio_get(2) (new in kernel 2.6.13) |
| ioprio_set(2) (new in kernel 2.6.13) |
| |
| mq_getsetattr(2) |
| mq_notify(2) |
| mq_open(2) |
| mq_receive() / mq_timedreceive(2) |
| mq_send() / mq_timedsend(2) |
| mq_unlink(2) |
| |
| Manual pages might also be useful for the following system calls: |
| |
| get_kernel_syms(2) (Present up to and including kernel 2.4, absent in 2.6) |
| restart_syscall(2) (new in 2.6) |
| set_zone_reclaim(2) (new in kernel 2.6.13) |
| sys_kexec_load(2) (new in kernel 2.6.13) |
| |
| |
| /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.) |
| |
| adjtime(3) |
| dlinfo(3) (Solaris and FreeBSD have a similar function.) |
| dladdr1(3) |
| dlmopen(3) (Since glibc 2.3.4; probably to be documented on dlopen.3 page) |
| memmem(3) (GNU extension) |
| readdir_r(3) (probably as additional text in readdir.3) |
| sigstack(3) |
| sigwait(3) |
| strftime_l(3) (since glibc 2.3) |
| strptime_l(3) (since glibc 2.3.2) |
| |
| The POSIX semaphores API: sem_close(3), sem_destroy(3), |
| sem_getvalue(3), sem_init(3), sem_open(3), sem_post(3), |
| sem_timedwait(3), sem_trywait(3), sem_unlink(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) |
| |
| 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, 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() |