man-pages-2.67 is released

[Michael Kerrisk <mtk.manpages@googlemail.com>]

Gidday,

Some news: as from now, my address as man-pages maintainer has changed to
mtk.manpages@gmail.com.  (Mail to the old address will continue to work for
a while, but eventually I will close that account.)

Some older news: the list linux-man@vger.kernel.org has been created for
the purpose of discussing Linux man page bugs, patches, and maintenance.
To subscribe, send a message to majordomo@vger.kernel.org, with the body:

    subscribe linux-man

Back to the news as usual...

I recently released man-pages-2.67.

This release is now available for download at:

    http://www.kernel.org/pub/linux/docs/manpages
    or ftp://ftp.kernel.org/pub/linux/docs/manpages

The changes in this release are primarily formatting fixes, and the
addition of a PROLOG section to the 1p and 3p (POSIX) pages giving a clear
indication that these are POSIX man pages (so as to prevent readers wrongly
understanding that they are looking at a description of Linux behavior).

There are many things to be fixed in the man pages.  Help with any of the
problems listed below would be greatly appreciated.

Cheers,

Michael
(man-pages maintenance is supported by Google, as a Google engineer 20%
project.)

=========================================================================

FIXMEs

==========
./man2/futex.2
     FIXME
     2.6.18 adds (Ingo Molnar) priority inheritance support:
     FUTEX_LOCK_PI, FUTEX_UNLOCK_PI, and FUTEX_TRYLOCK_PI.  These need
     to be documented in the manual page.  Probably there is sufficient
     material in the kernel source file Documentation/pi-futex.txt.

==========
./man2/ioperm.2
     FIXME is the following ("Only the first 0x3ff I/O ports can be
     specified in this manner") still true?  Looking at changes in
     include/asm-i386/processor.h between 2.4 and 2.6 suggests
     that the limit is different in 2.6.

==========
./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 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.

==========
./man2/mprotect.2
     FIXME
     Document PROT_GROWSUP and PROT_GROWSDOWN

==========
./man2/nfsservctl.2
     FIXME The description of nfsservctl() on this page
     is woefully thin.

==========
./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:

     Linux 2.2 has:

        Q_GETQUOTA
        Q_GETSTATS
        Q_QUOTAOFF
        Q_QUOTAON
        Q_RSQUASH (not currently documented)
        Q_SETQLIM
        Q_SETQUOTA
        Q_SETUSE
        Q_SYNC

     Linux 2.4 has:

        Q_COMP_QUOTAOFF
        Q_COMP_QUOTAON
        Q_COMP_SYNC
        Q_GETFMT
        Q_GETINFO
        Q_GETQUOTA
        Q_QUOTAOFF
        Q_QUOTAON
        Q_SETINFO
        Q_SETQUOTA
        Q_SYNC
        Q_V1_GETQUOTA Q_V1_GETSTATS Q_V1_RSQUASH Q_V1_SETQLIM
        Q_V1_SETQUOTA Q_V1_SETUSE
        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
        Q_XSETQLIM

     Linux 2.6.16 has:

        Q_GETFMT
        Q_GETINFO
        Q_GETQUOTA
        Q_QUOTAOFF
        Q_QUOTAON
        Q_SETINFO
        Q_SETQUOTA
        Q_SYNC
        Q_XGETQSTAT
        Q_XGETQUOTA
        Q_XQUOTAOFF
        Q_XQUOTAON
        Q_XQUOTARM
        Q_XQUOTASYNC
        Q_XSETQLIM

==========
./man2/shmop.2
     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

==========
./man2/sigaction.2
     FIXME si_tid and si_overrun are not documented.
     FIXME si_trapno is not documented; is it actually used?

==========
./man5/acct.5
     FIXME this page needs to say a lot more, including mentioning
        Version 3 format process accounting on Linux.

==========
./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 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]/mountstats and
           /proc/PID/task/TID/mountstats
          Some information can be found in the 2.6.17-rc1 change log.
           Added in 2.6.17

     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 The following is not the full picture for the 'intr' of
           /proc/stat on 2.6:

     FIXME more should be said about /proc/zoneinfo

==========
./man7/capabilities.7
     FIXME CAP_KILL also has an effect for threads + setting child
           termination signal to other than SIGCHLD: without this
           capability, the termination signal reverts to SIGCHLD
           if the child does an exec().  What is the rationale
           for this?

     FIXME CAP_SETUID also an effect in exec(); document this.

     FIXME CAP_SYS_NICE also has the following effect for
     migrate_pages(2):
         do_migrate_pages(mm, &old, &new,
             capable(CAP_SYS_NICE) ? MPOL_MF_MOVE_ALL : MPOL_MF_MOVE);

==========
./man7/ipv6.7
     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

==========
./man7/locale.7
     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.

==========
./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.

==========
./man7/socket.7
     FIXME Document SO_PASSSEC, added in 2.6.18; there is some info
     in the 2.6.18 ChangeLog

==========
./man7/tcp.7
     FIXME 2.6.17-rc1 adds the following /proc files, which need to be
          documented: tcp_mtu_probing, tcp_base_mss, and
          tcp_workaround_signed_windows

     FIXME As at Sept 2006, kernel 2.6.18-rc5, the following are
        not yet documented (shown with default values):

         /proc/sys/net/ipv4/tcp_congestion_control (since 2.6.13)
         bic
         /proc/sys/net/ipv4/tcp_moderate_rcvbuf
         1
         /proc/sys/net/ipv4/tcp_no_metrics_save
         0

     FIXME Document TCP_CONGESTION (new in 2.6.13)

==========
./man7/udp.7
     FIXME document UDP_ENCAP (new in kernel 2.5.67)