Debian Codegraph @

upstream/debian-trixie/man3/pthread_mutexattr_setrobust.3

raw
1 .\" Copyright (c) 2017, Yubin Ruan <[email protected]>
2 .\" and Copyright (c) 2017, Michael Kerrisk <[email protected]>
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH pthread_mutexattr_setrobust 3 2024-06-15 "Linux man-pages 6.9.1"
7 .SH NAME
8 pthread_mutexattr_getrobust, pthread_mutexattr_setrobust
9 \- get and set the robustness attribute of a mutex attributes object
10 .SH LIBRARY
11 POSIX threads library
12 .RI ( libpthread ", " \-lpthread )
13 .SH SYNOPSIS
14 .nf
15 .B #include <pthread.h>
16 .P
17 .BI "int pthread_mutexattr_getrobust(const pthread_mutexattr_t *" attr ,
18 .BI " int *" robustness ");"
19 .BI "int pthread_mutexattr_setrobust(pthread_mutexattr_t *" attr ,
20 .BI " int " robustness ");"
21 .fi
22 .P
23 .RS -4
24 Feature Test Macro Requirements for glibc (see
25 .BR feature_test_macros (7)):
26 .RE
27 .P
28 .BR pthread_mutexattr_getrobust (),
29 .BR pthread_mutexattr_setrobust ():
30 .nf
31 _POSIX_C_SOURCE >= 200809L
32 .\" FIXME .
33 .\" But see https://sourceware.org/bugzilla/show_bug.cgi?id=22125
34 .fi
35 .SH DESCRIPTION
36 The
37 .BR pthread_mutexattr_getrobust ()
38 function places the value of the robustness attribute of
39 the mutex attributes object referred to by
40 .I attr
41 in
42 .IR *robustness .
43 The
44 .BR pthread_mutexattr_setrobust ()
45 function sets the value of the robustness attribute of
46 the mutex attributes object referred to by
47 .I attr
48 to the value specified in
49 .IR *robustness .
50 .P
51 The robustness attribute specifies the behavior of the mutex when
52 the owning thread dies without unlocking the mutex.
53 The following values are valid for
54 .IR robustness :
55 .TP
56 .B PTHREAD_MUTEX_STALLED
57 This is the default value for a mutex attributes object.
58 If a mutex is initialized with the
59 .B PTHREAD_MUTEX_STALLED
60 attribute and its owner dies without unlocking it,
61 the mutex remains locked afterwards and any future attempts to call
62 .BR pthread_mutex_lock (3)
63 on the mutex will block indefinitely.
64 .TP
65 .B PTHREAD_MUTEX_ROBUST
66 If a mutex is initialized with the
67 .B PTHREAD_MUTEX_ROBUST
68 attribute and its owner dies without unlocking it,
69 any future attempts to call
70 .BR pthread_mutex_lock (3)
71 on this mutex will succeed and return
72 .B EOWNERDEAD
73 to indicate that the original owner no longer exists and the mutex is in
74 an inconsistent state.
75 Usually after
76 .B EOWNERDEAD
77 is returned, the next owner should call
78 .BR pthread_mutex_consistent (3)
79 on the acquired mutex to make it consistent again before using it any further.
80 .IP
81 If the next owner unlocks the mutex using
82 .BR pthread_mutex_unlock (3)
83 before making it consistent, the mutex will be permanently unusable and any
84 subsequent attempts to lock it using
85 .BR pthread_mutex_lock (3)
86 will fail with the error
87 .BR ENOTRECOVERABLE .
88 The only permitted operation on such a mutex is
89 .BR pthread_mutex_destroy (3).
90 .IP
91 If the next owner terminates before calling
92 .BR pthread_mutex_consistent (3),
93 further
94 .BR pthread_mutex_lock (3)
95 operations on this mutex will still return
96 .BR EOWNERDEAD .
97 .P
98 Note that the
99 .I attr
100 argument of
101 .BR pthread_mutexattr_getrobust ()
102 and
103 .BR pthread_mutexattr_setrobust ()
104 should refer to a mutex attributes object that was initialized by
105 .BR pthread_mutexattr_init (3),
106 otherwise the behavior is undefined.
107 .SH RETURN VALUE
108 On success, these functions return 0.
109 On error, they return a positive error number.
110 .P
111 In the glibc implementation,
112 .BR pthread_mutexattr_getrobust ()
113 always return zero.
114 .SH ERRORS
115 .TP
116 .B EINVAL
117 A value other than
118 .B PTHREAD_MUTEX_STALLED
119 or
120 .B PTHREAD_MUTEX_ROBUST
121 was passed to
122 .BR pthread_mutexattr_setrobust ().
123 .SH VERSIONS
124 In the Linux implementation,
125 when using process-shared robust mutexes, a waiting thread also receives the
126 .B EOWNERDEAD
127 notification if the owner of a robust mutex performs an
128 .BR execve (2)
129 without first unlocking the mutex.
130 POSIX.1 does not specify this detail,
131 but the same behavior also occurs in at least some
132 .\" E.g., Solaris, according to its manual page
133 other implementations.
134 .SH STANDARDS
135 POSIX.1-2008.
136 .SH HISTORY
137 glibc 2.12.
138 POSIX.1-2008.
139 .P
140 Before the addition of
141 .BR pthread_mutexattr_getrobust ()
142 and
143 .BR pthread_mutexattr_setrobust ()
144 to POSIX,
145 glibc defined the following equivalent nonstandard functions if
146 .B _GNU_SOURCE
147 was defined:
148 .P
149 .nf
150 .B [[deprecated]]
151 .BI "int pthread_mutexattr_getrobust_np(const pthread_mutexattr_t *" attr ,
152 .BI " int *" robustness ");"
153 .B [[deprecated]]
154 .BI "int pthread_mutexattr_setrobust_np(const pthread_mutexattr_t *" attr ,
155 .BI " int " robustness ");"
156 .fi
157 .P
158 Correspondingly, the constants
159 .B PTHREAD_MUTEX_STALLED_NP
160 and
161 .B PTHREAD_MUTEX_ROBUST_NP
162 were also defined.
163 .P
164 These GNU-specific APIs, which first appeared in glibc 2.4,
165 are nowadays obsolete and should not be used in new programs;
166 since glibc 2.34 these APIs are marked as deprecated.
167 .SH EXAMPLES
168 The program below demonstrates the use of the robustness attribute of a
169 mutex attributes object.
170 In this program, a thread holding the mutex
171 dies prematurely without unlocking the mutex.
172 The main thread subsequently acquires the mutex
173 successfully and gets the error
174 .BR EOWNERDEAD ,
175 after which it makes the mutex consistent.
176 .P
177 The following shell session shows what we see when running this program:
178 .P
179 .in +4n
180 .EX
181 $ \fB./a.out\fP
182 [original owner] Setting lock...
183 [original owner] Locked. Now exiting without unlocking.
184 [main] Attempting to lock the robust mutex.
185 [main] pthread_mutex_lock() returned EOWNERDEAD
186 [main] Now make the mutex consistent
187 [main] Mutex is now consistent; unlocking
188 .EE
189 .in
190 .SS Program source
191 .\" SRC BEGIN (pthread_mutexattr_setrobust.c)
192 .EX
193 #include <errno.h>
194 #include <pthread.h>
195 #include <stdio.h>
196 #include <stdlib.h>
197 #include <unistd.h>
198 \&
199 #define handle_error_en(en, msg) \[rs]
200 do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
201 \&
202 static pthread_mutex_t mtx;
203 \&
204 static void *
205 original_owner_thread(void *ptr)
206 {
207 printf("[original owner] Setting lock...\[rs]n");
208 pthread_mutex_lock(&mtx);
209 printf("[original owner] Locked. Now exiting without unlocking.\[rs]n");
210 pthread_exit(NULL);
211 }
212 \&
213 int
214 main(void)
215 {
216 pthread_t thr;
217 pthread_mutexattr_t attr;
218 int s;
219 \&
220 pthread_mutexattr_init(&attr);
221 \&
222 pthread_mutexattr_setrobust(&attr, PTHREAD_MUTEX_ROBUST);
223 \&
224 pthread_mutex_init(&mtx, &attr);
225 \&
226 pthread_create(&thr, NULL, original_owner_thread, NULL);
227 \&
228 sleep(2);
229 \&
230 /* "original_owner_thread" should have exited by now. */
231 \&
232 printf("[main] Attempting to lock the robust mutex.\[rs]n");
233 s = pthread_mutex_lock(&mtx);
234 if (s == EOWNERDEAD) {
235 printf("[main] pthread_mutex_lock() returned EOWNERDEAD\[rs]n");
236 printf("[main] Now make the mutex consistent\[rs]n");
237 s = pthread_mutex_consistent(&mtx);
238 if (s != 0)
239 handle_error_en(s, "pthread_mutex_consistent");
240 printf("[main] Mutex is now consistent; unlocking\[rs]n");
241 s = pthread_mutex_unlock(&mtx);
242 if (s != 0)
243 handle_error_en(s, "pthread_mutex_unlock");
244 \&
245 exit(EXIT_SUCCESS);
246 } else if (s == 0) {
247 printf("[main] pthread_mutex_lock() unexpectedly succeeded\[rs]n");
248 exit(EXIT_FAILURE);
249 } else {
250 printf("[main] pthread_mutex_lock() unexpectedly failed\[rs]n");
251 handle_error_en(s, "pthread_mutex_lock");
252 }
253 }
254 .EE
255 .\" SRC END
256 .SH SEE ALSO
257 .ad l
258 .nh
259 .BR get_robust_list (2),
260 .BR set_robust_list (2),
261 .BR pthread_mutex_consistent (3),
262 .BR pthread_mutex_init (3),
263 .BR pthread_mutex_lock (3),
264 .BR pthreads (7)