pthread_mutex_lock.3t (2010 09)

p
pthread_mutex_lock(3T) pthread_mutex_lock(3T)
(Pthread Library)
NAME
pthread_mutex_lock(), pthread_mutex_trylock() - lock or attempt to lock a mutex
SYNOPSIS
#include <pthread.h>
int pthread_mutex_lock(
pthread_mutex_t *mutex
);
int pthread_mutex_trylock(
pthread_mutex_t *mutex
);
PARAMETERS
mutex Pointer to the mutex to be locked.
DESCRIPTION
The mutex object mutex is locked by calling the
pthread_mutex_lock()
function. How the calling
thread acquires the mutex is dependent upon the type attribute for the mutex. This operation returns
with the mutex object referenced by mutex in the locked state with the calling thread as its owner.
If the mutex type is
PTHREAD_MUTEX_NORMAL
, deadlock detection is not provided. Attempting to
relock the 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.
If the mutex type is
PTHREAD_MUTEX_ERRORCHECK
, the mutex maintains the concept of an owner. If a
thread attempts to relock a mutex that it has already locked, an error shall be returned. If a thread
attempts to unlock a mutex that it has not locked or a mutex that is unlocked, an error shall be returned.
If the mutex type is
PTHREAD_MUTEX_RECURSIVE
, then the mutex maintains the concept of an owner
and a lock count. When a thread successfully acquires a mutex for the first time, the count field shall be
set to one. Every time a thread relocks this mutex, the count field shall be incremented by one. Each
time the thread unlocks the mutex, the count field shall be decremented by one. When the count field
reaches zero, the mutex shall become available for other threads to acquire. If a thread attempts to
unlock a mutex that it has not locked, an error shall be returned.
If the mutex type is
PTHREAD_MUTEX_NO_OWNER_NP
, deadlock detection is not provided. Attempting
to relock the mutex causes deadlock. A thread can unlock a mutex that it has not locked. Attempting to
unlock an unlocked mutex results in undefined behavior.
If the mutex type is
PTHREAD_MUTEX_DEFAULT
, attempting to recursively lock the mutex results in
undefined behavior. Attempting to unlock the mutex if it was not locked by the calling thread results in
undefined behavior. Attempting to unlocked the mutex if it is not locked results in undefined behavior.
The function
pthread_mutex_trylock()
is identical to the pthread_mutex_lock() function
except that if the mutex object referenced by mutex cannot be acquired after one attempt, the call returns
immediately with an error.
If a signal is delivered to a thread waiting for a mutex, upon return from the signal handler, the thread
shall resume waiting for the mutex as if it was not interrupted.
RETURN VALUE
Upon successful completion,
pthread_mutex_lock() and pthread_mutex_trylock()
return
zero. Otherwise, an error number is returned to indicate the error (the
errno variable is not set).
ERRORS
If any of the following occur, the
pthread_mutex_lock() and pthread_mutex_trylock() func-
tions return the corresponding error number:
[EINVAL] mutex is a
PTHREAD_PRIO_PROTECT mutex and the caller’s priority is higher
than mutex ’s priority ceiling.
If any of the following occur, the
pthread_mutex_trylock() function returns the corresponding
error number:
[EBUSY] mutex is currently locked by another thread.
HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1