NAME
pthread_mutex —
mutual exclusion
primitives
LIBRARY
POSIX Threads Library (libpthread, -lpthread)
SYNOPSIS
#include <pthread.h>
int
pthread_mutex_init(
pthread_mutex_t
* restrict mutex,
const
pthread_mutexattr_t * restrict attr);
pthread_mutex_t mutex =
PTHREAD_MUTEX_INITIALIZER
;
int
pthread_mutex_destroy(
pthread_mutex_t
*mutex);
int
pthread_mutex_lock(
pthread_mutex_t
*mutex);
int
pthread_mutex_trylock(
pthread_mutex_t
*mutex);
int
pthread_mutex_unlock(
pthread_mutex_t
*mutex);
int
pthread_mutex_timedlock(
pthread_mutex_t
*__restrict mutex,
const
struct timespec *__restrict timeout);
int
pthread_mutex_getprioceiling(
const
pthread_mutex_t * __restrict mutex,
int * __restrict
prioceiling);
int
pthread_mutex_setprioceiling(
pthread_mutex_t
* __restrict mutex,
int
prioceiling,
int *
__restrict old_ceiling);
DESCRIPTION
The
pthread_mutex_init() function creates a new mutex, with
attributes specified with
attr. If
attr is
NULL
, the default
attributes are used.
The macro
PTHREAD_MUTEX_INITIALIZER
can be used to
initialize a mutex when the default attributes are appropriate and the mutex
can be statically allocated. The behavior is similar to
pthread_mutex_init() with
attr
specified as
NULL
, except that no error checking is
done.
The
pthread_mutex_destroy() function frees the resources
allocated for
mutex. It is possible to reinitialize a
destroyed mutex, but undefined behavior may follow if the destroyed object is
otherwise referenced.
The
pthread_mutex_lock() function locks
mutex. If the mutex is already locked, the calling
thread will block until the mutex becomes available. The error conditions may
vary depending on the type of the mutex; see
pthread_mutexattr(3)
for additional details.
The
pthread_mutex_trylock() function locks
mutex. If the mutex is already locked,
pthread_mutex_trylock() will not block waiting for the
mutex, but will return an error condition.
The
pthread_mutex_unlock() function unlocks an acquired
mutex. When operating with the default mutex type,
undefined behavior follows if a thread tries to unlock a mutex that has not
been locked by it, or if a thread tries to release a mutex that is already
unlocked.
The
pthread_mutex_timedlock() function shall lock the mutex
object referenced by
mutex. If the mutex is already
locked, the calling thread shall block until the mutex becomes available in
the
pthread_mutex_lock() function. If the mutex cannot be
locked without waiting for another thread to unlock the mutex, this wait shall
be terminated when the specified timeout expires. The timeout shall expire
when the absolute time specified by
timeout passes, as
measured by the clock on which timeouts are based.
The
pthread_mutex_getprioceiling() function shall return the
current priority ceiling of the mutex.
The
pthread_mutex_setprioceiling() function shall either lock
the mutex if it is unlocked, or block until it can sucessfully lock the mutex,
then it shall change the mutex's priority ceiling and release the mutex. When
the change is successful, the previous value of the priority ceiling shall be
returned in
old_ceiling. The process of locking the
mutex need not adhere to the priority protect protocol. If
pthread_mutex_setprioceiling() function fails, the mutex
priority ceiling shall not be changed.
RETURN VALUES
Upon success all described functions return zero. Otherwise, an error number
will be returned to indicate the error.
ERRORS
pthread_mutex_init() may fail if:
-
-
- [
EAGAIN
]
- The system lacks the resources to initialize another
mutex.
-
-
- [
EINVAL
]
- The value specified by attr is
invalid.
-
-
- [
ENOMEM
]
- The process cannot allocate enough memory to initialize
another mutex.
pthread_mutex_destroy() may fail if:
-
-
- [
EBUSY
]
- Mutex is locked by another
thread.
-
-
- [
EINVAL
]
- The value specified by mutex is
invalid.
pthread_mutex_lock() may fail if:
-
-
- [
EDEADLK
]
- A deadlock would occur if the thread blocked waiting for
mutex.
-
-
- [
EINVAL
]
- The value specified by mutex is
invalid.
pthread_mutex_trylock() may fail if:
-
-
- [
EBUSY
]
- Mutex is already locked.
-
-
- [
EINVAL
]
- The value specified by mutex is
invalid.
pthread_mutex_unlock() may fail if:
-
-
- [
EINVAL
]
- The value specified by mutex is
invalid.
-
-
- [
EPERM
]
- The current thread does not hold a lock on
mutex.
pthread_mutex_timedlock() may fail if:
-
-
- [
EINVAL
]
- The mutex was created with the protocol attribute having
the value
PTHREAD_PRIO_PROTECT
and the calling
thread's priority is higher than the mutex current priority ceiling; or
the process or thread would have blocked, and the
timeout parameter specified a nanoseconds field
value less than zero or greater than or equal to 1000 million.
-
-
- [
ETIMEDOUT
]
- The mutex could not be locked before the specified timeout
expired.
The
pthread_mutex_getprioceiling() and
pthread_mutex_setprioceiling() functions may fail if:
-
-
- [
EINVAL
]
- The priority requested by prioceiling
is out of range; or the value specified by mutex
does not refer to a currently existing mutex.
-
-
- [
EPERM
]
- The caller does not have the privilege to perform the
operation.
SEE ALSO
pthread(3),
pthread_barrier(3),
pthread_cond(3),
pthread_mutexattr(3),
pthread_rwlock(3),
pthread_spin(3)
STANDARDS
These functions conform to
IEEE Std 1003.1-2001
(“POSIX.1”).