should i have all man pages referenced by *other* man pages?

[Robert P. J. Day]

On Tue, 29 May 2012, Krzysztof Mitko wrote:

> On 2012-05-29 14:26, Robert P. J. Day wrote:
> > On Tue, 29 May 2012, Krzysztof Mitko wrote:
> >
> >> On 2012-05-29 13:53, Robert P. J. Day wrote:
> >>>
> >>>   not sure if this question is appropriate for this list, but i'm
> >>> reading the man pages for threads, and in "man 7 pthreads", toward the
> >>> bottom, there are references to other man page entries:
> >>>
> >>>   "... pthread_mutex_lock(3), pthread_mutex_unlock(3) ..."
> >>>
> >>>   first, there are no such man pages:
> >>>
> >>> $ man 3 pthread_mutex_lock
> >>> No manual entry for pthread_mutex_lock in section 3
> >>> $ man 3 pthread_mutex_unlock
> >>> No manual entry for pthread_mutex_unlock in section 3
> >>> $
> >>>
> >>>   also, that list under "SEE ALSO" doesn't mention the closely-related
> >>> routine pthread_mutex_trylock().
> >>>
> >>>   is this considered a bug?  something worth reporting somewhere?
> >>
> >> You need manpages-dev package, which AFAIR is not installed by default.
> >> Fill a bug or submit a brainstorm idea if you think all manpages should
> >> be available by default.
> >
> >   it would appear i already have manpages-dev installed (not that i
> > remember installing it, so something else must have dragged it along).
> > so it would appear there are definite deficiencies in the man pages.
>
> My bad, I took a look on packages.ubuntu.com and these manpages are in
> packages manpages-posix-dev.

  ah, that i *don't* have so installing it now, but it will still be
curious if that fills in the holes since it would imply that some
pthread routine man pages come from one package and some from another,
even when they're *very* closely related.  (oh, and there's a
"manpages-posix" package as well of which i was unaware.)

  ah, suddenly, i have man pages for the pthread mutex locking
primitives, but in the "P" section of the docs:

PTHREAD_MUTEX_LOCK(P)               POSIX Programmer's Manual

NAME
       pthread_mutex_lock, pthread_mutex_trylock, pthread_mutex_unlock - lock and unlock a mutex

SYNOPSIS
       #include <pthread.h>

       int pthread_mutex_lock(pthread_mutex_t *mutex);
       int pthread_mutex_trylock(pthread_mutex_t *mutex);
       int pthread_mutex_unlock(pthread_mutex_t *mutex);
       ... snip ...

but that disagrees with the references at the bottom of "man 7
pthreads":

"... pthread_mutex_lock(3), pthread_mutex_unlock(3) ..."

which clearly refers to the wrong section, and also doesn't mention
the "trylock" variation.  oh, dear, what can of worms have i
opened here?

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================