pthread_cond_init(3T)

NAME

pthread_cond_init(), pthread_cond_destroy() — initialize or destroy a condition variable.

SYNOPSIS

#include <pthread.h>

int pthread_cond_init( 
   pthread_cond_t *cond, 
   const pthread_condattr_t *attr 
); 

pthread_cond_t cond = PTHREAD_COND_INITIALIZER;

int pthread_cond_destroy( 
   pthread_cond_t *cond 
); 

PARAMETERS

cond: Pointer to the condition variable to be initialized or destroyed.
attr: Pointer to the attributes object that defines the characteristics of the condition variable to be initialized. If the pointer is NULL, default attributes are used.

DESCRIPTION

The pthread_cond_init() function initializes the condition variable cond with the attributes attr. If attr is NULL, the default condition variable attributes are used to initialize the attributes object. Refer to pthread_condattr_init() for a list of the default condition variable attributes. After successful initialization, the condition variable may be used in condition variable operations. A condition variable should be initialized only once or the resulting behavior is undefined. The pthread_once() function provides a way to ensure that a condition variable is only initialized once.

The macro PTHREAD_COND_INITIALIZER can be used to initialize condition variables that are statically allocated. These condition variables will be initialized with default attributes. The pthread_cond_init() function does not need to be called for statically initialized condition variables.

If the process-shared attribute in the condition variable attributes object referenced by attr is defined as PTHREAD_PROCESS_SHARED, the condition variable must be allocated such that the processes sharing the condition variable have access to it. This may be done through the memory-mapping functions (see mmap(2)) or the shared memory functions (see shmget(2)).

pthread_cond_destroy() destroys the condition variable cond. This function may set cond to an invalid value. The destroyed condition variable can be reinitialized using the function pthread_cond_init(). If the condition variable is used after destruction in any condition variable call, the resulting behavior is undefined.

A condition variable should be destroyed only when there are no threads currently blocked on it. Destroying a condition variable that is currently in use results in undefined behavior.

RETURN VALUE

Upon successful completion, pthread_cond_init() and pthread_cond_destroy() return zero. Otherwise, an error number is returned to indicate the error (the errno variable is not set).

ERRORS

If any of the following occur, the pthread_cond_init() function returns the corresponding error number:

[EAGAIN]: The system does not have the available resources (other than memory) to initialize the condition variable.
[ENOMEM]: There is insufficient memory available in which to initialize the condition variable.

For each of the following conditions, if the condition is detected, the pthread_cond_init() function returns the corresponding error number:

[EINVAL]: The value specified by cond or attr is invalid.
[EBUSY]: The specified condition variable is an already initialized condition variable.
[EFAULT]: The cond parameter points to an illegal address.

For each of the following conditions, if the condition is detected, the pthread_cond_destroy() function returns the corresponding error number:

[EINVAL]: cond is not a valid condition variable.
[EBUSY]: An attempt to destroy cond while it is in use by another thread.

WARNINGS

The space for condition variable must be allocated before calling pthread_cond_init(). Undefined behavior will result if the process-shared attribute of attr is PTHREAD_PROCESS_SHARED and the space allocated for the condition variable is not accessible to cooperating threads.

AUTHOR

pthread_cond_init() and pthread_cond_destroy() were derived from the IEEE POSIX P1003.1c standard.

STANDARDS CONFORMANCE

pthread_cond_init(): POSIX 1003.1c.
pthread_cond_destroy(): POSIX 1003.1c.