]>
Commit | Line | Data |
---|---|---|
cb5f0589 | 1 | .\" Copyright (c) 2017, Yubin Ruan <ablacktshirt@gmail.com> |
d1524d18 | 2 | .\" and Copyright (c) 2017, Michael Kerrisk <mtk.manpages@gmail.com> |
cb5f0589 YR |
3 | .\" |
4 | .\" %%%LICENSE_START(VERBATIM) | |
5 | .\" Permission is granted to make and distribute verbatim copies of this | |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
13 | .\" | |
14 | .\" Since the Linux kernel and libraries are constantly changing, this | |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
21 | .\" | |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
24 | .\" %%%LICENSE_END | |
25 | .\" | |
9ba01802 | 26 | .TH PTHREAD_MUTEXATTR_SETROBUST 3 2019-03-06 "Linux" "Linux Programmer's Manual" |
cb5f0589 | 27 | .SH NAME |
61265f77 | 28 | pthread_mutexattr_getrobust, pthread_mutexattr_setrobust |
143e516f | 29 | \- get and set the robustness attribute of a mutex attributes object |
cb5f0589 YR |
30 | .SH SYNOPSIS |
31 | .nf | |
32 | .B #include <pthread.h> | |
33 | .PP | |
3a2b5cc7 MK |
34 | .BI "int pthread_mutexattr_getrobust(const pthread_mutexattr_t *" attr , |
35 | .BI " int *" robustness ");" | |
36 | .BI "int pthread_mutexattr_setrobust(const pthread_mutexattr_t *" attr , | |
37f0c285 | 37 | .BI " int " robustness ");" |
cb5f0589 YR |
38 | .fi |
39 | .PP | |
40 | Compile and link with \fI\-pthread\fP. | |
06ae85bd MK |
41 | .PP |
42 | .in -4n | |
43 | Feature Test Macro Requirements for glibc (see | |
44 | .BR feature_test_macros (7)): | |
45 | .in | |
46 | .PP | |
47 | .BR pthread_mutexattr_getrobust (), | |
48 | .BR pthread_mutexattr_setrobust (): | |
49 | .br | |
50 | .RS 4 | |
51 | .ad l | |
52 | _POSIX_C_SOURCE >= 200809L | |
53 | .\" FIXME . | |
54 | .\" But see https://sourceware.org/bugzilla/show_bug.cgi?id=22125 | |
55 | .RE | |
56 | .ad | |
cb5f0589 YR |
57 | .SH DESCRIPTION |
58 | The | |
3a2b5cc7 | 59 | .BR pthread_mutexattr_getrobust () |
700b4034 | 60 | function places the value of the robustness attribute of |
143e516f | 61 | the mutex attributes object referred to by |
d1524d18 MK |
62 | .I attr |
63 | in | |
64 | .IR *robustness . | |
65 | The | |
3a2b5cc7 | 66 | .BR pthread_mutexattr_setrobust () |
700b4034 | 67 | function sets the value of the robustness attribute of |
143e516f | 68 | the mutex attributes object referred to by |
d1524d18 MK |
69 | .I attr |
70 | to the value specified in | |
71 | .IR *robustness . | |
cb5f0589 | 72 | .PP |
d1524d18 MK |
73 | The robustness attribute specifies the behavior of the mutex when |
74 | the owning thread dies without unlocking the mutex. | |
99afed9e MK |
75 | The following values are valid for |
76 | .IR robustness : | |
150a51c6 | 77 | .TP |
cb5f0589 | 78 | .BR PTHREAD_MUTEX_STALLED |
143e516f | 79 | This is the default value for a mutex attributes object. |
d1524d18 | 80 | If a mutex is initialized with the |
cb5f0589 | 81 | .BR PTHREAD_MUTEX_STALLED |
d1524d18 MK |
82 | attribute and its owner dies without unlocking it, |
83 | the mutex remains locked afterwards and any future attempts to call | |
3a2b5cc7 | 84 | .BR pthread_mutex_lock (3) |
d1524d18 | 85 | on the mutex will block indefinitely. |
cb5f0589 YR |
86 | .TP |
87 | .B PTHREAD_MUTEX_ROBUST | |
d1524d18 | 88 | If a mutex is initialized with the |
91fd35ad | 89 | .BR PTHREAD_MUTEX_ROBUST |
d1524d18 | 90 | attribute and its owner dies without unlocking it, |
3a2b5cc7 MK |
91 | any future attempts to call |
92 | .BR pthread_mutex_lock (3) | |
2db68196 | 93 | on this mutex will succeed and return |
cb5f0589 | 94 | .B EOWNERDEAD |
d1524d18 | 95 | to indicate that the original owner no longer exists and the mutex is in |
f899f232 MK |
96 | an inconsistent state. |
97 | Usually after | |
cb5f0589 YR |
98 | .B EOWNERDEAD |
99 | is returned, the next owner should call | |
3a2b5cc7 | 100 | .BR pthread_mutex_consistent (3) |
cb5f0589 | 101 | on the acquired mutex to make it consistent again before using it any further. |
d1524d18 | 102 | .IP |
700b4034 | 103 | If the next owner unlocks the mutex using |
3a2b5cc7 | 104 | .BR pthread_mutex_unlock (3) |
d1524d18 | 105 | before making it consistent, the mutex will be permanently unusable and any |
cb5f0589 | 106 | subsequent attempts to lock it using |
3a2b5cc7 | 107 | .BR pthread_mutex_lock (3) |
ad2825bf | 108 | will fail with the error |
3a2b5cc7 | 109 | .BR ENOTRECOVERABLE . |
d1524d18 MK |
110 | The only permitted operation on such a mutex is |
111 | .BR pthread_mutex_destroy (3). | |
112 | .IP | |
cb5f0589 | 113 | If the next owner terminates before calling |
3a2b5cc7 | 114 | .BR pthread_mutex_consistent (3), |
2db68196 | 115 | further |
3a2b5cc7 | 116 | .BR pthread_mutex_lock (3) |
d1524d18 | 117 | operations on this mutex will still return |
150a51c6 | 118 | .BR EOWNERDEAD . |
3a2b5cc7 | 119 | .PP |
cb5f0589 YR |
120 | Note that the |
121 | .IR attr | |
122 | argument of | |
3a2b5cc7 | 123 | .BR pthread_mutexattr_getrobust () |
150a51c6 | 124 | and |
3a2b5cc7 | 125 | .BR pthread_mutexattr_setrobust () |
143e516f | 126 | should refer to a mutex attributes object that was initialized by |
3a2b5cc7 | 127 | .BR pthread_mutexattr_init (3), |
150a51c6 | 128 | otherwise the behavior is undefined. |
cb5f0589 | 129 | .SH RETURN VALUE |
d1524d18 MK |
130 | On success, these functions return 0. |
131 | On error, they return a positive error number. | |
132 | .PP | |
133 | In the glibc implementation, | |
3a2b5cc7 | 134 | .BR pthread_mutexattr_getrobust () |
cb5f0589 YR |
135 | always return zero. |
136 | .SH ERRORS | |
137 | .TP | |
138 | .B EINVAL | |
139 | A value other than | |
140 | .B PTHREAD_MUTEX_STALLED | |
141 | or | |
142 | .B PTHREAD_MUTEX_ROBUST | |
ad2825bf | 143 | was passed to |
150a51c6 | 144 | .BR pthread_mutexattr_setrobust (). |
5514936a MK |
145 | .SH VERSIONS |
146 | .BR pthread_mutexattr_getrobust () | |
147 | and | |
148 | .BR pthread_mutexattr_setrobust () | |
149 | were added to glibc in version 2.12. | |
06ae85bd MK |
150 | .SH CONFORMING TO |
151 | POSIX.1-2008. | |
61265f77 | 152 | .SH NOTES |
5ede40bb MK |
153 | In the Linux implementation, |
154 | when using process-shared robust mutexes, a waiting thread also receives the | |
155 | .B EOWNERDEAD | |
700b4034 | 156 | notification if the owner of a robust mutex performs an |
5ede40bb MK |
157 | .BR execve (2) |
158 | without first unlocking the mutex. | |
159 | POSIX.1 does not specify this detail, | |
160 | but the same behavior also occurs in at least some | |
161 | .\" E.g., Solaris, according to its manual page | |
162 | other implementations. | |
163 | .PP | |
61265f77 MK |
164 | Before the addition of |
165 | .BR pthread_mutexattr_getrobust () | |
166 | and | |
167 | .BR pthread_mutexattr_setrobust () | |
168 | to POSIX, | |
169 | glibc defined the following equivalent nonstandard functions if | |
170 | .BR _GNU_SOURCE | |
171 | was defined: | |
172 | .PP | |
173 | .nf | |
174 | .BI "int pthread_mutexattr_getrobust_np(const pthread_mutexattr_t *" attr , | |
175 | .BI " int *" robustness ");" | |
176 | .BI "int pthread_mutexattr_setrobust_np(const pthread_mutexattr_t *" attr , | |
177 | .BI " int " robustness ");" | |
178 | .fi | |
179 | .PP | |
180 | Correspondingly, the constants | |
181 | .B PTHREAD_MUTEX_STALLED_NP | |
182 | and | |
183 | .B PTHREAD_MUTEX_ROBUST_NP | |
184 | were also defined. | |
185 | .PP | |
186 | These GNU-specific APIs, which first appeared in glibc 2.4, | |
187 | are nowadays obsolete and should not be used in new programs. | |
cb5f0589 YR |
188 | .SH EXAMPLE |
189 | .PP | |
a25748e6 | 190 | The program below demonstrates the use of the robustness attribute of a |
143e516f | 191 | mutex attributes object. |
f899f232 | 192 | In this program, a thread holding the mutex |
2db68196 | 193 | dies prematurely without unlocking the mutex. |
f6569f44 | 194 | The main thread subsequently acquires the mutex |
ad2825bf | 195 | successfully and gets the error |
f6569f44 MK |
196 | .BR EOWNERDEAD , |
197 | after which it makes the mutex consistent. | |
8524bca5 MK |
198 | .PP |
199 | The following shell session shows what we see when running this program: | |
200 | .PP | |
201 | .in +4n | |
202 | .EX | |
203 | $ \fB./a.out\fP | |
204 | [original owner] Setting lock... | |
205 | [original owner] Locked. Now exiting without unlocking. | |
206 | [main thread] Attempting to lock the robust mutex. | |
207 | [main thread] pthread_mutex_lock() returned EOWNERDEAD | |
208 | [main thread] Now make the mutex consistent | |
209 | [main thread] Mutex is now consistent; unlocking | |
210 | .EE | |
211 | .in | |
cb5f0589 YR |
212 | .SS Program source |
213 | .EX | |
4057660b | 214 | #include <stdlib.h> |
cb5f0589 YR |
215 | #include <stdio.h> |
216 | #include <unistd.h> | |
217 | #include <pthread.h> | |
218 | #include <errno.h> | |
219 | ||
d1a71985 | 220 | #define handle_error_en(en, msg) \e |
a205ca43 MK |
221 | do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) |
222 | ||
5d26c00f | 223 | static pthread_mutex_t mtx; |
cb5f0589 | 224 | |
4057660b MK |
225 | static void * |
226 | original_owner_thread(void *ptr) | |
cb5f0589 | 227 | { |
d1a71985 | 228 | printf("[original owner] Setting lock...\en"); |
5d26c00f | 229 | pthread_mutex_lock(&mtx); |
d1a71985 | 230 | printf("[original owner] Locked. Now exiting without unlocking.\en"); |
cb5f0589 YR |
231 | pthread_exit(NULL); |
232 | } | |
233 | ||
4057660b MK |
234 | int |
235 | main(int argc, char *argv[]) | |
cb5f0589 | 236 | { |
a205ca43 | 237 | pthread_t thr; |
cb5f0589 | 238 | pthread_mutexattr_t attr; |
a205ca43 | 239 | int s; |
4057660b | 240 | |
143e516f MK |
241 | pthread_mutexattr_init(&attr); |
242 | /* initialize the attributes object */ | |
4057660b | 243 | pthread_mutexattr_setrobust(&attr, PTHREAD_MUTEX_ROBUST); |
143e516f | 244 | /* set robustness */ |
cb5f0589 | 245 | |
5d26c00f | 246 | pthread_mutex_init(&mtx, &attr); /* initialize the mutex */ |
cb5f0589 | 247 | |
a205ca43 | 248 | pthread_create(&thr, NULL, original_owner_thread, NULL); |
4057660b MK |
249 | |
250 | sleep(2); | |
251 | ||
a205ca43 | 252 | /* "original_owner_thread" should have exited by now */ |
cb5f0589 | 253 | |
d1a71985 | 254 | printf("[main thread] Attempting to lock the robust mutex.\en"); |
a205ca43 MK |
255 | s = pthread_mutex_lock(&mtx); |
256 | if (s == EOWNERDEAD) { | |
d1a71985 MK |
257 | printf("[main thread] pthread_mutex_lock() returned EOWNERDEAD\en"); |
258 | printf("[main thread] Now make the mutex consistent\en"); | |
a205ca43 MK |
259 | s = pthread_mutex_consistent(&mtx); |
260 | if (s != 0) | |
91fd35ad | 261 | handle_error_en(s, "pthread_mutex_consistent"); |
d1a71985 | 262 | printf("[main thread] Mutex is now consistent; unlocking\en"); |
a205ca43 MK |
263 | s = pthread_mutex_unlock(&mtx); |
264 | if (s != 0) | |
91fd35ad | 265 | handle_error_en(s, "pthread_mutex_unlock"); |
cb5f0589 | 266 | |
a205ca43 MK |
267 | exit(EXIT_SUCCESS); |
268 | } else if (s == 0) { | |
d1a71985 | 269 | printf("[main thread] pthread_mutex_lock() unexpectedly succeeded\en"); |
91fd35ad | 270 | exit(EXIT_FAILURE); |
a205ca43 | 271 | } else { |
d1a71985 | 272 | printf("[main thread] pthread_mutex_lock() unexpectedly failed\en"); |
91fd35ad | 273 | handle_error_en(s, "pthread_mutex_lock"); |
a205ca43 | 274 | } |
cb5f0589 YR |
275 | } |
276 | .EE | |
277 | .SH SEE ALSO | |
278 | .ad l | |
279 | .nh | |
8fbf748d MK |
280 | .BR get_robust_list (2), |
281 | .BR set_robust_list (2), | |
cb5f0589 YR |
282 | .BR pthread_mutex_init (3), |
283 | .BR pthread_mutex_consistent (3), | |
ad2825bf | 284 | .BR pthread_mutex_lock (3), |
cb5f0589 | 285 | .BR pthreads (7) |