Changes.old: Add missing entry in 5.13 changelog
[man-pages.git] / man3 / pthread_mutexattr_setrobust.3
blob86aab88ed0a380e080c37273ca4207673ab62081
1 .\" Copyright (c) 2017, Yubin Ruan <ablacktshirt@gmail.com>
2 .\" and Copyright (c) 2017, Michael Kerrisk <mtk.manpages@gmail.com>
3 .\"
4 .\" %%%LICENSE_START(VERBATIM)
5 .\" Permission is granted to make and distribute verbatim copies of this
6 .\" manual provided the copyright notice and this permission notice are
7 .\" preserved on all copies.
8 .\"
9 .\" Permission is granted to copy and distribute modified versions of this
10 .\" manual under the conditions for verbatim copying, provided that the
11 .\" entire resulting derived work is distributed under the terms of a
12 .\" permission notice identical to this one.
13 .\"
14 .\" Since the Linux kernel and libraries are constantly changing, this
15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
16 .\" responsibility for errors or omissions, or for damages resulting from
17 .\" the use of the information contained herein.  The author(s) may not
18 .\" have taken the same level of care in the production of this manual,
19 .\" which is licensed free of charge, as they might when working
20 .\" professionally.
21 .\"
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
24 .\" %%%LICENSE_END
25 .\"
26 .TH PTHREAD_MUTEXATTR_SETROBUST 3 2021-03-22 "Linux" "Linux Programmer's Manual"
27 .SH NAME
28 pthread_mutexattr_getrobust, pthread_mutexattr_setrobust
29 \- get and set the robustness attribute of a mutex attributes object
30 .SH SYNOPSIS
31 .nf
32 .B #include <pthread.h>
33 .PP
34 .BI "int pthread_mutexattr_getrobust(const pthread_mutexattr_t *" attr ,
35 .BI "                                int *" robustness ");"
36 .BI "int pthread_mutexattr_setrobust(pthread_mutexattr_t *" attr ,
37 .BI "                                int " robustness ");"
38 .fi
39 .PP
40 Compile and link with \fI\-pthread\fP.
41 .PP
42 .RS -4
43 Feature Test Macro Requirements for glibc (see
44 .BR feature_test_macros (7)):
45 .RE
46 .PP
47 .BR pthread_mutexattr_getrobust (),
48 .BR pthread_mutexattr_setrobust ():
49 .nf
50     _POSIX_C_SOURCE >= 200809L
51 .\" FIXME .
52 .\" But see https://sourceware.org/bugzilla/show_bug.cgi?id=22125
53 .fi
54 .SH DESCRIPTION
55 The
56 .BR pthread_mutexattr_getrobust ()
57 function places the value of the robustness attribute of
58 the mutex attributes object referred to by
59 .I attr
61 .IR *robustness .
62 The
63 .BR pthread_mutexattr_setrobust ()
64 function sets the value of the robustness attribute of
65 the mutex attributes object referred to by
66 .I attr
67 to the value specified in
68 .IR *robustness .
69 .PP
70 The robustness attribute specifies the behavior of the mutex when
71 the owning thread dies without unlocking the mutex.
72 The following values are valid for
73 .IR robustness :
74 .TP
75 .BR PTHREAD_MUTEX_STALLED
76 This is the default value for a mutex attributes object.
77 If a mutex is initialized with the
78 .BR PTHREAD_MUTEX_STALLED
79 attribute and its owner dies without unlocking it,
80 the mutex remains locked afterwards and any future attempts to call
81 .BR pthread_mutex_lock (3)
82 on the mutex will block indefinitely.
83 .TP
84 .B PTHREAD_MUTEX_ROBUST
85 If a mutex is initialized with the
86 .BR PTHREAD_MUTEX_ROBUST
87 attribute and its owner dies without unlocking it,
88 any future attempts to call
89 .BR pthread_mutex_lock (3)
90 on this mutex will succeed and return
91 .B EOWNERDEAD
92 to indicate that the original owner no longer exists and the mutex is in
93 an inconsistent state.
94 Usually after
95 .B EOWNERDEAD
96 is returned, the next owner should call
97 .BR pthread_mutex_consistent (3)
98 on the acquired mutex to make it consistent again before using it any further.
99 .IP
100 If the next owner unlocks the mutex using
101 .BR pthread_mutex_unlock (3)
102 before making it consistent, the mutex will be permanently unusable and any
103 subsequent attempts to lock it using
104 .BR pthread_mutex_lock (3)
105 will fail with the error
106 .BR ENOTRECOVERABLE .
107 The only permitted operation on such a mutex is
108 .BR pthread_mutex_destroy (3).
110 If the next owner terminates before calling
111 .BR pthread_mutex_consistent (3),
112 further
113 .BR pthread_mutex_lock (3)
114 operations on this mutex will still return
115 .BR EOWNERDEAD .
117 Note that the
118 .IR attr
119 argument of
120 .BR pthread_mutexattr_getrobust ()
122 .BR pthread_mutexattr_setrobust ()
123 should refer to a mutex attributes object that was initialized by
124 .BR pthread_mutexattr_init (3),
125 otherwise the behavior is undefined.
126 .SH RETURN VALUE
127 On success, these functions return 0.
128 On error, they return a positive error number.
130 In the glibc implementation,
131 .BR pthread_mutexattr_getrobust ()
132 always return zero.
133 .SH ERRORS
135 .B EINVAL
136 A value other than
137 .B PTHREAD_MUTEX_STALLED
139 .B PTHREAD_MUTEX_ROBUST
140 was passed to
141 .BR pthread_mutexattr_setrobust ().
142 .SH VERSIONS
143 .BR pthread_mutexattr_getrobust ()
145 .BR pthread_mutexattr_setrobust ()
146 were added to glibc in version 2.12.
147 .SH CONFORMING TO
148 POSIX.1-2008.
149 .SH NOTES
150 In the Linux implementation,
151 when using process-shared robust mutexes, a waiting thread also receives the
152 .B EOWNERDEAD
153 notification if the owner of a robust mutex performs an
154 .BR execve (2)
155 without first unlocking the mutex.
156 POSIX.1 does not specify this detail,
157 but the same behavior also occurs in at least some
158 .\" E.g., Solaris, according to its manual page
159 other implementations.
161 Before the addition of
162 .BR pthread_mutexattr_getrobust ()
164 .BR pthread_mutexattr_setrobust ()
165 to POSIX,
166 glibc defined the following equivalent nonstandard functions if
167 .BR _GNU_SOURCE
168 was defined:
171 .BI "int pthread_mutexattr_getrobust_np(const pthread_mutexattr_t *" attr ,
172 .BI "                                   int *" robustness ");"
173 .BI "int pthread_mutexattr_setrobust_np(const pthread_mutexattr_t *" attr ,
174 .BI "                                   int " robustness ");"
177 Correspondingly, the constants
178 .B PTHREAD_MUTEX_STALLED_NP
180 .B PTHREAD_MUTEX_ROBUST_NP
181 were also defined.
183 These GNU-specific APIs, which first appeared in glibc 2.4,
184 are nowadays obsolete and should not be used in new programs;
185 since glibc 2.34 these APIs are marked as deprecated.
186 .SH EXAMPLES
187 The program below demonstrates the use of the robustness attribute of a
188 mutex attributes object.
189 In this program, a thread holding the mutex
190 dies prematurely without unlocking the mutex.
191 The main thread subsequently acquires the mutex
192 successfully and gets the error
193 .BR EOWNERDEAD ,
194 after which it makes the mutex consistent.
196 The following shell session shows what we see when running this program:
198 .in +4n
200 $ \fB./a.out\fP
201 [original owner] Setting lock...
202 [original owner] Locked. Now exiting without unlocking.
203 [main] Attempting to lock the robust mutex.
204 [main] pthread_mutex_lock() returned EOWNERDEAD
205 [main] Now make the mutex consistent
206 [main] Mutex is now consistent; unlocking
209 .SS Program source
211 #include <stdlib.h>
212 #include <stdio.h>
213 #include <unistd.h>
214 #include <pthread.h>
215 #include <errno.h>
217 #define handle_error_en(en, msg) \e
218         do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
220 static pthread_mutex_t mtx;
222 static void *
223 original_owner_thread(void *ptr)
225     printf("[original owner] Setting lock...\en");
226     pthread_mutex_lock(&mtx);
227     printf("[original owner] Locked. Now exiting without unlocking.\en");
228     pthread_exit(NULL);
232 main(int argc, char *argv[])
234     pthread_t thr;
235     pthread_mutexattr_t attr;
236     int s;
238     pthread_mutexattr_init(&attr);
240     pthread_mutexattr_setrobust(&attr, PTHREAD_MUTEX_ROBUST);
242     pthread_mutex_init(&mtx, &attr);
244     pthread_create(&thr, NULL, original_owner_thread, NULL);
246     sleep(2);
248     /* "original_owner_thread" should have exited by now. */
250     printf("[main] Attempting to lock the robust mutex.\en");
251     s = pthread_mutex_lock(&mtx);
252     if (s == EOWNERDEAD) {
253         printf("[main] pthread_mutex_lock() returned EOWNERDEAD\en");
254         printf("[main] Now make the mutex consistent\en");
255         s = pthread_mutex_consistent(&mtx);
256         if (s != 0)
257             handle_error_en(s, "pthread_mutex_consistent");
258         printf("[main] Mutex is now consistent; unlocking\en");
259         s = pthread_mutex_unlock(&mtx);
260         if (s != 0)
261             handle_error_en(s, "pthread_mutex_unlock");
263         exit(EXIT_SUCCESS);
264     } else if (s == 0) {
265         printf("[main] pthread_mutex_lock() unexpectedly succeeded\en");
266         exit(EXIT_FAILURE);
267     } else {
268         printf("[main] pthread_mutex_lock() unexpectedly failed\en");
269         handle_error_en(s, "pthread_mutex_lock");
270     }
273 .SH SEE ALSO
274 .ad l
276 .BR get_robust_list (2),
277 .BR set_robust_list (2),
278 .BR pthread_mutex_consistent (3),
279 .BR pthread_mutex_init (3),
280 .BR pthread_mutex_lock (3),
281 .BR pthreads (7)