PTHREAD_COND(3) BSD Programmer's Manual PTHREAD_COND(3)NAME
pthread_cond_init, pthread_cond_destroy, pthread_cond_wait,
pthread_cond_timedwait, pthread_cond_signal, pthread_cond_broadcast - ma-
nipulate pthread condition variables
SYNOPSIS
#include <pthread.h>
#include <time.h>
int
pthread_cond_init(pthread_cond_t *cond, const pthread_condattr_t *attr);
int
pthread_cond_destroy(pthread_cond_t *cond);
int
pthread_cond_wait(pthread_cond_t *cond, pthread_mutex_t *mutex);
int
pthread_cond_timedwait(pthread_cond_t *cond, pthread_mutex_t *mutex,
const struct timespec *abstime);
int
pthread_cond_signal(pthread_cond_t *cond);
int
pthread_cond_broadcast(pthread_cond_t *cond);
pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
DESCRIPTION
This interface is defined by IEEE Std1003.1c (``POSIX'').
The pthread_cond_init() function initializes the condition variable
pointed to by cond with condition attributes specified by attr. If attr
is NULL the default condition attributes are used. All condition vari-
ables should be initialized either statically using
PTHREAD_COND_INITIALIZER or dynamically by calling pthread_cond_init().
After successful initialization, the condition variable is available for
use.
The pthread_cond_destroy() function destroys the condition variable
pointed to by cond, returning it to an uninitialized state. A destroyed
condition variable may be re-initialized by calling pthread_cond_init().
The pthread_cond_wait() function is used to block on a condition vari-
able. It is called with mutex locked by the calling thread. The mutex
is released and the calling thread is blocked atomically waiting for the
associated condition to be signalled by another thread. Upon successful
completion the mutex is re-locked and owned by the calling thread. The
predicate associated with the condition variable should be tested and the
pthread_cond_wait() call repeated if necessary.
The pthread_cond_timedwait() function performs exactly as does
pthread_cond_wait() except that an absolute timeout value is associated
with the call. Upon return (either because the condition was signalled
or because a timeout occurred) the mutex is re-acquired.
The pthread_cond_signal() function unblocks at least one of the threads
currently blocked on cond, if any are available. If more than one thread
is blocked, the scheduling priorities of the blocked threads determine
the order that blocked threads are awakened.
The pthread_cond_broadcast() function unblocks all threads that are cur-
rently blocked on cond.
RETURN VALUES
On success the pthread_cond functions all return a 0. A non-zero result
indicates that an error occurred.
ERRORS
The pthread_cond functions may fail and return one of the following er-
rors:
[EAGAIN] The system lacked the necessary resources (other than memo-
ry) to fulfill the requested operation.
[EBUSY] In a call to pthread_cond_init() an attempt to re-initial-
ize a previously initialized condition variable that had
not been destroyed was detected. In a call to
pthread_cond_destroy() an attempt to destroy a condition
variable that is currently in use was detected.
[EINVAL] The value of a function argument is invalid.
[ENOMEM] Insufficient memory exists to fulfill the requested opera-
tion.
[ETIMEDOUT] In a call to pthread_cond_timedwait() the time specified in
abstime expired before the condition variable was sig-
nalled.
SEE ALSOpthreads(3), pthread_mutex(3), pthread_create(3)STANDARDS
The pthread_cond functions conform to IEEE Std1003.1c (``POSIX'').
HISTORY
The pthread_cond functions first appeared in BSD/OS 3.0.
BUGS
Condition attributes are not supported. The attr argument to
pthread_cond_init() must be passed as NULL.
4th Berkeley Distribution June 3, 1996 2
