pthread_cond_wait(2)                               pthread_cond_wait(2)

  pthread_cond_timedwait()

  NAME

    pthread_cond_timedwait(), pthread_cond_wait() - wait on a condition
    variable

  SYNOPSIS

    #include 

    int pthread_cond_timedwait(pthread_cond_t *cond, pthread_mutex_t *mutex,
          const pthread_timespec *abstime);
    int pthread_cond_wait(pthread_cond_t *cond, pthread_mutex_t *mutex);

  DESCRIPTION

    The pthread_cond_wait(2) function unlocks the mutex referenced by mutex
    and blocks the calling thread on the condition variable referenced by
    cond. The pthread_cond_timedwait(2) unlocks mutex and blocks the calling
    thread on cond or until the system clock reaches or passes the absolute
    time referenced by abstime. The calling thread must have locked mutex
    before calling these functions; when the functions return (regardless of
    the reason or error condition), mutex is locked again and owned by the
    calling thread. The cond variable must have been initialized dynamically
    by a call to pthread_cond_init(2) or statically using the
    PTHREAD_COND_INITIALIZER macro.

    The release of mutex and the conditional block occur atomically. That is,
    it is possible for another thread to acquire the mutex after it has been
    released, in which case a subsequent call in that thread to
    pthread_cond_wait() or pthread_cond_timedwait() behaves as though the call
    were issued after the thread that released the mutex had blocked.

    With condition variables, a predicate is associated with the condition
    wait. The thread should continue only when this predicate is true.
    Spurious wakeups can occur when waiting on a condition variable because
    pthread_cond_wait() and pthread_cond_timedwait() can return even when the
    predicate is false. Consequently, each time these functions return, the
    calling thread should evaluate the predicate to determine whether or not
    it should, in fact, continue. Typically, these functions are called inside
    a loop that exits only when the predicate is true.

    Whether timed or not, a condition wait is a cancellation point. When the
    calling thread's cancelability type is set to PTHREAD_CANCEL_DEFERRED, a
    requested cancellation will be acted upon, and the mutex is reacquired
    before the first cancellation cleanup handler is called. The result is the
    same as though the thread were unblocked, allowed to execute up to the
    point of returning from the call to pthread_cond_wait() or
    pthread_cond_timedwait, notices the cancellation request and immediately
    starts the thread cancellation activities, including calling cancellation
    cleanup handlers. The cleanup handlers should release the mutex to prevent
    application deadlock. A thread that is unblocked because it has been
    cancelled should not consume a condition signal it receives for cond in
    case another thread is also blocked on the same condition variable.

  RETURN VALUES

    On success, both functions returns 0; otherwise, an error code is
    returned.

    With the exception of [ETIMEDOUT], the error checks behave as though they
    were performed immediately at the beginning of the function call and so
    cause the functions to return without modifying the state of mutex or
    cond.

  ERRORS

    The pthread_cond_timedwait() function can fail for the following reason:

    [ETIMEDOUT]
        The time specified by abstime has passed.

    Both functions can fail for the following reasons:

    [EINVAL]
        The value of cond, mutex, or abstime is invalid, or cond has been used
        for concurrent calls to pthread_cond_wait() or
        pthread_cond_timedwait() using different mutexes.

    [EPERM]
        The current thread did not own the mutex referenced by mutex when the
        function was called.

    Neither function returns [EINTR].

  SEE ALSO

    pthread_cond_destroy(2)

    pthread_cond_broadcast(2)

    time(2)

  USAGE NOTES

    All of these functions are thread safe.

    None of these functions are async-signal safe.