pthread_mutex_lock

Locks an unlocked mutex. If the mutex is already locked, the calling thread blocks until the mutex becomes available.

Syntax

pthread_mutex_lock( mutex );

Argument Data Type Access

mutex opaque pthread_mutex_t read

C Binding

#include 


int
pthread_mutex_lock (
         pthread_mutex_t   *mutex);

Arguments

mutex: Mutex to be locked.

Description

This routine locks a mutex with varying behavior as follows:

If a recursive mutex was specified, the current owner of a mutex can relock the same mutex without blocking. The lock count is incremented for each recursive lock within the thread.
If an error-check mutex was specified and the current owner tries to lock the mutex a second time, the EDEADLK error is reported. If the mutex is locked by another thread, the calling thread waits for the mutex to become available.
If a normal mutex is specified, a deadlock can result if the current owner of a mutex calls this routine in an attempt to lock the mutex a second time. (The deadlock is not detected or reported.)

Use the pthread_mutexattr_settype_np routine to set the type of the mutex to normal, recursive, or error-check. For more information about mutexes, see Chapter 2.

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.

A recursive or error-check mutex records the identity of the thread that locks it, allowing debuggers to display this information. In most cases, normal mutexes do not record the thread identity.

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. [EINVAL] The value specified by mutex is invalid, or The mutex was created with the protocol attribute set to PTHREAD_PRIO_PROTECT and the calling thread's priority set higher than the mutex's current priority ceiling. [EDEADLK] A deadlock condition is detected.

Associated Routines

   pthread_mutexattr_settype_np
   pthread_mutex_destroy
   pthread_mutex_init
   pthread_mutex_trylock
   pthread_mutex_unlock