1PTHREAD_MUTEXATTR_SETROBUST(L3i)nux Programmer's ManPuTaHlREAD_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 #include <pthread.h>
11 int pthread_mutexattr_getrobust(const pthread_mutexattr_t *attr,
13 int *robustness);
14 int pthread_mutexattr_setrobust(const pthread_mutexattr_t *attr,
15 int robustness);
16 Compile and link with -pthread.
18 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
20 pthread_mutexattr_getrobust(), pthread_mutexattr_setrobust():
22 _POSIX_C_SOURCE >= 200809L
23
25 The pthread_mutexattr_getrobust() function places the value of the
26 robustness attribute of the mutex attributes object referred to by attr
27 in *robustness. The pthread_mutexattr_setrobust() function sets the
28 value of the robustness attribute of the mutex attributes object
29 referred to by attr to the value specified in *robustness.
30 The robustness attribute specifies the behavior of the mutex when the
32 owning thread dies without unlocking the mutex. The following values
33 are valid for robustness:
34 PTHREAD_MUTEX_STALLED
36 This is the default value for a mutex attributes object. If a
37 mutex is initialized with the PTHREAD_MUTEX_STALLED attribute
38 and its owner dies without unlocking it, the mutex remains
39 locked afterwards and any future attempts to call
40 pthread_mutex_lock(3) on the mutex will block indefinitely.
41 PTHREAD_MUTEX_ROBUST
43 If a mutex is initialized with the PTHREAD_MUTEX_ROBUST
44 attribute and its owner dies without unlocking it, any future
45 attempts to call pthread_mutex_lock(3) on this mutex will suc‐
46 ceed and return EOWNERDEAD to indicate that the original owner
47 no longer exists and the mutex is in an inconsistent state.
48 Usually after EOWNERDEAD is returned, the next owner should call
49 pthread_mutex_consistent(3) on the acquired mutex to make it
50 consistent again before using it any further.
51 If the next owner unlocks the mutex using
53 pthread_mutex_unlock(3) before making it consistent, the mutex
54 will be permanently unusable and any subsequent attempts to lock
55 it using pthread_mutex_lock(3) will fail with the error ENOTRE‐
56 COVERABLE. The only permitted operation on such a mutex is
57 pthread_mutex_destroy(3).
58 If the next owner terminates before calling pthread_mutex_con‐
60 sistent(3), further pthread_mutex_lock(3) operations on this
61 mutex will still return EOWNERDEAD.
62 Note that the attr argument of pthread_mutexattr_getrobust() and
64 pthread_mutexattr_setrobust() should refer to a mutex attributes object
65 that was initialized by pthread_mutexattr_init(3), otherwise the behav‐
66 ior is undefined.
67
69 On success, these functions return 0. On error, they return a positive
70 error number.
71 In the glibc implementation, pthread_mutexattr_getrobust() always
73 return zero.
74
76 EINVAL A value other than PTHREAD_MUTEX_STALLED or PTHREAD_MUTEX_ROBUST
77 was passed to pthread_mutexattr_setrobust().
78
80 pthread_mutexattr_getrobust() and pthread_mutexattr_setrobust() were
81 added to glibc in version 2.12.
82
84 POSIX.1-2008.
85
87 In the Linux implementation, when using process-shared robust mutexes,
88 a waiting thread also receives the EOWNERDEAD notification if the owner
89 of a robust mutex performs an execve(2) without first unlocking the
90 mutex. POSIX.1 does not specify this detail, but the same behavior
91 also occurs in at least some other implementations.
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 int pthread_mutexattr_getrobust_np(const pthread_mutexattr_t *attr,
98 int *robustness);
99 int pthread_mutexattr_setrobust_np(const pthread_mutexattr_t *attr,
100 int robustness);
101 Correspondingly, the constants PTHREAD_MUTEX_STALLED_NP and
103 PTHREAD_MUTEX_ROBUST_NP were also defined.
104 These GNU-specific APIs, which first appeared in glibc 2.4, are nowa‐
106 days obsolete and should not be used in new programs.
107
109 The program below demonstrates the use of the robustness attribute of a
110 mutex attributes object. In this program, a thread holding the mutex
111 dies prematurely without unlocking the mutex. The main thread subse‐
112 quently acquires the mutex successfully and gets the error EOWNERDEAD,
113 after which it makes the mutex consistent.
114 The following shell session shows what we see when running this pro‐
116 gram:
117 $ ./a.out
119 [original owner] Setting lock...
120 [original owner] Locked. Now exiting without unlocking.
121 [main thread] Attempting to lock the robust mutex.
122 [main thread] pthread_mutex_lock() returned EOWNERDEAD
123 [main thread] Now make the mutex consistent
124 [main thread] Mutex is now consistent; unlocking
125 Program source
127 #include <stdlib.h>
128 #include <stdio.h>
129 #include <unistd.h>
130 #include <pthread.h>
131 #include <errno.h>
132 #define handle_error_en(en, msg) \
134 do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
135 static pthread_mutex_t mtx;
137 static void *
139 original_owner_thread(void *ptr)
140 {
141 printf("[original owner] Setting lock...\n");
142 pthread_mutex_lock(&mtx);
143 printf("[original owner] Locked. Now exiting without unlocking.\n");
144 pthread_exit(NULL);
145 }
146 int
148 main(int argc, char *argv[])
149 {
150 pthread_t thr;
151 pthread_mutexattr_t attr;
152 int s;
153 pthread_mutexattr_init(&attr);
155 /* initialize the attributes object */
156 pthread_mutexattr_setrobust(&attr, PTHREAD_MUTEX_ROBUST);
157 /* set robustness */
158 pthread_mutex_init(&mtx, &attr); /* initialize the mutex */
160 pthread_create(&thr, NULL, original_owner_thread, NULL);
162 sleep(2);
164 /* "original_owner_thread" should have exited by now */
166 printf("[main thread] Attempting to lock the robust mutex.\n");
168 s = pthread_mutex_lock(&mtx);
169 if (s == EOWNERDEAD) {
170 printf("[main thread] pthread_mutex_lock() returned EOWNERDEAD\n");
171 printf("[main thread] Now make the mutex consistent\n");
172 s = pthread_mutex_consistent(&mtx);
173 if (s != 0)
174 handle_error_en(s, "pthread_mutex_consistent");
175 printf("[main thread] Mutex is now consistent; unlocking\n");
176 s = pthread_mutex_unlock(&mtx);
177 if (s != 0)
178 handle_error_en(s, "pthread_mutex_unlock");
179 exit(EXIT_SUCCESS);
181 } else if (s == 0) {
182 printf("[main thread] pthread_mutex_lock() unexpectedly succeeded\n");
183 exit(EXIT_FAILURE);
184 } else {
185 printf("[main thread] pthread_mutex_lock() unexpectedly failed\n");
186 handle_error_en(s, "pthread_mutex_lock");
187 }
188 }
189
191 get_robust_list(2), set_robust_list(2), pthread_mutex_init(3),
192 pthread_mutex_consistent(3), pthread_mutex_lock(3), pthreads(7)
193
195 This page is part of release 4.16 of the Linux man-pages project. A
196 description of the project, information about reporting bugs, and the
197 latest version of this page, can be found at
198 https://www.kernel.org/doc/man-pages/.
199Linux 2017-08-20 PTHREAD_MUTEXATTR_SETROBUST(3)