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

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