May 26, 2008 PTHREAD_COND_WAIT 3

### NAME

pthread_cond_wait, pthread_cond_timedwait - wait on a condition variable

### LIBRARY

POSIX Thread Library (libpthread, -lpthread)

### SYNOPSIS

```int` pthread_cond_wait(```pthread_cond_t * restrict cond``, pthread_mutex_t * restrict mutex`)
```int` pthread_cond_timedwait(```pthread_cond_t * restrict cond``, pthread_mutex_t * restrict mutex``, const struct timespec * restrict abstime`)

### DESCRIPTION

The pthread_cond_wait(``) function atomically blocks the current thread waiting on the condition variable specified by ```cond`, and unblocks the mutex specified by ```mutex`. The waiting thread unblocks after another thread calls pthread_cond_signal(3), or pthread_cond_broadcast(3) with the same condition variable. The current thread holds the lock on ```mutex` upon return from the ```pthread_cond_wait` call.

The pthread_cond_timedwait(``) function atomically blocks the current thread waiting on the condition variable specified by ```cond`, and unblocks the mutex specified by ```mutex`. The waiting thread unblocks after another thread calls pthread_cond_signal(3), or pthread_cond_broadcast(3) with the same condition variable, or if the system time reaches the time specified in ```abstime`.

Note that a call to pthread_cond_wait(``) or pthread_cond_timedwait(``) may wake up spontaneously, without a call to pthread_cond_signal(3) or pthread_cond_broadcast(3). The caller should prepare for this by invoking pthread_cond_wait(``) or pthread_cond_timedwait(``) within a predicate loop that tests whether the thread should proceed.

When calling pthread_cond_wait(``) or pthread_cond_timedwait(``), a temporary binding is established between the condition variable ```cond` and the mutex ```mutex`.

The same mutex must be held while calling pthread_cond_broadcast(``) and pthread_cond_signal(``) on ```cond`. Additionally, the same mutex must be used for concurrent calls to pthread_cond_wait(``) and pthread_cond_timedwait(``). Only when a condition variable is known to be quiescent may an application change the mutex associated with it. In this implementation, none of the functions enforce this requirement, but if the mutex is not held or independent mutexes are used the resulting behaviour is undefined.

### RETURN VALUES

If successful, the pthread_cond_wait(``) and pthread_cond_timedwait(``) functions will return zero. Otherwise an error number will be returned to indicate the error.

### ERRORS

pthread_cond_wait(``) may fail if:

[```EINVAL`]
  The value specified by ```cond` or the value specified by ```mutex` is invalid.

pthread_cond_timedwait(``) shall fail if:

[```ETIMEDOUT`]
  The system time has reached or exceeded the time specified in ```abstime`.

pthread_cond_timedwait(``) may fail if:

[```EINVAL`]
  The value specified by ```cond`, ```mutex`, or ```abstime` is invalid.

### SEE ALSO

pthread_cond_broadcast(3), pthread_cond_destroy(3), pthread_cond_init(3), pthread_cond_signal(3)

### STANDARDS

pthread_cond_wait(``) and pthread_cond_timedwait(``) conform to ISO/IEC 9945-1:1996 (``POSIX.1'') .