Bug#460637: glibc-doc: Manual pages are outdated for NPTL

classic Classic list List threaded Threaded
13 messages Options
Reply | Threaded
Open this post in threaded view
|

Bug#460637: glibc-doc: Manual pages are outdated for NPTL

Josef Spillner-3
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



--
To UNSUBSCRIBE, email to [hidden email]
with a subject of "unsubscribe". Trouble? Contact [hidden email]

Reply | Threaded
Open this post in threaded view
|

Bug#460637: LinuxThreads manual pages (Re: glibc-doc: Manual pages are outdated for NPTL)

Jonathan Nieder
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



--
To UNSUBSCRIBE, email to [hidden email]
with a subject of "unsubscribe". Trouble? Contact [hidden email]
Archive: http://lists.debian.org/20100227181915.GA4238@...

Reply | Threaded
Open this post in threaded view
|

Bug#460637: LinuxThreads manual pages (Re: glibc-doc: Manual pages are outdated for NPTL)

Michael Kerrisk-4
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/



--
To UNSUBSCRIBE, email to [hidden email]
with a subject of "unsubscribe". Trouble? Contact [hidden email]
Archive: http://lists.debian.org/cfd18e0f1002280014i7db5d865o97766b4fdd1d51e8@...

Reply | Threaded
Open this post in threaded view
|

Bug#460637: LinuxThreads manual pages

Jonathan Nieder
In reply to this post by Jonathan Nieder
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



--
To UNSUBSCRIBE, email to [hidden email]
with a subject of "unsubscribe". Trouble? Contact [hidden email]
Archive: http://lists.debian.org/20100308053636.GA22951@...

Reply | Threaded
Open this post in threaded view
|

Processed: Re: LinuxThreads manual pages

Debian Bug Tracking System
Processing commands for [hidden email]:

> clone 460637 -1
Bug#460637: glibc-doc: Manual pages are outdated for NPTL
Bug 460637 cloned as bug 572996.

> retitle 460637 manpages-dev: Port over whatever is useful from LinuxThreads pages
Bug #460637 [glibc-doc] glibc-doc: Manual pages are outdated for NPTL
Changed Bug title to 'manpages-dev: Port over whatever is useful from LinuxThreads pages' from 'glibc-doc: Manual pages are outdated for NPTL'
> severity 460637 wishlist
Bug #460637 [glibc-doc] manpages-dev: Port over whatever is useful from LinuxThreads pages
Severity set to 'wishlist' from 'normal'

> reassign 460637 manpages-dev
Bug #460637 [glibc-doc] manpages-dev: Port over whatever is useful from LinuxThreads pages
Bug reassigned from package 'glibc-doc' to 'manpages-dev'.
Bug No longer marked as found in versions glibc/2.7-6.
> retitle -1 Please remove outdated LinuxThreads manpages
Bug #572996 [glibc-doc] glibc-doc: Manual pages are outdated for NPTL
Changed Bug title to 'Please remove outdated LinuxThreads manpages' from 'glibc-doc: Manual pages are outdated for NPTL'
> forcemerge 572716 -1
Bug#572716: glibc-doc: please stop providing man pages for pthread_kill(3) et al
Bug#572996: Please remove outdated LinuxThreads manpages
Forcibly Merged 572716 572996.

> severity -1 minor
Bug #572996 [glibc-doc] Please remove outdated LinuxThreads manpages
Bug #572716 [glibc-doc] glibc-doc: please stop providing man pages for pthread_kill(3) et al
Severity set to 'minor' from 'wishlist'

Severity set to 'minor' from 'wishlist'

> block -1 by 519781
Bug #572996 [glibc-doc] Please remove outdated LinuxThreads manpages
Bug #572716 [glibc-doc] glibc-doc: please stop providing man pages for pthread_kill(3) et al
Was not blocked by any bugs.
Added blocking bug(s) of 572996: 562148, 519781, 562150, and 562149
Was not blocked by any bugs.
Added blocking bug(s) of 572716: 562148, 519781, 562150, and 562149
> thanks
Stopping processing here.

Please contact me if you need assistance.

Debian bug tracking system administrator
(administrator, Debian Bugs database)


--
To UNSUBSCRIBE, email to [hidden email]
with a subject of "unsubscribe". Trouble? Contact [hidden email]
Archive: http://lists.debian.org/handler.s.C.126802660517430.transcript@...

Reply | Threaded
Open this post in threaded view
|

Bug#572716: LinuxThreads manual pages

Nikolaus Schulz
In reply to this post by Jonathan Nieder
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



--
To UNSUBSCRIBE, email to [hidden email]
with a subject of "unsubscribe". Trouble? Contact [hidden email]
Archive: http://lists.debian.org/20100315135541.GA28941@...

Reply | Threaded
Open this post in threaded view
|

Bug#572716: LinuxThreads manual pages

Jonathan Nieder
(Removing Bug#460637 from CC, since that bug doesn’t depend on this one.)

Nikolaus Schulz wrote:
> On Sun, Mar 07, 2010 at 11:36:37PM -0600, Jonathan Nieder wrote:

>> 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.
Good catch.  Here’s the more complete (but more dangerous) patch.

Thoughts?

>From 14ee79f0d36e7dd2a33b86197bd1fbbb691698c3 Mon Sep 17 00:00:00 2001
From: Jonathan Nieder <[hidden email]>
Date: Fri, 26 Mar 2010 00:00:00 -0500
Subject: [PATCH] manpages-dev: Take over pthread_* namespace from glibc-doc

The LinuxThreads manpages included in glibc-doc are starting to show
their age, and the pages on pthreads in man-pages are usable and
maintained.  I think we should start shipping the latter.  This
requires coordination between the two packages.  Actually,
manpages-dev gets the first move (with Replaces: glibc-doc, this
requires no action by the glibc maintainers).

An unversioned Replaces relation is very convenient, because it means we
can take our time removing relevant files from glibc-doc without
coordinating revisions to synchronize with this change.

The Replaces relation can be changed to a versioned Replaces as soon as
that work is complete.  Even without such a change, as long as the
pages are removed from glibc-doc before squeeze is released, the
Replaces can be completely removed from manpages-dev for squeeze+1.

Note!  If afterwards glibc-doc takes over some filenames from this
version of manpages-dev (before squeeze+1 is released), then glibc-doc
would have to use Conflicts rather than Replaces+Breaks to signal
that, making for a less pleasant upgrade.  I have no reason to believe
this would happen, but it’s worth keeping in mind.

Thanks to Nikolaus Schulz <[hidden email]> for an initial patch.
---
 debian/changelog |   28 ++++++++++++++++++++++++++++
 debian/control   |    2 +-
 debian/inst      |   12 +-----------
 3 files changed, 30 insertions(+), 12 deletions(-)

diff --git a/debian/changelog b/debian/changelog
index 71b9947..320dc18 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,31 @@
+manpages (3.24-1.1) experimental; urgency=low
+
+  * Added an unversioned Replaces entry against glibc-doc due to
+    old pthreads manpages shipped with glibc-doc.
+  * Distribute pthreads manpages that were removed in glibc-doc 2.9-1:
+    . pthread_attr_*(3)
+    . pthread_cleanup_*(3)
+    . pthread_create(3)
+    . pthread_detach(3)
+    . pthread_equal(3)
+    . pthread_exit(3)
+    . pthread_join(3)
+    . pthread_getschedparam(3)
+    . pthread_setschedparam(3)
+    . pthread_self(3)
+    . pthread_setcancelstate(3)
+    . pthread_setcanceltype(3)
+    . pthread_testcancel(3)
+    . pthread_cancel(3)
+  * Distribute more pthreads manpages to replace the ancient pages in
+    glibc-doc:
+    . pthread_kill(3)
+    . pthread_kill_other_threads_np(3)
+    . pthread_sigmask(3)
+    . sigwait(3)
+
+ -- Jonathan Nieder <[hidden email]>  Thu, 25 Mar 2010 23:22:13 -0500
+
 manpages (3.24-1) unstable; urgency=low
 
   * New upstream version
diff --git a/debian/control b/debian/control
index 6e6fd60..48a71ae 100644
--- a/debian/control
+++ b/debian/control
@@ -27,7 +27,7 @@ Package: manpages-dev
 Architecture: all
 Depends: manpages
 Suggests: man-browser
-Replaces: glibc-doc (<< 2.3.6-8)
+Replaces: glibc-doc
 Priority: optional
 Description: Manual pages about using GNU/Linux for development
  These man pages describe the Linux programming interface, including
diff --git a/debian/inst b/debian/inst
index de035bc..62e6ca8 100644
--- a/debian/inst
+++ b/debian/inst
@@ -65,17 +65,7 @@ for i in man[23]; do
  getxattr.2|lgetxattr.2|listxattr.2|llistxattr.2|lremovexattr.2|\
  get_kernel_syms.2|create_module.2|delete_module.2|\
  init_module.2|query_module.2|set_mempolicy.2|\
- pthread_attr_destroy.3|pthread_attr_getdetachstate.3|pthread_cleanup_pop.3|\
- pthread_attr_getscope.3|pthread_attr_init.3|pthread_attr_setdetachstate.3|\
- pthread_attr_setscope.3|pthread_create.3|pthread_detach.3|pthread_equal.3|\
- pthread_exit.3|pthread_join.3|pthread_self.3|pthread_attr_setschedpolicy.3|\
- pthread_setschedparam.3|pthread_attr_setschedparam.3|pthread_attr_getschedparam.3|\
- pthread_getschedparam.3|pthread_attr_getschedpolicy.3|pthread_cleanup_push.3|\
- pthread_testcancel.3|pthread_setcancelstate.3|pthread_attr_getinheritsched.3|\
- pthread_attr_setinheritsched.3|pthread_setcanceltype.3|pthread_cancel.3|\
- pthread_cleanup_push_defer_np.3|pthread_cleanup_pop_restore_np.3|\
- pthread_kill_other_threads_np.3|pthread_sigmask.3|pthread_kill.3|\
- lsetxattr.2|removexattr.2|setxattr.2|sigwait.3)
+ lsetxattr.2|removexattr.2|setxattr.2)
  echo -n "(skipped)"
  ;;
  *)
--
1.7.0.3

Reply | Threaded
Open this post in threaded view
|

Re: manpages-dev: does not install pthread_* manpages (Re: LinuxThreads manual pages)

Jonathan Nieder
Hi Joey,

Jonathan Nieder wrote:

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

Any thoughts on this?  Would you be more comfortable with a versioned
Replaces: (which requires a little more coordination with glibc
maintainers), or is there anything else I can do to help make this
happen?

In particular, if the problem is lack of time, I would be glad to work
on finding a DD willing to sponsor staging this in experimental so we
could try out both changes (manpages-dev, glibc-doc).

Thanks,
Jonathan


--
To UNSUBSCRIBE, email to [hidden email]
with a subject of "unsubscribe". Trouble? Contact [hidden email]
Archive: http://lists.debian.org/20100629103047.GA2712@burratino

Reply | Threaded
Open this post in threaded view
|

Re: manpages-dev: does not install pthread_* manpages (Re: LinuxThreads manual pages)

Aurelien Jarno
On Tue, Jun 29, 2010 at 05:30:47AM -0500, Jonathan Nieder wrote:

> Hi Joey,
>
> Jonathan Nieder wrote:
>
> >>>  - 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).
>
> Any thoughts on this?  Would you be more comfortable with a versioned
> Replaces: (which requires a little more coordination with glibc
> maintainers), or is there anything else I can do to help make this
> happen?
>
> In particular, if the problem is lack of time, I would be glad to work
> on finding a DD willing to sponsor staging this in experimental so we
> could try out both changes (manpages-dev, glibc-doc).
>

There is no need to go through experimental. Once the change is done on
manpages-dev, we can upload a fixed glibc-doc. A Replaces: is the way to
go.


--
Aurelien Jarno                          GPG: 1024D/F1BCDB73
[hidden email]                 http://www.aurel32.net


--
To UNSUBSCRIBE, email to [hidden email]
with a subject of "unsubscribe". Trouble? Contact [hidden email]
Archive: http://lists.debian.org/20100629215256.GA1995@...

Reply | Threaded
Open this post in threaded view
|

Re: Bug#519781: manpages-dev: does not install pthread_* manpages (Re: LinuxThreads manual pages)

Joey Schulze
Aurelien Jarno wrote:

> On Tue, Jun 29, 2010 at 05:30:47AM -0500, Jonathan Nieder wrote:
> > Hi Joey,
> >
> > Jonathan Nieder wrote:
> >
> > >>>  - 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).
> >
> > Any thoughts on this?  Would you be more comfortable with a versioned
> > Replaces: (which requires a little more coordination with glibc
> > maintainers), or is there anything else I can do to help make this
> > happen?
> >
> > In particular, if the problem is lack of time, I would be glad to work
> > on finding a DD willing to sponsor staging this in experimental so we
> > could try out both changes (manpages-dev, glibc-doc).
> >
>
> There is no need to go through experimental. Once the change is done on
> manpages-dev, we can upload a fixed glibc-doc. A Replaces: is the way to
> go.

I'll include pthread manpages in the next upload again.

Regards,

        Joey

--
Life is too short to run proprietary software.  -- Bdale Garbee

Please always Cc to me when replying to me on the lists.


--
To UNSUBSCRIBE, email to [hidden email]
with a subject of "unsubscribe". Trouble? Contact [hidden email]
Archive: http://lists.debian.org/20100630073310.GA29306@...

Reply | Threaded
Open this post in threaded view
|

Bug#572716: Bug#519781: manpages-dev: does not install pthread_* manpages (Re: LinuxThreads manual pages)

Jonathan Nieder
tags 572716 - moreinfo
quit

Joey Schulze wrote:

> I'll include pthread manpages in the next upload again.

Looks good.

Now glibc-doc 2.11.2-3 should use Breaks: manpages-dev (<< 3.25-1)
and... well, you know the drill.

Thanks.
Jonathan



--
To UNSUBSCRIBE, email to [hidden email]
with a subject of "unsubscribe". Trouble? Contact [hidden email]
Archive: http://lists.debian.org/20100705160019.GA22231@burratino

Reply | Threaded
Open this post in threaded view
|

Processed: Re: Bug#519781: manpages-dev: does not install pthread_* manpages (Re: LinuxThreads manual pages)

Debian Bug Tracking System
Processing commands for [hidden email]:

> tags 572716 - moreinfo
Bug #572716 [glibc-doc] glibc-doc: please stop providing man pages for pthread_kill(3) et al
Bug #572996 [glibc-doc] Please remove outdated LinuxThreads manpages
Removed tag(s) moreinfo.
Removed tag(s) moreinfo.
> quit
Stopping processing here.

Please contact me if you need assistance.
--
572716: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=572716
Debian Bug Tracking System
Contact [hidden email] with problems


--
To UNSUBSCRIBE, email to [hidden email]
with a subject of "unsubscribe". Trouble? Contact [hidden email]
Archive: http://lists.debian.org/handler.s.C.12783456615200.transcript@...

Reply | Threaded
Open this post in threaded view
|

Bug#572996: marked as done (Please remove outdated LinuxThreads manpages)

Debian Bug Tracking System
In reply to this post by Josef Spillner-3
Your message dated Mon, 7 Feb 2011 08:46:42 +0100
with message-id <[hidden email]>
and subject line Re: Bug#519781: manpages-dev: does not install pthread_* manpages (Re: LinuxThreads manual pages)
has caused the Debian Bug report #572716,
regarding Please remove outdated LinuxThreads manpages
to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
Bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact [hidden email]
immediately.)


--
572716: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=572716
Debian Bug Tracking System
Contact [hidden email] with problems

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



Version: 2.11.2-4

On Mon, Jul 05, 2010 at 11:00:19AM -0500, Jonathan Nieder wrote:

> tags 572716 - moreinfo
> quit
>
> Joey Schulze wrote:
>
> > I'll include pthread manpages in the next upload again.
>
> Looks good.
>
> Now glibc-doc 2.11.2-3 should use Breaks: manpages-dev (<< 3.25-1)
> and... well, you know the drill.
>
This has been fixed in version 2.11.2-4. Closing the bug.

--
Aurelien Jarno                          GPG: 1024D/F1BCDB73
[hidden email]                 http://www.aurel32.net