pthread_mutex_trylock

Tries to lock a mutex. If the mutex is already locked, the calling thread does not wait for the mutex to become available.

Syntax

pthread_mutex_trylock( mutex );

Argument Data Type Access

mutex opaque pthread_mutex_t read

C Binding

#include 


int
pthread_mutex_trylock (
         pthread_mutex_t   *mutex);

Arguments

mutex: Mutex to be locked.

Description

This routine tries to lock a mutex. When a thread calls this routine, an attempt is made to immediately lock the mutex. If the mutex is successfully locked, 0 is returned and the current thread is then the mutex's current owner. If the specified mutex is locked when a thread calls this routine, the calling thread does not wait for the mutex to become available.

The behavior of this routine is as follows:

If a recursive mutex is owned by the current thread, a zero is returned and the mutex lock count is incremented. (To unlock a recursive mutex, each call to pthread_mutex_trylock must be matched by a call to pthread_mutex_unlock.)
If a normal or error-check mutex is locked by any thread (including the current thread) when this routine is called, EBUSY is returned and the thread does not wait to acquire the lock.
If a normal or error-check mutex is not owned, a zero is returned and the mutex becomes locked.

Use the pthread_mutexattr_settype_np routine to set the mutex type attribute (normal, recursive, or errorcheck). For information about mutex types and their usage, see Chapter 2.

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. [EBUSY] The mutex is already locked; therefore, it was not acquired. [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.

Associated Routines

   pthread_mutexattr_settype_np
   pthread_mutex_destroy
   pthread_mutex_init
   pthread_mutex_lock
   pthread_mutex_unlock