pthread_cond_wait(3T)													     pthread_cond_wait(3T)

NAME

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

SYNOPSIS


   Parameters
       cond	 Pointer to the condition variable to be waited on.

       mutex	 Pointer to the mutex associated with the condition variable cond.

       abstime	 Absolute time at which the wait expires, even if the condition has not been signaled or broadcast.

DESCRIPTION

       The function is used to wait for the occurrence of a condition associated with the condition variable cond.

       The  function  is used to wait a limited amount of time for the occurrence of a condition associated with the condition variable cond.  The
       abstime parameter specifies the time at which this function should time out.  If the absolute time specified  by  abstime  passes  and  the
       indicated condition has not been signaled, the function returns an error to the caller.

       Note: abstime is the time at which the wait expires, not the length of time the thread will wait.

       The condition variabled denoted by cond must have been dynamically initialized by a call to or statically initialized with the macro

       Both  functions should be called with mutex locked by the calling thread.  If mutex is not locked by the calling thread, undefined behavior
       will result.  These functions atomically release mutex and cause the calling thread to block on the condition variable  cond.   If  another
       thread  is  able to acquire the mutex after the about-to-block thread has released it but before it has actually blocked, a subsequent call
       to or by the other thread will behave as if it were issued after the about-to-block thread has blocked.

       When the condition is signaled or the timed wait expires, the caller is unblocked and will reacquire mutex before returning.  Whether these
       functions succeed or fail, mutex will always be reacquired before returning to the caller.

       Using different mutexes for concurrent calls to these functions on the same condition variable results in undefined behavior.

       When  using  condition  variables,  there is a predicate associated with the condition wait.  If this predicate is false, the thread should
       perform a condition wait.  Spurious wakeups may occur when waiting on a condition variable.  A spurious wakeup occurs when a thread returns
       from a condition wait when it should really continue waiting.  A normal signal being delivered to a thread may cause a spurious wakeup dur-
       ing a condition wait.  Since the return values from and do not imply anything about the value of the predicate, the predicate should be re-
       evaluated.

       A condition wait is a When the calling thread has deferred cancellation enabled, cancellation requested will be acted upon.  If a cancella-
       tion request is acted upon while a thread is blocked in one of these functions, mutex is reacquired before calling the cancellation cleanup
       handlers.  The cancellation cleanup handlers should release mutex so that application deadlock does not occur.  If the condition signal and
       the cancellation request both occur, the canceled thread will not consume the condition signal (i.e., a different thread will be  unblocked
       due to the condition signal).

       If  a signal is delivered to a thread waiting for a condition variable, upon return from the signal handler, the thread may return zero due
       to a spurious wakeup or continue waiting for the condition.

RETURN VALUE

       and return the following values:

	      Successful completion.

	      Failure.
		     An error number is returned to indicate the error.  (The variable is not set.)

ERRORS

       The following error value is returned by if the corresponding condition is detected.

       abstime		   has passed and a condition signal has not been received.

       One of the following error values is returned by and if the corresponding condition is detected.

       A		   cond, mutex, or abstime parameter points to an illegal address.

       The value specified by
			   cond, mutex, or abstime is invalid.

			   mutex is not owned by the calling thread.  This error is not returned for a or mutex on HP-UX.

       Different mutexes are being used for
			   cond.  This error is not detected on HP-UX.

WARNINGS

       It is important to note that when or return without error, the associated predicate may still be false.	 When  returns	with  the  timeout
       error,  the  associated	predicate  may	be true.  It is recommended that a condition wait be enclosed in the equivalent of a "while loop,"
       which checks the predicate.

       Undefined behavior results if these functions are called with a mutex.

EXAMPLES

       is recommended to be used in a loop testing the predicate associated with it.  This will take care of any spurious wakeups that may occur.

       is also recommended to be used in a loop.  This function can return success even if the predicate is not true.  It should be  called  in  a
       loop  while  checking the predicate.  If the function times out, the predicate may still have become true.  The predicate should be checked
       before processing the timeout case.  The example given below does not do any other error checking.

AUTHOR

       and were derived from the IEEE POSIX P1003.1c standard.

SEE ALSO

       pthread_cond_init(3T), pthread_cond_signal(3T).

STANDARDS CONFORMANCE

								  Pthread Library					     pthread_cond_wait(3T)