man-pages-2.22 is released

man-pages-2.22 is released

[Michael Kerrisk]

Gidday,

I recently released man-pages-2.22, which 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'.

Re: man-pages-2.22 is released

[Jesse Barnes]

On Monday, February 6, 2006 11:59 am, Michael Kerrisk wrote:
> 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):

Wouldn't it be easier for you to keep them up to date if sections 2, 4, 
and parts of 5 were included in the kernel source tree?  Documentation 
updates could be enforced as part of the patch process--all you'd have 
to do is NAK patches that modified userland interfaces if they didn't 
contain documentation updates (and I'm sure others would help you with 
that task).

Likewise with the glibc stuff.  Doesn't it belong with the glibc project?  
Wouldn't that make more sense, both from a packaging and maintenance 
perspective?

Either way, thanks a lot for keeping the pages in good shape, it's much 
appreciated.

Thanks,
Jesse

Re: man-pages-2.22 is released

[Michael Kerrisk]

> --- Ursprüngliche Nachricht ---
> Von: Jesse Barnes <jbarnes@virtuousgeek.org>
> An: "Michael Kerrisk" <mtk-manpages@gmx.net>
> Kopie: linux-kernel@vger.kernel.org, michael.kerrisk@gmx.net
> Betreff: Re: man-pages-2.22 is released
> Datum: Mon, 6 Feb 2006 14:51:36 -0800
> 
> On Monday, February 6, 2006 11:59 am, Michael Kerrisk wrote:
> > 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):
> 
> Wouldn't it be easier for you to keep them up to date if sections 2, 4, 
> and parts of 5 were included in the kernel source tree?  Documentation 
> updates could be enforced as part of the patch process--all you'd have 
> to do is NAK patches that modified userland interfaces if they didn't 
> contain documentation updates (and I'm sure others would help you with 
> that task).

Life is not so simple, as I think we discussed when you made 
a similar comment after my man-pages-2.08 release.  Maybe the
system can be improved still.  Currently Andrew Morton is being
rather good about CCing me on patches that are likely to need
man-pages changes.  (Thanks Andrew!)

> Likewise with the glibc stuff.  Doesn't it belong with the glibc project? 
> Wouldn't that make more sense, both from a packaging and maintenance 
> perspective?

Not really -- glibc has a differnt philosophy about documentation
(less focus on historical information and less comparison
with other Unix systems, as far as I can see), and uses info(1), 
not man(1).

> Either way, thanks a lot for keeping the pages in good shape, it's much 
> appreciated.

You're welcome.  Several people help.  More help is 
always welcome.

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'.

Re: man-pages-2.22 is released

[Jesse Barnes]

On Monday, February 6, 2006 2:59 pm, Michael Kerrisk wrote:
> > Wouldn't it be easier for you to keep them up to date if sections 2,
> > 4, and parts of 5 were included in the kernel source tree? 
> > Documentation updates could be enforced as part of the patch
> > process--all you'd have to do is NAK patches that modified userland
> > interfaces if they didn't contain documentation updates (and I'm
> > sure others would help you with that task).
>
> Life is not so simple, as I think we discussed when you made
> a similar comment after my man-pages-2.08 release.  Maybe the
> system can be improved still.  Currently Andrew Morton is being
> rather good about CCing me on patches that are likely to need
> man-pages changes.  (Thanks Andrew!)

Yeah, vigilance is key; maybe I'm wrong that putting the kernel stuff 
into the kernel tree would help, but it's worth a try, don't you 
think? :)

> > Likewise with the glibc stuff.  Doesn't it belong with the glibc
> > project? Wouldn't that make more sense, both from a packaging and
> > maintenance perspective?
>
> Not really -- glibc has a differnt philosophy about documentation
> (less focus on historical information and less comparison
> with other Unix systems, as far as I can see), and uses info(1),
> not man(1).

Oh yeah, forgot about that...  I guess man vs. info and glibc development 
philosophy is for another thread.

Thanks,
Jesse

Re: man-pages-2.22 is released

[Michael Kerrisk]

> On Monday, February 6, 2006 2:59 pm, Michael Kerrisk wrote:
> > > Wouldn't it be easier for you to keep them up to date if sections 2,
> > > 4, and parts of 5 were included in the kernel source tree? 
> > > Documentation updates could be enforced as part of the patch
> > > process--all you'd have to do is NAK patches that modified userland
> > > interfaces if they didn't contain documentation updates (and I'm
> > > sure others would help you with that task).
> >
> > Life is not so simple, as I think we discussed when you made
> > a similar comment after my man-pages-2.08 release.  Maybe the
> > system can be improved still.  Currently Andrew Morton is being
> > rather good about CCing me on patches that are likely to need
> > man-pages changes.  (Thanks Andrew!)
> 
> Yeah, vigilance is key; maybe I'm wrong that putting the kernel stuff 
> into the kernel tree would help, but it's worth a try, don't you 
> think? :)

There is no simple solution to this problem, but I will
give it some thought one day...

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'.

man-pages-2.23 is released

[Michael Kerrisk]

Gidday,

I recently released man-pages-2.23, which can be found at the 
location listed in the .sig.

This release includes the following new manual pages:

inotify_init.2
inotify_add_watch.2
inotify_rm_watch.2
    Robert Love, with some additions by mtk.
        New pages describing the inotify API.
    
inotify.7
    mtk
        Overview of the inotify API.

mbind.2
get_mempolicy.2
set_mempolicy.2
    Andi Kleen, with additional work by mtk
        New pages describing the NUMA memory allocation policy API.

rtc.4
    Urs Thuermann, with additional work by mtk
        New page describing the real-time clock driver.

Among other notable changes for existing pages are the following:

mlock.2
    mtk / Matthias Andree
        Added BUGS txt on interaction between MCL_FUTURE and
        RLIMIT_MEMLOCK.
        See the following LKML thread:
        http://marc.theaimsgroup.com/?l=linux-kernel&m=113801392825023&w=2
        "Rationale for RLIMIT_MEMLOCK"
        
sched_setaffinity.2
    mtk
        Major rewrite.

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'.

Re: man-pages-2.23 is released

[Christoph Lameter]

On Fri, 10 Feb 2006, Michael Kerrisk wrote:

> mbind.2

Does this include a description of the new flags MPOL_MF_MOVE and 
MPOL_MF_MOVE_ALL? There is a manpage in Andi Kleen's numactl 0.9.2 that 
describes these.

Re: man-pages-2.23 is released

[Michael Kerrisk]

> > mbind.2
> 
> Does this include a description of the new flags MPOL_MF_MOVE and 
> MPOL_MF_MOVE_ALL? There is a manpage in Andi Kleen's numactl 0.9.2 that 
> describes these.

Not yet, because 2.6.16 (which adds these flags) is not yet 
released.  However, I have the material in my queue to be 
integrated when 2.6.16 is released.

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'.

man-pages-2.24 is released

[Michael Kerrisk]

Gidday,

I recently released man-pages-2.24, which can be found at the 
location listed in the .sig.

This release includes the following new manual pages:

get_kernel_syms.2 
create_module.2  
delete_module.2  
init_module.2    
query_module.2
    FSF / mtk (with assistance of Luc Van Oostenryck)
        man-pages finally gets pages for these system calls, several
        of which are obsolete in Linux 2.6.
        Took the old GPLed pages dated 1996 and made a number of
        clean-ups and minor additions.

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'.

man-pages-2.25 is released

[Michael Kerrisk]

Gidday,

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:

mq_close.3
mq_getattr.3
mq_notify.3
mq_open.3
mq_receive.3
mq_send.3
mq_unlink.3
    mtk
        New pages describing POSIX message queue API.

mq_overview.7
    mtk
        New page giving overview of the POSIX message queue API.

posix_fallocate.3
    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.

==========
fcntl.2
     FIXME According to SUSv3, O_SYNC should also be modifiable
     via fcntl(2), but currently Linux does not permit this
     See http://bugzilla.kernel.org/show_bug.cgi?id=5994

     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
     effective.
     See http://bugzilla.kernel.org/show_bug.cgi?id=5993

     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

==========
mount.2
     FIXME 2.6.15-rc1 has 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

==========
open.2
     FIXME Check bugzilla report on open(O_ASYNC)
     See http://bugzilla.kernel.org/show_bug.cgi?id=5993

==========
prctl.2
     FIXME: The following (applicable only on IA-64) are not currently
     described: PR_SET_UNALIGN, PR_GET_UNALIGN, PR_SET_FPEMU, PR_GET_FPEMU

==========
ptrace.2
     FIXME The following are not documented:
     	PTRACE_SETOPTIONS (2.4.6)
    		plus associated flags:
    			PTRACE_O_TRACESYSGOOD (2.4.6)
    			PTRACE_O_TRACEFORK (2.5.46)
    			PTRACE_O_TRACEVFORK (2.5.46)
    			PTRACE_O_TRACECLONE (2.5.46)
    			PTRACE_O_TRACEEXEC (2.5.46)
    			PTRACE_O_TRACEVFORKDONE (2.5.60)
    			PTRACE_O_TRACEEXIT (2.5.60)
    	PTRACE_SETSIGINFO (2.3.99-pre6)
    	PTRACE_GETSIGINFO (2.3.99-pre6)
    	PTRACE_GETEVENTMSG (2.5.46)

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

==========
send.2
     FIXME? document MSG_PROXY (which went away in 2.3.15)

==========
shmget.2
     FIXME 2.6.15 adds SHM_NORESERVE; document it.

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

     FIXME That last sentence isn't true for all Linux
     architectures (i.e., SHMLBA != PAGE_SIZE for some architectures)
     -- MTK, Nov 04

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

==========
proc.5
     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
     Changelog
     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

==========
capabilities.7
     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
     the details?

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

     FIXME 2.6.14-rc1: CAP_SYS_ADMIN:
    		/* Allow setting zone reclaim policy */

==========
ddp.7
     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
     EACCES etc.)

==========
icmp.7
     FIXME  better description needed

==========
ip.7
     FIXME As at 2.6.12, 14 Jun 2005, the following are undocumented:
    	ip_queue_maxlen
    	ip_conntrack_max

     FIXME: document ip_autoconfig

     FIXME Document the conf/*/* sysctls
     FIXME Document the route/* sysctls

     FIXME Add a discussion of multicasting

     FIXME document all errors.

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

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

==========
tcp.7
     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)

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

man-pages-2.26 is released

[Michael Kerrisk]

Gidday,

I recently released man-pages-2.26, which can be found at:

    ftp://ftp.win.tue.nl/pub/linux-local/manpages

or:

    ftp://ftp.kernel.org/pub/linux/docs/manpages
    or mirrors: ftp://ftp.XX.kernel.org/pub/linux/docs/manpages

This release includes various changes that may be significant 
for readers of this list, including documentation on various new
kernel 2.6.16 interfaces, listed further down in this message.

I'd like to request that any kernel developers who make changes 
to the kernel-userland interface (e.g., system calls, /proc,
netlink interfaces, etc.) do some or (preferably) all of the
following when initially submitting the patch (to, for example, 
the -mm tree):

   a) CC me at mtk-manpages@gmx.net,
   b) include or point me at some text that explains the 
      interface change (more on the preferred ways for doing 
      that below), and
   c) include or point me at userland test programs that 
      demonstrate/test the interface.

This will likely have two effects:

    * The process of getting the change documented in the man-pages
      once it enters mainline will be speeded up.

    * I will try testing the change (as time permits).  Even if
      you do c) above, I will typically still write my own
      test program(s), since I often like to test things in 
      additional ways.

New pages
---------

openat.2
    mtk
        New page describing openat(2), added in kernel 2.6.16,
        and some notes on rationale for the at*(2) system calls.

mbind.2
    Andi Kleen, Christoph Lameter, mtk
       Added MPOL_MF_MOVE and MPOL_MF_MOVE_ALL descriptions,
       from numactl-0.9.2 man page.

fexecve.3
    mtk
        New page describing fexecve(3).

futimes.3
    mtk
        New page describing futimes(3).

Apologies: The "Changes" file in the release mentions a new unshare.2 
page documenting the unshare() system call that is new in kernel 
2.6.16.  This manual page will only appear with man-pages-2.27.

Changes to individual pages
---------------------------

poll.2
    mtk
        Added discussion of ppoll(2), which is new in 2.6.16.
    
select.2
    mtk
        Updated to reflect the fact that pselect() has been implemented
        in the kernel in 2.6.16; various other minor wording changes.

netlink.7
    Hasso Tepper
        Substantial updates to various parts of this page.

pthreads.7
    mtk
        Updated to reflect that the NPTL limitation that only the main 
        thread could call setsid() and setpgid() was removed in 2.6.16.

socket.7
    mtk
        Documented SO_SNDBUFFORCE and SO_RCVBUFFORCE socket options,
        new in 2.6.14.

==========

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).

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. Some raw text 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'.

man-pages-2.27 is released

[Michael Kerrisk]

Gidday,

I recently released man-pages-2.27, which can be found at:

    ftp://ftp.win.tue.nl/pub/linux-local/manpages

or:

    ftp://ftp.kernel.org/pub/linux/docs/manpages
    or mirrors: ftp://ftp.XX.kernel.org/pub/linux/docs/manpages

This release includes various changes that may be significant 
for readers of this list, including documentation on various new
kernel 2.6.16 interfaces, listed further down in this message.

At the moment, manual pages for the following system calls
are notably absent:

add_key(2)          (new in 2.6.10)
keyctl(2)           (new in 2.6.10)
request_key(2)      (new in 2.6.10)
    See:
        Documentation/keys.txt
        Documentation/keys-request-key.txt

        
ioprio_get(2)       (new in kernel 2.6.13) 
ioprio_set(2)       (new in kernel 2.6.13)
    See Documentation/block/ioprio.txt


restart_syscall(2)  (new in 2.6)
kexec_load(2)       (new in kernel 2.6.13)

migrate_pages(2)    (new in 2.6.16)
                    See Documentation/vm/page_migration

New manual pages for the above system calls would be most 
welcome.

2.27 Changes
============

Notable changes in this release include the following:

New pages
---------

ushare.2
    mtk, with reference to documentation by Janak Desai
        New page describing unshare(2), added in kernel 2.6.16.


Changes to individual pages
---------------------------

ptrace.2
    Chuck Ebbert, with assistance from Daniel Jacobowitz, 
    Paolo (Blaisorblade) Giarrusso, and Charles P. Wright;
    after a suggestion from Heiko Carstens.
        Document the following ptrace requests: 
            PTRACE_SETOPTIONS (2.4.6)
                plus associated flags:
                    PTRACE_O_TRACESYSGOOD (2.4.6)
                    PTRACE_O_TRACEFORK (2.5.46)
                    PTRACE_O_TRACEVFORK (2.5.46)
                    PTRACE_O_TRACECLONE (2.5.46)
                    PTRACE_O_TRACEEXEC (2.5.46)
                    PTRACE_O_TRACEVFORKDONE (2.5.60)
                    PTRACE_O_TRACEEXIT (2.5.60)
            PTRACE_SETSIGINFO (2.3.99-pre6)
            PTRACE_GETSIGINFO (2.3.99-pre6)
            PTRACE_GETEVENTMSG (2.5.46)
            PTRACE_SYSEMU (since Linux 2.6.14)
            PTRACE_SYSEMU_SINGLESTEP (since Linux 2.6.14)
    
sched_get_priority_max.2
sched_setscheduler.2
sched_setparam.2
    mtk, Ingo Molnar
        Modified to document SCHED_BATCH policy, new in kernel 2.6.16.

        Text describing SCHED_BATCH was added to sched_setscheduler.2,
        and was drawn in part from Ingo Molnar's description in the
        mail message containing the patch that implemented this policy.

        Various other minor rewordings and formatting fixes.

proc.5
    mtk, using text from Documentation/filesystems/proc.txt
        Document /proc/sys/vm/drop_caches, new in kernel 2.6.16.
    mtk, using information from ChangeLog-2.6.14.
        Document /proc/PID/smaps, new in kernel 2.6.14.

capabilities.7
    mtk
        Noted affect of CAP_SYS_NICE for mbind(MPOL_MF_MOVE_ALL).

pthreads.7
    mtk
        Kernel 2.6.16 eliminated buggy behaviour with respect to
        the alternate signal stack.

==========

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).

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. Some raw text 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'.

man-pages-2.28 is released

[Michael Kerrisk]

Gidday,

I recently released man-pages-2.28, which can be found at:

    ftp://ftp.win.tue.nl/pub/linux-local/manpages

or:

    ftp://ftp.kernel.org/pub/linux/docs/manpages
    or mirrors: ftp://ftp.XX.kernel.org/pub/linux/docs/manpages

This release includes the following new pages:

sem_post.3
sem_getvalue.3
sem_close.3
sem_open.3
sem_destroy.3
sem_wait.3
sem_unlink.3
sem_init.3
sem_overview.7
    mtk
        New pages describing the POSIX semaphores API.

        These pages supercede and provide a superset of the information 
        in the glibc (3thr) "semaphores(3)" manual page.

==========

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).

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. Some raw text 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'.

man-pages-2.29 is released

[Michael Kerrisk]

Gidday,

I recently released man-pages-2.29, which can be found at the 
location in the .sig.  A list of some notable changes can be found
further down in this message

*** A request ***

Manual pages for the follwoing system calls are notably absent
from the man-pages set.  Contributions would be most welcome.

add_key(2)              (new in kernel 2.6.10)
keyctl(2)               (new in kernel 2.6.10)
request_key(2)          (new in kernel 2.6.10)
    See:
        Documentation/keys.txt
        Documentation/keys-request-key.txt

ioprio_get(2)           (new in kernel 2.6.13)
ioprio_set(2)           (new in kernel 2.6.13)
    See:
        Documentation/block/ioprio.txt

restart_syscall(2)      (new in kernel 2.6)

kexec_load(2)           (new in kernel 2.6.13)

migrate_pages(2)        (new in kernel 2.6.16)
                        See Documentation/vm/page_migration

2.29 Changes
============

Changes in this release that may be of interest to readers
of this list include the following:

New pages
---------

mkdirat.2
    mtk
        New page describing mkdirat(2), new in 2.6.16.

mknodat.2
    mtk
        New page describing mknodat(2), new in 2.6.16.

core.5
    mtk
        New page describing core dump files.

mkfifoat.3
    mtk
        New page describing mkfifoat(3).


Changes to individual pages
---------------------------

getrlimit.2
    mtk
        Added BUGS text on 2.6.x handling of RLIMIT_CPU limit
        of zero seconds.  See
        http://marc.theaimsgroup.com/?l=linux-kernel&m=112256338703880&w=2

==========

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).

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. Some raw text 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'.

man-pages-2.30 is released

[Michael Kerrisk]

Gidday,

I recently released man-pages-2.30, which can be found at the 
location in the .sig.  

Changes in this release that may be of interest to readers
of this list include the following:

New pages
---------

linkat.2
    mtk
        New page describing linkat(), new in kernel 2.6.16

renameat.2
    mtk
        New page describing renameat(), new in kernel 2.6.16

symlinkat.2
    mtk
        New page describing symlinkat(), new in kernel 2.6.16

unlinkat.2
    mtk
        New page describing unlinkat(), new in kernel 2.6.16

==========

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).

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. Some raw text 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'.

man-pages-2.32 is released

[Michael Kerrisk]

Gidday,

I recently released man-pages-2.32, which can be found at the 
location in the .sig.  

Changes in this release that may be of interest to readers
of this list include the following:

New pages
---------

faccessat.2
    mtk
        New page for faccessat(2), new in 2.6.16.

fchmodat.2
    mtk
        New page for fchmodat(2), new in 2.6.16.

fchownat.2
    mtk
        New page for fchownat(2), new in 2.6.16.

futimesat.2
    mtk
        New page for futimesat(2), new in 2.6.16.

Changes to individual pages
---------------------------

capabilities.7
    mtk
        Reworded to reflect that capabilities are per-thread.
        Add ioprio_set() to list of operations permitted by
        CAP_SYS_NICE.
        Add ioprio_set() IOPRIO_CLASS_RT and IOPRIO_CLASS_IDLE
        scheduling classes to list of operations permitted by
        CAP_SYS_ADMIN.
        Note effects of CAP_SYS_NICE for migrate_pages().


==========

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).

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. Some raw text 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'.

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@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'.