Gidday,
I recently released man-pages-2.31, which can be found at the
location listed in the .sig.
This release includes the following new manual pages:
fstatat.2
mtk
New page for fstatat(2), new in 2.6.16.
adjtime.3
mtk
New page for adjtime(3).
ftm.7
mtk
New page describing feature test macros.
time.7
mtk
New page giving an overview of "time" on Linux systems.
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.
==========
/home/mtk/man-pages/man2/madvise.2
FIXME 2.6.16 added MADV_REMOVE, MADV_DONTFORK, and MADV_DOFORK.
These need to be documented.
MADV_REMOVE /* remove these pages & resources */
MADV_DONTFORK /* don't inherit across fork */
MADV_DOFORK /* do inherit across fork */
A discussion of MADV_DONTFORK and MADV_DOFORK can be found
at http://lwn.net/Articles/171941/
==========
/home/mtk/man-pages/man2/mount.2
FIXME 2.6.15 added flags for "shared sub-tree" functionality:
MS_UNBINDABLE, MS_PRIVATE, MS_SHARED, MS_SLAVE
These need to be documented on this page.
See Documentation/sharedsubtree.txt
FIXME Say more about MS_MOVE
FIXME Document MS_REC, available since 2.4.11.
This flag has meaning in conjunction with MS_BIND and
also with the shared sub-tree flags.
FIXME Since Linux 2.6.16, MS_NODIRATIME and MS_NOATIME are
also settable on a per-mount basis
FIXME Can MNT_FORCE result in data loss? According to
the Solaris manual page it can cause data loss on Solaris.
If the same holds on Linux, then this should be documented.
==========
/home/mtk/man-pages/man2/quotactl.2
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:
==========
/home/mtk/man-pages/man2/shmop.2
FIXME What does "failing attach at brk" mean? (Is this phrase
just junk?)
FIXME A good explanation of the rationale for the existence
of SHMLBA would be useful here
==========
/home/mtk/man-pages/man5/acct.5
FIXME this page needs to say a lot more, including mentioning
Version 3 format process accounting on Linux.
==========
/home/mtk/man-pages/man5/proc.5
FIXME 2.6.14 has /proc/PID/numa_maps (if CONFIG_NUMA is
enabled); this needs to be documented.
Info on numa_maps can be found in the patch-2.6.14
Changelog, but this is possibly not up to date.
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 2.6.17-rc1 has /proc/PID/mountstats and
/proc/PID/task/TID/mountstats; these need to be documented
Some information can be found in the 2.6.17-rc1 change log.
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 Document /proc/config.gz (new in kernel 2.6)
FIXME Actually, the following info abut the /proc/stat 'cpu' field
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 The following is not the full picture for the 'intr' of
/proc/stat on 2.6:
FIXME more should be said about /proc/zoneinfo
==========
/home/mtk/man-pages/man7/netlink.7
FIXME More details on NETLINK_INET_DIAG needed.
FIXME More details on NETLINK_XFRM needed.
FIXME More details on NETLINK_ISCSI needed.
FIXME More details on NETLINK_AUDIT needed.
FIXME More details on NETLINK_FIB_LOOKUP needed.
FIXME More details on NETLINK_NETFILTER needed.
FIXME More details on NETLINK_KOBJECT_UEVENT needed.
FIXME NLM_F_ATOMIC is not used any more?
FIXME Explain more about nlmsg_seq and nlmsg_pid.
==========
/home/mtk/man-pages/man7/tcp.7
FIXME 2.6.17-rc1 adds the following /proc files, which need to
documentedtcp_mtu_probing, tcp_base_mss, and
tcp_workaround_signed_windows
FIXME As at 14 Jun 2005, kernel 2.6.12, the following are
not yet documented (shown with default values):
/proc/sys/net/ipv4/tcp_bic_beta
819
/proc/sys/net/ipv4/tcp_moderate_rcvbuf
1
/proc/sys/net/ipv4/tcp_no_metrics_save
0
/proc/sys/net/ipv4/tcp_vegas_alpha
2
/proc/sys/net/ipv4/tcp_vegas_beta
6
/proc/sys/net/ipv4/tcp_vegas_gamma
2
FIXME Document TCP_CONGESTION (new in 2.6.13)
==========
/home/mtk/man-pages/man7/udp.7
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
4: Devices
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 protected] ) 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
ftp://ftp.win.tue.nl/pub/linux-local/manpages or
ftp://ftp.kernel.org/pub/linux/docs/manpages .)
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.
Cheers,
Michael
--
Michael Kerrisk
maintainer of Linux man pages Sections 2, 3, 4, 5, and 7
Want to help with man page maintenance?
Grab the latest tarball at
ftp://ftp.win.tue.nl/pub/linux-local/manpages/,
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 [email protected]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
[Index of Archives]
[Kernel Newbies]
[Netfilter]
[Bugtraq]
[Photo]
[Stuff]
[Gimp]
[Yosemite News]
[MIPS Linux]
[ARM Linux]
[Linux Security]
[Linux RAID]
[Video 4 Linux]
[Linux for the blind]
[Linux Resources]
