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

Start of man-pages-3.52: updating Changes and Changes.old

This commit is contained in:
Michael Kerrisk 2013-04-19 14:03:08 +02:00
parent d7a98f241e
commit e59de0aeb0
2 changed files with 342 additions and 305 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

313
Changes
View File

@ -1,6 +1,6 @@
==================== Changes in man-pages-3.51 ====================
==================== Changes in man-pages-3.52 ====================
Released: 2013-04-17, Munich
Released: ????-??-??, Munich
Contributors
@ -10,323 +10,26 @@ The following people contributed patches/fixes or (noted in brackets
in the changelog below) reports, notes, and ideas that have been
incorporated in changes in this release:
Andreas Jaeger <aj@suse.de>
Andrew Clayton <andrew@digital-domain.net>
Brian M. Carlson <sandals@crustytoothpaste.net>
Changhee Han <ch0.han@lge.com>
Cyril Hrubis <chrubis@suse.cz>
Damien Grassart <damien@grassart.com>
David Prévot <taffit@debian.org>
Denis Barbier <bouzim@gmail.com>
Jeff Moyer <jmoyer@redhat.com>
Krzysztof Konopko <krzysztof.konopko@gmail.com>
Kyle McMartin <kyle@mcmartin.ca>
Mark H Weaver <mhw@netris.org>
Michael Kerrisk <mtk.manpages@gmail.com>
Mike Frysinger <vapier@gentoo.org>
Nicolas Hillegeer <nicolas@hillegeer.com>
Pavel Emelyanov <xemul@parallels.com>
Peter Schiffer <pschiffe@redhat.com>
Radek Pazdera <rpazdera@redhat.com>
Ralph Loader <suckfish@ihug.co.nz>
Simon Paillard <spaillard@debian.org>
The Wanderer <wanderer@fastmail.fm>
Apologies if I missed anyone!
New and rewritten pages
-----------------------
Newly documented interfaces in existing pages
---------------------------------------------
sched_rr_get_interval.2
Michael Kerrisk
Document /proc/sys/kernel/sched_rr_timeslice_ms
proc.5
Pavel Emelyanov
Document /proc/[pid]/map_files directory
This directory was added in Linux v3.3 and provides info about
files being mmap-ed in a way very similar to how /proc/[pid]/fd
works.
v2: Added examples of how links look like and noted dependency
on kernel config option CONFIG_CHECKPOINT_RESTORE.
Michael Kerrisk
Document /proc/sys/kernel/shm_rmid_forced
capabilities.7
Michael Kerrisk
Document /proc/sys/kernel/cap_last_cap
New and changed links
---------------------
Global changes
--------------
Various pages
Michael Kerrisk
Global fix: fix placement of word "only"
Various pages
Simon Paillard
License headers: consistent format
Various pages
Michael Kerrisk
Global fix: s/since kernel/since Linux/
Various System V IPC pages in Section 2
Michael Kerrisk
Add "System V" to .TH line and text
Make it clear that these pages relate to System V IPC,
not POSIX IPC.
Changes to individual pages
---------------------------
access.2
Michael Kerrisk [The Wanderer]
Clarify RETURN VALUE for F_OK
See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=705293
alarm.2
Michael Kerrisk
Correct the description of behavior when 'seconds' is 0
clone.2
Michael Kerrisk [Peter Schiffer]
Add prototype for syscall to SYNOPSIS
And further clarify the distinction between the system call
and the wrapper function in the introductory text.
Michael Kerrisk
Update feature test macro requirements
The requirements quietly changed changed in glibc 2.14
See also http://www.sourceware.org/bugzilla/show_bug.cgi?id=4749
Michael Kerrisk [Mike Frysinger]
Clarify differences between clone2() syscall and wrapper function
Michael Kerrisk [Mike Frysinger]
Note those architectures where the sys_clone argument order differs
Michael Kerrisk [Mike Frysinger]
Add short subsection noting that blackfin, m68k, and sparc are different
Michael Kerrisk
Move clone2() text to subsection in description
The description of ia64 clone2() should follow the discussion
of the raw system call interface.
Michael Kerrisk
Change subhead for ia64 discussion
getcpu.2
Michael Kerrisk
Recommend that 'tcache' should be specified as NULL nowadays
io_cancel.2
Jeff Moyer, Michael Kerrisk [Cyril Hrubis]
Improve description
io_destroy.2
Jeff Moyer
Improve description
The description was rather vague, citing a "list of I/O contexts"
and stating that it "can" cancel outstanding requests. This
update makes things more concrete so that the reader knows exactly
what's going on.
io_getevents.2
Jeff Moyer
The 'timeout' argument is not updated
I looked back through the kernel code, and the timeout was
never updated in any case. I've submitted a patch upstream
to change the comment above io_getevents.
io_setup.2
Jeff Moyer
Clarify nr_events
nr_events is technically the number of completion events that can
be stored in the completion ring. The wording of the man page:
"capable of receiving at least nr_events" seems dubious to me,
only because I worry that folks might interpret that to mean
'nr_events' total, instead of 'nr_events' concurrently.
Further, I've added information on where to find the per-user
limit on 'nr_events', /proc/sys/fs/aio-max-nr. Let me know if
you think that is not relevant.
listxattr.2
Michael Kerrisk
Explain use of 'size' argument
lseek.2
Michael Kerrisk [Andreas Jaeger]
_GNU_SOURCE must be defined to get SEEK_DATE and SEEK_HOLE definitions
See http://sourceware.org/bugzilla/show_bug.cgi?id=15312
mmap.2
Michael Kerrisk
Add pointers to relevant /proc files described in proc(5)
posix_fadvise.2
pread.2
readahead.2
sync_file_range.2
truncate.2
Michael Kerrisk
Refer to syscall(2) for ABI semantics on certain 32-bit architectures
Also: in sync_file_range.2 and posix_fadvise.2 remove description
of conventional calling signature as flawed, and in
posix_fadvise.2, de-emphasize focus on ARM, and rather phrase
as a more general discussion of certain architectures.
readdir.2
Michael Kerrisk
readdir(2) doesn't exist on x86-64
semop.2
Michael Kerrisk
Clarify the discussion of 'semadj'
shmctl.2
Michael Kerrisk
Refer to proc(5) for description of /proc/sys/kernel/shm_rmid_forced
syscall.2
Changhee Han
Add notes that caution users when passing arguments to syscall()
For example, passing 'long long' on ARM-32 requires special
treatment.
Mike Frysinger [Michael Kerrisk]
Document the exact calling convention for architecture system calls
Mike Frysinger [Kyle McMartin]
Add PA-RISC details under calling conventions
Michael Kerrisk [Mike Frysinger]
Refine discussion of ARM and other ABIs
syscalls.2
Michael Kerrisk
Update kernel version number at start of list
umask.2
Michael Kerrisk
SEE ALSO: add acl(5)
unshare.2
Michael Kerrisk
Update feature test macro requirements
The requirements quietly changed changed in glibc 2.14
See also http://www.sourceware.org/bugzilla/show_bug.cgi?id=4749
fopencookie.3
Michael Kerrisk [Ralph Loader]
Correct definition of cookie_io_functions_t
pthread_setname_np.3
Andrew Clayton
The thread argument is passed in by value
readir.3
seekdir.3
telldir.3
Michael Kerrisk
Eliminate the implication that these functions deal with "offsets"
The directory position dealt with by the readdir() and
friends is not a simple file offset in modern file systems.
Typically, it is some kind of cookie value. Add text and
make other changes to these pages to eliminate the
implication that this is an offset, and warn the reader
that directory positions should be treated strictly as
opaque values.
In the process, rename the 'offset' argument of seekdir(3)
to 'loc', and add some text to readdir(3) to note that
the 'd_off' field is the same value returned by telldir(3)
at the current directory position.
See also https://lwn.net/Articles/544298/
scalb.3
Mark H Weaver
Fix prototypes for scalbf() and scalbl()
sched_getcpu.3
Michael Kerrisk
Update feature test macro requirements
The requirements quietly changed changed in glibc 2.14
See also http://www.sourceware.org/bugzilla/show_bug.cgi?id=4749
ualarm.3
Michael Kerrisk [Nicolas Hillegeer]
Add note on the behavior when 'usecs' is zero
POSIX.1-2001 does not specify the behavior in this case
and no other system that I checked documented the behavior.
Probably, most or all systems do what Linux does in this
case: cancel any pending alarm, just as alarm(0) does.
Add that info in NOTES.
elf.5
Mike Frysinger
Add byte positions for all EI_xxx fields
When describing e_ident, most of the EI_xxx defines mention the
exact byte number. This is useful when manually hacking an ELF
with a hex editor. However, the last few fields don't do this,
which means you have to count things up yourself.
Add a single word to each so you don't have to do that.
proc.5
Michael Kerrisk
Refer to sched_rr_get_interval(2) for info on sched_rr_timeslice_ms
Since Linux 3.9, /proc/sys/kernel/sched_rr_timeslice_ms can
be used to change the SCHED_RR quantum.
Michael Kerrisk
SEE ALSO: Add sysctl(8)
Krzysztof Konopko
Simplify the example of printing out environ
The binutils package contains a very handy utility to
print out null-byte delimited strings from a file. This
can replace a rather complex expression with cat(1)
provided as an example for printing out /proc/[pid]/environ.
Michael Kerrisk
Update /proc/PID/maps example
Update to 64-bit example that includes "[heap]", "[stack],
and "[vdso]"
Michael Kerrisk
Formatting fixes for /proc/PID/maps
Mike Frysinger
Document the "pathname" field of /proc/PID/maps
Michael Kerrisk
Add reference to capabilities(7) for /proc/sys/kernel/cap_last_cap
Michael Kerrisk
/proc/PID/maps: add a reference to mmap(2)
ip.7
Radek Pazdera
Document IP_MULTICAST_ALL
This commit adds documentation for the IP_MULTICAST_ALL socket
option.
The option was added to the Linux kernel in 2.6.31:
Author Nivedita Singhvi <niv@us.ibm.com>
Commit f771bef98004d9d141b085d987a77d06669d4f4f
The description is based on a previous one [3] posted by the
original author of the code -- Nivedita, but it is slightly
re-worded.
I tested it myself and it works as described.
References:
[1] http://lxr.free-electrons.com/source/net/ipv4/ip_sockglue.c#L972
[2] http://lxr.free-electrons.com/source/net/ipv4/igmp.c#L2267
[3] http://patchwork.ozlabs.org/patch/28902/
units.7
Brian M. Carlson
units should use an actual µ
The units(7) man page uses an ASCII u in place of the actual Greek
letter mu. Since we're in the twenty-first century, with
UTF-8-compatible terminals and terminal emulators, we should use
the actual letter µ instead of an ASCII approximation.
See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=704787

334
Changes.old
View File

@ -26322,3 +26322,337 @@ socket.7
Michael Kerrisk [Florian Weimer]
Define _GNU_SOURCE to obtain the definition of 'struct ucred'
See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=572210
==================== Changes in man-pages-3.51 ====================
Released: 2013-04-17, Munich
Contributors
------------
The following people contributed patches/fixes or (noted in brackets
in the changelog below) reports, notes, and ideas that have been
incorporated in changes in this release:
Andreas Jaeger <aj@suse.de>
Andrew Clayton <andrew@digital-domain.net>
Brian M. Carlson <sandals@crustytoothpaste.net>
Changhee Han <ch0.han@lge.com>
Cyril Hrubis <chrubis@suse.cz>
Damien Grassart <damien@grassart.com>
David Prévot <taffit@debian.org>
Denis Barbier <bouzim@gmail.com>
Jeff Moyer <jmoyer@redhat.com>
Krzysztof Konopko <krzysztof.konopko@gmail.com>
Kyle McMartin <kyle@mcmartin.ca>
Mark H Weaver <mhw@netris.org>
Michael Kerrisk <mtk.manpages@gmail.com>
Mike Frysinger <vapier@gentoo.org>
Nicolas Hillegeer <nicolas@hillegeer.com>
Pavel Emelyanov <xemul@parallels.com>
Peter Schiffer <pschiffe@redhat.com>
Radek Pazdera <rpazdera@redhat.com>
Ralph Loader <suckfish@ihug.co.nz>
Simon Paillard <spaillard@debian.org>
The Wanderer <wanderer@fastmail.fm>
Apologies if I missed anyone!
Newly documented interfaces in existing pages
---------------------------------------------
sched_rr_get_interval.2
Michael Kerrisk
Document /proc/sys/kernel/sched_rr_timeslice_ms
proc.5
Pavel Emelyanov
Document /proc/[pid]/map_files directory
This directory was added in Linux v3.3 and provides info about
files being mmap-ed in a way very similar to how /proc/[pid]/fd
works.
v2: Added examples of how links look like and noted dependency
on kernel config option CONFIG_CHECKPOINT_RESTORE.
Michael Kerrisk
Document /proc/sys/kernel/shm_rmid_forced
capabilities.7
Michael Kerrisk
Document /proc/sys/kernel/cap_last_cap
Global changes
--------------
Various pages
Michael Kerrisk
Global fix: fix placement of word "only"
Various pages
Simon Paillard
License headers: consistent format
Various pages
Michael Kerrisk
Global fix: s/since kernel/since Linux/
Various System V IPC pages in Section 2
Michael Kerrisk
Add "System V" to .TH line and text
Make it clear that these pages relate to System V IPC,
not POSIX IPC.
Changes to individual pages
---------------------------
access.2
Michael Kerrisk [The Wanderer]
Clarify RETURN VALUE for F_OK
See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=705293
alarm.2
Michael Kerrisk
Correct the description of behavior when 'seconds' is 0
clone.2
Michael Kerrisk [Peter Schiffer]
Add prototype for syscall to SYNOPSIS
And further clarify the distinction between the system call
and the wrapper function in the introductory text.
Michael Kerrisk
Update feature test macro requirements
The requirements quietly changed changed in glibc 2.14
See also http://www.sourceware.org/bugzilla/show_bug.cgi?id=4749
Michael Kerrisk [Mike Frysinger]
Clarify differences between clone2() syscall and wrapper function
Michael Kerrisk [Mike Frysinger]
Note those architectures where the sys_clone argument order differs
Michael Kerrisk [Mike Frysinger]
Add short subsection noting that blackfin, m68k, and sparc are different
Michael Kerrisk
Move clone2() text to subsection in description
The description of ia64 clone2() should follow the discussion
of the raw system call interface.
Michael Kerrisk
Change subhead for ia64 discussion
getcpu.2
Michael Kerrisk
Recommend that 'tcache' should be specified as NULL nowadays
io_cancel.2
Jeff Moyer, Michael Kerrisk [Cyril Hrubis]
Improve description
io_destroy.2
Jeff Moyer
Improve description
The description was rather vague, citing a "list of I/O contexts"
and stating that it "can" cancel outstanding requests. This
update makes things more concrete so that the reader knows exactly
what's going on.
io_getevents.2
Jeff Moyer
The 'timeout' argument is not updated
I looked back through the kernel code, and the timeout was
never updated in any case. I've submitted a patch upstream
to change the comment above io_getevents.
io_setup.2
Jeff Moyer
Clarify nr_events
nr_events is technically the number of completion events that can
be stored in the completion ring. The wording of the man page:
"capable of receiving at least nr_events" seems dubious to me,
only because I worry that folks might interpret that to mean
'nr_events' total, instead of 'nr_events' concurrently.
Further, I've added information on where to find the per-user
limit on 'nr_events', /proc/sys/fs/aio-max-nr. Let me know if
you think that is not relevant.
listxattr.2
Michael Kerrisk
Explain use of 'size' argument
lseek.2
Michael Kerrisk [Andreas Jaeger]
_GNU_SOURCE must be defined to get SEEK_DATE and SEEK_HOLE definitions
See http://sourceware.org/bugzilla/show_bug.cgi?id=15312
mmap.2
Michael Kerrisk
Add pointers to relevant /proc files described in proc(5)
posix_fadvise.2
pread.2
readahead.2
sync_file_range.2
truncate.2
Michael Kerrisk
Refer to syscall(2) for ABI semantics on certain 32-bit architectures
Also: in sync_file_range.2 and posix_fadvise.2 remove description
of conventional calling signature as flawed, and in
posix_fadvise.2, de-emphasize focus on ARM, and rather phrase
as a more general discussion of certain architectures.
readdir.2
Michael Kerrisk
readdir(2) doesn't exist on x86-64
semop.2
Michael Kerrisk
Clarify the discussion of 'semadj'
shmctl.2
Michael Kerrisk
Refer to proc(5) for description of /proc/sys/kernel/shm_rmid_forced
syscall.2
Changhee Han
Add notes that caution users when passing arguments to syscall()
For example, passing 'long long' on ARM-32 requires special
treatment.
Mike Frysinger [Michael Kerrisk]
Document the exact calling convention for architecture system calls
Mike Frysinger [Kyle McMartin]
Add PA-RISC details under calling conventions
Michael Kerrisk [Mike Frysinger]
Refine discussion of ARM and other ABIs
syscalls.2
Michael Kerrisk
Update kernel version number at start of list
umask.2
Michael Kerrisk
SEE ALSO: add acl(5)
unshare.2
Michael Kerrisk
Update feature test macro requirements
The requirements quietly changed changed in glibc 2.14
See also http://www.sourceware.org/bugzilla/show_bug.cgi?id=4749
fopencookie.3
Michael Kerrisk [Ralph Loader]
Correct definition of cookie_io_functions_t
pthread_setname_np.3
Andrew Clayton
The thread argument is passed in by value
readir.3
seekdir.3
telldir.3
Michael Kerrisk
Eliminate the implication that these functions deal with "offsets"
The directory position dealt with by the readdir() and
friends is not a simple file offset in modern file systems.
Typically, it is some kind of cookie value. Add text and
make other changes to these pages to eliminate the
implication that this is an offset, and warn the reader
that directory positions should be treated strictly as
opaque values.
In the process, rename the 'offset' argument of seekdir(3)
to 'loc', and add some text to readdir(3) to note that
the 'd_off' field is the same value returned by telldir(3)
at the current directory position.
See also https://lwn.net/Articles/544298/
scalb.3
Mark H Weaver
Fix prototypes for scalbf() and scalbl()
sched_getcpu.3
Michael Kerrisk
Update feature test macro requirements
The requirements quietly changed changed in glibc 2.14
See also http://www.sourceware.org/bugzilla/show_bug.cgi?id=4749
ualarm.3
Michael Kerrisk [Nicolas Hillegeer]
Add note on the behavior when 'usecs' is zero
POSIX.1-2001 does not specify the behavior in this case
and no other system that I checked documented the behavior.
Probably, most or all systems do what Linux does in this
case: cancel any pending alarm, just as alarm(0) does.
Add that info in NOTES.
elf.5
Mike Frysinger
Add byte positions for all EI_xxx fields
When describing e_ident, most of the EI_xxx defines mention the
exact byte number. This is useful when manually hacking an ELF
with a hex editor. However, the last few fields don't do this,
which means you have to count things up yourself.
Add a single word to each so you don't have to do that.
proc.5
Michael Kerrisk
Refer to sched_rr_get_interval(2) for info on sched_rr_timeslice_ms
Since Linux 3.9, /proc/sys/kernel/sched_rr_timeslice_ms can
be used to change the SCHED_RR quantum.
Michael Kerrisk
SEE ALSO: Add sysctl(8)
Krzysztof Konopko
Simplify the example of printing out environ
The binutils package contains a very handy utility to
print out null-byte delimited strings from a file. This
can replace a rather complex expression with cat(1)
provided as an example for printing out /proc/[pid]/environ.
Michael Kerrisk
Update /proc/PID/maps example
Update to 64-bit example that includes "[heap]", "[stack],
and "[vdso]"
Michael Kerrisk
Formatting fixes for /proc/PID/maps
Mike Frysinger
Document the "pathname" field of /proc/PID/maps
Michael Kerrisk
Add reference to capabilities(7) for /proc/sys/kernel/cap_last_cap
Michael Kerrisk
/proc/PID/maps: add a reference to mmap(2)
ip.7
Radek Pazdera
Document IP_MULTICAST_ALL
This commit adds documentation for the IP_MULTICAST_ALL socket
option.
The option was added to the Linux kernel in 2.6.31:
Author Nivedita Singhvi <niv@us.ibm.com>
Commit f771bef98004d9d141b085d987a77d06669d4f4f
The description is based on a previous one [3] posted by the
original author of the code -- Nivedita, but it is slightly
re-worded.
I tested it myself and it works as described.
References:
[1] http://lxr.free-electrons.com/source/net/ipv4/ip_sockglue.c#L972
[2] http://lxr.free-electrons.com/source/net/ipv4/igmp.c#L2267
[3] http://patchwork.ozlabs.org/patch/28902/
units.7
Brian M. Carlson
units should use an actual µ
The units(7) man page uses an ASCII u in place of the actual Greek
letter mu. Since we're in the twenty-first century, with
UTF-8-compatible terminals and terminal emulators, we should use
the actual letter µ instead of an ASCII approximation.
See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=704787