Debian Codegraph @

upstream/debian-unstable/man3/pthread_mutex_init.3

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