pthread_mutex_init() — Initialize a mutex object
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
POSIX.4a |
both | POSIX(ON) |
Format
#define _OPEN_THREADS
#include <pthread.h>
int pthread_mutex_init(pthread_mutex_t *mutex, pthread_mutexattr_t *attr);
#define _UNIX03_THREADS
#include <pthread.h>
int pthread_mutex_init(pthread_mutex_t * __restrict__mutex,
const pthread_mutexattr_t * __restrict__attr);
General description
Creates a mutex, referenced by mutex, with attributes specified by attr. If attr is NULL, the default mutex attribute (NONRECURSIVE) is used.
Returned value
If successful, pthread_mutex_init() returns 0, and the state of the mutex becomes initialized and unlocked.
- Error Code
- Description
- EAGAIN
- The system lacked the necessary resources (other than memory) to initialize another mutex.
- EBUSY
- detected an attempt to re-initialize the object referenced by mutex, a previously initialized, but not yet destroyed, mutex.
- EINVAL
- The value specified by attr is not valid.
- ENOMEM
- There is not enough memory to acquire a lock. This errno will only occur in the private path.
- EPERM
- The caller does not have the privilege to perform the operation.
Special behavior for Single UNIX Specification, Version 3: If unsuccessful, pthread_mutex_init() returns an error number to indicate the error.
Usage notes
The _OPEN_SYS_MUTEX_EXT feature switch can be optionally included. If the feature is set, then significantly larger pthread_mutex_t objects will be defined. The feature is used for the management of mutex and condition variables in shared memory.
If the supplied extended pthread_mutex_t object is not in shared memory, pthread_mutex_init() will treat the object as a non-shared object, since it is not accessible to any other process.
It is recommended that you define and initialize the pthread_mutex_t objects in the same compile unit. If you pass a pthread_mutex_t object around to be initialized, make sure the initialization code has been compiled with the same _OPEN_SYS_MUTEX_EXT feature setting as the code that defines the object.
- Declare or define a pthread_mutex_t object (in shared storage) without #define of the _OPEN_SYS_MUTEX_EXT feature. The created pthread_mutex_t object is standard size (i.e. small) without the _OPEN_SYS_MUTEX_EXT feature defined.
- Pass the pthread_mutex_t object to another code unit, which was
compiled with the _OPEN_SYS_MUTEX_EXT feature defined, to be initialized
as a shared object. The pthread_mutex_t initialization generally
involves the following steps:
- pthread_mutexattr_init()
- pthread_mutexattr_setpshared(). Shared pthread_mutex_t objects can be small or of extended size. The presence of the _OPEN_SYS_MUTEX_EXT feature declares it to be of extended size.
- pthread_mutex_init(). This step initializes the passed-in (small) pthread_mutex_t object as if it is an extended object, causing storage overlay.
Example
/* CELEBP37 */
#ifndef _OPEN_THREADS
#define _OPEN_THREADS
#endif
#include <pthread.h>
main() {
pthread_mutexattr_t attr;
pthread_mutex_t mut;
if (pthread_mutexattr_init(&attr) == -1) {
perror("mutexattr_init error");
exit(1);
}
if (pthread_mutex_init(&mut, &attr) == -1) {
perror("mutex_init error");
exit(2);
}
exit(0);
}
Related information
- pthread.h
- pthread_cond_init() — Initialize a condition variable
- pthread_cond_timedwait() — Wait on a condition variable
- pthread_cond_wait() — Wait on a condition variable
- pthread_mutexattr_init() — Initialize a mutex attribute object
- pthread_mutex_lock() — Wait for a lock on a mutex object
- pthread_mutex_trylock() — Attempt to lock a mutex object
- pthread_mutex_unlock() — Unlock a mutex object