File: HOWTOHELP

package info (click to toggle)
man-pages-it 2.80-3
  • links: PTS
  • area: main
  • in suites: lenny, squeeze, wheezy
  • size: 1,660 kB
  • ctags: 13
  • sloc: makefile: 109
file content (542 lines) | stat: -rwxr-xr-x 18,744 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
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()