.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "PTHREAD_MUTEXATTR_GETTYPE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" pthread_mutexattr_gettype 
.SH NAME
pthread_mutexattr_gettype, pthread_mutexattr_settype \- get and set
the mutex type attribute
.SH SYNOPSIS
.LP
\fB#include <pthread.h>
.br
.sp
int pthread_mutexattr_gettype(const pthread_mutexattr_t *restrict\fP
\fIattr\fP\fB,
.br
\ \ \ \ \ \  int *restrict\fP \fItype\fP\fB);
.br
int pthread_mutexattr_settype(pthread_mutexattr_t\fP \fI*attr\fP\fB,
int\fP \fItype\fP\fB); \fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIpthread_mutexattr_gettype\fP() and \fIpthread_mutexattr_settype\fP()
functions, respectively, shall get and set the
mutex \fItype\fP attribute. This attribute is set in the \fItype\fP
parameter to these functions. The default value of the
\fItype\fP attribute is PTHREAD_MUTEX_DEFAULT.
.LP
The type of mutex is contained in the \fItype\fP attribute of the
mutex attributes. Valid mutex types include:
.TP 7
PTHREAD_MUTEX_NORMAL
.sp
This type of mutex does not detect deadlock. A thread attempting to
relock this mutex without first unlocking it shall deadlock.
Attempting to unlock a mutex locked by a different thread results
in undefined behavior. Attempting to unlock an unlocked mutex
results in undefined behavior.
.TP 7
PTHREAD_MUTEX_ERRORCHECK
.sp
This type of mutex provides error checking. A thread attempting to
relock this mutex without first unlocking it shall return with
an error. A thread attempting to unlock a mutex which another thread
has locked shall return with an error. A thread attempting to
unlock an unlocked mutex shall return with an error.
.TP 7
PTHREAD_MUTEX_RECURSIVE
.sp
A thread attempting to relock this mutex without first unlocking it
shall succeed in locking the mutex. The relocking deadlock
which can occur with mutexes of type PTHREAD_MUTEX_NORMAL cannot occur
with this type of mutex. Multiple locks of this mutex shall
require the same number of unlocks to release the mutex before another
thread can acquire the mutex. A thread attempting to unlock
a mutex which another thread has locked shall return with an error.
A thread attempting to unlock an unlocked mutex shall return
with an error.
.TP 7
PTHREAD_MUTEX_DEFAULT
.sp
Attempting to recursively lock a mutex of this type results in undefined
behavior. Attempting to unlock a mutex of this type which
was not locked by the calling thread results in undefined behavior.
Attempting to unlock a mutex of this type which is not locked
results in undefined behavior. An implementation may map this mutex
to one of the other mutex types.
.sp
.SH RETURN VALUE
.LP
Upon successful completion, the \fIpthread_mutexattr_gettype\fP()
function shall return zero and store the value of the
\fItype\fP attribute of \fIattr\fP into the object referenced by the
\fItype\fP parameter. Otherwise, an error shall be returned
to indicate the error.
.LP
If successful, the \fIpthread_mutexattr_settype\fP() function shall
return zero; otherwise, an error number shall be returned
to indicate the error.
.SH ERRORS
.LP
The \fIpthread_mutexattr_settype\fP() function shall fail if:
.TP 7
.B EINVAL
The value \fItype\fP is invalid.
.sp
.LP
The \fIpthread_mutexattr_gettype\fP() and \fIpthread_mutexattr_settype\fP()
functions may fail if:
.TP 7
.B EINVAL
The value specified by \fIattr\fP is invalid.
.sp
.LP
These functions shall not return an error code of [EINTR].
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
It is advised that an application should not use a PTHREAD_MUTEX_RECURSIVE
mutex with condition variables because the implicit
unlock performed for a \fIpthread_cond_timedwait\fP() or \fIpthread_cond_wait\fP()
may not actually release the mutex (if it had been locked
multiple times). If this happens, no other thread can satisfy the
condition of the predicate.
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIpthread_cond_timedwait\fP() , the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, \fI<pthread.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .