1pthread_mutexattr_setrobust(L3i)brary Functions Manupatlhread_mutexattr_setrobust(3)
2
6 pthread_mutexattr_getrobust, pthread_mutexattr_setrobust - get and set
7 the robustness attribute of a mutex attributes object
8
10 POSIX threads library (libpthread, -lpthread)
11
13 #include <pthread.h>
14 int pthread_mutexattr_getrobust(const pthread_mutexattr_t *attr,
16 int *robustness);
17 int pthread_mutexattr_setrobust(pthread_mutexattr_t *attr,
18 int robustness);
19 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
21 pthread_mutexattr_getrobust(), pthread_mutexattr_setrobust():
23 _POSIX_C_SOURCE >= 200809L
24
26 The pthread_mutexattr_getrobust() function places the value of the ro‐
27 bustness attribute of the mutex attributes object referred to by attr
28 in *robustness. The pthread_mutexattr_setrobust() function sets the
29 value of the robustness attribute of the mutex attributes object re‐
30 ferred to by attr to the value specified in *robustness.
31 The robustness attribute specifies the behavior of the mutex when the
33 owning thread dies without unlocking the mutex. The following values
34 are valid for robustness:
35 PTHREAD_MUTEX_STALLED
37 This is the default value for a mutex attributes object. If a
38 mutex is initialized with the PTHREAD_MUTEX_STALLED attribute
39 and its owner dies without unlocking it, the mutex remains
40 locked afterwards and any future attempts to call pthread_mu‐
41 tex_lock(3) on the mutex will block indefinitely.
42 PTHREAD_MUTEX_ROBUST
44 If a mutex is initialized with the PTHREAD_MUTEX_ROBUST attri‐
45 bute and its owner dies without unlocking it, any future at‐
46 tempts to call pthread_mutex_lock(3) on this mutex will succeed
47 and return EOWNERDEAD to indicate that the original owner no
48 longer exists and the mutex is in an inconsistent state. Usu‐
49 ally after EOWNERDEAD is returned, the next owner should call
50 pthread_mutex_consistent(3) on the acquired mutex to make it
51 consistent again before using it any further.
52 If the next owner unlocks the mutex using pthread_mutex_un‐
54 lock(3) before making it consistent, the mutex will be perma‐
55 nently unusable and any subsequent attempts to lock it using
56 pthread_mutex_lock(3) will fail with the error ENOTRECOVERABLE.
57 The only permitted operation on such a mutex is pthread_mu‐
58 tex_destroy(3).
59 If the next owner terminates before calling pthread_mutex_con‐
61 sistent(3), further pthread_mutex_lock(3) operations on this mu‐
62 tex will still return EOWNERDEAD.
63 Note that the attr argument of pthread_mutexattr_getrobust() and
65 pthread_mutexattr_setrobust() should refer to a mutex attributes object
66 that was initialized by pthread_mutexattr_init(3), otherwise the behav‐
67 ior is undefined.
68
70 On success, these functions return 0. On error, they return a positive
71 error number.
72 In the glibc implementation, pthread_mutexattr_getrobust() always re‐
74 turn zero.
75
77 EINVAL A value other than PTHREAD_MUTEX_STALLED or PTHREAD_MUTEX_ROBUST
78 was passed to pthread_mutexattr_setrobust().
79
81 In the Linux implementation, when using process-shared robust mutexes,
82 a waiting thread also receives the EOWNERDEAD notification if the owner
83 of a robust mutex performs an execve(2) without first unlocking the mu‐
84 tex. POSIX.1 does not specify this detail, but the same behavior also
85 occurs in at least some other implementations.
86
88 POSIX.1-2008.
89
91 glibc 2.12. POSIX.1-2008.
92 Before the addition of pthread_mutexattr_getrobust() and pthread_mutex‐
94 attr_setrobust() to POSIX, glibc defined the following equivalent non‐
95 standard functions if _GNU_SOURCE was defined:
96 [[deprecated]]
98 int pthread_mutexattr_getrobust_np(const pthread_mutexattr_t *attr,
99 int *robustness);
100 [[deprecated]]
101 int pthread_mutexattr_setrobust_np(const pthread_mutexattr_t *attr,
102 int robustness);
103 Correspondingly, the constants PTHREAD_MUTEX_STALLED_NP and PTHREAD_MU‐
105 TEX_ROBUST_NP were also defined.
106 These GNU-specific APIs, which first appeared in glibc 2.4, are nowa‐
108 days obsolete and should not be used in new programs; since glibc 2.34
109 these APIs are marked as deprecated.
110
112 The program below demonstrates the use of the robustness attribute of a
113 mutex attributes object. In this program, a thread holding the mutex
114 dies prematurely without unlocking the mutex. The main thread subse‐
115 quently acquires the mutex successfully and gets the error EOWNERDEAD,
116 after which it makes the mutex consistent.
117 The following shell session shows what we see when running this pro‐
119 gram:
120 $ ./a.out
122 [original owner] Setting lock...
123 [original owner] Locked. Now exiting without unlocking.
124 [main] Attempting to lock the robust mutex.
125 [main] pthread_mutex_lock() returned EOWNERDEAD
126 [main] Now make the mutex consistent
127 [main] Mutex is now consistent; unlocking
128 Program source
130 #include <errno.h>
131 #include <pthread.h>
132 #include <stdio.h>
133 #include <stdlib.h>
134 #include <unistd.h>
135 #define handle_error_en(en, msg) \
137 do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
138 static pthread_mutex_t mtx;
140 static void *
142 original_owner_thread(void *ptr)
143 {
144 printf("[original owner] Setting lock...\n");
145 pthread_mutex_lock(&mtx);
146 printf("[original owner] Locked. Now exiting without unlocking.\n");
147 pthread_exit(NULL);
148 }
149 int
151 main(void)
152 {
153 pthread_t thr;
154 pthread_mutexattr_t attr;
155 int s;
156 pthread_mutexattr_init(&attr);
158 pthread_mutexattr_setrobust(&attr, PTHREAD_MUTEX_ROBUST);
160 pthread_mutex_init(&mtx, &attr);
162 pthread_create(&thr, NULL, original_owner_thread, NULL);
164 sleep(2);
166 /* "original_owner_thread" should have exited by now. */
168 printf("[main] Attempting to lock the robust mutex.\n");
170 s = pthread_mutex_lock(&mtx);
171 if (s == EOWNERDEAD) {
172 printf("[main] pthread_mutex_lock() returned EOWNERDEAD\n");
173 printf("[main] Now make the mutex consistent\n");
174 s = pthread_mutex_consistent(&mtx);
175 if (s != 0)
176 handle_error_en(s, "pthread_mutex_consistent");
177 printf("[main] Mutex is now consistent; unlocking\n");
178 s = pthread_mutex_unlock(&mtx);
179 if (s != 0)
180 handle_error_en(s, "pthread_mutex_unlock");
181 exit(EXIT_SUCCESS);
183 } else if (s == 0) {
184 printf("[main] pthread_mutex_lock() unexpectedly succeeded\n");
185 exit(EXIT_FAILURE);
186 } else {
187 printf("[main] pthread_mutex_lock() unexpectedly failed\n");
188 handle_error_en(s, "pthread_mutex_lock");
189 }
190 }
191
193 get_robust_list(2), set_robust_list(2), pthread_mutex_consistent(3),
194 pthread_mutex_init(3), pthread_mutex_lock(3), pthreads(7)
195Linux man-pages 6.05 2023-05-03 pthread_mutexattr_setrobust(3)