pthread_mutex_lock(3pthread)

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

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

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

Diagnostics

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

Standards Compliance

References