From nobody@FreeBSD.org  Mon Nov  1 18:25:38 2004
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 3FCDD16A4CE
	for <freebsd-gnats-submit@FreeBSD.org>; Mon,  1 Nov 2004 18:25:38 +0000 (GMT)
Received: from www.freebsd.org (www.freebsd.org [216.136.204.117])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 13FC643D41
	for <freebsd-gnats-submit@FreeBSD.org>; Mon,  1 Nov 2004 18:25:38 +0000 (GMT)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (localhost [127.0.0.1])
	by www.freebsd.org (8.12.11/8.12.11) with ESMTP id iA1IPbXd036253
	for <freebsd-gnats-submit@FreeBSD.org>; Mon, 1 Nov 2004 18:25:37 GMT
	(envelope-from nobody@www.freebsd.org)
Received: (from nobody@localhost)
	by www.freebsd.org (8.12.11/8.12.11/Submit) id iA1IPads036140;
	Mon, 1 Nov 2004 18:25:36 GMT
	(envelope-from nobody)
Message-Id: <200411011825.iA1IPads036140@www.freebsd.org>
Date: Mon, 1 Nov 2004 18:25:36 GMT
From: Thomas Ludwig <tludwig@smr.ch>
To: freebsd-gnats-submit@FreeBSD.org
Subject: manpage of pthread_mutex_lock does not mention EBUSY (libpthread)
X-Send-Pr-Version: www-2.3

>Number:         73387
>Category:       docs
>Synopsis:       manpage of pthread_mutex_lock does not mention EBUSY (libpthread)
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    trhodes
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          sw-bug
>Submitter-Id:   current-users
>Arrival-Date:   Mon Nov 01 18:30:38 GMT 2004
>Closed-Date:    Tue Feb 08 20:23:48 GMT 2005
>Last-Modified:  Fri Jan 27 16:30:03 GMT 2006
>Originator:     Thomas Ludwig
>Release:        RELENG_5
>Organization:
SMR Engineering & Development
>Environment:
FreeBSD pingu.smr-internal.ch 5.3-STABLE FreeBSD 5.3-STABLE #1: Mon Nov  1 18:19:35 CET 2004 root@pingu.smr-internal.ch:/usr/obj/usr/src/sys/PINGU i386
>Description:
The manpage of pthread_mutex_lock mentions EINVAL and EDEADLK as possible error codes, but not EBUSY.  However, threads not owning the mutex will get EBUSY when compiled with -lpthread:

from src/lib/libpthread/thread/thr_mutex.c:

        /* case PTHREAD_MUTEX_DEFAULT: */
        case PTHREAD_MUTEX_ERRORCHECK:
        case PTHREAD_MUTEX_NORMAL:
                /*
                 * POSIX specifies that mutexes should return EDEADLK if a 
                 * recursive lock is detected.
                 */
                if (m->m_owner == curthread)
                        ret = EDEADLK;
                else
                        ret = EBUSY;
                break;

>How-To-Repeat:
Compile and execute the following program:

#include <sys/types.h>

#include <pthread.h>
#include <stdio.h>
#include <stdlib.h>

pthread_mutex_t mutex;

void
trylock(const char* tname)
{
    int rc;

    rc = pthread_mutex_trylock(&mutex);
    if (rc != 0) 
        fprintf(stderr, "%s: Could not lock mutex again: %s\n", 
                tname, strerror(rc));
    else {
        fprintf(stderr, "Could lock mutex again!");
        exit(1);
    }
}

void*
start(void* data)
{
    /* try to lock the mutex again */
    trylock("Second thread");
}

int
main(int argc, const char* argv[])
{
    pthread_t       thread;
    int             rc;

    /* create a mutex and acquire a lock on it for the main thread */
    if (pthread_mutex_init(&mutex, NULL) != 0) {
        perror("Could not initialize mutex");
        exit(1);
    }
    if (pthread_mutex_lock(&mutex) != 0) {
        perror("Could not lock mutex");
        exit(1);
    }

    /* spawn a second thread */
    if (pthread_create(&thread, NULL, start, NULL) != 0) {
        perror("Could not create thread");
        exit(1);
    }
    
    /* try to lock the mutex again */
    trylock("Main thread");

    if (pthread_join(thread, NULL) != 0)  {
        perror("Could not join threads");
        exit(1);
    }

    exit(0);
}

>Fix:
Something like this:

--- /usr/src/share/man/man3/pthread_mutex_lock.3        Thu Jan 15 16:59:00 2004
+++ /tmp/pthread_mutex_lock.3   Mon Nov  1 19:19:54 2004
@@ -62,8 +62,11 @@
 The value specified by
 .Fa mutex
 is invalid.
+.It Bq Er EBUSY
+.Fa mutex 
+is locked by another thread.
 .It Bq Er EDEADLK
-A deadlock would occur if the thread blocked waiting for
+Attempt to recursively lock 
 .Fa mutex .
 .El
 .Sh SEE ALSO

>Release-Note:
>Audit-Trail:
Responsible-Changed-From-To: freebsd-bugs->freebsd-doc 
Responsible-Changed-By: linimon 
Responsible-Changed-When: Mon Nov 1 19:58:45 GMT 2004 
Responsible-Changed-Why:  
Man pages are docs PRs. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=73387 
State-Changed-From-To: open->closed 
State-Changed-By: trhodes 
State-Changed-When: Tue Feb 8 20:22:31 GMT 2005 
State-Changed-Why:  
Slightly modified version of your patch applied to avoid 
starting a sentence with an uncapitalised word. 

Thanks for the submission. 


Responsible-Changed-From-To: freebsd-doc->trhodes 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Tue Feb 8 20:22:31 GMT 2005 
Responsible-Changed-Why:  
Over to me. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=73387 

From: mistral@imasy.or.jp (Yoshihiko Sarumaru)
To: bug-followup@FreeBSD.org
Cc: tludwig@smr.ch, trhodes@FreeBSD.org
Subject: Re: docs/73387: manpage of pthread_mutex_lock does not mention EBUSY
	 (libpthread)
Date: Sat, 28 Jan 2006 00:57:06 +0900

 Hi,
 
 This is a already closed PR on a year ago, but I found it today.
 http://www.freebsd.org/cgi/query-pr.cgi?pr=73387
 
 The pthread_mutex_lock(3) tells me that it can return with EBUSY.
 But I beleive that pthread_mutex_lock() never returned with
 EBUSY, because it must keep blocking until the mutex will be
 unlocked. In the DESCRIPTION section, it was clearly described.
 If it returns with EBUSY, it is not a document bug, but the
 implementation is wrong.
 
 In the test code that PR originator attached, the function that
 returns EBUSY is not pthread_mutex_lock() but pthread_mutex_trylock().
 It is very reasonable that pthread_mutex_trylock() returns EBUSY
 while other pthread_mutex_lock() or pthread_mutex_trylock() is
 locking that mutex, but pthread_mutex_trylock() and
 pthread_mutex_lock() are different. 
 
 In addtion, SUSv3 does not saying that pthread_mutex_lock()
 returns EBUSY.
 
 Thanks,
 
 -- 
 sarumaru
>Unformatted:
