Bug 73387 - manpage of pthread_mutex_lock does not mention EBUSY (libpthread)
Summary: manpage of pthread_mutex_lock does not mention EBUSY (libpthread)
Status: Closed FIXED
Alias: None
Product: Documentation
Classification: Unclassified
Component: Books & Articles (show other bugs)
Version: Latest
Hardware: Any Any
: Normal Affects Only Me
Assignee: Tom Rhodes
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2004-11-01 18:30 UTC by Thomas Ludwig
Modified: 2006-01-27 16:30 UTC (History)
0 users

See Also:


Attachments
file.diff (402 bytes, patch)
2004-11-01 18:30 UTC, Thomas Ludwig
no flags Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description Thomas Ludwig 2004-11-01 18:30:38 UTC
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;

Fix: Something like this:
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);
}
Comment 1 Mark Linimon freebsd_committer freebsd_triage 2004-11-01 19:58:45 UTC
Responsible Changed
From-To: freebsd-bugs->freebsd-doc

Man pages are docs PRs.
Comment 2 Tom Rhodes freebsd_committer freebsd_triage 2005-02-08 20:22:31 UTC
State Changed
From-To: open->closed

Slightly modified version of your patch applied to avoid 
starting a sentence with an uncapitalised word. 

Thanks for the submission. 


Comment 3 Tom Rhodes freebsd_committer freebsd_triage 2005-02-08 20:22:31 UTC
Responsible Changed
From-To: freebsd-doc->trhodes

Over to me.
Comment 4 Yoshihiko Sarumaru 2006-01-27 15:57:06 UTC
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