pthread_mutex_init or pthread_mutex_destroy Subroutine
Purpose
Initializes or destroys a mutex.
Library
Threads Library (libpthreads.a)
Syntax
#include <pthread.h>
int pthread_mutex_init (mutex, attr)
pthread_mutex_t *mutex;
const pthread_mutexattr_t *attr;
int pthread_mutex_destroy (mutex)
pthread_mutex_t *mutex;
Description
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 initialization, 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. An implementation may cause pthread_mutex_destroy to set the object referenced by mutex to an invalid value. 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.
Parameters
| Item | Description |
|---|---|
| mutex | Specifies the mutex to initialize or delete. |
| attr | Specifies the mutex attributes object. |
Return Values
If successful, the pthread_mutex_init and pthread_mutex_destroy functions return zero. Otherwise, an error number is returned to indicate the error. The EBUSY and EINVAL error checks act as if they were performed immediately at the beginning of processing for the function and cause an error return prior to modifying the state of the mutex specified by mutex.
Error Codes
The pthread_mutex_init function will fail if:
| Item | Description |
|---|---|
| ENOMEM | Insufficient memory exists to initialize the mutex. |
| EINVAL | The value specified by attr is invalid. |
| EPERM | The caller does not have the privilege to perform the operation in a strictly standards conforming environment where environment variable XPG_SUS_ENV=ON. |
The pthread_mutex_destroy function may fail if:
| Item | Description |
|---|---|
| EBUSY | The implementation has detected an attempt to destroy the object referenced by mutex while it is locked or referenced (for example, while being used in a pthread_cond_waitor pthread_cond_timedwait by another thread. |
| EINVAL | The value specified by mutex is invalid. |
These functions will not return an error code of EINTR.