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(const 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
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
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
40              pthread_mutex_lock(3) on the mutex will block indefinitely.
41
42       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
52              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
59              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
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
73       return 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
90       mutex.  POSIX.1 does not specify this detail,  but  the  same  behavior
91       also 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
103       PTHREAD_MUTEX_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.
107

EXAMPLES

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
115       The  following  shell  session shows what we see when running this pro‐
116       gram:
117
118           $ ./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
126   Program source
127       #include <stdlib.h>
128       #include <stdio.h>
129       #include <unistd.h>
130       #include <pthread.h>
131       #include <errno.h>
132
133       #define handle_error_en(en, msg) \
134                      do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
135
136       static pthread_mutex_t mtx;
137
138       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
147       int
148       main(int argc, char *argv[])
149       {
150           pthread_t thr;
151           pthread_mutexattr_t attr;
152           int s;
153
154           pthread_mutexattr_init(&attr);
155                                       /* initialize the attributes object */
156           pthread_mutexattr_setrobust(&attr, PTHREAD_MUTEX_ROBUST);
157                                      /* set robustness */
158
159           pthread_mutex_init(&mtx, &attr);   /* initialize the mutex */
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 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
180               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

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.07 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                             2020-06-09    PTHREAD_MUTEXATTR_SETROBUST(3)
Impressum