pthread_mutex_lock() — Wait for a lock on a mutex object

Standards

Standards / Extensions	C or C++	Dependencies
POSIX.4a Single UNIX Specification, Version 3	both	POSIX(ON)

Format

#define _OPEN_THREADS
#include <pthread.h>

int pthread_mutex_lock(pthread_mutex_t *mutex);

SUSV3:

#define _UNIX03_THREADS
#include <pthread.h>

int pthread_mutex_lock(pthread_mutex_t *mutex);

General description

Locks a mutex object, which identifies a mutex. Mutexes are used to protect shared resources. If the mutex is already locked by another thread, 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.

When the mutex has the attribute of recursive, the use of the lock may be different. When this kind of mutex is locked multiple times by the same thread, then a count is incremented and no waiting thread is posted. The owning thread must call pthread_mutex_unlock() the same number of times to decrement the count to zero.

The mutex types are described below:

PTHREAD_MUTEX_NORMAL: A normal type mutex does not detect deadlock. That is, a thread attempting to relock this mutex without first unlocking it will deadlock. The mutex is either in a locked or unlocked state for a thread.
PTHREAD_MUTEX_ERRORCHECK: An errorcheck type mutex provides error checking. That is, a thread attempting to relock this mutex without first unlocking it will return with an error. The mutex is either in a locked or unlocked state for a thread. If a thread attempts to relock a mutex that it has already locked, it will return with an error. If a thread attempts to unlock a mutex that is unlocked, it will return with an error.
PTHREAD_MUTEX_RECURSIVE: A recursive type mutex permits a thread to lock many times. That is, a thread attempting to relock this mutex without first unlocking will succeed. This type of mutex must be unlocked the same number to times it is locked before the mutex will be returned to an unlocked state. If locked, an error is returned.
PTHREAD_MUTEX_DEFAULT: The default type mutex is mapped to a normal type mutex which does not detect deadlock. That is, a thread attempting to relock this mutex without first unlocking it will deadlock. The mutex is either in a locked or unlocked state for a thread. The normal mutex is the default type mutex.

Returned value

If successful, pthread_mutex_lock() returns 0.

If unsuccessful, pthread_mutex_lock() returns -1 and sets errno to one of the following values:

Error Code: Description
EAGAIN: The mutex could not be acquired because the maximum number of recursive locks for mutex has been exceeded. This errno will only occur in the shared path.
EDEADLK: The current thread already owns the mutex, and the mutex has a kind attribute of __MUTEX_NONRECURSIVE.
EINVAL: The value specified by mutex is not valid.

Special behavior for Single UNIX Specification, Version 3: If unsuccessful, pthread_mutex_lock() returns an error number to indicate the error.

Usage notes

If the _OPEN_SYS_MUTEX_EXT feature switch is set, all shared (extended) mutex locks are released when the thread ends, whether normally or abnormally. If the thread ends normally (i.e. pthread_exit() or pthread_cancel()), the first waiter of the mutex lock will be resumed. If the thread ends abnormally, the processes of the mutex waiters for this mutex lock will be terminated.

Example

CELEBP38

⁄* CELEBP38 *⁄                                   
#ifndef _OPEN_THREADS                                                           
#define _OPEN_THREADS                                                           
#endif                                                                          
                                                                                
#include <pthread.h>                                                            
#include <stdio.h>                                                              
                                                                                
main() {                                                                        
  pthread_mutex_t mut;                                                          
                                                                                
  if (pthread_mutex_init(&mut, NULL) != 0) {                                    
    perror("mutex_lock");                                                       
    exit(1);                                                                    
  }                                                                             
                                                                                
  if (pthread_mutex_lock(&mut) != 0) {                                          
    perror("mutex_lock");                                                       
    exit(2);                                                                    
  }                                                                             
                                                                                
  puts("the mutex has been locked");                                            
  exit(0);                                                                      
}