man-pages-2.08 is released

man-pages-2.08 is released

[Michael Kerrisk]

Gidday,

I recently released man-pages-2.08, 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.

To give an idea of the kinds of things that are desired as 
manual page additions/improvements, I've shown extracts from 
the man-pages-2.08 Changelog below.

Cheers,

Michael

==================== Changes in man-pages-2.08 ====================

connect.2
        Add EINTR error

getpriority.2
        Expanded discussion of relationship between user and kernel
            representations of the nice value.
        Added discussion of RLIMIT_NICE and a cross reference to
            getrlimit.2 under the description of the EACCES error.
        Noted 2.6.12 change in credentials checking for setpriority().

getrlimit.2
        Added description of RLIMIT_RTPRIO
        Added description of RLIMIT_NICE

mmap.2
        Noted bug in MAP_POPULATE for kernels before 2.6.7.

mremap.2
        Added _GNU_SOURCE to prototype.
        Rewrote description of MREMAP_MAYMOVE.
        Rewrote description of EAGAIN error.
        Added discussion of resizing of memory locks.

msgctl.2
        Added IPC_INFO, MSG_INFO, MSG_STAT descriptions.

prctl.2
        Since kernel 2.6.13 PR_SET_DUMPABLE can also have the value 2.

remap_file_pages.2
        Added text to note that start and size are both rounded 
        downwards.

sched_setparam.2
       Modified discussion of privileges; added pointer to
           sched_setscheduler.2 for a discussion of privileges and
           resource limits.

sched_setscheduler.2
       Modified discussion of privileges; added discussion of 
       RLIMIT_RTPRIO.

semctl.2
        Added IPC_INFO, SEM_INFO, SEM_STAT descriptions.

shmctl.2
        Added IPC_INFO, SHM_INFO, SHM_STAT descriptions.

sigaction.2
        Split sigpending(), sigprocmask(), and sigsuspend() out
        into separate new pages.

sigpending.2
        New page created by splitting out from sigaction.2

sigprocmask.2
        New page created by splitting out from sigaction.2
        Added text on effect of NULL for 'set' argument.
        Added text noting effect of ignoring SIGBUS, SIGFPE, SIGILL,
                and SIGSEGV.
        Noted that sigprocmask() can't be used in multithreaded process.
        Fixed EINVAL error diagnostic.

sigsuspend.2
        New page created by splitting out from sigaction.2
        Added NOTES on usage.

stat.2
        Improve st_blocks description.

getaddrinfo.3
        Nowadays (since 2.3.4) glibc only sets the first ai_canonname
        field if AI_CANONNAME was specified (the current behavior
        is all that SUSv3 requires).

        1,$s/PF_/AF_/g

        Added descriptions of AI_ALL, AI_ADDRCONFIG, AI_V4MAPPED,
        and AI_NUMERICSERV.

setenv.3
        glibc 2.3.4 fixed the "name contains '='" bug

proc.5
        Improve text describing /proc/sys/fs/mqueue/* files

        Describe /proc/sys/fs/suid_dumpable (new in 2.6.13)

        Added placeholder mention of /proc/zoneinfo (new in 2.6.13)
            More needs to be said about this file

        Repaired earlier cut and paste mistake which resulted
            in part of the text of this page being duplicated.

capabilities.7
        Added CAP_AUDIT_CONTROL and CAP_AUDIT_WRITE.

ip.7
        Fix discussion of IPC_RECVTTL / IP_TTL

socket.7
        Clarified details of use of SO_PEERCRED.

udp.7
        Added description of UDP_CORK socket option

-- 
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/
and grep the source files for 'FIXME'.

Re: man-pages-2.08 is released

[Jesse Barnes]

On Wednesday, October 12, 2005 9:26 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):

Would it make sense for some of the man pages (or maybe all of them) that 
correspond directly to kernel interfaces (e.g. syscalls, procfs & sysfs 
descriptions) to be bundled directly with the kernel?  Andrew is 
generally pretty good about asking people to update the stuff in 
Documentation/ when necessary, so maybe the man pages would be kept more 
up to date if developers were forced to deal with them more directly.

OTOH, they comprise a fairly large package, so adding them to the kernel 
tarball would increase its size a lot.

The man pages are great; I'm just thinking that if some of them were 
bundled with the kernel there'd be a bit less work for you to do (just 
proofreading and acking changes hopefully).  Also, if they were there, 
it might motivate people to convert some of the stuff in Documentation 
to section 7 man pages (the janitors have been doing a lot of good 
stuff, maybe that would be another area where they could contribute).

Thanks,
Jesse

Re: man-pages-2.08 is released

[Michael Kerrisk]

> Von: Jesse Barnes <jbarnes@virtuousgeek.org>
> 
> On Wednesday, October 12, 2005 9:26 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):
> 
> Would it make sense for some of the man pages (or maybe all of them) that 
> correspond directly to kernel interfaces (e.g. syscalls, procfs & sysfs 
> descriptions) to be bundled directly with the kernel?  Andrew is 
> generally pretty good about asking people to update the stuff in 
> Documentation/ when necessary, so maybe the man pages would be kept more 
> up to date if developers were forced to deal with them more directly.

Recently, I was just wondering the same thing.  However, there 
are complexities to consider.  C libraries (okay, glibc is the 
main one I concern myself with) sometimes add some functionality 
in the wrapper function for a particular system call.  This also
needs to be documented in the Secion 2 page. 

Nevertheless, I think the idea of binding the kernel sources and 
Sections 2 and 4 of the manual pages a bit more tightly bears
some consideration.  In the ideal world, when a change is made to
the kernel, the patch could include adjustments to the man 
pages (if relevant) -- then the changes could follow the patch 
through the -mm tree and then into Linus's tree.

> OTOH, they comprise a fairly large package, so adding them to the kernel 
> tarball would increase its size a lot.

I'd guess that the uncompressed source of the relevant pages 
would be around 3 MB.
 
> The man pages are great; 

Thanks.  But the greatest part of credit must go to Andries, 
the maintainer for nearly 10 years.  I'm shortly coming up to my 
first anniversary...

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/
and grep the source files for 'FIXME'.

Re: man-pages-2.08 is released

[Jesse Barnes]

On Thursday, October 13, 2005 1:52 am, Michael Kerrisk wrote:
> Recently, I was just wondering the same thing.  However, there
> are complexities to consider.  C libraries (okay, glibc is the
> main one I concern myself with) sometimes add some functionality
> in the wrapper function for a particular system call.  This also
> needs to be documented in the Secion 2 page.

True.  But there are other libcs available (e.g. klibc, dietlibc) too.  
I'd think that if the pages were bundled with the kernel, they should 
describe exactly what the kernel does, while pages bundled with a libc 
would describe any enhancements (or breakages) that the particular libc 
includes.  But then what to do about duplicates?  Or should the raw 
kernel interfaces have their own section, while libc interfaces remain 
in section 2?  Or should the libc versions typically replace the kernel 
versions on running systems?  Or 'patch' the existing kernel pages 
somehow?  So many questions... ;)

> Nevertheless, I think the idea of binding the kernel sources and
> Sections 2 and 4 of the manual pages a bit more tightly bears
> some consideration.  In the ideal world, when a change is made to
> the kernel, the patch could include adjustments to the man
> pages (if relevant) -- then the changes could follow the patch
> through the -mm tree and then into Linus's tree.

That was my though too; it's certainly easier to ask people to update 
manual pages in Documentation/ or man/ when they do a kernel patch than 
to ask them to download a separate package and make the changes (since 
they'll probably never get around to doing the latter :).

> > OTOH, they comprise a fairly large package, so adding them to the
> > kernel tarball would increase its size a lot.
>
> I'd guess that the uncompressed source of the relevant pages
> would be around 3 MB.

Ok, that's not too bad.  Having full, up-to-date man pages would be worth 
the extra few megs to me at least.

> > The man pages are great;
>
> Thanks.  But the greatest part of credit must go to Andries,
> the maintainer for nearly 10 years.  I'm shortly coming up to my
> first anniversary...

Many thanks to both of you then!

Jesse