pthread_mutex_lock or pthread_mutex_trylock Subroutine



Purpose

Locks a mutex.

Library

Threads Library (libpthreads.a)

Syntax

#include <pthread.h>

int pthread_mutex_lock (mutex)
pthread_mutex_t *mutex;

int pthread_mutex_trylock (mutex)
pthread_mutex_t *mutex;

Description

These subroutines lock the mutex mutex. If the mutex is already locked,
their behavior differs; the pthread_mutex_lock subroutine blocks the
calling thread until the mutex is unlocked, while the pthread_mutex_trylock
subroutine returns an error.

The pthread_mutex_lock and pthread_mutex_trylock subroutines return
an error if the calling thread has already locked the mutex using
one of these subroutines, preventing deadlocks caused by recursive
locking.

Note:	The pthread.h header file must be the first included file of
each source file using the threads library.

Parameter

mutex	Specifies the mutex to lock.

Return Values

Upon successful completion, 0 is returned. Otherwise, an error code
is returned.

Error Codes

The pthread_mutex_lock and pthread_mutex_trylock subroutines is unsuccessful
if the following is true:

EDEADLK	A deadlock was detected; the calling thread has already locked
the mutex.

EINVAL	The mutex parameter is not valid.

The pthread_mutex_trylock subroutine fails if the following is true:

EBUSY	The mutex mutex is already locked.

Implementation Specifics

These subroutines are part of the Base Operating System (BOS) Runtime.

Related Information

The pthread_mutex_unlock subroutine, pthread_mutex_init subroutine,
pthread_cond_wait or pthread_cond_timedwait subroutine.

Using Mutexes and Threads Library Quick Reference.