pthread_cond_init() — Initialize a condition variable

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_cond_init(pthread_cond_t *cond, pthread_condattr_t *attr);

SUSV3:

#define _UNIX03_THREADS 
#include <pthread.h>
int pthread_cond_init(pthread_cond_t * __restrict__cond, 
                      pthread_condattr_t * __restrict__attr);

General description

Initializes the condition variable referenced by cond with attributes referenced by attr. If attr is NULL, the default condition variable attributes are used.

Returned value

If successful, pthread_cond_init() returns 0.

If unsuccessful, pthread_cond_init() returns -1 and sets errno to one of the following values:

Error Code: Description
ENOMEM: There is not enough memory to initialize the condition variable.
EAGAIN: The system lacked the necessary resources (other than memory) to initialize another condition variable.
EBUSY: The implementation has detected an attempt to reinitialize the object referenced by cond, a previously initialized, but not yet destroyed, condition variable.
EINVAL: The value specified by attr is invalid.

Special behavior for Single UNIX Specification, Version 3: If unsuccessful, pthread_cond_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_cond_t objects will be defined. The feature is used for the management of mutex and condition variables in shared memory. If the feature switch is set in the define of the condition variables in shared memory, then the same feature switch must be set in the define of the mutex associated with the condition variables.

If the supplied extended pthread_cond_t object is not in shared memory, pthread_cond_init() will treat the object as a non-shared object, since it is not accessible to any other process.

If the _OPEN_SYS_MUTEX_EXT feature switch is set, a shared condition variable is tied to the specified mutex for the life of the condition variable and mutex the very first time a pthread_cond_wait() or pthread_cond_timedwait() is issued. No other mutex can be associated with the specified condition variable or vise versa until the condition variable or mutex is destroyed.

It is recommended that you define and initialize pthread_cond_t objects in the same compile unit. If you pass a pthread_cond_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_cond_t object (in shared storage) without #define of the _OPEN_SYS_MUTEX_EXT feature. The created pthread_cond_t object is standard size (i.e. small) without the _OPEN_SYS_MUTEX_EXT feature defined.
Pass the pthread_cond_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_cond_t initialization generally involves the following steps:
1. pthread_condattr_init()
2. pthread_condattr_setpshared(). This step sets the attribute of the pthread_cond_t as PTHREAD_PROCESS_SHARED and designates the object to be of extended size.
3. pthread_cond_init(). This step initializes the passed-in (small) pthread_cond_t object as if it is an extended object, causing storage overlay.

Example

CELEBP19

⁄* CELEBP19 *⁄                                   
#define _OPEN_THREADS                                                           
#include <pthread.h>                                                            
#include <stdio.h>                                                              
                                                                                
main() {                                                                        
  pthread_cond_t cond;                                                          
                                                                                
  if (pthread_cond_init(&cond, NULL) != 0) {                                    
    perror("pthread_cond_init() error");                                        
    exit(1);                                                                    
  }                                                                             
                                                                                
  if (pthread_cond_destroy(&cond) != 0) {                                       
    perror("pthread_cond_destroy() error");                                     
    exit(2);                                                                    
  }                                                                             
}