pthread_mutex_unlock() — Unlock 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_unlock(pthread_mutex_t *mutex);

SUSV3:

#define _UNIX03_THREADS
#include <pthread.h>

int pthread_mutex_unlock(pthread_mutex_t *mutex);

General description

Releases a mutex object. If one or more threads are waiting to lock the mutex, pthread_mutex_unlock() causes one of those threads to return from pthread_mutex_lock() with the mutex object acquired. If no threads are waiting for the mutex, the mutex unlocks with no current owner.

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 unlock will decrement the count and no waiting thread is posted to continue running with the lock. If the count is decremented to zero, then the mutex is released and if any thread is waiting it is posted.

Returned value

If successful, pthread_mutex_unlock() returns 0.

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

Error Code: Description
EINVAL: The value specified by mutex is not valid.
EPERM: The current thread does not own the mutex.

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

Example

CELEBP41

⁄* CELEBP41 *⁄                                   
#define _OPEN_THREADS                                                           
#include <pthread.h>                                                            
#include <stdio.h>                                                              
#include <errno.h>                                                              
                                                                                
pthread_mutex_t mutex;                                                          
                                                                                
void *thread(void *arg) {                                                       
  if (pthread_mutex_lock(&mutex) != 0) {                                        
    perror("pthread_mutex_lock() error");                                       
    exit(1);                                                                    
  }                                                                             
                                                                                
  puts("thread was granted the mutex");                                         
                                                                                
  if (pthread_mutex_unlock(&mutex) != 0) {                                      
    perror("pthread_mutex_unlock() error");                                     
    exit(2);                                                                    
  }                                                                             
}                                                                               
                                                                                
main() {                                                                        
  pthread_t thid;                                                               
                                                                                
  if (pthread_mutex_init(&mutex, NULL) != 0) {                                  
    perror("pthread_mutex_init() error");                                       
    exit(3);                                                                    
  }                                                                             
                                                                                
  if (pthread_create(&thid, NULL, thread, NULL) != 0) {                         
    perror("pthread_create() error");                                           
    exit(4);                                                                    
  }                                                                             
  if (pthread_mutex_lock(&mutex) != 0) {                                        
    perror("pthread_mutex_lock() error");                                       
    exit(5);                                                                    
  }                                                                             
                                                                                
  puts("IPT was granted the mutex");                                            
                                                                                
  if (pthread_mutex_unlock(&mutex) != 0) {                                      
    perror("pthread_mutex_unlock() error");                                     
    exit(6);                                                                    
  }                                                                             
                                                                                
  if (pthread_join(thid, NULL) != 0) {                                          
    perror("pthread_mutex_lock() error");                                       
    exit(7);                                                                    
  }                                                                             
}

Output:

IPT was granted the mutex
thread was granted the mutex