From nobody@FreeBSD.org  Fri May  8 19:25:10 2009
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id 41D361065670
	for <freebsd-gnats-submit@FreeBSD.org>; Fri,  8 May 2009 19:25:10 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (www.freebsd.org [IPv6:2001:4f8:fff6::21])
	by mx1.freebsd.org (Postfix) with ESMTP id 150F28FC08
	for <freebsd-gnats-submit@FreeBSD.org>; Fri,  8 May 2009 19:25:10 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (localhost [127.0.0.1])
	by www.freebsd.org (8.14.3/8.14.3) with ESMTP id n48JP9HJ080523
	for <freebsd-gnats-submit@FreeBSD.org>; Fri, 8 May 2009 19:25:09 GMT
	(envelope-from nobody@www.freebsd.org)
Received: (from nobody@localhost)
	by www.freebsd.org (8.14.3/8.14.3/Submit) id n48JP9ws080522;
	Fri, 8 May 2009 19:25:09 GMT
	(envelope-from nobody)
Message-Id: <200905081925.n48JP9ws080522@www.freebsd.org>
Date: Fri, 8 May 2009 19:25:09 GMT
From: Trk Edwin <edwintorok@gmail.com>
To: freebsd-gnats-submit@FreeBSD.org
Subject: pthread manpages don't mention that PTHREAD_MUTEX_INITIALIZER may leak memory
X-Send-Pr-Version: www-3.1
X-GNATS-Notify:

>Number:         134376
>Category:       docs
>Synopsis:       pthread(3): pthread manpages don't mention that PTHREAD_MUTEX_INITIALIZER may leak memory
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Fri May 08 19:30:03 UTC 2009
>Closed-Date:    Fri Jul 09 21:52:32 UTC 2010
>Last-Modified:  Fri Jul 09 21:52:32 UTC 2010
>Originator:     Trk 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@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:
State-Changed-From-To: open->closed 
State-Changed-By: bcr 
State-Changed-When: Fri Jul 9 21:41:37 UTC 2010 
State-Changed-Why:  
I talked with das@ about this issue. According to him, the pthread man page 
is currently not written with the goal of teaching people how to use pthreads. 
The addition you're proposing would be a little out of place, perhaps a  
good book about that subject would be a better way to gain such knowledge. 
If anyone is willing to write much more detailed man pages on pthreads, we 
would be glad for this contribution. But as far as this PR is concerned, 
we agree that it would be best to close it for now. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=134376 
>Unformatted:
