man-pages-2.31 is released

[Michael Kerrisk]

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 mtk-manpages@xxxxxxx ) 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 majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/