lkml.org 
[lkml]   [2006]   [May]   [3]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    Date
    From
    Subjectman-pages-2.31 is released
    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@gmx.net ) 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@vger.kernel.org
    More majordomo info at http://vger.kernel.org/majordomo-info.html
    Please read the FAQ at http://www.tux.org/lkml/

    \
     
     \ /
      Last update: 2006-05-04 01:30    [W:6.758 / U:0.048 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site