mirror of https://github.com/mkerrisk/man-pages
429 lines
15 KiB
Plaintext
429 lines
15 KiB
Plaintext
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)
|
|
|
|
inotify_add_watch(2)
|
|
inotify_init(2)
|
|
inotify_rm_watch(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)
|
|
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()
|