]>
Commit | Line | Data |
---|---|---|
13151ec5 AC |
1 | .\" Copyright, Xavier Leroy <Xavier.Leroy@inria.fr> |
2 | .\" Copyright 2023, Alejandro Colomar <alx@kernel.org> | |
3 | .\" | |
4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft | |
5 | .\" | |
6 | .TH pthread_mutex_init 3 (date) "Linux man-pages (unreleased)" | |
74235f15 AC |
7 | . |
8 | . | |
87d09778 | 9 | .SH NAME |
8a00cac7 AC |
10 | pthread_mutex_init, |
11 | pthread_mutex_lock, | |
12 | pthread_mutex_trylock, | |
13 | pthread_mutex_unlock, | |
14 | pthread_mutex_destroy | |
15 | \- | |
16 | operations on mutexes | |
74235f15 AC |
17 | . |
18 | . | |
87d09778 | 19 | .SH SYNOPSIS |
b841c4f3 | 20 | .nf |
c1c253d0 | 21 | .B #include <pthread.h> |
c6d039a3 | 22 | .P |
c1c253d0 | 23 | .BI "pthread_mutex_t " fastmutex " = PTHREAD_MUTEX_INITIALIZER;" |
c1c253d0 | 24 | .BI "pthread_mutex_t " recmutex " = PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP;" |
c1c253d0 | 25 | .BI "pthread_mutex_t " errchkmutex " = PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP;" |
c6d039a3 | 26 | .P |
b841c4f3 AC |
27 | .BI "int pthread_mutex_init(pthread_mutex_t *" mutex , |
28 | .BI " const pthread_mutexattr_t *" mutexattr ); | |
29 | .BI "int pthread_mutex_lock(pthread_mutex_t *" mutex ); | |
30 | .BI "int pthread_mutex_trylock(pthread_mutex_t *" mutex ); | |
31 | .BI "int pthread_mutex_unlock(pthread_mutex_t *" mutex ); | |
32 | .BI "int pthread_mutex_destroy(pthread_mutex_t *" mutex ); | |
33 | .fi | |
74235f15 AC |
34 | . |
35 | . | |
87d09778 | 36 | .SH DESCRIPTION |
8a00cac7 AC |
37 | A mutex is a MUTual EXclusion device, |
38 | and is useful for | |
39 | protecting shared data structures from concurrent modifications, | |
40 | and implementing critical sections and monitors. | |
c6d039a3 | 41 | .P |
8a00cac7 AC |
42 | A mutex has two possible states: |
43 | unlocked (not owned by any thread), | |
44 | and locked (owned by one thread). | |
45 | A mutex can never be owned by two different threads simultaneously. | |
46 | A thread attempting to lock a mutex | |
47 | that is already locked by another thread | |
48 | is suspended until the owning thread unlocks the mutex first. | |
c6d039a3 | 49 | .P |
8a00cac7 AC |
50 | \fBpthread_mutex_init\fP initializes the mutex object pointed to by \fImutex\fP |
51 | according to the mutex attributes specified in \fImutexattr\fP. | |
52 | If \fImutexattr\fP is \fBNULL\fP, | |
53 | default attributes are used instead. | |
c6d039a3 | 54 | .P |
87d09778 | 55 | The LinuxThreads implementation supports only one mutex attributes, |
8a00cac7 AC |
56 | the \fImutex kind\fP, |
57 | which is either ``fast'', | |
58 | ``recursive'', | |
59 | or ``error checking''. | |
60 | The kind of a mutex determines | |
61 | whether it can be locked again by a thread that already owns it. | |
62 | The default kind is ``fast''. | |
63 | See \fBpthread_mutexattr_init\fP(3) for more information on mutex attributes. | |
c6d039a3 | 64 | .P |
8a00cac7 AC |
65 | Variables of type \fBpthread_mutex_t\fP can also be initialized statically, |
66 | using the constants | |
67 | \fBPTHREAD_MUTEX_INITIALIZER\fP | |
68 | (for fast mutexes), | |
69 | \fBPTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP\fP | |
70 | (for recursive mutexes), | |
71 | and \fBPTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP\fP | |
72 | (for error checking mutexes). | |
c6d039a3 | 73 | .P |
8a00cac7 AC |
74 | \fBpthread_mutex_lock\fP locks the given mutex. |
75 | If the mutex is currently unlocked, | |
76 | it becomes locked and owned by the calling thread, | |
77 | and \fBpthread_mutex_lock\fP returns immediately. | |
78 | If the mutex is already locked by another thread, | |
79 | \fBpthread_mutex_lock\fP suspends the calling thread | |
80 | until the mutex is unlocked. | |
c6d039a3 | 81 | .P |
8a00cac7 AC |
82 | If the mutex is already locked by the calling thread, |
83 | the behavior of \fBpthread_mutex_lock\fP depends on the kind of the mutex. | |
84 | If the mutex is of the ``fast'' kind, | |
85 | the calling thread is suspended until the mutex is unlocked, | |
86 | thus effectively causing the calling thread to deadlock. | |
87 | If the mutex is of the ``error checking'' kind, | |
c1c253d0 | 88 | \fBpthread_mutex_lock\fP returns immediately with the error code \fBEDEADLK\fP. |
8a00cac7 AC |
89 | If the mutex is of the ``recursive'' kind, |
90 | \fBpthread_mutex_lock\fP succeeds and returns immediately, | |
91 | recording the number of times the calling thread has locked the mutex. | |
92 | An equal number of \fBpthread_mutex_unlock\fP operations | |
93 | must be performed before the mutex returns to the unlocked state. | |
c6d039a3 | 94 | .P |
c1c253d0 | 95 | \fBpthread_mutex_trylock\fP behaves identically to \fBpthread_mutex_lock\fP, |
8a00cac7 AC |
96 | except that it does not block the calling thread |
97 | if the mutex is already locked by another thread | |
98 | (or by the calling thread in the case of a ``fast'' mutex). | |
99 | Instead, | |
100 | \fBpthread_mutex_trylock\fP returns immediately | |
101 | with the error code \fBEBUSY\fP. | |
c6d039a3 | 102 | .P |
8a00cac7 AC |
103 | \fBpthread_mutex_unlock\fP unlocks the given mutex. |
104 | The mutex is assumed to be locked and owned by the calling thread | |
105 | on entrance to \fBpthread_mutex_unlock\fP. | |
106 | If the mutex is of the ``fast'' kind, | |
107 | \fBpthread_mutex_unlock\fP always returns it to the unlocked state. | |
108 | If it is of the ``recursive'' kind, | |
109 | it decrements the locking count of the mutex | |
110 | (number of \fBpthread_mutex_lock\fP operations | |
111 | performed on it by the calling thread), | |
112 | and only when this count reaches zero is the mutex actually unlocked. | |
c6d039a3 | 113 | .P |
c1c253d0 | 114 | On ``error checking'' and ``recursive'' mutexes, |
8a00cac7 AC |
115 | \fBpthread_mutex_unlock\fP actually checks at run-time |
116 | that the mutex is locked on entrance, | |
117 | and that it was locked by the same thread | |
118 | that is now calling \fBpthread_mutex_unlock\fP. | |
119 | If these conditions are not met, | |
120 | an error code is returned and the mutex remains unchanged. | |
121 | ``Fast'' mutexes perform no such checks, | |
122 | thus allowing a locked mutex to be | |
123 | unlocked by a thread other than its owner. | |
124 | This is non-portable behavior and must not be relied upon. | |
c6d039a3 | 125 | .P |
8a00cac7 AC |
126 | \fBpthread_mutex_destroy\fP destroys a mutex object, |
127 | freeing the resources it might hold. | |
128 | The mutex must be unlocked on entrance. | |
129 | In the LinuxThreads implementation, | |
130 | no resources are associated with mutex objects, | |
131 | thus \fBpthread_mutex_destroy\fP actually does nothing | |
132 | except checking that the mutex is unlocked. | |
74235f15 AC |
133 | . |
134 | . | |
87d09778 | 135 | .SH CANCELLATION |
ee7b1c77 | 136 | None of the mutex functions is a cancelation point, |
8a00cac7 AC |
137 | not even \fBpthread_mutex_lock\fP, |
138 | in spite of the fact that it can suspend a thread for arbitrary durations. | |
139 | This way, | |
ee7b1c77 AC |
140 | the status of mutexes at cancelation points is predictable, |
141 | allowing cancelation handlers | |
8a00cac7 AC |
142 | to unlock precisely those mutexes that need to be unlocked |
143 | before the thread stops executing. | |
144 | Consequently, | |
ee7b1c77 | 145 | threads using deferred cancelation |
8a00cac7 | 146 | should never hold a mutex for extended periods of time. |
74235f15 AC |
147 | . |
148 | . | |
87d09778 | 149 | .SH "ASYNC-SIGNAL SAFETY" |
8a00cac7 AC |
150 | The mutex functions are not async-signal safe. |
151 | What this means is that they should not be called from a signal handler. | |
152 | In particular, | |
153 | calling \fBpthread_mutex_lock\fP or \fBpthread_mutex_unlock\fP | |
154 | from a signal handler | |
155 | may deadlock the calling thread. | |
74235f15 AC |
156 | . |
157 | . | |
87d09778 | 158 | .SH "RETURN VALUE" |
8a00cac7 AC |
159 | \fBpthread_mutex_init\fP always returns 0. |
160 | The other mutex functions | |
87d09778 | 161 | return 0 on success and a non-zero error code on error. |
74235f15 AC |
162 | . |
163 | . | |
87d09778 | 164 | .SH ERRORS |
8a00cac7 AC |
165 | The \fBpthread_mutex_lock\fP function returns |
166 | the following error code on error: | |
87d09778 AC |
167 | .RS |
168 | .TP | |
c1c253d0 | 169 | \fBEINVAL\fP |
8a00cac7 | 170 | The mutex has not been properly initialized. |
87d09778 | 171 | .TP |
c1c253d0 | 172 | \fBEDEADLK\fP |
8a00cac7 | 173 | The mutex is already locked by the calling thread |
87d09778 AC |
174 | (``error checking'' mutexes only). |
175 | .RE | |
c6d039a3 | 176 | .P |
8a00cac7 AC |
177 | The \fBpthread_mutex_trylock\fP function returns |
178 | the following error codes on error: | |
87d09778 AC |
179 | .RS |
180 | .TP | |
c1c253d0 | 181 | \fBEBUSY\fP |
8a00cac7 | 182 | The mutex could not be acquired because it was currently locked. |
87d09778 | 183 | .TP |
c1c253d0 | 184 | \fBEINVAL\fP |
8a00cac7 | 185 | The mutex has not been properly initialized. |
87d09778 | 186 | .RE |
c6d039a3 | 187 | .P |
8a00cac7 AC |
188 | The \fBpthread_mutex_unlock\fP function returns |
189 | the following error code on error: | |
87d09778 AC |
190 | .RS |
191 | .TP | |
c1c253d0 | 192 | \fBEINVAL\fP |
8a00cac7 | 193 | The mutex has not been properly initialized. |
87d09778 | 194 | .TP |
c1c253d0 | 195 | \fBEPERM\fP |
8a00cac7 AC |
196 | The calling thread does not own the mutex |
197 | (``error checking'' mutexes only). | |
87d09778 | 198 | .RE |
c6d039a3 | 199 | .P |
8a00cac7 AC |
200 | The \fBpthread_mutex_destroy\fP function returns |
201 | the following error code on error: | |
87d09778 AC |
202 | .RS |
203 | .TP | |
c1c253d0 | 204 | \fBEBUSY\fP |
8a00cac7 | 205 | The mutex is currently locked. |
87d09778 | 206 | .RE |
74235f15 AC |
207 | . |
208 | . | |
87d09778 | 209 | .SH "SEE ALSO" |
c1c253d0 AC |
210 | \fBpthread_mutexattr_init\fP(3), |
211 | \fBpthread_mutexattr_setkind_np\fP(3), | |
212 | \fBpthread_cancel\fP(3). | |
74235f15 AC |
213 | . |
214 | . | |
87d09778 | 215 | .SH EXAMPLE |
c1c253d0 | 216 | A shared global variable \fIx\fP can be protected by a mutex as follows: |
c6d039a3 | 217 | .P |
87d09778 AC |
218 | .RS |
219 | .ft 3 | |
220 | .nf | |
221 | .sp | |
222 | int x; | |
223 | pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER; | |
224 | .ft | |
c6d039a3 | 225 | .P |
87d09778 AC |
226 | .RE |
227 | .fi | |
c6d039a3 | 228 | .P |
8a00cac7 AC |
229 | All accesses and modifications to \fIx\fP |
230 | should be bracketed by calls to | |
231 | \fBpthread_mutex_lock\fP and \fBpthread_mutex_unlock\fP | |
232 | as follows: | |
c6d039a3 | 233 | .P |
87d09778 AC |
234 | .RS |
235 | .ft 3 | |
236 | .nf | |
237 | .sp | |
238 | pthread_mutex_lock(&mut); | |
239 | /* operate on x */ | |
240 | pthread_mutex_unlock(&mut); | |
241 | .ft | |
c6d039a3 | 242 | .P |
87d09778 AC |
243 | .RE |
244 | .fi |