Causes a thread to wait for the specified condition variable to
    be signaled or broadcast.

1  –  C Binding

    #include <pthread.h>

    int
    pthread_cond_wait (
             pthread_cond_t   *cond,
             pthread_mutex_t   *mutex);

2  –  Arguments

 cond

    Condition variable that the calling thread waits on.

 mutex

    Mutex associated with the condition variable specified in cond.

3  –  Description

    This routine causes a thread to wait for the specified condition
    variable to be signaled or broadcast. Each condition corresponds
    to one or more Boolean relations, called a predicate, based on
    shared data. The calling thread waits for the data to reach a
    particular state for the predicate to become true. However, the
    return from this routine does not imply anything about the value
    of the predicate and it should be reevaluated upon return.

    Call this routine after you have locked the mutex specified in
    mutex. The results of this routine are unpredictable if this
    routine is called without first locking the mutex.

    This routine atomically releases the mutex and causes the calling
    thread to wait on the condition. When the thread regains control
    after calling pthread_cond_wait(), the mutex is locked and the
    thread is the owner. This is true regardless of why the wait
    ended. If general cancelability is enabled, the thread reacquires
    the mutex (blocking for it if necessary) before the cleanup
    handlers are run (or before the exception is raised).

    A thread that changes the state of storage protected by the
    mutex in such a way that a predicate associated with a condition
    variable might now be true, must call either pthread_cond_
    signal() or pthread_cond_broadcast()  for that condition
    variable. If neither call is made, any thread waiting on the
    condition variable continues to wait.

    This routine might (with low probability) return when the
    condition variable has not been signaled or broadcast. When
    this occurs, the mutex is reacquired before the routine returns.
    To handle this type of situation, enclose each call to this
    routine in a loop that checks the predicate. The loop provides
    documentation of your intent and protects against these spurious
    wakeups, while also allowing correct behavior even if another
    thread consumes the desired state before the awakened thread
    runs.

    It is illegal for threads to wait on the same condition variable
    by specifying different mutexes.

    The only routines that are supported for use with asynchronous
    cancelability enabled are those that disable asynchronous
    cancelability.

4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by cond or mutex is invalid, or

                Different mutexes are supplied for concurrent
                pthread_cond_wait()  or pthread_cond_timedwait()
                operations on the same condition variable, or

                The mutex was not owned by the calling thread at the
                time of the call.
    [ENOMEM]    The Threads Library cannot acquire memory needed
                to block using a statically initialized condition
                variable.

5  –  Associated Routines

       pthread_cond_broadcast()
       pthread_cond_destroy()
       pthread_cond_init()
       pthread_cond_signal()
       pthread_cond_timedwait()