1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
<TITLE>PTHREAD_MUTEXATTR(3) manual page</TITLE>
<META NAME="GENERATOR" CONTENT="OpenOffice.org 3.2 (Linux)">
<META NAME="CREATED" CONTENT="20050504;23040500">
<META NAME="CHANGEDBY" CONTENT="Ross Johnson">
<META NAME="CHANGED" CONTENT="20110326;13190500">
<!-- manual page source format generated by PolyglotMan v3.2, -->
<!-- available at http://polyglotman.sourceforge.net/ -->
<STYLE TYPE="text/css">
<!--
H4.cjk { font-family: "AR PL UMing CN" }
H4.ctl { font-family: "Lohit Devanagari" }
H2.cjk { font-family: "AR PL UMing CN" }
H2.ctl { font-family: "Lohit Devanagari" }
-->
</STYLE>
</HEAD>
<BODY LANG="en-GB" BGCOLOR="#ffffff" DIR="LTR">
<H4 CLASS="western">POSIX Threads for Windows – REFERENCE -
<A HREF="http://sources.redhat.com/pthreads-win32">Pthreads-w32</A></H4>
<P><A HREF="index.html">Reference Index</A></P>
<P><A HREF="#toc">Table of Contents</A></P>
<H2 CLASS="western"><A HREF="#toc0" NAME="sect0">Name</A></H2>
<P>pthread_mutexattr_init, pthread_mutexattr_destroy,
pthread_mutexattr_settype, pthread_mutexattr_gettype - mutex creation
attributes
</P>
<H2 CLASS="western"><A HREF="#toc1" NAME="sect1">Synopsis</A></H2>
<P><B>#include <pthread.h></B>
</P>
<P><B>int pthread_mutexattr_init(pthread_mutexattr_t *</B><I>attr</I><B>);</B>
</P>
<P><B>int pthread_mutexattr_destroy(pthread_mutexattr_t *</B><I>attr</I><B>);</B>
</P>
<P><B>int pthread_mutexattr_settype(pthread_mutexattr_t *</B><I>attr</I><B>,
int </B><I>type</I><B>);</B>
</P>
<P><B>int pthread_mutexattr_gettype(const pthread_mutexattr_t *</B><I>attr</I><B>,
int *</B><I>type</I><B>);</B>
</P>
<P><B>int pthread_mutexattr_setkind_np(pthread_mutexattr_t *</B><I>attr</I><B>,
int </B><I>type</I><B>);</B>
</P>
<P><B>int pthread_mutexattr_getkind_np(const pthread_mutexattr_t
*</B><I>attr</I><B>, int *</B><I>type</I><B>);</B>
</P>
<P><B>int pthread_mutexattr_setrobust(pthread_mutexattr_t *</B><I>attr</I><B>,
int</B><SPAN STYLE="font-weight: normal"> </SPAN><I><SPAN STYLE="font-weight: normal">robust</SPAN></I><B>);</B>
</P>
<P><B>int pthread_mutexattr_getrobust(pthread_mutexattr_t *</B><I>attr</I><B>,
int</B><SPAN STYLE="font-weight: normal"> </SPAN><B>*</B><I><SPAN STYLE="font-weight: normal">robust</SPAN></I><B>);</B>
</P>
<H2 CLASS="western"><A HREF="#toc2" NAME="sect2">Description</A></H2>
<P>Mutex attributes can be specified at mutex creation time, by
passing a mutex attribute object as second argument to
<A HREF="pthread_mutex_init.html"><B>pthread_mutex_init</B>(3)</A> .
Passing <B>NULL</B> is equivalent to passing a mutex attribute object
with all attributes set to their default values.
</P>
<P><B>pthread_mutexattr_init</B> initializes the mutex attribute
object <I>attr</I> and fills it with default values for the
attributes.
</P>
<P><B>pthread_mutexattr_destroy</B> destroys a mutex attribute
object, which must not be reused until it is reinitialized.</P>
<P><B>pthread_mutexattr_settype</B> sets the mutex type attribute in
<I>attr</I> to the value specified by <I>type</I>.
</P>
<P><B>pthread_mutexattr_gettype</B> retrieves the current value of
the mutex kind attribute in <I>attr</I> and stores it in the location
pointed to by <I>type</I>.
</P>
<P><B>Pthreads-w32</B> also recognises the following equivalent
functions that are used in Linux:</P>
<P><B>pthread_mutexattr_setkind_np</B> is an alias for
<B>pthread_mutexattr_settype</B>.
</P>
<P STYLE="font-weight: normal"><B>pthread_mutexattr_getkind_np</B> is
an alias for <B>pthread_mutexattr_gettype</B>.
</P>
<P>The following mutex types are supported:</P>
<P STYLE="margin-left: 0.79in"><B>PTHREAD_MUTEX_NORMAL</B> - for
‘‘fast’’ mutexes.</P>
<P STYLE="margin-left: 0.79in"><B>PTHREAD_MUTEX_RECURSIVE</B> - for
‘‘recursive’’ mutexes.</P>
<P STYLE="margin-left: 0.79in"><B>PTHREAD_MUTEX_ERRORCHECK</B> - for
‘‘error checking’’ mutexes.</P>
<P>The mutex type determines what happens if a thread attempts to
lock a mutex it already owns with <A HREF="pthread_mutex_lock.html"><B>pthread_mutex_lock</B>(3)</A>
. If the mutex is of the “normal” or “fast” type,
<A HREF="pthread_mutex_lock.html"><B>pthread_mutex_lock</B>(3)</A>
simply suspends the calling thread forever. If the mutex is of the
‘‘error checking’’ type, <A HREF="pthread_mutex_lock.html"><B>pthread_mutex_lock</B>(3)</A>
returns immediately with the error code <B>EDEADLK</B>. If the mutex
is of the ‘‘recursive’’ type, the call to
<A HREF="pthread_mutex_lock.html"><B>pthread_mutex_lock</B>(3)</A>
returns immediately with a success return code. The number of times
the thread owning the mutex has locked it is recorded in the mutex.
The owning thread must call <A HREF="pthread_mutex_unlock.html"><B>pthread_mutex_unlock</B>(3)</A>
the same number of times before the mutex returns to the unlocked
state.
</P>
<P>The default mutex type is <B>PTHREAD_MUTEX_NORMAL</B></P>
<P><B>Pthreads-w32</B> also recognises the following equivalent types
that are used by Linux:</P>
<P STYLE="margin-left: 0.79in; font-weight: normal"><B>PTHREAD_MUTEX_FAST_NP</B>
– equivalent to <B>PTHREAD_MUTEX_NORMAL</B></P>
<P STYLE="margin-left: 0.79in"><B>PTHREAD_MUTEX_RECURSIVE_NP</B></P>
<P STYLE="margin-left: 0.79in"><B>PTHREAD_MUTEX_ERRORCHECK_NP</B></P>
<P><B>pthread_mutexattr_setrobust</B><SPAN STYLE="font-weight: normal">
sets the robustness attribute to the value given by </SPAN><I><SPAN STYLE="font-weight: normal">robust</SPAN></I><SPAN STYLE="font-weight: normal">.</SPAN></P>
<P><B>pthread_mutexattr_getrobust</B><SPAN STYLE="font-weight: normal">
returns the current robustness value to the location given by
*</SPAN><I><SPAN STYLE="font-weight: normal">robust</SPAN></I><SPAN STYLE="font-weight: normal">.</SPAN></P>
<P><SPAN STYLE="font-weight: normal">The possible values for </SPAN><I><SPAN STYLE="font-weight: normal">robust</SPAN></I><SPAN STYLE="font-weight: normal">
are:</SPAN></P>
<P STYLE="margin-left: 0.79in"><B>PTHREAD_MUTEX_STALLED</B><SPAN STYLE="font-weight: normal">
- when the owner of the mutex terminates without unlocking the mutex,
all subsequent calls
to pthread_mutex_*lock() are blocked from
progress in an unspecified manner.</SPAN></P>
<P STYLE="margin-left: 0.79in"><B>PTHREAD_MUTEX_ROBUST</B><SPAN STYLE="font-weight: normal">
- when the owner of the mutex terminates without unlocking the mutex,
the mutex is
unlocked. The next owner of this mutex acquires the
mutex with an error return of
EOWNERDEAD.</SPAN></P>
<H2 CLASS="western"><A HREF="#toc3" NAME="sect3">Return Value</A></H2>
<P><SPAN STYLE="font-weight: normal">On success all functions return
0, otherwise they return an error code as follows:</SPAN></P>
<P><B>pthread_mutexattr_init</B></P>
<P STYLE="margin-left: 0.79in"><B>ENOMEM</B><SPAN STYLE="font-weight: normal">
- insufficient memory for </SPAN><I><SPAN STYLE="font-weight: normal">attr</SPAN></I><SPAN STYLE="font-weight: normal">.</SPAN></P>
<P><B>pthread_mutexattr_destroy</B></P>
<P STYLE="margin-left: 0.79in"><B>EINVAL</B><SPAN STYLE="font-weight: normal">
- </SPAN><I><SPAN STYLE="font-weight: normal">attr</SPAN></I><SPAN STYLE="font-weight: normal">
is invalid.</SPAN></P>
<P><B>pthread_mutexattr_gettype</B></P>
<P STYLE="margin-left: 0.79in"><B>EINVAL</B><SPAN STYLE="font-weight: normal">
- </SPAN><I><SPAN STYLE="font-weight: normal">attr</SPAN></I><SPAN STYLE="font-weight: normal">
is invalid.</SPAN></P>
<P><B>pthread_mutexattr_settype</B></P>
<DL>
<DL>
<DL>
<DT><B>EINVAL</B><SPAN STYLE="font-weight: normal"> - </SPAN><I><SPAN STYLE="font-weight: normal">attr</SPAN></I><SPAN STYLE="font-weight: normal">
is invalid or </SPAN><I><SPAN STYLE="font-weight: normal">type</SPAN></I><SPAN STYLE="font-weight: normal">
is none of:</SPAN></DT><DL>
<DL>
<DT>
<B>PTHREAD_MUTEX_NORMAL<BR>PTHREAD_MUTEX_FAST_NP<BR>PTHREAD_MUTEX_RECURSIVE<BR>PTHREAD_MUTEX_RECURSIVE_NP<BR>PTHREAD_MUTEX_ERRORCHECK<BR>PTHREAD_MUTEX_ERRORCHECK_NP</B></DT></DL>
</DL>
</DL>
</DL>
<DD STYLE="margin-left: 0in">
<BR>
</DD></DL>
<P>
<B>pthread_mutexattr_getrobust</B></P>
<P STYLE="margin-left: 0.79in"><B>EINVAL</B><SPAN STYLE="font-weight: normal">
– </SPAN><I><SPAN STYLE="font-weight: normal">attr</SPAN></I><SPAN STYLE="font-weight: normal">
or </SPAN><I><SPAN STYLE="font-weight: normal">robust</SPAN></I><SPAN STYLE="font-weight: normal">
is invalid.</SPAN></P>
<P><B>pthread_mutexattr_setrobust</B></P>
<P STYLE="margin-left: 0.79in"><B>EINVAL</B><SPAN STYLE="font-weight: normal">
– </SPAN><I><SPAN STYLE="font-weight: normal">attr</SPAN></I><SPAN STYLE="font-weight: normal">
or </SPAN><I><SPAN STYLE="font-weight: normal">robust</SPAN></I><SPAN STYLE="font-weight: normal">
is invalid.</SPAN></P>
<H2 CLASS="western"><A HREF="#toc5" NAME="sect5">Author</A></H2>
<P>Xavier Leroy <Xavier.Leroy@inria.fr>
</P>
<P>Modified by Ross Johnson for use with <A HREF="http://sources.redhat.com/pthreads-win32">Pthreads-w32</A>.</P>
<H2 CLASS="western"><A HREF="#toc6" NAME="sect6">See Also</A></H2>
<P><A HREF="pthread_mutex_init.html"><B>pthread_mutex_init</B>(3)</A>
, <A HREF="pthread_mutex_lock.html"><B>pthread_mutex_lock</B>(3)</A>
, <A HREF="pthread_mutex_unlock.html"><B>pthread_mutex_unlock</B>(3)</A>
.
</P>
<H2 CLASS="western"><A HREF="#toc7" NAME="sect7"><FONT COLOR="#000080"><U>Notes</U></FONT></A></H2>
<P>For speed, <B>Pthreads-w32</B> never checks the thread ownership
of non-robust mutexes of type <B>PTHREAD_MUTEX_NORMAL</B> (or
<B>PTHREAD_MUTEX_FAST_NP</B>) when performing operations on the
mutex. It is therefore possible for one thread to lock such a mutex
and another to unlock it.</P>
<P STYLE="font-weight: normal">When developing code, it is a common
precaution to substitute the error checking type, then drop in the
normal type for release if the extra performance is required.</P>
<HR>
<P><A NAME="toc"></A><B>Table of Contents</B></P>
<UL>
<LI><P STYLE="margin-bottom: 0in"><A HREF="#sect0" NAME="toc0">Name</A>
</P>
<LI><P STYLE="margin-bottom: 0in"><A HREF="#sect1" NAME="toc1">Synopsis</A>
</P>
<LI><P STYLE="margin-bottom: 0in"><A HREF="#sect2" NAME="toc2">Description</A>
</P>
<LI><P STYLE="margin-bottom: 0in"><A HREF="#sect3" NAME="toc3">Return
Value</A>
</P>
<LI><P STYLE="margin-bottom: 0in"><A HREF="#sect5" NAME="toc5">Author</A>
</P>
<LI><P STYLE="margin-bottom: 0in"><A HREF="#sect6" NAME="toc6">See
Also</A></P>
<LI><P><A HREF="#sect7" NAME="toc7">Notes</A></P>
</UL>
</BODY>
</HTML>
|
