pthread_mutex_init() — Initialize a mutex object

Standards

Standards / Extensions	C or C++	Dependencies
POSIX.4a Single UNIX Specification, Version 3	both	POSIX(ON)

Format

#define _OPEN_THREADS
#include <pthread.h>

int pthread_mutex_init(pthread_mutex_t *mutex, pthread_mutexattr_t *attr);

SUSV3:

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

The following sequence may cause storage overlay with unpredictable results:

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

Example

CELEBP37

/* 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);                                                                      
}