pthread_mutex_lock(3pthread)


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

Synopsis

   cc [options] -Kthread file
   

#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);

Description

pthread_mutex_lock locks the mutual exclusion lock (mutex) pointed to by mutex. If mutex is already locked, the calling thread is blocked until mutex becomes available. When pthread_mutex_lock returns successfully, the caller has locked mutex.

If a signal is delivered to a thread waiting for a mutex, upon return from the signal handler the thread resumes waiting for the mutex as if it was not interrupted.

From the point of view of the caller, pthread_mutex_lock is atomic: even if interrupted by a signal or fork (see fork(2)), pthread_mutex_lock will not return until it holds the locked mutex. As a consequence, if pthread_mutex_lock is interrupted, an error indication such as EINTR is never returned to the caller.

pthread_mutex_trylock is used when the caller does not want to block. pthread_mutex_trylock attempts once to lock mutex. If mutex is available, pthread_mutex_trylock will return successfully with mutex locked. If mutex is already locked, pthread_mutex_trylock immediately returns EBUSY to the caller without acquiring mutex or blocking.

The function pthread_mutex_trylock is identical to pthread_mutex_lock except that if mutex is currently locked (by any thread, including the current thread), the call returns immediately.

The manner in which mutex is released is dependent upon its type attribute. If there are threads blocked on mutex when pthread_mutex_unlock is called, resulting in mutex becoming available, the scheduling policy is used to determine which thread shall acquire it. (In the case of PTHREAD_MUTEX_RECURSIVE mutexes, mutex becomes available when the count reaches zero and the calling thread no longer has any locks on mutex).

Mutex types

The type of mutex is contained in the type attribute of the mutex attributes. Valid mutex types include the following:

PTHREAD_MUTEX_NORMAL
If the mutex type is PTHREAD_MUTEX_NORMAL, deadlock detection is not provided. Attempting to relock mutex causes deadlock. If a thread attempts to unlock a mutex that it has not locked or a mutex which is unlocked, undefined behavior results.

PTHREAD_MUTEX_ERRORCHECK
If the mutex type is PTHREAD_MUTEX_ERRORCHECK, then error checking is provided. If a thread attempts to relock a mutex that it has already locked, an error will be returned. If a thread attempts to unlock a mutex that it has not locked or a mutex which is unlocked, an error will be returned.

PTHREAD_MUTEX_RECURSIVE
If the mutex type is PTHREAD_MUTEX_RECURSIVE, then mutex maintains the concept of a lock count. When a thread successfully acquires a mutex for the first time, the lock count is set o one. Every time a thread relocks this mutex, the lock count is incremented by one. Each time the thread unlocks the mutex, the lock count is decremented by one. When the lock count reaches zero, the mutex becomes available for other threads to acquire. If a thread attempts to unlock a mutex that it has not locked or a mutex which is unlocked, an error will be returned.

PTHREAD_MUTEX_DEFAULT
If the mutex type is PTHREAD_MUTEX_DEFAULT, attempting to recursively lock mutex results in undefined behavior. Attempting to unlock mutex if it was not locked by the calling thread results in undefined behavior. Attempting to unlock mutex if it is not locked results in undefined behavior.

The mutex parameter is a pointer to the mutex to be locked or unlocked. mutex must previously have been initialized, either by pthread_mutex_init, or statically (see pthread_mutex_init(3pthread)).

Mutexes acquired with pthread_mutex_lock or pthread_mutex_trylock should be released with pthread_mutex_unlock.

Return values

pthread_mutex_lock, pthread_mutex_unlock, and pthread_mutex_trylock return zero for success and an error number for failure.

Diagnostics

pthread_mutex_lock, pthread_mutex_trylock, and pthread_mutex_unlock return the following value if the corresponding condition is detected:

EINVAL
The value specified by mutex does not refer to an initialized mutex object.

EDEADLK
The current thread already owns mutex.

pthread_mutex_trylock returns the following value if the corresponding condition is detected:


EBUSY
mutex could not be acquired because it was already locked.

pthread_mutex_unlock returns the following values if the corresponding conditions are detected:


EPERM
The current thread does not own mutex.

Warnings

If a thread exits while holding a mutex, the mutex will not be unlocked, and other threads waiting for it will wait forever.

Standards Compliance

The Single UNIX Specification, Version 2; The Open Group.

References

Intro(3pthread), fork(2), pthread_mutex_destroy(3pthread), pthread_mutex_init(3pthread), pthread(4)
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004