Initializes a mutex.

1  –  C Binding

    #include <pthread.h>

    int
    pthread_mutex_init (
             pthread_mutex_t   *mutex,
             const pthread_mutexattr_t   *attr);

2  –  Arguments

 mutex

    Mutex to be initialized.

 attr

    Mutex attributes object that defines the characteristics of the
    mutex to be initialized.

3  –  Description

    This routine initializes a mutex with the attributes specified
    by the mutex attributes object specified in the attr argument. A
    mutex is a synchronization object that allows multiple threads to
    serialize their access to shared data.

    The mutex is initialized and set to the unlocked state. If attr
    is set to NULL, the default mutex attributes are used. The
    pthread_mutexattr_settype() routine can be used to specify the
    type of mutex that is created (normal, recursive, or errorcheck).

    Use the PTHREAD_MUTEX_INITIALIZER macro to statically initialize
    a mutex without calling this routine. Statically initialized
    mutexes need not be destroyed using pthread_mutex_destroy(). Use
    this macro as follows:

       pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER

    Only normal mutexes can be statically initialized.

    A mutex is a resource of the process, not part of any particular
    thread. A mutex is neither destroyed nor unlocked automatically
    when any thread exits. If a mutex is allocated on a stack, static
    initializers cannot be used on the mutex.

4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error, the mutex is not initialized,
    and the contents of mutex are undefined. Possible return values
    are as follows:

    Return      Description

    0           Successful completion.
    [EAGAIN]    The system lacks the necessary resources to
                initialize the mutex.
    [EBUSY]     The implementation has detected an attempt to
                reinitialize the mutex (a previously initialized,
                but not yet destroyed mutex).
    [EINVAL]    The value specified by mutex is not a valid mutex.
    [ENOMEM]    Insufficient memory exists to initialize the mutex.
    [EPERM]     The caller does not have privileges to perform this
                operation.

5  –  Associated Routines

       pthread_mutexattr_init()
       pthread_mutexattr_gettype()
       pthread_mutexattr_settype()
       pthread_mutex_lock()
       pthread_mutex_trylock()
       pthread_mutex_unlock()