Initializes a condition variable.

1  –  C Binding

    #include <pthread.h>

    int
    pthread_cond_init (
             pthread_cond_t   *cond,
             const pthread_condattr_t   *attr);

2  –  Arguments

 cond

    Condition variable to be initialized.

 attr

    Condition variable attributes object that defines the
    characteristics of the condition variable to be initialized.

3  –  Description

    This routine initializes the condition variable cond with
    attributes specified in the attr argument. If attr is NULL, the
    default condition variable attributes are used.

    A condition variable is a synchronization object used in
    conjunction with a mutex. A mutex controls access to data that
    is shared among threads; a condition variable allows threads to
    wait for that data to enter a defined state.

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

    Use the macro PTHREAD_COND_INITIALIZER to initialize statically
    allocated condition variables to the default condition variable
    attributes. To invoke this macro, enter:

       pthread_cond_t condition = PTHREAD_COND_INITIALIZER

    When statically initialized, a condition variable should not also
    be initialized using pthread_cond_init(). Also, a statically
    initialized condition variable need not be destroyed using
    pthread_cond_destroy().

    Under certain circumstances it might be impossible to wait upon
    a statically initialized condition variable when the process
    virtual address space (or some other memory limit) is nearly
    exhausted. In such a case pthread_cond_wait() or pthread_cond_
    timedwait() can return [ENOMEM]. To avoid this possibility,
    initialize critical condition variables using pthread_cond_
    init().

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.
    [EAGAIN]    The system lacks the necessary resources to
                initialize another condition variable, or

                The system-imposed limit on the total number of
                condition variables under execution by a single user
                is exceeded.
    [EBUSY]     The implementation has detected an attempt to
                reinitialize the object referenced by cond, a
                previously initialized, but not yet destroyed
                condition variable.
    [EINVAL]    The value specified by attr is not a valid attributes
                object.
    [ENOMEM]    Insufficient memory exists to initialize the
                condition variable.

5  –  Associated Routines

       pthread_cond_broadcast()
       pthread_cond_destroy()
       pthread_cond_signal()
       pthread_cond_timedwait()
       pthread_cond_wait()