Subject: glibc-doc: Manual pages are outdated for NPTL
Date: Mon, 14 Jan 2008 11:03:37 +0100
Package: glibc-doc
Version: 2.7-6
Severity: normal
The man pages are LinuxThreads-specific, even though the default
implementation of pthreads is NPTL nowadays. Some library calls such as
pthread_mutexattr_setpshared are missing, and some of the limitations
(such as using inter-process mutex locking), options and other
peculiarities also differ.
Unfortunately I think that the docs are outdated upstream as well
(including the info pages in glibc-doc-reference), but nevertheless this
is a drawback for development and thus constitutes a reason to have a
bug filed. Maybe adding a few lines on top of each man page already
avoids some of the misleading information.
Usually I wouldn't choose severity normal for man pages, but this page
doesn't really contain anything else. Feel free to readjust :)
-- System Information:
Debian Release: lenny/sid
APT prefers unstable
APT policy: (500, 'unstable')
Architecture: amd64 (x86_64)
Kernel: Linux 2.6.22-3-amd64 (SMP w/2 CPU cores)
Locale: LANG=de_DE.UTF-8, LC_CTYPE=de_DE.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/bash
-- no debconf information
Acknowledgement sent
to Jonathan Nieder <[email protected]>:
Extra info received and forwarded to list. Copy sent to GNU Libc Maintainers <[email protected]>.
(Sat, 27 Feb 2010 18:21:07 GMT) (full text, mbox, link).
Subject: LinuxThreads manual pages (Re: glibc-doc: Manual pages are
outdated for NPTL)
Date: Sat, 27 Feb 2010 12:19:16 -0600
Hi,
Josef Spillner wrote:
> The man pages are LinuxThreads-specific, even though the default
> implementation of pthreads is NPTL nowadays. Some library calls such as
> pthread_mutexattr_setpshared are missing, and some of the limitations
> (such as using inter-process mutex locking), options and other
> peculiarities also differ.
>
> Unfortunately I think that the docs are outdated upstream as well
Indeed, the LinuxThreads man pages are not even maintained upstream
any more AFAICT.
My suggestion would be to copy over any information and text that applies
for NPTL to the man-pages project, and once the man-pages versions are
deemed suitable (or maybe right away), get the Debian glibc-doc package
to stop shipping these files and manpages-dev to start.
The LinuxThreads man pages can be found in the subdirectory
linuxthreads/man/ of the tree
git://sourceware.org/git/glibc.git tags/glibc-2.4~922
The man-pages project repository can be found in the subdirectory man3/
of the tree
git://git.kernel.org/pub/scm/docs/man-pages/man-pages.git
I could not find an explicit distribution license for the LinuxThreads
man page, but they are part of LinuxThreads, so they are presumably
LGPL-2.1+; man-pages, on the other hand, consists mostly of pages with
a more permissive license but accepts pages under the GPL as well. [1]
I am cc-ing Michael Kerrisk, who wrote all of the pthread_* pages in
man-pages I’ve checked. Michael, what do you think? Would you be
interested in patches porting over details and explanations from
LinuxThreads?
Jonathan
[1] http://www.kernel.org/doc/man-pages/licenses.html
Subject: Re: LinuxThreads manual pages (Re: glibc-doc: Manual pages are
outdated for NPTL)
Date: Sun, 28 Feb 2010 09:14:30 +0100
Hello Jonathan,
> I am cc-ing Michael Kerrisk, who wrote all of the pthread_* pages in
> man-pages I’ve checked. Michael, what do you think? Would you be
> interested in patches porting over details and explanations from
> LinuxThreads?
I would accept such patches.
Cheers,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface" http://blog.man7.org/
Acknowledgement sent
to Jonathan Nieder <[email protected]>:
Extra info received and forwarded to list. Copy sent to GNU Libc Maintainers <[email protected]>.
(Mon, 08 Mar 2010 05:39:03 GMT) (full text, mbox, link).
clone 460637 -1
retitle 460637 manpages-dev: Port over whatever is useful from LinuxThreads pages
severity 460637 wishlist
reassign 460637 manpages-dev
retitle -1 Please remove outdated LinuxThreads manpages
forcemerge 572716 -1
severity -1 minor
block -1 by 519781
thanks
Jonathan Nieder wrote:
> Josef Spillner wrote:
>> The man pages are LinuxThreads-specific, even though the default
>> implementation of pthreads is NPTL nowadays. Some library calls such as
>> pthread_mutexattr_setpshared are missing, and some of the limitations
>> (such as using inter-process mutex locking), options and other
>> peculiarities also differ.
>>
>> Unfortunately I think that the docs are outdated upstream as well
>
> Indeed, the LinuxThreads man pages are not even maintained upstream
> any more AFAICT.
>
> My suggestion would be to copy over any information and text that applies
> for NPTL to the man-pages project, and once the man-pages versions are
> deemed suitable (or maybe right away), get the Debian glibc-doc package
> to stop shipping these files and manpages-dev to start.
So splitting the bug in two:
- Since the LinuxThreads man pages tend to be nice though outdated, I will
be working as time permits to copy what is still applicable to man-pages.
mtk seems to be okay with this plan, which is nice. See [1] for details
on how to help out.
- The pages in man-pages are usable and maintained, and I think we should
ship them. This requires coordination between the two packages.
Actually, manpages-dev should be changed first (with Replaces: glibc-doc,
this requires no action by the glibc maintainers).
[1] http://bugs.debian.org/460637
Changed Bug title to 'manpages-dev: Port over whatever is useful from LinuxThreads pages' from 'glibc-doc: Manual pages are outdated for NPTL'
Request was from Jonathan Nieder <[email protected]>
to [email protected].
(Mon, 08 Mar 2010 05:39:06 GMT) (full text, mbox, link).
On Sun, Mar 07, 2010 at 11:36:37PM -0600, Jonathan Nieder wrote:
> clone 460637 -1
> retitle 460637 manpages-dev: Port over whatever is useful from LinuxThreads pages
> severity 460637 wishlist
> reassign 460637 manpages-dev
> retitle -1 Please remove outdated LinuxThreads manpages
> forcemerge 572716 -1
> severity -1 minor
> block -1 by 519781
> thanks
[snip]
> - The pages in man-pages are usable and maintained, and I think we should
> ship them. This requires coordination between the two packages.
> Actually, manpages-dev should be changed first (with Replaces: glibc-doc,
> this requires no action by the glibc maintainers).
Note that in order to avoid file conflicts, my patch for #519781 just
adds pages to manpages-dev that are long removed from glibc-doc.
In particular, it does *not* add the man-pages for
pthread_kill_other_threads_np(3), pthread_kill(3), pthread_sigmask(3)
and sigwait(3), because these are still shipped by glibc-doc; glibc-doc
bug #572716 suggests to remove these from glibc-doc.
Nikolaus