1PTHREAD_MUTEXATTR_SETROBUST(L3i)nux Programmer's ManPuTaHlREAD_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

SYNOPSIS

10       #include <pthread.h>
11
12       int pthread_mutexattr_getrobust(const pthread_mutexattr_t *attr,
13                                       int *robustness);
14       int pthread_mutexattr_setrobust(pthread_mutexattr_t *attr,
15                                       int robustness);
16
17       Compile and link with -pthread.
18
19   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
20
21       pthread_mutexattr_getrobust(), pthread_mutexattr_setrobust():
22           _POSIX_C_SOURCE >= 200809L
23

DESCRIPTION

25       The pthread_mutexattr_getrobust() function places the value of the  ro‐
26       bustness  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 re‐
29       ferred to by attr to the value specified in *robustness.
30
31       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
35       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 pthread_mu‐
40              tex_lock(3) on the mutex will block indefinitely.
41
42       PTHREAD_MUTEX_ROBUST
43              If a mutex is initialized with the  PTHREAD_MUTEX_ROBUST  attri‐
44              bute  and  its  owner  dies without unlocking it, any future at‐
45              tempts to call pthread_mutex_lock(3) on this mutex will  succeed
46              and  return  EOWNERDEAD  to  indicate that the original owner no
47              longer exists and the mutex is in an inconsistent  state.   Usu‐
48              ally  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
52              If  the  next  owner  unlocks  the mutex using pthread_mutex_un‐
53              lock(3) before making it consistent, the mutex  will  be  perma‐
54              nently  unusable  and  any  subsequent attempts to lock it using
55              pthread_mutex_lock(3) will fail with the error  ENOTRECOVERABLE.
56              The  only  permitted  operation  on  such a mutex is pthread_mu‐
57              tex_destroy(3).
58
59              If the next owner terminates before  calling  pthread_mutex_con‐
60              sistent(3), further pthread_mutex_lock(3) operations on this mu‐
61              tex will still return EOWNERDEAD.
62
63       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

RETURN VALUE

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

ERRORS

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

VERSIONS

80       pthread_mutexattr_getrobust()  and  pthread_mutexattr_setrobust()  were
81       added to glibc in version 2.12.
82

CONFORMING TO

84       POSIX.1-2008.
85

NOTES

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 mu‐
90       tex.  POSIX.1 does not specify this detail, but the same behavior  also
91       occurs in at least some other implementations.
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       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
102       Correspondingly, the constants PTHREAD_MUTEX_STALLED_NP and PTHREAD_MU‐
103       TEX_ROBUST_NP were also defined.
104
105       These GNU-specific APIs, which first appeared in glibc 2.4,  are  nowa‐
106       days  obsolete and should not be used in new programs; since glibc 2.34
107       these APIs are marked as deprecated.
108

EXAMPLES

110       The program below demonstrates the use of the robustness attribute of a
111       mutex  attributes  object.  In this program, a thread holding the mutex
112       dies prematurely without unlocking the mutex.  The main  thread  subse‐
113       quently  acquires the mutex successfully and gets the error EOWNERDEAD,
114       after which it makes the mutex consistent.
115
116       The following shell session shows what we see when  running  this  pro‐
117       gram:
118
119           $ ./a.out
120           [original owner] Setting lock...
121           [original owner] Locked. Now exiting without unlocking.
122           [main] Attempting to lock the robust mutex.
123           [main] pthread_mutex_lock() returned EOWNERDEAD
124           [main] Now make the mutex consistent
125           [main] Mutex is now consistent; unlocking
126
127   Program source
128       #include <stdlib.h>
129       #include <stdio.h>
130       #include <unistd.h>
131       #include <pthread.h>
132       #include <errno.h>
133
134       #define handle_error_en(en, msg) \
135               do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
136
137       static pthread_mutex_t mtx;
138
139       static void *
140       original_owner_thread(void *ptr)
141       {
142           printf("[original owner] Setting lock...\n");
143           pthread_mutex_lock(&mtx);
144           printf("[original owner] Locked. Now exiting without unlocking.\n");
145           pthread_exit(NULL);
146       }
147
148       int
149       main(int argc, char *argv[])
150       {
151           pthread_t thr;
152           pthread_mutexattr_t attr;
153           int s;
154
155           pthread_mutexattr_init(&attr);
156
157           pthread_mutexattr_setrobust(&attr, PTHREAD_MUTEX_ROBUST);
158
159           pthread_mutex_init(&mtx, &attr);
160
161           pthread_create(&thr, NULL, original_owner_thread, NULL);
162
163           sleep(2);
164
165           /* "original_owner_thread" should have exited by now. */
166
167           printf("[main] Attempting to lock the robust mutex.\n");
168           s = pthread_mutex_lock(&mtx);
169           if (s == EOWNERDEAD) {
170               printf("[main] pthread_mutex_lock() returned EOWNERDEAD\n");
171               printf("[main] 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] 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
180               exit(EXIT_SUCCESS);
181           } else if (s == 0) {
182               printf("[main] pthread_mutex_lock() unexpectedly succeeded\n");
183               exit(EXIT_FAILURE);
184           } else {
185               printf("[main] pthread_mutex_lock() unexpectedly failed\n");
186               handle_error_en(s, "pthread_mutex_lock");
187           }
188       }
189

SEE ALSO

191       get_robust_list(2), set_robust_list(2), pthread_mutex_consistent(3),
192       pthread_mutex_init(3), pthread_mutex_lock(3), pthreads(7)
193

COLOPHON

195       This page is part of release 5.12 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/.
199
200
201
202Linux                             2021-03-22    PTHREAD_MUTEXATTR_SETROBUST(3)
Impressum