Locks an unlocked mutex.

1  –  C Binding

    #include <pthread.h>

    int
    pthread_mutex_lock (
             pthread_mutex_t   *mutex);

2  –  Arguments

 mutex

    Mutex to be locked.

3  –  Description

    This routine locks a mutex with behavior that depends upon the
    type of mutex, as follows:

    o  If a normal or default mutex is specified, a deadlock can
       result if the current owner of the mutex calls this routine in
       an attempt to lock the mutex a second time. (The deadlock is
       not detected or reported.)

    o  If a recursive mutex is specified, the current owner of the
       mutex can relock the same mutex without blocking. The lock
       count is incremented for each recursive lock within the
       thread.

    o  If an errorcheck mutex is specified and the current owner
       tries to lock the mutex a second time, this routine reports
       the [EDEADLK] error. If the mutex is locked by another thread,
       the calling thread waits for the mutex to become available.

    Use the pthread_mutexattr_settype() routine to set the type of
    the mutex to normal, default, recursive, or errorcheck.

    The thread that has locked a mutex becomes its current owner and
    remains its owner until the same thread has unlocked it. This
    routine returns with the mutex in the locked state and with the
    calling thread as the mutex's current owner.

    A recursive or errorcheck mutex records the identity of the
    thread that locks it, allowing debuggers to display this
    information. In most cases, normal and default mutexes do not
    record the owning thread's identity.

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.
    [EDEADLK]   A deadlock condition is detected.
    [EINVAL]    The value specified by mutex is not a valid mutex.

5  –  Associated Routines

       pthread_mutexattr_settype()
       pthread_mutex_destroy()
       pthread_mutex_init()
       pthread_mutex_trylock()
       pthread_mutex_unlock()