|| ||"Michael Kerrisk" <firstname.lastname@example.org>|
|| ||man-pages-2.25 is released|
|| ||Thu, 2 Mar 2006 23:00:08 +0100 (MET)|
I recently released man-pages-2.25, which can be found at the
location listed in the .sig.
This release includes the following new manual pages:
New pages describing POSIX message queue API.
New page giving overview of the POSIX message queue API.
mtk, after a suggestion by James Peach
New page describing posix_fallocate().
There are a number of known places where things need
to be fixed in the manual pages. I have included a partial
list below. Any help on these points would be most welcome.
FIXME According to SUSv3, O_SYNC should also be modifiable
via fcntl(2), but currently Linux does not permit this
FIXME The statement that O_ASYNC can be used in open() does not
match reality; setting O_ASYNC via open() does not seem to be
FIXME Dec 04: some limited testing on alpha and ia64 seems to
indicate that ANY negative PGID value will cause F_GETOWN
to misinterpret the return as an error. Some other architectures
seem to have the same range check as x86. Must document
the reality on other architectures -- MTK
FIXME 2.6.15-rc1 has MS_UNBINDABLE, MS_PRIVATE, MS_SHARED, MS_SLAVE
These need to be documented on this page.
FIXME: Say more about MS_MOVE
FIXME Check bugzilla report on open(O_ASYNC)
FIXME: The following (applicable only on IA-64) are not currently
described: PR_SET_UNALIGN, PR_GET_UNALIGN, PR_SET_FPEMU, PR_GET_FPEMU
FIXME The following are not documented:
plus associated flags:
FIXME There is much that is missing and/or out of date in this page.
As things stand the page more or less documents Linux 2.2 reality:
Linux 2.2 has:
Q_RSQUASH (not currently documented)
Linux 2.4 has:
Q_V1_GETQUOTA Q_V1_GETSTATS Q_V1_RSQUASH Q_V1_SETQLIM
Q_V2_GETINFO Q_V2_GETQUOTA Q_V2_SETFLAGS Q_V2_SETGRACE
Q_V2_SETINFO Q_V2_SETQUOTA Q_V2_SETUSE
Q_XGETQSTAT Q_XGETQUOTA Q_XQUOTAOFF Q_XQUOTAON Q_XQUOTARM
Linux 2.6.16 has:
FIXME? document MSG_PROXY (which went away in 2.3.15)
FIXME 2.6.15 adds SHM_NORESERVE; document it.
FIXME What does "failing attach at brk" mean? (Is this phrase
FIXME A good explanation of the rationale for the existence
of SHMLBA would be useful here
FIXME That last sentence isn't true for all Linux
architectures (i.e., SHMLBA != PAGE_SIZE for some architectures)
-- MTK, Nov 04
FIXME this page needs to say a lot more, including mentioning
Version 3 format process accounting on Linux.
FIXME 2.6.14 has added /proc/PID/smaps (if CONFIG_MMU
is enabled) and /proc/PID/numa_maps (if CONFIG_NUMA is
enabled); they need to be documented.
Info on smaps can be found in the patch-2.6.14-rc1 Changelog
and in Documentation/filesystems/proc.txt
Info on numa_maps can be found in the patch-2.6.14-rc1
FIXME 2.6.13 seems to have /proc/vmcore implemented
in the source code, but there is no option available under
'make xconfig'; eventually this should be fixed, and then info
from the patch-2.6.13 and change log could be used to write an
entry in this man page.
FIXME -- cross check against Documentation/filesystems/proc.txt
to see what information could be imported from that file
into this file.
FIXME Describe /proc/[number]/loginuid
Added in 2.6.11; updating requires CAP_AUDIT_CONTROL
FIXME Describe /proc/[number]/oom_adj
Added in 2.6.11; updating requires CAP_SYS_RESOURCE
Mention OOM_DISABLE (-17)
FIXME Describe /proc/[number]/oom_score
Added in 2.6.11; read-only
FIXME Describe /proc/[number]/seccomp
Added in 2.6.12
FIXME: Actually, the following does not seem to be quite
right (at least in 2.6.12)
FIXME 2.6.11 adds a further column "steal" (see
fs/proc/proc_misc.c); this is not yet described...
FIXME -- more should be said about /proc/zoneinfo
FIXME Capabilities are actually per-thread.
FIXME: CAP_KILL also an effect for threads + setting child
termination signal to other than SIGCHLD; but what are
FIXME: CAP_SETUID also an effect in exec(); document this.
FIXME 2.6.14-rc1: CAP_SYS_ADMIN:
/* Allow setting zone reclaim policy */
FIXME Add a section about multicasting
FIXME document all errors. We should really fix the kernels to
give more uniform error returns (ENOMEM vs ENOBUFS, EPERM vs
FIXME better description needed
FIXME As at 2.6.12, 14 Jun 2005, the following are undocumented:
FIXME: document ip_autoconfig
FIXME Document the conf/*/* sysctls
FIXME Document the route/* sysctls
FIXME Add a discussion of multicasting
FIXME document all errors.
FIXME IPV6_CHECKSUM is not documented, and probably should be
FIXME IPV6_JOIN_ANYCAST is not documented, and probably should be
FIXME IPV6_LEAVE_ANYCAST is not documented, and probably should be
FIXME IPV6_V6ONLY is not documented, and probably should be
FIXME IPV6_RECVPKTINFO is not documented, and probably should be
FIXME IPV6_2292PKTINFO is not documented, and probably should be
FIXME there are probably many other IPV6_* socket options that
should be documented
FIXME glibc 2.2.2 added new non-standard locale categories:
LC_ADDRESS, LC_IDENTIFICATION, LC_MEASUREMENT, LC_NAME,
LC_PAPER, LC_TELEPHONE. These need to be documented.
FIXME: As at 14 Jun 2005, kernel 2.6.12, the following are
not yet documented (shown with default values):
FIXME Document TCP_CONGESTION (new in 2.6.13)
FIXME document UDP_ENCAP (new in kernel 2.5.67)
The man-pages set contains sections 2, 3, 4, 5, and 7 of
the manual pages. These sections describe the following:
2: (Linux) system calls
3: (libc) library functions
5: File formats and protocols
7: Overview pages, conventions, etc.
As far as this list is concerned the most relevant parts are:
all of sections 2 and 4, which describe kernel-userland interfaces;
in section 5, the proc(5) manual page, which attempts (it's always
catching up) to be a comprehensive description of /proc; and
various pages in section 7, some of which are overview pages of
kernel features (e.g., networking protocols).
This is a request to kernel developers: if you make a change
to a kernel-userland interface, or observe a discrepancy
between the manual pages and reality, would you please send
me (at email@example.com ) one of the following
(in decreasing order of preference):
1. An in-line "diff -u" patch with text changes for the
corresponding manual page. (The most up-to-date version
of the manual pages can always be found at
2. An email describing the changes, which I can then
integrate into the appropriate manual page.
3. A message alerting me that some part of the manual pages
does not correspond to reality. Eventually, I will try to
remedy the situation.
Obviously, as we get further down this list, more of my time
is required, and things may go slower, especially when the
changes concern some part of the kernel that I am ignorant
about and I can't find someone to assist.
maintainer of Linux man pages Sections 2, 3, 4, 5, and 7
Want to help with man page maintenance?
Grab the latest tarball at
read the HOWTOHELP file and grep the source
files for 'FIXME'.
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to firstname.lastname@example.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/