1pthread_mutexattr_setrobust(L3i)brary Functions Manupatlhread_mutexattr_setrobust(3)
2
3
4

NAME

6       pthread_mutexattr_getrobust,  pthread_mutexattr_setrobust - get and set
7       the robustness attribute of a mutex attributes object
8

LIBRARY

10       POSIX threads library (libpthread, -lpthread)
11

SYNOPSIS

13       #include <pthread.h>
14
15       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
20   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
21
22       pthread_mutexattr_getrobust(), pthread_mutexattr_setrobust():
23           _POSIX_C_SOURCE >= 200809L
24

DESCRIPTION

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
32       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
36       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
43       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
53              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
60              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
64       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

RETURN VALUE

70       On success, these functions return 0.  On error, they return a positive
71       error number.
72
73       In the glibc implementation, pthread_mutexattr_getrobust()  always  re‐
74       turn zero.
75

ERRORS

77       EINVAL A value other than PTHREAD_MUTEX_STALLED or PTHREAD_MUTEX_ROBUST
78              was passed to pthread_mutexattr_setrobust().
79

VERSIONS

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

STANDARDS

88       POSIX.1-2008.
89

HISTORY

91       glibc 2.12.  POSIX.1-2008.
92
93       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
97       [[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
104       Correspondingly, the constants PTHREAD_MUTEX_STALLED_NP and PTHREAD_MU‐
105       TEX_ROBUST_NP were also defined.
106
107       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

EXAMPLES

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
118       The  following  shell  session shows what we see when running this pro‐
119       gram:
120
121           $ ./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
129   Program source
130       #include <errno.h>
131       #include <pthread.h>
132       #include <stdio.h>
133       #include <stdlib.h>
134       #include <unistd.h>
135
136       #define handle_error_en(en, msg) \
137               do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
138
139       static pthread_mutex_t mtx;
140
141       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
150       int
151       main(void)
152       {
153           pthread_t thr;
154           pthread_mutexattr_t attr;
155           int s;
156
157           pthread_mutexattr_init(&attr);
158
159           pthread_mutexattr_setrobust(&attr, PTHREAD_MUTEX_ROBUST);
160
161           pthread_mutex_init(&mtx, &attr);
162
163           pthread_create(&thr, NULL, original_owner_thread, NULL);
164
165           sleep(2);
166
167           /* "original_owner_thread" should have exited by now. */
168
169           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
182               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

SEE ALSO

193       get_robust_list(2), set_robust_list(2), pthread_mutex_consistent(3),
194       pthread_mutex_init(3), pthread_mutex_lock(3), pthreads(7)
195
196
197
198Linux man-pages 6.04              2023-03-30    pthread_mutexattr_setrobust(3)
Impressum