mirror of https://github.com/mkerrisk/man-pages
Ready for 2.49
This commit is contained in:
parent
cd8a9ce442
commit
c710d55271
123
Changes
123
Changes
|
@ -5,11 +5,11 @@ Released: 2007-??-??
|
||||||
Contributors
|
Contributors
|
||||||
------------
|
------------
|
||||||
|
|
||||||
Bruni Haible <bruno@clisp.org>
|
|
||||||
|
|
||||||
The following people contributed notes, ideas, or patches that have
|
The following people contributed notes, ideas, or patches that have
|
||||||
been incorporated in changes in this release:
|
been incorporated in changes in this release:
|
||||||
|
|
||||||
|
Bruno Haible <bruno@clisp.org>
|
||||||
|
Justin Pryzby <justinpryzby@users.sourceforge.net>
|
||||||
|
|
||||||
Apologies if I missed anyone!
|
Apologies if I missed anyone!
|
||||||
|
|
||||||
|
@ -17,6 +17,43 @@ Apologies if I missed anyone!
|
||||||
New pages
|
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
|
Global changes
|
||||||
--------------
|
--------------
|
||||||
|
|
||||||
|
@ -27,6 +64,70 @@ places.
|
||||||
Changes to individual pages
|
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
|
copysign.3
|
||||||
Bruno Haible
|
Bruno Haible
|
||||||
Clarify discussion of negative zero.
|
Clarify discussion of negative zero.
|
||||||
|
@ -34,8 +135,24 @@ copysign.3
|
||||||
iconv_open.3
|
iconv_open.3
|
||||||
Bruno Haible
|
Bruno Haible
|
||||||
Describe the glibc/libiconv //TRANSLIT and //IGNORE extensions
|
Describe the glibc/libiconv //TRANSLIT and //IGNORE extensions
|
||||||
for 'tocode'.
|
for 'tocode'.
|
||||||
|
|
||||||
iswblank.3
|
iswblank.3
|
||||||
Bruno Haible
|
Bruno Haible
|
||||||
Update CONFORMING TO; iswblank() is in POSIX.1-2001.
|
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
146
Changes.old
|
@ -4774,12 +4774,12 @@ Thomas Huriaux / mtk
|
||||||
Various formatting found as a result of reviewing the following
|
Various formatting found as a result of reviewing the following
|
||||||
command were fixed.
|
command were fixed.
|
||||||
|
|
||||||
for a in $(wc man?/*.?| awk '$1 > 2 ' | grep -v total); do
|
for a in $(wc man?/*.?| awk '$1 > 2 ' | grep -v total); do
|
||||||
echo $a; groff -Tascii -wmac -mman $a > /dev/null;
|
echo $a; groff -Tascii -wmac -mman $a > /dev/null;
|
||||||
done 2>&1 | less
|
done 2>&1 | less
|
||||||
|
|
||||||
See Debian Bug# 378544.
|
See Debian Bug# 378544.
|
||||||
|
|
||||||
Typographical or grammatical errors have been corrected in several
|
Typographical or grammatical errors have been corrected in several
|
||||||
places.
|
places.
|
||||||
|
|
||||||
|
@ -4789,7 +4789,7 @@ New pages
|
||||||
readlinkat.2
|
readlinkat.2
|
||||||
mtk (after prompting from Ivana Varekova)
|
mtk (after prompting from Ivana Varekova)
|
||||||
New page for readlinkat(2), new in kernel 2.6.16.
|
New page for readlinkat(2), new in kernel 2.6.16.
|
||||||
|
|
||||||
Changes to individual pages
|
Changes to individual pages
|
||||||
---------------------------
|
---------------------------
|
||||||
|
|
||||||
|
@ -4811,14 +4811,14 @@ epoll_ctl.2
|
||||||
|
|
||||||
exevce.2
|
exevce.2
|
||||||
mtk
|
mtk
|
||||||
Add text noting that effective IDs are copied to
|
Add text noting that effective IDs are copied to
|
||||||
saved set-IDs during execve().
|
saved set-IDs during execve().
|
||||||
See Debian bug 379297.
|
See Debian bug 379297.
|
||||||
|
|
||||||
getitimer.2
|
getitimer.2
|
||||||
mtk
|
mtk
|
||||||
Noted effect of fork() and execve() on interval timers.
|
Noted effect of fork() and execve() on interval timers.
|
||||||
|
|
||||||
getrlimit.2
|
getrlimit.2
|
||||||
mtk
|
mtk
|
||||||
Noted effect of fork() and execve() on resource limits.
|
Noted effect of fork() and execve() on resource limits.
|
||||||
|
@ -4829,7 +4829,7 @@ getpriority.2
|
||||||
|
|
||||||
inotify_add_watch.2
|
inotify_add_watch.2
|
||||||
mtk
|
mtk
|
||||||
Some rewording; included text describing required file
|
Some rewording; included text describing required file
|
||||||
permissions.
|
permissions.
|
||||||
|
|
||||||
intro.2
|
intro.2
|
||||||
|
@ -4850,7 +4850,7 @@ mmap.2
|
||||||
Expand description MAP_NONBLOCK.
|
Expand description MAP_NONBLOCK.
|
||||||
mtk
|
mtk
|
||||||
Various minor formatting fixes.
|
Various minor formatting fixes.
|
||||||
|
|
||||||
openat.2
|
openat.2
|
||||||
mtk
|
mtk
|
||||||
Added SEE ALSO linking to readlinkat.2.
|
Added SEE ALSO linking to readlinkat.2.
|
||||||
|
@ -4863,7 +4863,7 @@ nanosleep.2
|
||||||
nice.2
|
nice.2
|
||||||
mtk
|
mtk
|
||||||
Very minor rewording.
|
Very minor rewording.
|
||||||
|
|
||||||
readlink.2
|
readlink.2
|
||||||
mtk
|
mtk
|
||||||
Added SEE ALSO linking to readlinkat.2.
|
Added SEE ALSO linking to readlinkat.2.
|
||||||
|
@ -4871,15 +4871,15 @@ readlink.2
|
||||||
sched_setscheduler.2
|
sched_setscheduler.2
|
||||||
mtk
|
mtk
|
||||||
Noted preservation of scheduling parameters across execve().
|
Noted preservation of scheduling parameters across execve().
|
||||||
|
|
||||||
setpgid.2
|
setpgid.2
|
||||||
mtk
|
mtk
|
||||||
Noted effect of fork() and execve() on process group ID.
|
Noted effect of fork() and execve() on process group ID.
|
||||||
|
|
||||||
setsid.2
|
setsid.2
|
||||||
mtk
|
mtk
|
||||||
Noted effect of fork() and execve() on session ID.
|
Noted effect of fork() and execve() on session ID.
|
||||||
|
|
||||||
umask.2
|
umask.2
|
||||||
mtk
|
mtk
|
||||||
Noted effect of fork() and execve() on umask.
|
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
|
* eliminate discussion of errors that can occur on other
|
||||||
systems. This information exists only patchily in the
|
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).
|
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.
|
POSIX.1-2001 are marked as such in their manual pages.
|
||||||
|
|
||||||
intro.1
|
intro.1
|
||||||
|
@ -5064,7 +5064,7 @@ execve.2
|
||||||
|
|
||||||
fork.2
|
fork.2
|
||||||
mtk, after a suggestion by Christoph Hellwig
|
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.
|
in parent and child.
|
||||||
|
|
||||||
linkat.2
|
linkat.2
|
||||||
|
@ -5074,7 +5074,7 @@ linkat.2
|
||||||
set_mempolicy.2
|
set_mempolicy.2
|
||||||
mtk / Andi Kleen
|
mtk / Andi Kleen
|
||||||
Memory policy is preserved across execve().
|
Memory policy is preserved across execve().
|
||||||
|
|
||||||
write.2
|
write.2
|
||||||
mtk / Alain Portal
|
mtk / Alain Portal
|
||||||
SEE ALSO for writev should refer to Section 2, not 3.
|
SEE ALSO for writev should refer to Section 2, not 3.
|
||||||
|
@ -5082,7 +5082,7 @@ write.2
|
||||||
|
|
||||||
getcwd.3
|
getcwd.3
|
||||||
Samuel Thibault / mtk
|
Samuel Thibault / mtk
|
||||||
Fix SYNOPSIS and CONFORMING TO text for getwd() and
|
Fix SYNOPSIS and CONFORMING TO text for getwd() and
|
||||||
get_current_dir().
|
get_current_dir().
|
||||||
See Debian bug: 381692
|
See Debian bug: 381692
|
||||||
|
|
||||||
|
@ -5093,7 +5093,7 @@ proc.5
|
||||||
capabilities.7
|
capabilities.7
|
||||||
Alain Portal
|
Alain Portal
|
||||||
Restore text accidentally deleted in 2.39.
|
Restore text accidentally deleted in 2.39.
|
||||||
|
|
||||||
regex.7
|
regex.7
|
||||||
mtk / Alain Portal
|
mtk / Alain Portal
|
||||||
Change references to "1003.2" to "POSIX.2".
|
Change references to "1003.2" to "POSIX.2".
|
||||||
|
@ -5162,20 +5162,20 @@ execve.2
|
||||||
|
|
||||||
fork.2
|
fork.2
|
||||||
mtk
|
mtk
|
||||||
Mappings marked with madvise(MADV_DONTFORK) are not inherited
|
Mappings marked with madvise(MADV_DONTFORK) are not inherited
|
||||||
by child.
|
by child.
|
||||||
|
|
||||||
getdtablesize.2
|
getdtablesize.2
|
||||||
mtk
|
mtk
|
||||||
Noted that sysconf(_SC_OPEN_MAX) is preferred in portable
|
Noted that sysconf(_SC_OPEN_MAX) is preferred in portable
|
||||||
applications.
|
applications.
|
||||||
|
|
||||||
getpagesize.2
|
getpagesize.2
|
||||||
mtk
|
mtk
|
||||||
Noted that sysconf(_SC_PAGE_SIZE) is preferred in portable
|
Noted that sysconf(_SC_PAGE_SIZE) is preferred in portable
|
||||||
applications.
|
applications.
|
||||||
_SC_PAGE_SIZE is available on most systems.
|
_SC_PAGE_SIZE is available on most systems.
|
||||||
|
|
||||||
madvise.2
|
madvise.2
|
||||||
mtk
|
mtk
|
||||||
Document MADV_REMOVE, new in 2.6.16.
|
Document MADV_REMOVE, new in 2.6.16.
|
||||||
|
@ -5184,10 +5184,10 @@ madvise.2
|
||||||
mount.2
|
mount.2
|
||||||
mtk / Trond Myklebust
|
mtk / Trond Myklebust
|
||||||
MNT_FORCE can cause data loss.
|
MNT_FORCE can cause data loss.
|
||||||
|
|
||||||
mmap.2
|
mmap.2
|
||||||
mtk
|
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.
|
length==0.
|
||||||
Justin Pryzby / mtk
|
Justin Pryzby / mtk
|
||||||
Added some EINVAL errors.
|
Added some EINVAL errors.
|
||||||
|
@ -5198,7 +5198,7 @@ mremap.2
|
||||||
|
|
||||||
msync.2
|
msync.2
|
||||||
mtk
|
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.
|
a locked region.
|
||||||
|
|
||||||
posix_fadvise.2
|
posix_fadvise.2
|
||||||
|
@ -5216,7 +5216,7 @@ prctl.2
|
||||||
PR_SET_FPEXC, PR_GET_FPEXC.
|
PR_SET_FPEXC, PR_GET_FPEXC.
|
||||||
Michael Kerrisk
|
Michael Kerrisk
|
||||||
Document PR_GET_ENDIAN and PR_SET_ENDIAN.
|
Document PR_GET_ENDIAN and PR_SET_ENDIAN.
|
||||||
|
|
||||||
remap_file_pages.2
|
remap_file_pages.2
|
||||||
mtk
|
mtk
|
||||||
Add "#define _GNU_SOURCE" to SYNOPSIS.
|
Add "#define _GNU_SOURCE" to SYNOPSIS.
|
||||||
|
@ -5228,11 +5228,11 @@ sync_file_range.2
|
||||||
vfork.2
|
vfork.2
|
||||||
mtk
|
mtk
|
||||||
Noted interactions with fork handlers in multithreaded programs.
|
Noted interactions with fork handlers in multithreaded programs.
|
||||||
|
|
||||||
wait4.2
|
wait4.2
|
||||||
mtk
|
mtk
|
||||||
Added feature test macros to SYNOPSIS.
|
Added feature test macros to SYNOPSIS.
|
||||||
|
|
||||||
clog2.3
|
clog2.3
|
||||||
mtk / aeb / Kevin Ryde
|
mtk / aeb / Kevin Ryde
|
||||||
Fix broken text in description.
|
Fix broken text in description.
|
||||||
|
@ -5250,10 +5250,10 @@ mq_receive.3
|
||||||
|
|
||||||
qsort.2
|
qsort.2
|
||||||
Hrvoje Niksic
|
Hrvoje Niksic
|
||||||
Fix wording referring to the use of strcmp() in 'compar'
|
Fix wording referring to the use of strcmp() in 'compar'
|
||||||
function.
|
function.
|
||||||
See Debian bug 391402.
|
See Debian bug 391402.
|
||||||
|
|
||||||
sendfile.2
|
sendfile.2
|
||||||
mtk
|
mtk
|
||||||
Added SEE ALSO referring to new splice.2 page.
|
Added SEE ALSO referring to new splice.2 page.
|
||||||
|
@ -5261,7 +5261,7 @@ sendfile.2
|
||||||
termios.3
|
termios.3
|
||||||
mtk
|
mtk
|
||||||
Documented IUTF8 (which was new in kernel 2.6.4).
|
Documented IUTF8 (which was new in kernel 2.6.4).
|
||||||
|
|
||||||
tzset.3
|
tzset.3
|
||||||
mtk
|
mtk
|
||||||
Added some TZ examples.
|
Added some TZ examples.
|
||||||
|
@ -5320,10 +5320,10 @@ Changes to individual pages
|
||||||
brk.2
|
brk.2
|
||||||
Evan Teran / mtk
|
Evan Teran / mtk
|
||||||
Add text describing behaviour of the Linux brk() system call
|
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.
|
behaviour.
|
||||||
mtk
|
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.
|
that calls the brk() system call.
|
||||||
|
|
||||||
futex.2
|
futex.2
|
||||||
|
@ -5335,10 +5335,10 @@ getnameinfo.3
|
||||||
Ulrich Drepper, with edits by mtk
|
Ulrich Drepper, with edits by mtk
|
||||||
Add text describing Internationalized Domain Name
|
Add text describing Internationalized Domain Name
|
||||||
extensions.
|
extensions.
|
||||||
|
|
||||||
open.2
|
open.2
|
||||||
mtk / Eduard Bloch
|
mtk / Eduard Bloch
|
||||||
Fix description of O_LARGEFILE to mention required feature test
|
Fix description of O_LARGEFILE to mention required feature test
|
||||||
macros.
|
macros.
|
||||||
|
|
||||||
ptrace.2
|
ptrace.2
|
||||||
|
@ -5357,7 +5357,7 @@ wcwidth.3
|
||||||
core.5
|
core.5
|
||||||
mtk
|
mtk
|
||||||
Linux 2.4.21 added core_pattern (which was already in 2.6).
|
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.
|
be produced.
|
||||||
|
|
||||||
|
|
||||||
|
@ -5409,7 +5409,7 @@ strerror.3
|
||||||
|
|
||||||
rtc.4
|
rtc.4
|
||||||
David Brownell
|
David Brownell
|
||||||
|
|
||||||
Update the RTC man page to reflect the new RTC class framework:
|
Update the RTC man page to reflect the new RTC class framework:
|
||||||
|
|
||||||
- Generalize ... it's not just for PC/AT style RTCs, and there
|
- Generalize ... it's not just for PC/AT style RTCs, and there
|
||||||
|
@ -5516,13 +5516,13 @@ mtk
|
||||||
unlinkat.2
|
unlinkat.2
|
||||||
mkfifoat.3
|
mkfifoat.3
|
||||||
|
|
||||||
mtk
|
mtk
|
||||||
Various references to "getty" were changed to "mingetty", since
|
Various references to "getty" were changed to "mingetty", since
|
||||||
that is the manual page more likely to be found on current systems.
|
that is the manual page more likely to be found on current systems.
|
||||||
|
|
||||||
mtk, after a suggestion by Reuben Thomas <rrt@sc3d.org>
|
mtk, after a suggestion by Reuben Thomas <rrt@sc3d.org>
|
||||||
Updated various header pages to accurately reflect which functions
|
Updated various header pages to accurately reflect which functions
|
||||||
are and are not part of C89. Also fixed/improved a few other
|
are and are not part of C89. Also fixed/improved a few other
|
||||||
CONFORMING TO entries.
|
CONFORMING TO entries.
|
||||||
|
|
||||||
mtk
|
mtk
|
||||||
|
@ -5633,7 +5633,7 @@ mbind.2
|
||||||
Samuel Thibault / mtk
|
Samuel Thibault / mtk
|
||||||
Fix EINVAL description.
|
Fix EINVAL description.
|
||||||
See Debian bug 411777.
|
See Debian bug 411777.
|
||||||
|
|
||||||
mincore.2
|
mincore.2
|
||||||
Nick Piggin
|
Nick Piggin
|
||||||
Kernel 2.6.21 fixes several earlier bugs in mincore().
|
Kernel 2.6.21 fixes several earlier bugs in mincore().
|
||||||
|
@ -5647,16 +5647,16 @@ mmap.2
|
||||||
mtk
|
mtk
|
||||||
Rewrote and reorganised various parts to be clearer.
|
Rewrote and reorganised various parts to be clearer.
|
||||||
Taken from Fedora downstream patches; thanks to Ivana Varekova
|
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.
|
not true.
|
||||||
|
|
||||||
mount.2
|
mount.2
|
||||||
mtk / Val Henson
|
mtk / Val Henson
|
||||||
Document MS_RELATIME, new in Linux 2.6.20.
|
Document MS_RELATIME, new in Linux 2.6.20.
|
||||||
|
|
||||||
open.2
|
open.2
|
||||||
Andre Majorel / mtk
|
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.
|
32-bit system is actually EFBIG, not EOVERFLOW.
|
||||||
|
|
||||||
posix_fadvise.2
|
posix_fadvise.2
|
||||||
|
@ -5673,7 +5673,7 @@ semop.2
|
||||||
If sops contains multiple operations, then these are performed
|
If sops contains multiple operations, then these are performed
|
||||||
in array order. All Unix systems that I know of do this,
|
in array order. All Unix systems that I know of do this,
|
||||||
and some Linux applications depend on this behaviour. SUSv3
|
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.
|
require this behaviour.
|
||||||
Small rewording of explanation of "atomically".
|
Small rewording of explanation of "atomically".
|
||||||
|
|
||||||
|
@ -5682,11 +5682,11 @@ signal.2
|
||||||
Fix incorrect argument name in DESCRIPTION.
|
Fix incorrect argument name in DESCRIPTION.
|
||||||
mtk
|
mtk
|
||||||
Small wording improvement.
|
Small wording improvement.
|
||||||
|
|
||||||
socket.2
|
socket.2
|
||||||
Nicolas François
|
Nicolas François
|
||||||
Add reference to ipv6.7 page.
|
Add reference to ipv6.7 page.
|
||||||
|
|
||||||
socketcall.2
|
socketcall.2
|
||||||
Nicolas François
|
Nicolas François
|
||||||
Fix .TH line.
|
Fix .TH line.
|
||||||
|
@ -5701,8 +5701,8 @@ statvfs.2
|
||||||
|
|
||||||
symlink.2
|
symlink.2
|
||||||
mtk / Nicolas François
|
mtk / Nicolas François
|
||||||
Removed cryptic text under CONFORMING to referring to
|
Removed cryptic text under CONFORMING to referring to
|
||||||
"open(2) and NFS". There is no relevant text in open.2 as
|
"open(2) and NFS". There is no relevant text in open.2 as
|
||||||
far as I (mtk) can see.
|
far as I (mtk) can see.
|
||||||
|
|
||||||
time.2
|
time.2
|
||||||
|
@ -5717,21 +5717,21 @@ write.2
|
||||||
|
|
||||||
ptrace.2
|
ptrace.2
|
||||||
Chuck Ebbert
|
Chuck Ebbert
|
||||||
When the parent receives an event with PTRACE_EVENT_* set,
|
When the parent receives an event with PTRACE_EVENT_* set,
|
||||||
the child is not in the normal signal delivery path. This
|
the child is not in the normal signal delivery path. This
|
||||||
means the parent cannot do ptrace(PTRACE_CONT) with a signal
|
means the parent cannot do ptrace(PTRACE_CONT) with a signal
|
||||||
or ptrace(PTRACE_KILL). kill() with a SIGKILL signal can be
|
or ptrace(PTRACE_KILL). kill() with a SIGKILL signal can be
|
||||||
used instead to kill the child process after receiving one
|
used instead to kill the child process after receiving one
|
||||||
of these messages.
|
of these messages.
|
||||||
|
|
||||||
sched_setaffinity.2
|
sched_setaffinity.2
|
||||||
mtk
|
mtk
|
||||||
Fix glibc version number in description of 'cpusetsize' argument.
|
Fix glibc version number in description of 'cpusetsize' argument.
|
||||||
|
|
||||||
vfork.2
|
vfork.2
|
||||||
mtk
|
mtk
|
||||||
Stripped some excess/outdated text from the BUGS section.
|
Stripped some excess/outdated text from the BUGS section.
|
||||||
|
|
||||||
basename.3
|
basename.3
|
||||||
mtk / Jorge Peixoto de Morais Neto
|
mtk / Jorge Peixoto de Morais Neto
|
||||||
Add text to clarify that the pointer returned by these
|
Add text to clarify that the pointer returned by these
|
||||||
|
@ -5751,8 +5751,8 @@ getopt.3
|
||||||
mtk
|
mtk
|
||||||
Added getopt() example program.
|
Added getopt() example program.
|
||||||
mtk
|
mtk
|
||||||
Add a few words to clarify the operation of the GNU-specific
|
Add a few words to clarify the operation of the GNU-specific
|
||||||
double-colon feature, which allows options to have optional
|
double-colon feature, which allows options to have optional
|
||||||
arguments.
|
arguments.
|
||||||
See Debian bug352139.
|
See Debian bug352139.
|
||||||
|
|
||||||
|
@ -5775,18 +5775,18 @@ log10.3
|
||||||
malloc.3
|
malloc.3
|
||||||
Nicolas François
|
Nicolas François
|
||||||
Small rewording to mention calloc().
|
Small rewording to mention calloc().
|
||||||
|
|
||||||
posix_openpt.3
|
posix_openpt.3
|
||||||
Martín Ferrari
|
Martín Ferrari
|
||||||
Fix return type in SYNOPSIS; as per Debian bug 400971.
|
Fix return type in SYNOPSIS; as per Debian bug 400971.
|
||||||
Needs _XOPEN_SOURCE == 600; as per Debian bug 400975.
|
Needs _XOPEN_SOURCE == 600; as per Debian bug 400975.
|
||||||
Julien BLACHE
|
Julien BLACHE
|
||||||
s/ptsname/posix_openpt/ in RETURN VALUE
|
s/ptsname/posix_openpt/ in RETURN VALUE
|
||||||
|
|
||||||
re_comp.3
|
re_comp.3
|
||||||
Taken from Fedora downstream patches; thanks to Ivana Varekova
|
Taken from Fedora downstream patches; thanks to Ivana Varekova
|
||||||
Add "#define _REGEX_RE_COMP" to SYNOPSIS.
|
Add "#define _REGEX_RE_COMP" to SYNOPSIS.
|
||||||
|
|
||||||
regex.3
|
regex.3
|
||||||
Nicolas François
|
Nicolas François
|
||||||
Fix .TH line.
|
Fix .TH line.
|
||||||
|
@ -5843,10 +5843,10 @@ mdoc.7
|
||||||
mtk / Nicolas François
|
mtk / Nicolas François
|
||||||
Remove CONFIGURATION section, since this does not seem to be
|
Remove CONFIGURATION section, since this does not seem to be
|
||||||
true for Linux.
|
true for Linux.
|
||||||
|
|
||||||
svipc.7
|
svipc.7
|
||||||
Nicolas François
|
Nicolas François
|
||||||
Fix data types in associated data structures;
|
Fix data types in associated data structures;
|
||||||
remove non-existent semzcnt and semncnt fields.
|
remove non-existent semzcnt and semncnt fields.
|
||||||
|
|
||||||
time.7
|
time.7
|
||||||
|
@ -5859,9 +5859,9 @@ Released: 2007-04-05
|
||||||
Global changes
|
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.
|
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.
|
no changes were made to content.
|
||||||
|
|
||||||
Changes to individual pages
|
Changes to individual pages
|
||||||
|
@ -5887,17 +5887,17 @@ Released: 2007-04-06
|
||||||
Global changes
|
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:
|
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.
|
page output were shrunk to a single line.
|
||||||
* A number of example programs were reformatted
|
* A number of example programs were reformatted
|
||||||
to more closely match K&R style.
|
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
|
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.
|
no changes were made to content.
|
||||||
|
|
||||||
|
|
||||||
|
@ -5951,7 +5951,7 @@ sched_rr_get_interval.2
|
||||||
mtk
|
mtk
|
||||||
Remove crufty statement that this system call is not implemented.
|
Remove crufty statement that this system call is not implemented.
|
||||||
The nice interval can be used to control the size of
|
The nice interval can be used to control the size of
|
||||||
the round-robin quantum.
|
the round-robin quantum.
|
||||||
Corrected .TH line.
|
Corrected .TH line.
|
||||||
|
|
||||||
ip.7
|
ip.7
|
||||||
|
@ -5986,7 +5986,7 @@ There is very little change to output formatting or content (see the
|
||||||
notes below).
|
notes below).
|
||||||
|
|
||||||
mtk
|
mtk
|
||||||
In various places where it occurred,
|
In various places where it occurred,
|
||||||
s/nonnegative/non-negative/
|
s/nonnegative/non-negative/
|
||||||
|
|
||||||
mtk
|
mtk
|
||||||
|
|
251
HOWTOHELP
251
HOWTOHELP
|
@ -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.
|
maintaining manual pages in the Linux man-pages package.
|
||||||
|
|
||||||
See also the MAINTAINING and TODO documents in this directory.
|
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:
|
You can help in the following ways:
|
||||||
|
|
||||||
-- sending in bug reports about problems in existing pages;
|
-- sending in bug reports about problems in existing pages;
|
||||||
(An alternative is to report the bug in one of the
|
(An alternative is to report the bug in one of the
|
||||||
distribution-specific Bugzilla facilities, if that facility
|
distribution-specific Bugzilla facilities, if that facility
|
||||||
provides a mechanism to automatically forward bug reports
|
provides a mechanism to automatically forward bug reports
|
||||||
to me. Currently, I am registered to receive man-page bug
|
to me. Currently, I am registered to receive man-page bug
|
||||||
reports from the Debian bugzilla, but if other distributions
|
reports from the Debian bugzilla, but if other distributions
|
||||||
provide a similar facility I may get myself registered for
|
provide a similar facility I may get myself registered for
|
||||||
those; let me know.)
|
those; let me know.)
|
||||||
|
|
||||||
-- writing patches that improve existing pages (see below);
|
-- 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
|
-- asking me to add you to my distribution list for notification of
|
||||||
new man-pages releases, and reviewing the changes that have
|
new man-pages releases, and reviewing the changes that have
|
||||||
occurred during a release (do "diff -ruN" between the directory
|
occurred during a release (do "diff -ruN" between the directory
|
||||||
trees for the current and previous releases); and
|
trees for the current and previous releases); and
|
||||||
|
|
||||||
-- suggesting improvements to this document.
|
-- 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:
|
When you submit a patch, please note the following:
|
||||||
|
|
||||||
-- Submit a patch against the current version of the page. The current
|
-- 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
|
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
|
or mirrors: ftp://ftp.XX.kernel.org/pub/linux/docs/manpages
|
||||||
|
|
||||||
-- Let me know how you obtained the information: was it by reading (or
|
-- 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
|
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
|
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
|
simple to use); from other documentation; from a mailing list or
|
||||||
Usenet thread (please provide a URL if possible).
|
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
|
is usually best; if it is a very long patch then send it both inline
|
||||||
and as an attachment.
|
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.
|
separate mails.
|
||||||
|
|
||||||
-- In the body of the mail message, identify the manual page
|
-- In the body of the mail message, identify the manual page
|
||||||
version against which the patch applies.
|
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
|
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
|
manual page version in the subject line (it should already be in the
|
||||||
body, and cluttering the subject line with a version number does
|
body, and cluttering the subject line with a version number does
|
||||||
not help me when filing messages...). A suitable subject line might
|
not help me when filing messages...). A suitable subject line might
|
||||||
be something like:
|
be something like:
|
||||||
|
|
||||||
[patch] shmop.2: add "(void *)" cast to RETURN VALUE
|
[patch] shmop.2: add "(void *)" cast to RETURN VALUE
|
||||||
|
|
||||||
-- If editing a page, and you find one or two white spaces at the end
|
-- 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
|
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
|
that in a "diff -u" patch this will make it look like there is a
|
||||||
when in fact nothing has changed. In most cases, these extra white
|
change when in fact nothing has changed. In most cases, these
|
||||||
spaces do no harm, so just leave them be.
|
extra white spaces do no harm, so just leave them be.
|
||||||
|
|
||||||
|
|
||||||
MANUAL PAGES IN OTHER PACKAGES
|
MANUAL PAGES IN OTHER PACKAGES
|
||||||
==============================
|
==============================
|
||||||
|
|
||||||
Not all Linux manual pages are part of the man-pages set. In
|
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
|
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
|
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
|
man-pages package is to download the latest tarball, and see if the
|
||||||
page is present.
|
page is present.
|
||||||
|
|
||||||
If you want to submit a patch for a manual page that comes from another
|
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.
|
(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
|
On an RPM-based distribution (e..g., SUSE, Red Had, Mandriva), you
|
||||||
which package owns a particular file. For example, suppose we want
|
can do the following to find out which package owns a particular file.
|
||||||
to find out who maintains the fstab(5) manual page:
|
For example, suppose we want to find out who maintains the fstab(5)
|
||||||
|
manual page:
|
||||||
|
|
||||||
$ man -w fstab
|
$ man -w fstab
|
||||||
/usr/share/man/man5/fstab.5.gz
|
/usr/share/man/man5/fstab.5.gz
|
||||||
$ rpm -qf /usr/share/man/man5/fstab.5.gz
|
$ rpm -qf /usr/share/man/man5/fstab.5.gz
|
||||||
util-linux-2.12q-7.2
|
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:
|
package, we see:
|
||||||
|
|
||||||
Maintainer: Adrian Bunk <bunk@stusta.de>
|
Maintainer: Adrian Bunk <bunk@stusta.de>
|
||||||
|
@ -120,7 +121,7 @@ package, we see:
|
||||||
Maintainer of getopt: Frodo Looijaard <frodol@dds.nl>
|
Maintainer of getopt: Frodo Looijaard <frodol@dds.nl>
|
||||||
Maintainer of simpleinit: Richard Gooch <rgooch@atnf.csiro.au>
|
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:
|
do the following:
|
||||||
|
|
||||||
$ man -w fstab
|
$ man -w fstab
|
||||||
|
@ -131,11 +132,15 @@ do the following:
|
||||||
Maintainer: LaMont Jones <lamont@debian.org>
|
Maintainer: LaMont Jones <lamont@debian.org>
|
||||||
|
|
||||||
Note: this gives you the Debian maintainer of the package in question,
|
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
|
which is a good address to report to, since many packages and manual
|
||||||
pages are modified by Debian. The maintainer of the original package
|
pages are modified by Debian. The maintainer of the original package
|
||||||
can usually be found in a README in /usr/share/doc/<package-name>.
|
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.
|
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
|
(FIXME: add instructions for doing the equivalent of the above on
|
||||||
distributions that use other schemes.)
|
distributions that use other schemes.)
|
||||||
|
|
||||||
|
@ -144,92 +149,92 @@ SECTION 9 MAN PAGES
|
||||||
===================
|
===================
|
||||||
|
|
||||||
These have nothing to with man-pages. They are documentation
|
These have nothing to with man-pages. They are documentation
|
||||||
of in-kernel APIs, built from specially formatted comments in
|
of in-kernel APIs, built from specially formatted comments in
|
||||||
the kernel source. After installing the required software, these
|
the kernel source. After installing the required software, these
|
||||||
pages can be built from a kernel source tree using the command
|
pages can be built from a kernel source tree using the command
|
||||||
'make mandocs'; see the kernel source file Documentation/HOWTO
|
'make mandocs'; see the kernel source file Documentation/HOWTO
|
||||||
for more information.
|
for more information.
|
||||||
|
|
||||||
|
|
||||||
REPAIRING PAGES MARKED "FIXME"
|
REPAIRING PAGES MARKED "FIXME"
|
||||||
==============================
|
==============================
|
||||||
|
|
||||||
Grepping the source of the manual pages will show various places where
|
Grepping the source of the manual pages will show various places where
|
||||||
pages are marked with the string FIXME. There is also shell script
|
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
|
(scripts/FIXME_list.sh) that can be used to obtain a list of FIXMEs
|
||||||
in the manual page sources:
|
in the manual page sources:
|
||||||
|
|
||||||
$ cd man-pages
|
$ cd man-pages
|
||||||
$ sh scripts/FIXME_list.sh .
|
$ sh scripts/FIXME_list.sh .
|
||||||
|
|
||||||
The presence of a FIXME usually indicates that someone has
|
The presence of a FIXME usually indicates that someone has
|
||||||
noticed that some information on the page is incorrect or
|
noticed that some information on the page is incorrect or
|
||||||
incomplete, but has not had the time/knowledge to fix problem.
|
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
|
(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
|
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.)
|
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.
|
If you know how to fix the problem, then please send a patch.
|
||||||
However, note that some of the FIXME markings are associated with
|
However, note that some of the FIXME markings are associated with
|
||||||
problems that are quite difficult: you need to ensure that you are
|
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
|
knowledgeable on the relevant point(s), or you need to be willing to
|
||||||
invest the time to become knowledgeable (by reading kernel or
|
invest the time to become knowledgeable (by reading kernel or
|
||||||
[g]libc source files and/or writing suitable test programs).
|
[g]libc source files and/or writing suitable test programs).
|
||||||
|
|
||||||
|
|
||||||
CONVENTIONS FOR MANUAL PAGE LAYOUT
|
CONVENTIONS FOR MANUAL PAGE LAYOUT
|
||||||
==================================
|
==================================
|
||||||
|
|
||||||
Please keep source code line length <= 72 characters wherever possible.
|
Please keep source code line length <= 72 characters wherever possible.
|
||||||
This helps avoid line-wrapping in some mail clients when patches are
|
This helps avoid line-wrapping in some mail clients when patches are
|
||||||
submitted inline.
|
submitted inline.
|
||||||
|
|
||||||
New sentences are generally best started on new lines. This makes
|
New sentences should be started on new lines. This makes it easier
|
||||||
it easier to see the effect of patches, which often operate at the
|
to see the effect of patches, which often operate at the
|
||||||
level of individual sentences.
|
level of individual sentences.
|
||||||
|
|
||||||
|
|
||||||
EXAMPLE PROGRAMS
|
EXAMPLE PROGRAMS
|
||||||
================
|
================
|
||||||
|
|
||||||
New manual pages, or patches to existing manual pages, can include
|
New manual pages, or patches to existing manual pages, can include
|
||||||
example programs demonstrating how to use a system call or library
|
example programs demonstrating how to use a system call or library
|
||||||
function. However, note the following:
|
function. However, note the following:
|
||||||
|
|
||||||
-- Example programs should be written in C.
|
-- Example programs should be written in C.
|
||||||
|
|
||||||
-- An example program is only necessary and useful if it demonstrates
|
-- An example program is only necessary and useful if it demonstrates
|
||||||
something beyond what can easily be provided in a textual
|
something beyond what can easily be provided in a textual
|
||||||
description of the interface. An example program that does nothing
|
description of the interface. An example program that does nothing
|
||||||
other than call an interface usually serves little purpose.
|
other than call an interface usually serves little purpose.
|
||||||
|
|
||||||
-- Example programs should be fairly short (preferably < 100 lines;
|
-- Example programs should be fairly short (preferably < 100 lines;
|
||||||
ideally < 50 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.
|
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",
|
warnings when compiled with "cc -Wall",
|
||||||
|
|
||||||
-- Where possible and appropriate, example programs should allow
|
-- Where possible and appropriate, example programs should allow
|
||||||
experimentation, by varying their behaviour based on inputs
|
experimentation, by varying their behaviour based on inputs
|
||||||
(ideally from command-line arguments, or alternatively, via
|
(ideally from command-line arguments, or alternatively, via
|
||||||
input read by the program).
|
input read by the program).
|
||||||
|
|
||||||
Example programs should be laid out according to Kernighan and
|
Example programs should be laid out according to Kernighan and
|
||||||
Ritchie, with a few concessions:
|
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 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:
|
error-handling code such as in the following is acceptable:
|
||||||
|
|
||||||
if (func(...) == -1)
|
if (func(...) == -1)
|
||||||
{ perror("func"); exit(EXIT_FAILURE); }
|
{ 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.
|
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
|
also be able point you at useful sources of information for
|
||||||
the manual page.
|
the manual page.
|
||||||
|
|
||||||
-- You need to have a reasonably high degree of understanding of the
|
-- 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,
|
topic, or be prepared to invest the time (e.g., reading source code,
|
||||||
writing test programs) to gain that understanding. Writing test
|
writing test programs) to gain that understanding. Writing test
|
||||||
programs is important; quite a few kernel and glibc bugs have been
|
programs is important; quite a few kernel and glibc bugs have been
|
||||||
uncovered while writing test programs during the preparation of
|
uncovered while writing test programs during the preparation of
|
||||||
manual pages.
|
manual pages.
|
||||||
|
|
||||||
-- Follow the existing formatting conventions for 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).
|
(man2/fcntl.2).
|
||||||
|
|
||||||
-- The page must be submitted under some sort of license that permits
|
-- The page must be submitted under some sort of license that permits
|
||||||
the page to be freely redistributed and modified. Include that
|
the page to be freely redistributed and modified. Include that
|
||||||
license or a reference to it, in the source code of the manual page.
|
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
|
Possible licenses include the GPL, the BSD license, or a range of
|
||||||
other licenses, some of which can be seen in existing manual pages.
|
other licenses, some of which can be seen in existing manual pages.
|
||||||
|
|
||||||
-- You may find it useful to check the information in your page
|
-- You may find it useful to check the information in your page
|
||||||
against the specifications in SUSv3/POSIX.1-2001
|
against the specifications in SUSv3/POSIX.1-2001
|
||||||
(http://www.opengroup.org/onlinepubs/009695399/toc.htm) or against
|
(http://www.opengroup.org/onlinepubs/009695399/toc.htm) or against
|
||||||
manual pages on other implementations, but do not not violate the
|
manual pages on other implementations, but do not not violate the
|
||||||
copyright on those publications by copying text from them.
|
copyright on those publications by copying text from them.
|
||||||
|
|
||||||
-- The GNU C library documents many of the functions that it provides
|
-- 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
|
using info(1). If you are thinking of writing a manual page for
|
||||||
a function that is already documented in info(1) format, then
|
a function that is already documented in info(1) format, then
|
||||||
ideally this page needs to present new or different information from
|
ideally this page needs to present new or different information from
|
||||||
that provided by the info(1) page (for example, historical
|
that provided by the info(1) page (for example, historical
|
||||||
information about how the function has changed across various glibc
|
information about how the function has changed across various glibc
|
||||||
versions, or variations in operation across C libraries; such
|
versions, or variations in operation across C libraries; such
|
||||||
information is often not present in info pages). (An alternative to
|
information is often not present in info pages). (An alternative to
|
||||||
consider is submitting a patch to the maintainers of the glibc
|
consider is submitting a patch to the maintainers of the glibc
|
||||||
documentation, if that is more appropriate.)
|
documentation, if that is more appropriate.)
|
||||||
|
|
||||||
|
|
||||||
System Calls
|
System Calls
|
||||||
------------
|
------------
|
||||||
|
@ -294,29 +299,32 @@ request_key(2) (new in kernel 2.6.10)
|
||||||
under "Security options"
|
under "Security options"
|
||||||
|
|
||||||
restart_syscall(2) (new in kernel 2.6)
|
restart_syscall(2) (new in kernel 2.6)
|
||||||
|
|
||||||
kexec_load(2) (new in kernel 2.6.13)
|
kexec_load(2) (new in kernel 2.6.13)
|
||||||
|
|
||||||
migrate_pages(2) (new in kernel 2.6.16)
|
migrate_pages(2) (new in kernel 2.6.16)
|
||||||
See Documentation/vm/page_migration
|
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/ )
|
http://www.lwn.net/Articles/164887/ )
|
||||||
(Perhaps these will ultimately be library
|
(Perhaps these will ultimately be library
|
||||||
functions.)
|
functions.)
|
||||||
|
|
||||||
set_robust_list(2) New in 2.6.17
|
set_robust_list(2) New in 2.6.17
|
||||||
get_robust_list(2) Information can be found in the 2.6.17 ChangeLog
|
get_robust_list(2) Information can be found in the 2.6.17 ChangeLog
|
||||||
under "lightweight robust futexes"
|
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
|
lutimesat(2) Likely to appear in a future kernel
|
||||||
|
|
||||||
fallocate(2) May 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
|
/sys file system
|
||||||
----------------
|
----------------
|
||||||
|
|
||||||
|
@ -329,9 +337,10 @@ this page.
|
||||||
Library Functions
|
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:
|
that need to be documented:
|
||||||
|
|
||||||
|
|
||||||
|
@ -339,27 +348,24 @@ MPDIR=~/man-pages # Directory containing uncompressed man-pages
|
||||||
GLIBCDIR=/SOME_DIR # Directory containing glibc tree
|
GLIBCDIR=/SOME_DIR # Directory containing glibc tree
|
||||||
|
|
||||||
for f in $(cat $(echo $GLIBCDIR/abilist/*.abilist) | grep -v 'GLIBC' | \
|
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 && \
|
if ! test -f $MPDIR/man3/$f.3 > /dev/null 2>&1 && \
|
||||||
! test -f $MPDIR/man2/$f.2 > /dev/null 2>&1 ; then
|
! test -f $MPDIR/man2/$f.2 > /dev/null 2>&1 ; then
|
||||||
echo $f;
|
echo $f;
|
||||||
fi
|
fi
|
||||||
done
|
done
|
||||||
)
|
)
|
||||||
|
|
||||||
bsd_signal(3)
|
|
||||||
clock_nanosleep(3)
|
clock_nanosleep(3)
|
||||||
crypt_r(3) (To be added to crypt.3)
|
crypt_r(3) (To be added to crypt.3)
|
||||||
dlinfo(3) (Solaris and FreeBSD have a similar function.)
|
dlinfo(3) (Solaris and FreeBSD have a similar function.)
|
||||||
dladdr1(3)
|
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)
|
probably to be documented in dlopen.3)
|
||||||
etext, edata, end (variables)
|
etext, edata, end (variables)
|
||||||
euidaccess(3) / eaccess(3)
|
|
||||||
fdopendir(3) (since glibc 2.4)
|
fdopendir(3) (since glibc 2.4)
|
||||||
fopencookie(3)
|
fopencookie(3)
|
||||||
getgrouplist(3) (since glibc 2.2.4)
|
getgrouplist(3) (since glibc 2.2.4)
|
||||||
getsubopt(3)
|
|
||||||
getutmp(3)
|
getutmp(3)
|
||||||
getutmpx(3)
|
getutmpx(3)
|
||||||
gnu_get_libc_release(3)
|
gnu_get_libc_release(3)
|
||||||
|
@ -375,7 +381,6 @@ sigstack(3)
|
||||||
sigwait(3)
|
sigwait(3)
|
||||||
strftime_l(3) (since glibc 2.3)
|
strftime_l(3) (since glibc 2.3)
|
||||||
strptime_l(3) (since glibc 2.3.2)
|
strptime_l(3) (since glibc 2.3.2)
|
||||||
sysv_signal(3)
|
|
||||||
tmpnam_r(3) (probably as additional text in tmpnam.3)
|
tmpnam_r(3) (probably as additional text in tmpnam.3)
|
||||||
updwtmpx(3)
|
updwtmpx(3)
|
||||||
|
|
||||||
|
@ -425,12 +430,12 @@ if_nameindex(3)
|
||||||
if_nametoindex(3)
|
if_nametoindex(3)
|
||||||
|
|
||||||
|
|
||||||
getaddrinfo_a(3), gai_cancel(3), gai_error(3), gai_suspend(3)
|
getaddrinfo_a(3), gai_cancel(3), gai_error(3), gai_suspend(3)
|
||||||
(libanl; since glibc 2.2.3; See
|
(libanl; since glibc 2.2.3; See
|
||||||
http://people.redhat.com/~drepper/asynchnl.pdf)
|
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):
|
mentioned in parentheses):
|
||||||
|
|
||||||
wscanf(3) (scanf(3))
|
wscanf(3) (scanf(3))
|
||||||
|
@ -451,25 +456,25 @@ wcstoq(3) (strtoq(3))
|
||||||
wcstouq(3) (strtouq(3))
|
wcstouq(3) (strtouq(3))
|
||||||
wcswcs(3) (strstr(3))
|
wcswcs(3) (strstr(3))
|
||||||
wcsxfrm(3) (strxfrm(3))
|
wcsxfrm(3) (strxfrm(3))
|
||||||
After these manual pages are written, add SEE ALSO entries
|
After these manual pages are written, add SEE ALSO entries
|
||||||
from the pages for the traditional functions to the pages
|
from the pages for the traditional functions to the pages
|
||||||
describing their wide-character equivalents.
|
describing their wide-character equivalents.
|
||||||
|
|
||||||
|
|
||||||
And last, but far from least, the POSIX threads API. Note that there is
|
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
|
an existing, outdated set of pages supplied with glibc that document the
|
||||||
old LinuxThreads implementation. (These pages are written under a
|
old LinuxThreads implementation. (These pages are written under a
|
||||||
license that allows re-use, so some material that they contain could
|
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
|
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
|
the complete API, describing details where LinuxThreads and NPTL diverge
|
||||||
from the standard. The existing pthreads(7) manual page, which gives an
|
from the standard. The existing pthreads(7) manual page, which gives an
|
||||||
overview of Pthreads implementations on Linux, is designed as a base
|
overview of Pthreads implementations on Linux, is designed as a base
|
||||||
document for these manual pages. The list of required manual pages is
|
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:
|
with more asterisks are probably the most desirable to get done first:
|
||||||
|
|
||||||
pthread_atfork() *
|
pthread_atfork() *
|
||||||
pthread_attr_destroy()
|
pthread_attr_destroy()
|
||||||
pthread_attr_getaffinity_np()
|
pthread_attr_getaffinity_np()
|
||||||
pthread_attr_getdetachstate()
|
pthread_attr_getdetachstate()
|
||||||
pthread_attr_getguardsize()
|
pthread_attr_getguardsize()
|
||||||
|
|
10
MAINTAINING
10
MAINTAINING
|
@ -37,7 +37,7 @@ Glibc source code
|
||||||
|
|
||||||
Same story as the kernel.
|
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.
|
-- Keep diff files for all minor releases of the glibc tree.
|
||||||
As with kernel, these can be grepped to help determine
|
As with kernel, these can be grepped to help determine
|
||||||
|
@ -65,7 +65,7 @@ Linux Kernel (LKML)
|
||||||
subscribe linux-kernel
|
subscribe linux-kernel
|
||||||
|
|
||||||
The problem with this list is that the volume is extremely high,
|
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
|
http://www.kernel.org/ provides the locations of a few searchable
|
||||||
archives of this mailing list.
|
archives of this mailing list.
|
||||||
|
@ -90,7 +90,7 @@ http://kerneltrap.org/news
|
||||||
Kernel releases
|
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.
|
patch and Changelog, to see what important changes there have been.
|
||||||
This is quite a big job, and pretty much impossible to do thoroughly,
|
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
|
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
|
Debian even provides an email interface which allows an upstream
|
||||||
maintainer to manipulate Debian bug reports (using the "tags"
|
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
|
Perhaps some other distributions do the same, but Debian is the
|
||||||
only one I know about so far.
|
only one I know about so far.
|
||||||
|
@ -182,7 +182,7 @@ electronic form.
|
||||||
And get the C99 standard. There are electronic versions of near
|
And get the C99 standard. There are electronic versions of near
|
||||||
final drafts available on the net, if one searches on the net.
|
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
|
Other Manual Pages
|
||||||
------------------
|
------------------
|
||||||
|
|
4
TODO
4
TODO
|
@ -37,8 +37,8 @@ Markup language
|
||||||
The existing man-pages set is an unfortunate mixture pages written in
|
The existing man-pages set is an unfortunate mixture pages written in
|
||||||
two formats: 'man' and 'mdoc' (BSD). Neither is optimal, since they
|
two formats: 'man' and 'mdoc' (BSD). Neither is optimal, since they
|
||||||
don't encode sufficient semantic detail about the elements of a page.
|
don't encode sufficient semantic detail about the elements of a page.
|
||||||
What is required is a new markup language (probably some form of
|
What is perhaps required is a new markup language (probably some form
|
||||||
docbook) that:
|
of docbook) that:
|
||||||
|
|
||||||
a) is unintrusive: the raw page source should remain very readable
|
a) is unintrusive: the raw page source should remain very readable
|
||||||
b) applies markup by function, not by effect
|
b) applies markup by function, not by effect
|
||||||
|
|
Loading…
Reference in New Issue