Debian Codegraph @

upstream/debian-trixie/man3/pthread_mutex_init.3

raw
1 .\" Copyright, Xavier Leroy <[email protected]>
2 .\" Copyright 2023, Alejandro Colomar <[email protected]>
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH pthread_mutex_init 3 2024-06-16 "Linux man-pages 6.9.1"
7 .
8 .
9 .SH NAME
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
17 .
18 .
19 .SH SYNOPSIS
20 .nf
21 .B #include <pthread.h>
22 .P
23 .BI "pthread_mutex_t " fastmutex " = PTHREAD_MUTEX_INITIALIZER;"
24 .BI "pthread_mutex_t " recmutex " = PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP;"
25 .BI "pthread_mutex_t " errchkmutex " = PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP;"
26 .P
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
34 .
35 .
36 .SH DESCRIPTION
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.
41 .P
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.
49 .P
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.
54 .P
55 The LinuxThreads implementation supports only one mutex attributes,
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.
64 .P
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).
73 .P
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.
81 .P
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,
88 \fBpthread_mutex_lock\fP returns immediately with the error code \fBEDEADLK\fP.
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.
94 .P
95 \fBpthread_mutex_trylock\fP behaves identically to \fBpthread_mutex_lock\fP,
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.
102 .P
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.
113 .P
114 On ``error checking'' and ``recursive'' mutexes,
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.
125 .P
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.
133 .
134 .
135 .SH CANCELLATION
136 None of the mutex functions is a cancelation point,
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,
140 the status of mutexes at cancelation points is predictable,
141 allowing cancelation handlers
142 to unlock precisely those mutexes that need to be unlocked
143 before the thread stops executing.
144 Consequently,
145 threads using deferred cancelation
146 should never hold a mutex for extended periods of time.
147 .
148 .
149 .SH "ASYNC-SIGNAL SAFETY"
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.
156 .
157 .
158 .SH "RETURN VALUE"
159 \fBpthread_mutex_init\fP always returns 0.
160 The other mutex functions
161 return 0 on success and a non-zero error code on error.
162 .
163 .
164 .SH ERRORS
165 The \fBpthread_mutex_lock\fP function returns
166 the following error code on error:
167 .RS
168 .TP
169 \fBEINVAL\fP
170 The mutex has not been properly initialized.
171 .TP
172 \fBEDEADLK\fP
173 The mutex is already locked by the calling thread
174 (``error checking'' mutexes only).
175 .RE
176 .P
177 The \fBpthread_mutex_trylock\fP function returns
178 the following error codes on error:
179 .RS
180 .TP
181 \fBEBUSY\fP
182 The mutex could not be acquired because it was currently locked.
183 .TP
184 \fBEINVAL\fP
185 The mutex has not been properly initialized.
186 .RE
187 .P
188 The \fBpthread_mutex_unlock\fP function returns
189 the following error code on error:
190 .RS
191 .TP
192 \fBEINVAL\fP
193 The mutex has not been properly initialized.
194 .TP
195 \fBEPERM\fP
196 The calling thread does not own the mutex
197 (``error checking'' mutexes only).
198 .RE
199 .P
200 The \fBpthread_mutex_destroy\fP function returns
201 the following error code on error:
202 .RS
203 .TP
204 \fBEBUSY\fP
205 The mutex is currently locked.
206 .RE
207 .
208 .
209 .SH "SEE ALSO"
210 \fBpthread_mutexattr_init\fP(3),
211 \fBpthread_mutexattr_setkind_np\fP(3),
212 \fBpthread_cancel\fP(3).
213 .
214 .
215 .SH EXAMPLE
216 A shared global variable \fIx\fP can be protected by a mutex as follows:
217 .P
218 .RS
219 .ft 3
220 .nf
221 .sp
222 int x;
223 pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
224 .ft
225 .RE
226 .fi
227 .P
228 All accesses and modifications to \fIx\fP
229 should be bracketed by calls to
230 \fBpthread_mutex_lock\fP and \fBpthread_mutex_unlock\fP
231 as follows:
232 .P
233 .RS
234 .ft 3
235 .nf
236 .sp
237 pthread_mutex_lock(&mut);
238 /* operate on x */
239 pthread_mutex_unlock(&mut);
240 .ft
241 .RE
242 .fi