LDP
/
man-pages
mirror of https://github.com/mkerrisk/man-pages
0
1
Fork 0
Code Releases Activity

Ready for 2.49

This commit is contained in:
Michael Kerrisk 2007-05-11 20:01:16 +00:00
parent cd8a9ce442
commit c710d55271
5 changed files with 328 additions and 206 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

123
Changes
View File

@ -5,11 +5,11 @@ Released: 2007-??-??
Contributors
------------
Bruni Haible <bruno@clisp.org>
The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:
Bruno Haible <bruno@clisp.org>
Justin Pryzby <justinpryzby@users.sourceforge.net>
Apologies if I missed anyone!
@ -17,6 +17,43 @@ Apologies if I missed anyone!
New pages
---------
bsd_signal.3
mtk
Documentation of bsd_signal().
euidaccess.3
mtk
Manual page for euidaccess() and eaccess().
getsubopt.3
mtk / Justin Pryzby
Documentation of getsubopt().
sysv_signal.3
mtk
Documentation of sysv_signal().
New links
---------
epoll_pwait.2
mtk
New link to epoll_wait.2.
eaccess.3
mtk
New link to new euidaccess.3,
sem_timedwait.3
mtk
New link to sem_wait.3.
sem_trywait.3
mtk
New link to sem_wait.3.
Global changes
--------------
@ -27,6 +64,70 @@ places.
Changes to individual pages
---------------------------
access.3
mtk
Added SEE ALSO ref to new euidaccess.3 page.
epoll_pwait.2
mtk
Added description of epoll_pwait(), new in kernel 2.6.19.
execve.2
mtk
Add text noting that Linux allows 'argv' and 'envp' to be
NULL, but warning that this is non-standard and non-portable,
and should be avoided in portable programs.
Bug filed (http://bugzilla.kernel.org/show_bug.cgi?id=8408)
to get this changed, but maybe that won't be done because it
is an ABI change.
mtk
Added an example program.
mtk
Expanded the discussion of interpreter scripts and the
'optional-arg' argument of an interpreter script.
For further info, see
http://homepages.cwi.nl/~aeb/std/hashexclam-1.html
http://www.in-ulm.de/~mascheck/various/shebang/
mtk
Added text noting that FD_CLOEXEC causes record locks to be
released.
mtk
Mention effect of MS_NOSUID mount(2) flag for set-user-ID
programs.
mtk
Expanded description of handling of file descriptors during
execve(), adding text to note that descriptors 0, 1, and 2
may be treated specially.
faccessat.3
mtk
Added SEE ALSO ref to new euidaccess.3 page.
mmap.2
mtk
Place MAP_* flags list in alphabetical order.
readv.2
mtk
A fairly substantial rewrite, which among other things
fixes the problem reported by Kyle Sluder in
http://bugzilla.kernel.org/show_bug.cgi?id=8399
And added some example code.
sigaction.2
mtk
Added text referring to the discussion of async-signal-safe
functions in signal(7).
A few other minor formatting and wording changes.
signal.2
mtk
Moved the discussion of async-signal-safe functions to signal(7).
Added text referring to the discussion of async-signal-safe
functions in signal(7).
Added SEE ALSO entries referring to new bsd_signal.3 and
sysv_signal.3 pages.
copysign.3
Bruno Haible
Clarify discussion of negative zero.
@ -34,8 +135,24 @@ copysign.3
iconv_open.3
Bruno Haible
Describe the glibc/libiconv //TRANSLIT and //IGNORE extensions
for 'tocode'.
for 'tocode'.
iswblank.3
Bruno Haible
Update CONFORMING TO; iswblank() is in POSIX.1-2001.
subopt.3
mtk
Add SEE ALSO ref to new getsubopt.3.
inotify.7
mtk
Defintions for IN_DONT_FOLLOW, IN_MASK_ADD, and IN_ONLYDIR
were added to glibc in version 2.5.
signal.7
mtk
Incorporated (and slightly modified) the text on
async-signal-safe functions that was formerly in signal(2).
Added SEE ALSO entries referring to new bsd_signal.3 and
sysv_signal.3 pages.

146
Changes.old
View File

@ -4774,12 +4774,12 @@ Thomas Huriaux / mtk
Various formatting found as a result of reviewing the following
command were fixed.
for a in $(wc man?/*.?| awk '$1 > 2 ' | grep -v total); do
echo $a; groff -Tascii -wmac -mman $a > /dev/null;
for a in $(wc man?/*.?| awk '$1 > 2 ' | grep -v total); do
echo $a; groff -Tascii -wmac -mman $a > /dev/null;
done 2>&1 | less
See Debian Bug# 378544.
Typographical or grammatical errors have been corrected in several
places.
@ -4789,7 +4789,7 @@ New pages
readlinkat.2
mtk (after prompting from Ivana Varekova)
New page for readlinkat(2), new in kernel 2.6.16.
Changes to individual pages
---------------------------
@ -4811,14 +4811,14 @@ epoll_ctl.2
exevce.2
mtk
Add text noting that effective IDs are copied to
Add text noting that effective IDs are copied to
saved set-IDs during execve().
See Debian bug 379297.
getitimer.2
mtk
Noted effect of fork() and execve() on interval timers.
getrlimit.2
mtk
Noted effect of fork() and execve() on resource limits.
@ -4829,7 +4829,7 @@ getpriority.2
inotify_add_watch.2
mtk
Some rewording; included text describing required file
Some rewording; included text describing required file
permissions.
intro.2
@ -4850,7 +4850,7 @@ mmap.2
Expand description MAP_NONBLOCK.
mtk
Various minor formatting fixes.
openat.2
mtk
Added SEE ALSO linking to readlinkat.2.
@ -4863,7 +4863,7 @@ nanosleep.2
nice.2
mtk
Very minor rewording.
readlink.2
mtk
Added SEE ALSO linking to readlinkat.2.
@ -4871,15 +4871,15 @@ readlink.2
sched_setscheduler.2
mtk
Noted preservation of scheduling parameters across execve().
setpgid.2
mtk
Noted effect of fork() and execve() on process group ID.
setsid.2
mtk
Noted effect of fork() and execve() on session ID.
umask.2
mtk
Noted effect of fork() and execve() on umask.
@ -4927,10 +4927,10 @@ in most manual pages.
* eliminate discussion of errors that can occur on other
systems. This information exists only patchily in the
manual pages, is probably of limited use, is hard to maintain,
manual pages, is probably of limited use, is hard to maintain,
and was in some cases simply wrong (and probably always was).
* Tried to ensure that those interfaces specified in C99 or
* Tried to ensure that those interfaces specified in C99 or
POSIX.1-2001 are marked as such in their manual pages.
intro.1
@ -5064,7 +5064,7 @@ execve.2
fork.2
mtk, after a suggestion by Christoph Hellwig
Greatly expanded, to describe all attributes that differ
Greatly expanded, to describe all attributes that differ
in parent and child.
linkat.2
@ -5074,7 +5074,7 @@ linkat.2
set_mempolicy.2
mtk / Andi Kleen
Memory policy is preserved across execve().
write.2
mtk / Alain Portal
SEE ALSO for writev should refer to Section 2, not 3.
@ -5082,7 +5082,7 @@ write.2
getcwd.3
Samuel Thibault / mtk
Fix SYNOPSIS and CONFORMING TO text for getwd() and
Fix SYNOPSIS and CONFORMING TO text for getwd() and
get_current_dir().
See Debian bug: 381692
@ -5093,7 +5093,7 @@ proc.5
capabilities.7
Alain Portal
Restore text accidentally deleted in 2.39.
regex.7
mtk / Alain Portal
Change references to "1003.2" to "POSIX.2".
@ -5162,20 +5162,20 @@ execve.2
fork.2
mtk
Mappings marked with madvise(MADV_DONTFORK) are not inherited
Mappings marked with madvise(MADV_DONTFORK) are not inherited
by child.
getdtablesize.2
mtk
Noted that sysconf(_SC_OPEN_MAX) is preferred in portable
Noted that sysconf(_SC_OPEN_MAX) is preferred in portable
applications.
getpagesize.2
mtk
Noted that sysconf(_SC_PAGE_SIZE) is preferred in portable
Noted that sysconf(_SC_PAGE_SIZE) is preferred in portable
applications.
_SC_PAGE_SIZE is available on most systems.
madvise.2
mtk
Document MADV_REMOVE, new in 2.6.16.
@ -5184,10 +5184,10 @@ madvise.2
mount.2
mtk / Trond Myklebust
MNT_FORCE can cause data loss.
mmap.2
mtk
Added note on Linux's old (pre-2.6.12) buggy treatment of
Added note on Linux's old (pre-2.6.12) buggy treatment of
length==0.
Justin Pryzby / mtk
Added some EINVAL errors.
@ -5198,7 +5198,7 @@ mremap.2
msync.2
mtk
Added EBUSY error for case where MS_INVALIDATE is applied to
Added EBUSY error for case where MS_INVALIDATE is applied to
a locked region.
posix_fadvise.2
@ -5216,7 +5216,7 @@ prctl.2
PR_SET_FPEXC, PR_GET_FPEXC.
Michael Kerrisk
Document PR_GET_ENDIAN and PR_SET_ENDIAN.
remap_file_pages.2
mtk
Add "#define _GNU_SOURCE" to SYNOPSIS.
@ -5228,11 +5228,11 @@ sync_file_range.2
vfork.2
mtk
Noted interactions with fork handlers in multithreaded programs.
wait4.2
mtk
Added feature test macros to SYNOPSIS.
clog2.3
mtk / aeb / Kevin Ryde
Fix broken text in description.
@ -5250,10 +5250,10 @@ mq_receive.3
qsort.2
Hrvoje Niksic
Fix wording referring to the use of strcmp() in 'compar'
Fix wording referring to the use of strcmp() in 'compar'
function.
See Debian bug 391402.
sendfile.2
mtk
Added SEE ALSO referring to new splice.2 page.
@ -5261,7 +5261,7 @@ sendfile.2
termios.3
mtk
Documented IUTF8 (which was new in kernel 2.6.4).
tzset.3
mtk
Added some TZ examples.
@ -5320,10 +5320,10 @@ Changes to individual pages
brk.2
Evan Teran / mtk
Add text describing behaviour of the Linux brk() system call
and point out that the glibc brk() wrapper provides different
and point out that the glibc brk() wrapper provides different
behaviour.
mtk
Note that sbrk() is implemented as a library function in glibc
Note that sbrk() is implemented as a library function in glibc
that calls the brk() system call.
futex.2
@ -5335,10 +5335,10 @@ getnameinfo.3
Ulrich Drepper, with edits by mtk
Add text describing Internationalized Domain Name
extensions.
open.2
mtk / Eduard Bloch
Fix description of O_LARGEFILE to mention required feature test
Fix description of O_LARGEFILE to mention required feature test
macros.
ptrace.2
@ -5357,7 +5357,7 @@ wcwidth.3
core.5
mtk
Linux 2.4.21 added core_pattern (which was already in 2.6).
Noted a few more reasons why a core dump file might not
Noted a few more reasons why a core dump file might not
be produced.
@ -5409,7 +5409,7 @@ strerror.3
rtc.4
David Brownell
Update the RTC man page to reflect the new RTC class framework:
- Generalize ... it's not just for PC/AT style RTCs, and there
@ -5516,13 +5516,13 @@ mtk
unlinkat.2
mkfifoat.3
mtk
mtk
Various references to "getty" were changed to "mingetty", since
that is the manual page more likely to be found on current systems.
mtk, after a suggestion by Reuben Thomas <rrt@sc3d.org>
Updated various header pages to accurately reflect which functions
are and are not part of C89. Also fixed/improved a few other
Updated various header pages to accurately reflect which functions
are and are not part of C89. Also fixed/improved a few other
CONFORMING TO entries.
mtk
@ -5633,7 +5633,7 @@ mbind.2
Samuel Thibault / mtk
Fix EINVAL description.
See Debian bug 411777.
mincore.2
Nick Piggin
Kernel 2.6.21 fixes several earlier bugs in mincore().
@ -5647,16 +5647,16 @@ mmap.2
mtk
Rewrote and reorganised various parts to be clearer.
Taken from Fedora downstream patches; thanks to Ivana Varekova
Removed text stating that mmap() never returns 0; that's
Removed text stating that mmap() never returns 0; that's
not true.
mount.2
mtk / Val Henson
Document MS_RELATIME, new in Linux 2.6.20.
open.2
Andre Majorel / mtk
On Linux, the error returned when opening a large file on a
On Linux, the error returned when opening a large file on a
32-bit system is actually EFBIG, not EOVERFLOW.
posix_fadvise.2
@ -5673,7 +5673,7 @@ semop.2
If sops contains multiple operations, then these are performed
in array order. All Unix systems that I know of do this,
and some Linux applications depend on this behaviour. SUSv3
made no explicit statement here, but SUSv4 will explicitly
made no explicit statement here, but SUSv4 will explicitly
require this behaviour.
Small rewording of explanation of "atomically".
@ -5682,11 +5682,11 @@ signal.2
Fix incorrect argument name in DESCRIPTION.
mtk
Small wording improvement.
socket.2
Nicolas François
Add reference to ipv6.7 page.
socketcall.2
Nicolas François
Fix .TH line.
@ -5701,8 +5701,8 @@ statvfs.2
symlink.2
mtk / Nicolas François
Removed cryptic text under CONFORMING to referring to
"open(2) and NFS". There is no relevant text in open.2 as
Removed cryptic text under CONFORMING to referring to
"open(2) and NFS". There is no relevant text in open.2 as
far as I (mtk) can see.
time.2
@ -5717,21 +5717,21 @@ write.2
ptrace.2
Chuck Ebbert
When the parent receives an event with PTRACE_EVENT_* set,
the child is not in the normal signal delivery path. This
means the parent cannot do ptrace(PTRACE_CONT) with a signal
or ptrace(PTRACE_KILL). kill() with a SIGKILL signal can be
used instead to kill the child process after receiving one
When the parent receives an event with PTRACE_EVENT_* set,
the child is not in the normal signal delivery path. This
means the parent cannot do ptrace(PTRACE_CONT) with a signal
or ptrace(PTRACE_KILL). kill() with a SIGKILL signal can be
used instead to kill the child process after receiving one
of these messages.
sched_setaffinity.2
mtk
Fix glibc version number in description of 'cpusetsize' argument.
vfork.2
mtk
Stripped some excess/outdated text from the BUGS section.
basename.3
mtk / Jorge Peixoto de Morais Neto
Add text to clarify that the pointer returned by these
@ -5751,8 +5751,8 @@ getopt.3
mtk
Added getopt() example program.
mtk
Add a few words to clarify the operation of the GNU-specific
double-colon feature, which allows options to have optional
Add a few words to clarify the operation of the GNU-specific
double-colon feature, which allows options to have optional
arguments.
See Debian bug352139.
@ -5775,18 +5775,18 @@ log10.3
malloc.3
Nicolas François
Small rewording to mention calloc().
posix_openpt.3
Martín Ferrari
Fix return type in SYNOPSIS; as per Debian bug 400971.
Needs _XOPEN_SOURCE == 600; as per Debian bug 400975.
Julien BLACHE
s/ptsname/posix_openpt/ in RETURN VALUE
re_comp.3
Taken from Fedora downstream patches; thanks to Ivana Varekova
Add "#define _REGEX_RE_COMP" to SYNOPSIS.
regex.3
Nicolas François
Fix .TH line.
@ -5843,10 +5843,10 @@ mdoc.7
mtk / Nicolas François
Remove CONFIGURATION section, since this does not seem to be
true for Linux.
svipc.7
Nicolas François
Fix data types in associated data structures;
Fix data types in associated data structures;
remove non-existent semzcnt and semncnt fields.
time.7
@ -5859,9 +5859,9 @@ Released: 2007-04-05
Global changes
--------------
This release consists mainly of formatting fixes (to a large
This release consists mainly of formatting fixes (to a large
number of pages) to achieve greater consistency across pages.
With the exception of the few individual changes noted below,
With the exception of the few individual changes noted below,
no changes were made to content.
Changes to individual pages
@ -5887,17 +5887,17 @@ Released: 2007-04-06
Global changes
--------------
This release consists mainly of formatting fixes (to a large
This release consists mainly of formatting fixes (to a large
number of pages) to achieve greater consistency across pages:
* Most instances of two or more consecutive blank lines in man
* Most instances of two or more consecutive blank lines in man
page output were shrunk to a single line.
* A number of example programs were reformatted
to more closely match K&R style.
* In various places (mainly code examples), the use of tabs was
* In various places (mainly code examples), the use of tabs was
replaced by spaces
With the exception of the few individual changes noted below,
With the exception of the few individual changes noted below,
no changes were made to content.
@ -5951,7 +5951,7 @@ sched_rr_get_interval.2
mtk
Remove crufty statement that this system call is not implemented.
The nice interval can be used to control the size of
the round-robin quantum.
the round-robin quantum.
Corrected .TH line.
ip.7
@ -5986,7 +5986,7 @@ There is very little change to output formatting or content (see the
notes below).
mtk
In various places where it occurred,
In various places where it occurred,
s/nonnegative/non-negative/
mtk

251
HOWTOHELP
View File

@ -1,4 +1,4 @@
The following notes are written for people who want to help with
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.
@ -18,25 +18,25 @@ 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
-- 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);
-- 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);
-- 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
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.
@ -49,7 +49,7 @@ 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
version of the man-pages package can be downloaded from
ftp://ftp.win.tue.nl/pub/linux-local/manpages
@ -59,60 +59,61 @@ When you submit a patch, please note the following:
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
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
-- 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
-- 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
-- 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
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" 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.
-- 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
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
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:
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
If we then look in the MAINTAINERS file in the util-linux
package, we see:
Maintainer: Adrian Bunk <bunk@stusta.de>
@ -120,7 +121,7 @@ package, we see:
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
On a Debian-based distribution (e.g. Debian, Knoppix, Ubuntu) you can
do the following:
$ man -w fstab
@ -131,11 +132,15 @@ do the following:
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
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.)
@ -144,92 +149,92 @@ 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
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 shell script
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 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
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
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
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.
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
New sentences should be 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
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
-- 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
-- Example programs should do error checking after system calls and
library function calls.
-- Example programs should be complete, and compile without
-- 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
-- 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:
Example programs should be laid out according to Kernighan and
Ritchie style, with a few concessions:
-- 4-space indents are preferred. (Avoid the use of TAB characters
-- 4-space indents are preferred. (Avoid the use of TAB characters
in source code!)
-- In the interests of keeping a program short, compressing
-- In the interests of keeping a program short, compressing
error-handling code such as in the following is acceptable:
if (func(...) == -1)
{ perror("func"); exit(EXIT_FAILURE); }
For some examples of what example programs should look like, see
For some examples of what example programs should look like, see
the wait.2 and pipe.2 manual pages.
@ -244,11 +249,11 @@ If you are thinking of writing one or more of these pages, then:
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
-- 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.
@ -258,28 +263,28 @@ If you are thinking of writing one or more of these pages, then:
(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
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
-- 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
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
------------
@ -294,29 +299,32 @@ request_key(2) (new in kernel 2.6.10)
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
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
epoll_pwait(2) New in 2.6.19
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
----------------
@ -329,9 +337,10 @@ this page.
Library Functions
-----------------
(See a further list of missing pages in the "undocumented(3)" manual page.
(See a further list of missing pages in the "undocumented(3)"
manual page.)
Searches like the following are likely to sugest other functions
Searches like the following are likely to suggest other functions
that need to be documented:
@ -339,27 +348,24 @@ 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
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;
echo $f;
fi
done
)
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) (Solaris has a similar function; since glibc 2.3.4;
dlmopen(3) (Solaris has a similar function; since glibc 2.3.4;
probably to be documented in dlopen.3)
etext, edata, end (variables)
euidaccess(3) / eaccess(3)
fdopendir(3) (since glibc 2.4)
fopencookie(3)
getgrouplist(3) (since glibc 2.2.4)
getsubopt(3)
getutmp(3)
getutmpx(3)
gnu_get_libc_release(3)
@ -375,7 +381,6 @@ sigstack(3)
sigwait(3)
strftime_l(3) (since glibc 2.3)
strptime_l(3) (since glibc 2.3.2)
sysv_signal(3)
tmpnam_r(3) (probably as additional text in tmpnam.3)
updwtmpx(3)
@ -425,12 +430,12 @@ 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
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
Various wide-character functions (with their traditional equivalents
mentioned in parentheses):
wscanf(3) (scanf(3))
@ -451,25 +456,25 @@ 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
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
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
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_destroy()
pthread_attr_getaffinity_np()
pthread_attr_getdetachstate()
pthread_attr_getguardsize()

10
MAINTAINING
View File

@ -37,7 +37,7 @@ Glibc source code
Same story as the kernel.
-- Keep up to date trees for 2.0.x, 2.1.x, 2.2.x, 2.3.x, 2.4.x.
-- Keep up to date trees for all 2.x, x >= 0 releases.
-- Keep diff files for all minor releases of the glibc tree.
As with kernel, these can be grepped to help determine
@ -65,7 +65,7 @@ Linux Kernel (LKML)
subscribe linux-kernel
The problem with this list is that the volume is extremely high,
so keeping track of it all would require a lot of time.
so keeping close track of it all would require a lot of time.
http://www.kernel.org/ provides the locations of a few searchable
archives of this mailing list.
@ -90,7 +90,7 @@ http://kerneltrap.org/news
Kernel releases
---------------
When a new minor kernel release is made (e.g., 2.6.19), scan the
When a new minor kernel release is made (e.g., 2.6.22), scan the
patch and Changelog, to see what important changes there have been.
This is quite a big job, and pretty much impossible to do thoroughly,
unless doing man-pages is your full time job, but a bit of scripting
@ -113,7 +113,7 @@ found at http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=manpages.
Debian even provides an email interface which allows an upstream
maintainer to manipulate Debian bug reports (using the "tags"
command; see http://www.debian.org/Bugs/server-control.
command; see http://www.debian.org/Bugs/server-control).
Perhaps some other distributions do the same, but Debian is the
only one I know about so far.
@ -182,7 +182,7 @@ electronic form.
And get the C99 standard. There are electronic versions of near
final drafts available on the net, if one searches on the net.
And have a look at the LSB, http://www.freestandards.org/.
And have a look at the LSB, http://www.linux-foundation.org/en/LSB.
Other Manual Pages
------------------

4
TODO
View File

@ -37,8 +37,8 @@ Markup language
The existing man-pages set is an unfortunate mixture pages written in
two formats: 'man' and 'mdoc' (BSD). Neither is optimal, since they
don't encode sufficient semantic detail about the elements of a page.
What is required is a new markup language (probably some form of
docbook) that:
What is perhaps required is a new markup language (probably some form
of docbook) that:
a) is unintrusive: the raw page source should remain very readable
b) applies markup by function, not by effect