NAME

    pthread_cond_init - Creates a condition variable

 SYNOPSIS

     #include <pthread.h>

     int pthread_cond_init( pthread_cond_t *cond,
                             pthread_condattr_t attr );

 PARAMETERS

     cond             Condition variable that is created.

     attr             Condition variable attributes object that
                      defines the characteristics of the condition
                      variable created. If you specify
                      pthread_condattr_default, default attributes
                      are used.

 DESCRIPTION

 The pthread_cond_init()  routine creates and initializes a condition
 variable. A condition variable is a synchronization object used in con-
 junction with a mutex. A mutex controls access to shared data; a condi-
 tion variable allows threads to wait for that data to enter a defined
 state. The state is defined by a Boolean expression called a predicate.

 A condition variable is signaled or broadcast to indicate that a predi-
 cate might have become true. The broadcast operation indicates that all
 waiting threads need to resume and reevaluate the predicate. The signal
 operation is used when any one waiting thread can continue.

 If a thread that holds a mutex determines that the shared data is not in
 the correct state for it to proceed (the associated predicate is not
 true), it waits on a condition variable associated with the desired
 state. Waiting on the condition variable automatically releases the
 mutex so that other threads can modify or examine the shared data. When
 a thread modifies the state of the shared data so that a predicate might
 be true, it signals or broadcasts on the appropriate condition variable
 so that threads waiting for that predicate can continue.

 It is important that all threads waiting on a particular condition vari-
 able at any time hold the same mutex. If they do not, the behavior of
 the wait operation is unpredictable (an implementation can use the mutex
 to control internal access to the condition variable object). However,
 it is legal for a client to store condition variables and mutexes and
 later reuse them in different combinations. The client must ensure that
 no threads use the condition variable with the old mutex. At any time,
 an arbitrary number of condition variables can be associated with a sin-
 gle mutex, each representing a different predicate of the shared data
 protected by that mutex.

 Condition variables are not owned by a particular thread. Any associated
 storage is not automatically deallocated when the creating thread ter-
 minates.

 RETURN VALUES

 If the function fails, errno may be set to one of the following values:

    Return   Error      Description
    __________________________________________________
     0                  Successful completion.

    -1      [EAGAIN]    The system lacks the necessary resources
                        to initialize another condition variable.

    -1      [EINVAL]    Invalid attributes object.

    -1      [ENOMEM]    Insufficient memory exists to initialize
                        the condition variable.

 RELATED INFORMATION

      FUNCTIONS: pthread_cond_broadcast
                 pthread_cond_destroy
                 pthread_cond_signal
                 pthread_cond_timedwait
                 pthread_cond_wait