Debian Codegraph @

upstream/debian-unstable/man3/pthread_mutexattr_setrobust.3

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