133 lines
3.5 KiB
Plaintext
133 lines
3.5 KiB
Plaintext
'\"macro stdmacro
|
|
.TH pthread_mutex_lock 3P
|
|
.SH NAME
|
|
pthread_mutex_init, pthread_mutex_lock,
|
|
pthread_mutex_trylock, pthread_mutex_unlock,
|
|
pthread_mutex_destroy \- mutual exclusion locks
|
|
.Op c p a
|
|
.SH C SYNOPSIS
|
|
.nf
|
|
.ft 3
|
|
#include <pthread.h>
|
|
.HP
|
|
.ft 3
|
|
int pthread_mutex_init(pthread_mutex_t \(**mutex,
|
|
.br
|
|
const pthread_mutexattr_t \(**attr);
|
|
.HP
|
|
.ft 3
|
|
int pthread_mutex_lock(pthread_mutex_t \(**mutex);
|
|
.HP
|
|
.ft 3
|
|
int pthread_mutex_trylock(pthread_mutex_t \(**mutex);
|
|
.HP
|
|
.ft 3
|
|
int pthread_mutex_unlock(pthread_mutex_t \(**mutex);
|
|
.HP
|
|
.ft 3
|
|
int pthread_mutex_destroy(pthread_mutex_t \(**mutex);
|
|
.ft 1
|
|
.Op
|
|
.SH DESCRIPTION
|
|
Mutual exclusion locks (mutexes) are used to serialize the execution
|
|
of threads through critical sections of code which access shared data.
|
|
A successful call for a mutex lock via
|
|
.IR pthread_mutex_lock ()
|
|
or
|
|
.IR pthread_mutex_trylock ()
|
|
will cause another thread that tries to acquire the same mutex via
|
|
.IR pthread_mutex_lock ()
|
|
to block until the owning thread calls
|
|
.IR pthread_mutex_unlock ().
|
|
.SS Initialize
|
|
Mutexes may be initialized either dynamically, by calling
|
|
.IR pthread_mutex_init (),
|
|
or statically, via the macro
|
|
.BR PTHREAD_MUTEX_INITIALIZER .
|
|
.PP
|
|
The personality of the mutex is determined by the attribute structure
|
|
.I attr
|
|
passed with the call to
|
|
.IR pthread_mutex_init ().
|
|
These attributes are set by calls to
|
|
.IR pthread_mutexattr_init ()
|
|
and the various pthread mutex attribute functions.
|
|
If
|
|
.I attr
|
|
is null (or the mutex is statically initialized),
|
|
the default attributes are used.
|
|
.SS Lock and Unlock
|
|
A mutex lock
|
|
protects shared data from simultaneous access by multiple threads.
|
|
A thread that calls
|
|
.IR pthread_mutex_lock ()
|
|
will block until it can gain exclusive ownership
|
|
of a mutex, and retains ownership until it calls
|
|
.IR pthread_mutex_unlock ().
|
|
Only the thread that locked a mutex should unlock it.
|
|
When unlocked, if there are any threads waiting for the mutex
|
|
the relative priorities of the blocked threads and the
|
|
scheduling policy determines which thread next acquires the mutex.
|
|
.LP
|
|
If a thread waiting for a mutex receives a signal,
|
|
upon return from the signal handler, the thread resumes waiting
|
|
for the mutex as if there was no interrupt.
|
|
.SS Destroy
|
|
The routine
|
|
.IR pthread_mutex_destroy ()
|
|
uninitializes the mutex object referenced by
|
|
.IR mutex .
|
|
.SH "DIAGNOSTICS"
|
|
All of the mutex functions return zero if successful;
|
|
otherwise, an error number is returned.
|
|
.PP
|
|
.IR pthread_mutex_lock ()
|
|
can return the following errors:
|
|
.TP 15
|
|
.B [EDEADLK]
|
|
The current thread already owns the mutex.
|
|
The mutex type must be
|
|
.BR PTHREAD_MUTEX_ERRORCHECK .
|
|
.TP 15
|
|
.B [EINVAL]
|
|
The mutex was initialized as type
|
|
.B PTHREAD_PRIO_PROTECT
|
|
and the calling thread's priority was greater than the mutex's
|
|
priority ceiling.
|
|
.PP
|
|
.IR pthread_mutex_trylock ()
|
|
can return the following errors:
|
|
.TP 15
|
|
.B [EBUSY]
|
|
The mutex is currently held by another thread.
|
|
.TP 15
|
|
.B [EINVAL]
|
|
The mutex was initialized as type
|
|
.B PTHREAD_PRIO_PROTECT
|
|
and the calling thread's priority was greater than the mutex's
|
|
priority ceiling.
|
|
.PP
|
|
.IR pthread_mutex_unlock ()
|
|
can return the following error:
|
|
.TP 15
|
|
.B [EPERM]
|
|
The current thread does not own the mutex.
|
|
The mutex type must be
|
|
.B PTHREAD_MUTEX_ERRORCHECK
|
|
or
|
|
.BR PTHREAD_MUTEX_RECURSIVE .
|
|
.PP
|
|
.IR pthread_mutex_destroy ()
|
|
can return the following error:
|
|
.TP 15
|
|
.B [EBUSY]
|
|
The mutex is currently held by any thread.
|
|
.\" ---------------------
|
|
.SH "SEE ALSO"
|
|
pthread_cond_init(3P),
|
|
pthread_mutexattr_init(3P),
|
|
pthread_mutexattr_setprioceiling(3P),
|
|
pthread_mutexattr_setprotocol(3P),
|
|
pthread_mutexattr_setpshared(3P),
|
|
pthread_mutexattr_settype(3P).
|