Ready for 2.28.

[thirdparty/man-pages.git] / HOWTOHELP

The following notes are written for people who want to help with 
maintaining manual pages in the Linux 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


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 (preferably < 100 lines;
   ideally < 50 lines).

-- Example programs should do error checking after system calls and 
   library function calls.

-- Example programs should be complete, and compile without 
   warnings when compiled with "cc -Wall",

-- 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 such as the following is acceptable:

        if (func(...) == -1)
            { perror("func"); exit(EXIT_FAILURE); }

For 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 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

        
ioprio_get(2)       (new in kernel 2.6.13) 
ioprio_set(2)       (new in kernel 2.6.13)
    See Documentation/block/ioprio.txt


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/ )
    
    
epoll_pwait(2)        (probably will arrive in 2.6.17)

    
The new *at(2) system calls in 2.6.16: 

    openat(2)       S                           [Already documented]
    faccessat(2)
    fstatat(2)      S   f (AT_SYMLINK_NOFOLLOW)
    fchmodat(2)
    fchownat(2)     S   f (AT_SYMLINK_NOFOLLOW)
    futimesat(2)    S                           [See also glibc wrapper]
    mkdirat(2)
    mknodat(2)
    linkat(2)         2
    unlinkat(2)     S   f (AT_REMOVEDIR)
    symlinkat(2)
    readlinkat(2)
    renameat(2)       2

In the above list: functions marked '2' take two dirfd arguments; 
functions marked 'f' take a flags argument that is not present 
in their traditional counterparts (and possible flag values
are listed in parentheses); and functions marked 'S' have
counterparts (not exactly the same) on Solaris.

Note that openat(2) is already documented and includes some NOTES 
on the rationale for the *at() interfaces; this page could serve 
as a template for the documentation of the remaining 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
-----------------

(See a further list of missing pages in the "undocumented(3)" manual page.

Searches like the following are likely to sugest 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
)

adjtime(3)  
bsd_signal(3)
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)    (Since glibc 2.3.4; probably to be documented in dlopen.3)
euidaccess(3) / eaccess(3)
fdopendir(3)  (since glibc 2.4)
fopencookie(3)
getsubopt(3)
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)
mkfifoat(3) -- see notes on the *at(2) syscalls above (since glibc 2.4)
readdir_r(3)  (probably as additional text in readdir.3)
open_wmemstream(3)   (since glibc 2.4)
posix_madvise(3)
program_invocation_name(3)
program_invocation_short_name(3)
sigstack(3)
sigwait(3)
sockatmark(3)
strftime_l(3) (since glibc 2.3)
strptime_l(3) (since glibc 2.3.2)
sysv_signal(3)
updwtmpx(3)

sigandset(3), sigosset(3), sigisemptyset(3) 
    (perhaps on same page as sigemptyset(3))

fwscanf(3), swscanf(3), vfwscanf(3), vswscanf(3), wscanf(3) 


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):

wcscoll(3)       (strcoll(3))
wcsxfrm(3)       (strxfrm(3))
wcschrnul(3)     (strchrnul(3))
wcswcs(3)        (strstr(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))
wscanf(3)        (scanf(3))
wcsftime(3)      (strftime(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()