Use pthread_cond_wait(3THR) to atomically release the mutex pointed to by mp and to cause the calling thread to block on the condition variable pointed to by cv. (For Solaris threads, see cond_wait(3THR).)
Prototype: int pthread_cond_wait(pthread_cond_t *cv,pthread_mutex_t *mutex);
#include <pthread.h> pthread_cond_t cv; pthread_mutex_t mp; int ret; /* wait on condition variable */ ret = pthread_cond_wait(&cv, &mp);
Any change in the value of a condition associated with the condition variable cannot be inferred by the return of pthread_cond_wait(), and any such condition must be reevaluated.
The pthread_cond_wait() routine always returns with the mutex locked and owned by the calling thread, even when returning an error.
This function blocks until the condition is signaled. It atomically releases the associated mutex lock before blocking, and atomically acquires it again before returning.
In typical use, a condition expression is evaluated under the protection of a mutex lock. When the condition expression is false, the thread blocks on the condition variable. The condition variable is then signaled by another thread when it changes the condition value. This causes one or all of the threads waiting on the condition to unblock and to try to acquire the mutex lock again.
Because the condition can change before an awakened thread reacquires the mutes and returns from pthread_cond_wait(), and because a waiting thread can be awakened spuriously, the condition that caused the wait must be retested before continuing execution from the point of the pthread_cond_wait(). The recommended test method is to write the condition check as a while() loop that calls pthread_cond_wait().
pthread_mutex_lock(); while(condition_is_false) pthread_cond_wait(); pthread_mutex_unlock();
No specific order of acquisition is guaranteed when more than one thread blocks on the condition variable.
pthread_cond_wait() is a cancellation point. If a cancel is pending and the calling thread has cancellation enabled, the thread terminates and begins executing its cleanup handlers while continuing to hold the lock.
pthread_cond_wait() returns zero after completing successfully. Any other return value indicates that an error occurred. When the following condition occurs, the function fails and returns the corresponding value.