pthread_mutex_init() — Initialize a mutex object


Standards / Extensions C or C++ Dependencies
Single UNIX Specification, Version 3


#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.

If unsuccessful, pthread_mutex_init() returns -1 and sets errno to one of the following values:
Error Code
The system lacked the necessary resources (other than memory) to initialize another mutex.
detected an attempt to re-initialize the object referenced by mutex, a previously initialized, but not yet destroyed, mutex.
The value specified by attr is not valid.
There is not enough memory to acquire a lock. This errno will only occur in the private path.
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.

The following sequence may cause storage overlay with unpredictable results:
  1. 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.
  2. 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:
    1. pthread_mutexattr_init()
    2. 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.
    3. pthread_mutex_init(). This step initializes the passed-in (small) pthread_mutex_t object as if it is an extended object, causing storage overlay.


/* CELEBP37 */                                   
#ifndef _OPEN_THREADS                                                           
#define _OPEN_THREADS                                                           
#include <pthread.h>                                                            
main() {                                                                        
  pthread_mutexattr_t     attr;                                                 
  pthread_mutex_t         mut;                                                  
  if (pthread_mutexattr_init(&attr) == -1) {                                    
    perror("mutexattr_init error");                                             
  if (pthread_mutex_init(&mut, &attr) == -1) {                                  
    perror("mutex_init error");                                                 

Related information