docs/134376: pthread manpages don't mention that PTHREAD_MUTEX_INITIALIZER may leak memory

[Török Edwin]

>Number:         134376
>Category:       docs
>Synopsis:       pthread manpages don't mention that PTHREAD_MUTEX_INITIALIZER may leak memory
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Fri May 08 19:30:03 UTC 2009
>Closed-Date:
>Last-Modified:
>Originator:     Török Edwin
>Release:        FreeBSD 7.2-RELEASE amd64
>Organization:
>Environment:
FreeBSD freebsd72.localdomain 7.2-RELEASE FreeBSD 7.2-RELEASE #0: Fri May 1 07:18:07 UTC 2009 root at driscoll.cse.buffalo.edu:/usr/o
bj/usr/src/sys/GENERIC amd64
>Description:
The manpages for pthread(3), pthread_mutex_lock(5), pthread_mutex_init(3), pthread_mutex_destroy(3) make no mention of PTHREAD_MUT
EX_INITIALIZER, and that using it in a loop causes memory leaks.                                                                          
It  is obvious that PTHREAD_MUTEX_INITIALIZER acts like pthread_mutex_init, which on FreeBSD allocates memory.                    
If pthread_mutex_destroy is not called this results in a 60 byte memory leak (on amd64), which in turn can cause long running daemons to r
un out of memory as described here: https://wwws.clamav.net/bugzilla/show_bug.cgi?id=1567#c33, and here: https://wwws.clamav.net/bugzilla/show_bug.cgi?id=1567#c32                                                                                 
 
        Although portable programs shouldn't rely on knowing the implementation details of pthreads, knowing that it allocates memory can
(and maybe other implementation details) can provide useful debugging hints when something goes wrong.                                   

>How-To-Repeat:
Assign PTHREAD_MUTEX_INITIALIZER to a variable in a function, call pthread_mutex_lock/unlock, call function in a loop ->          
there is a 60-byte memory leak. Look at pthread manpages for clues about what can be wrong, find no clues.
>Fix:
PTHREAD_MUTEX_INITIALIZER doesn't appear in any of the pthread manpages, it should be added.                                 
        The FreeBSD manpages for pthread_mutex_lock, or pthread_mutex_init should document that on FreeBSD memory is allocated when these 
functions are used (I was not aware of this for example), and that one shouldn't use PTHREAD_MUTEX_INITIALIZER in code that is possibly ca
lled in a loop. Since you can't pthread_mutex_destroy a mutex "allocated" with PTHREAD_MUTEX_INITIALIZER, the manpage should recommend the
use of pthread_mutex_init/pthread_mutex_destroy in this case.
        By reading the /usr/include/pthread.h file I realize that PTHREAD_MUTEX_INITIALIZER is actually NULL, so I guess memory allocation
 happens on first pthread_mutex_lock call, maybe the manpage should document that.

>Release-Note:
>Audit-Trail:
>Unformatted: