pthread_mutex_trylock() — Attempt to lock 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_trylock(pthread_mutex_t *mutex);
SUSV3: 
#define _UNIX03_THREADS
#include <pthread.h>

int pthread_mutex_trylock(pthread_mutex_t *mutex);

General description

Locks a mutex object, which identifies a mutex. Mutexes are used to protect shared resources. If pthread_mutex_trylock() is locked, it returns immediately.

For recursive mutexes, pthread_mutex_trylock() will effectively add to the count of the number of times pthread_mutex_unlock() must be called by the thread to release the mutex. (That is, it has the same behavior as a pthread_mutex_lock().)

Returned value

If successful, pthread_mutex_trylock() returns 0.

If unsuccessful, pthread_mutex_trylock() 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.
EBUSY
mutex could not be acquired because it was already locked.
EINVAL
The value specified by mutex is not valid.

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

Usage notes

  1. 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

CELEBP40 
/* CELEBP40 */                                   
#define _OPEN_THREADS                                                           
#include <pthread.h>                                                            
#include <stdio.h>                                                              
#include <errno.h>                                                              
                                                                                
pthread_mutex_t mutex;                                                          
                                                                                
void *thread(void *arg) {                                                       
  if (pthread_mutex_trylock(&mutex) != 0)                                       
    if (errno == EBUSY)                                                         
      puts("thread was denied access to the mutex");                            
    else {                                                                      
      perror("pthread_mutex_trylock() error");                                  
      exit(1);                                                                  
    }                                                                           
  else puts("thread was granted the mutex");                                    
}                                                                               
                                                                                
main() {                                                                        
  pthread_t thid;                                                               
                                                                                
  if (pthread_mutex_init(&mutex, NULL) != 0) {                                  
    perror("pthread_mutex_init() error");                                       
    exit(2);                                                                    
  }                                                                             
                                                                                
  if (pthread_create(&thid, NULL, thread, NULL) != 0) {                         
    perror("pthread_create() error");                                           
    exit(3);                                                                    
  }                                                                             
  if (pthread_mutex_trylock(&mutex) != 0)                                       
    if (errno == EBUSY)                                                         
      puts("IPT was denied access to the mutex");                               
    else {                                                                      
      perror("pthread_mutex_trylock() error");                                  
      exit(4);                                                                  
    }                                                                           
  else puts("IPT was granted the mutex");                                       
                                                                                
  if (pthread_join(thid, NULL) != 0) {                                          
    perror("pthread_mutex_trylock() error");                                    
    exit(5);                                                                    
  }                                                                             
}
Output: 
IPT was granted the mutex
thread was denied access to the mutex

Related information