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

Hi,

Josef Spillner wrote:

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

Hello Jonathan,

I would accept such patches.

Cheers,

Michael

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:

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

[snip]

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