NAME

    pthread_mutex_lock - Locks an unlocked mutex

 SYNOPSIS

     #include <pthread.h>

     int pthread_mutex_lock( pthread_mutex_t *mutex );

 PARAMETERS

     mutex                Mutex that is locked.

 DESCRIPTION

 The pthread_mutex_lock() routine locks a mutex. If the mutex is locked
 when a thread calls this routine, the thread waits for the mutex to
 become available.

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

 If you specified a fast mutex in a call to
 pthread_mutexattr_setkind_np(), a deadlock can result if the current
 owner of a mutex calls this routine in an attempt to lock the mutex a
 second time. If you specified a recursive mutex in a call to
 pthread_mutexattr_setkind_np(), the current owner of a mutex can relock
 the same mutex without blocking.  If you specify a nonrecursive mutex in
 a call to pthread_mutexattr_setkind_np(), an error is returned and the
 thread does not block if the current owner of a mutex calls this routine
 in an attempt to lock the mutex a second time.

 The preemption of a lower-priority thread that locks a mutex possibly
 results in the indefinite blocking of higher-priority threads waiting
 for the same mutex. The execution of the waiting higher-priority threads
 is blocked for as long as there is a sufficient number of runable
 threads of any priority between the lower-priority and higher-priority
 values. Priority inversion occurs when any resource is shared between
 threads with different priorities.

 RETURN VALUES

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

    Return   Error       Description
    _____________________________________________________________
     0                   Successful completion.

    -1      [EINVAL]     The value specified by mutex is invalid.

    -1      [EDEADLK]    A deadlock condition is detected.

 RELATED INFORMATION

     FUNCTIONS:  pthread_mutexattr_setkind_np
                 pthread_mutex_destroy
                 pthread_mutex_init
                 pthread_mutex_trylock
                 pthread_mutex_unlock