pthread_mutex_lock(PTHREAD)
pthread_mutex_lock, pthread_mutex_trylock, pthread_mutex_unlock --
lock, unlock a mutex
Synopsis
cc [options] -Kthread file
#include <pthread.h>
int pthread_mutex_lock(pthread_mutex_t *mutex);
int pthread_mutex_trylock(pthread_mutex_t *mutex);
int pthread_mutex_unlock(pthread_mutex_t *mutex);
Description
pthread_mutex_lock locks the mutual exclusion lock
(mutex) pointed to by mutex.
If mutex is already locked, the calling thread is
blocked until mutex becomes available.
When pthread_mutex_lock returns successfully,
the caller has locked mutex.
If a signal is delivered to a thread waiting for a mutex,
upon return from the signal handler the thread resumes waiting for
the mutex as if it was not interrupted.
From the point of view of the caller,
pthread_mutex_lock is atomic: even if
interrupted by a signal or fork (see
fork(S)),
pthread_mutex_lock will not return until it
holds the locked mutex.
As a consequence, if pthread_mutex_lock is
interrupted, an error indication such as EINTR
is never returned to the caller.
pthread_mutex_trylock is used when the caller
does not want to block.
pthread_mutex_trylock attempts once to lock
mutex.
If mutex is available, pthread_mutex_trylock
will return successfully with mutex locked.
If mutex is already locked, pthread_mutex_trylock
immediately returns EBUSY to the caller without
acquiring mutex or blocking.
The function pthread_mutex_trylock is
identical to pthread_mutex_lock except
that if mutex is
currently locked (by any thread,
including the current thread), the
call returns immediately.
The manner in which mutex is
released is dependent upon its
type attribute.
If there are threads blocked on mutex when
pthread_mutex_unlock is called,
resulting in mutex becoming available,
the scheduling policy is used to determine which
thread shall acquire it.
(In the case of PTHREAD_MUTEX_RECURSIVE
mutexes, mutex becomes available when the count
reaches zero and the calling thread no longer has any locks
on mutex).
Mutex types
The type of mutex is contained in the type
attribute of the mutex attributes.
Valid mutex types include the following:
PTHREAD_MUTEX_NORMAL-
If the mutex type is
PTHREAD_MUTEX_NORMAL, deadlock detection is
not provided.
Attempting to relock mutex causes deadlock.
If a thread attempts to unlock a mutex that
it has not locked or a mutex which is unlocked, undefined
behavior results.
PTHREAD_MUTEX_ERRORCHECK-
If the mutex type is
PTHREAD_MUTEX_ERRORCHECK, then error checking
is provided.
If a thread attempts to relock a mutex that it
has already locked, an error will be returned.
If a thread attempts to unlock a mutex that it
has not locked or
a mutex which is unlocked, an error will be returned.
PTHREAD_MUTEX_RECURSIVE-
If the mutex type is
PTHREAD_MUTEX_RECURSIVE, then mutex maintains the
concept of a lock count.
When a thread successfully acquires a mutex for the
first time, the lock count is set o one.
Every time a thread relocks this mutex,
the lock count is incremented by one.
Each time the thread unlocks the
mutex, the lock count is
decremented by one.
When the lock count reaches zero, the mutex becomes
available for other threads to acquire.
If a thread attempts to unlock a mutex that
it has not locked or a mutex which is unlocked,
an error will be returned.
PTHREAD_MUTEX_DEFAULT-
If the mutex type is
PTHREAD_MUTEX_DEFAULT, attempting to
recursively lock mutex results in
undefined behavior.
Attempting to unlock mutex if it was
not locked by the calling thread results in
undefined behavior.
Attempting to unlock mutex if it is not
locked results in undefined behavior.
The mutex parameter is a pointer to the mutex to
be locked or unlocked.
mutex must previously have been initialized,
either by pthread_mutex_init, or
statically (see
pthread_mutex_init(PTHREAD)).
Mutexes acquired with pthread_mutex_lock or
pthread_mutex_trylock should be
released with pthread_mutex_unlock.
Return values
pthread_mutex_lock, pthread_mutex_unlock,
and pthread_mutex_trylock return
zero for success and an error number for failure.
Diagnostics
pthread_mutex_lock, pthread_mutex_trylock,
and pthread_mutex_unlock return
the following value if the corresponding condition is detected:
EINVAL-
The value specified by mutex does not
refer to an initialized mutex object.
EDEADLK-
The current thread already owns mutex.
pthread_mutex_trylock returns the following value if
the corresponding condition is detected:
EBUSY-
mutex could not be acquired because it was
already locked.
pthread_mutex_unlock returns the following
values if the corresponding conditions are detected:
EPERM-
The current thread does not own mutex.
Warnings
If a thread exits while holding a mutex,
the mutex will not be unlocked,
and other threads waiting for it
will wait forever.
Standards Compliance
The Single UNIX Specification, Version 2; The Open Group.
References
Intro(PTHREAD),
fork(S),
pthread_mutex_destroy(PTHREAD),
pthread_mutex_init(PTHREAD),
pthread(F)
© 2005 The SCO Group, Inc. All rights reserved.
SCO OpenServer Release 6.0.0 - 01 June 2005