pthread_mutex_init(3C) pthread_mutex_init(3C)
NAME
pthread_mutex_init, pthread_mutex_destroy - initialize or destroy a mutex
SYNOPSIS
cc -mt [ flag... ] file... -lpthread [ library... ]
#include <pthread.h>
int pthread_mutex_init(pthread_mutex_t *restrict mutex, const pthread_mutexattr_t *restrict attr);
int pthread_mutex_destroy(pthread_mutex_t *mutex);
pthread_mutex_t mutex= PTHREAD_MUTEX_INITIALIZER
The pthread_mutex_init() function initializes the mutex referenced by mutex with attributes specified by attr. If attr is NULL, the
default mutex attributes are used; the effect is the same as passing the address of a default mutex attributes object. Upon successful ini-
tialization, the state of the mutex becomes initialized and unlocked.
Attempting to initialize an already initialized mutex results in undefined behavior.
The pthread_mutex_destroy() function destroys the mutex object referenced by mutex; the mutex object becomes, in effect, uninitialized. A
destroyed mutex object can be re-initialized using pthread_mutex_init(); the results of otherwise referencing the object after it has been
destroyed are undefined.
It is safe to destroy an initialized mutex that is unlocked. Attempting to destroy a locked mutex results in undefined behavior.
In cases where default mutex attributes are appropriate, the macro PTHREAD_MUTEX_INITIALIZER can be used to initialize mutexes that are
statically allocated. The effect is equivalent to dynamic initialization by a call to pthread_mutex_init() with parameter attr specified as
NULL, except that no error checks are performed.
If successful, the pthread_mutex_init() and pthread_mutex_destroy() functions return 0. Otherwise, an error number is returned to indicate
the error.
The pthread_mutex_init() function will fail if:
EAGAIN The system lacked the necessary resources (other than memory) to initialize another mutex.
EBUSY An attempt was detected to re-initialize the object referenced by mutex, a robust mutex previously initialized but not
yet destroyed.
EINVAL The value specified by attr has not been initialized using pthread_mutexattr_init(3C).
EINVAL An attempt was made to initialize mutex to be robust and not PTHREAD_PRIO_INHERIT.
EINVAL An attempt was made to initalize mutex to be PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT and the type of the mutex to be
PTHREAD_MUTEX_ERRORCHECK or PTHREAD_MUTEX_RECURSIVE.
EINVAL An attpemt was made to initalize mutex to be PTHREAD_PROCESS_SHARED and the type of the mutex to be PTHREAD_MUTEX_RECUR-
SIVE.
EINVAL The process-shared attribute associated with attr is invalid.
ENOMEM Insufficient memory exists to initialize the mutex.
EPERM The caller does not have the privilege to perform the operation.
The pthread_mutex_init() function may fail if:
EBUSY An attempt was detected to re-initialize the object referenced by mutex, a mutex previously initialized but not yet
destroyed.
EINVAL The value specified by attr or mutex is invalid.
The pthread_mutex_destroy() function may fail if:
EBUSY An attempt was detected to destroy the object referenced by mutex while it is locked or referenced (for example, while
being used in a pthread_cond_wait(3C) or pthread_cond_timedwait(3C)) by another thread.
EINVAL The value specified by mutex is invalid.
See attributes(5) for descriptions of the following attributes:
+-----------------------------+-----------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+-----------------------------+-----------------------------+
|Interface Stability |Standard |
+-----------------------------+-----------------------------+
|MT-Level |MT-Safe |
+-----------------------------+-----------------------------+
pthread_cond_timedwait(3C), pthread_cond_wait(3C), pthread_mutex_getprioceiling(3C), pthread_mutex_lock(3C), pthread_mutex_unlock(3C),
pthread_mutex_setprioceiling(3C), pthread_mutex_trylock(3C), pthread_mutexattr_init(3C), pthread_mutexattr_getpshared(3C), pthread_mutex-
attr_setpshared(3C) attributes(5), mutex(5), standards(5)
23 Mar 2005 pthread_mutex_init(3C)