summaryrefslogtreecommitdiffstats
path: root/man3/pthread_mutexattr_setrobust.3
blob: 802b400ad52c40d29eced748e22be769b6739d48 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
.\" Copyright (c) 2017, Yubin Ruan <ablacktshirt@gmail.com>
.\" and Copyright (c) 2017, Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.TH pthread_mutexattr_setrobust 3 2023-10-31 "Linux man-pages 6.7"
.SH NAME
pthread_mutexattr_getrobust, pthread_mutexattr_setrobust
\- get and set the robustness attribute of a mutex attributes object
.SH LIBRARY
POSIX threads library
.RI ( libpthread ", " \-lpthread )
.SH SYNOPSIS
.nf
.B #include <pthread.h>
.P
.BI "int pthread_mutexattr_getrobust(const pthread_mutexattr_t *" attr ,
.BI "                                int *" robustness ");"
.BI "int pthread_mutexattr_setrobust(pthread_mutexattr_t *" attr ,
.BI "                                int " robustness ");"
.fi
.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
.P
.BR pthread_mutexattr_getrobust (),
.BR pthread_mutexattr_setrobust ():
.nf
    _POSIX_C_SOURCE >= 200809L
.\" FIXME .
.\" But see https://sourceware.org/bugzilla/show_bug.cgi?id=22125
.fi
.SH DESCRIPTION
The
.BR pthread_mutexattr_getrobust ()
function places the value of the robustness attribute of
the mutex attributes object referred to by
.I attr
in
.IR *robustness .
The
.BR pthread_mutexattr_setrobust ()
function sets the value of the robustness attribute of
the mutex attributes object referred to by
.I attr
to the value specified in
.IR *robustness .
.P
The robustness attribute specifies the behavior of the mutex when
the owning thread dies without unlocking the mutex.
The following values are valid for
.IR robustness :
.TP
.B PTHREAD_MUTEX_STALLED
This is the default value for a mutex attributes object.
If a mutex is initialized with the
.B PTHREAD_MUTEX_STALLED
attribute and its owner dies without unlocking it,
the mutex remains locked afterwards and any future attempts to call
.BR pthread_mutex_lock (3)
on the mutex will block indefinitely.
.TP
.B PTHREAD_MUTEX_ROBUST
If a mutex is initialized with the
.B PTHREAD_MUTEX_ROBUST
attribute and its owner dies without unlocking it,
any future attempts to call
.BR pthread_mutex_lock (3)
on this mutex will succeed and return
.B EOWNERDEAD
to indicate that the original owner no longer exists and the mutex is in
an inconsistent state.
Usually after
.B EOWNERDEAD
is returned, the next owner should call
.BR pthread_mutex_consistent (3)
on the acquired mutex to make it consistent again before using it any further.
.IP
If the next owner unlocks the mutex using
.BR pthread_mutex_unlock (3)
before making it consistent, the mutex will be permanently unusable and any
subsequent attempts to lock it using
.BR pthread_mutex_lock (3)
will fail with the error
.BR ENOTRECOVERABLE .
The only permitted operation on such a mutex is
.BR pthread_mutex_destroy (3).
.IP
If the next owner terminates before calling
.BR pthread_mutex_consistent (3),
further
.BR pthread_mutex_lock (3)
operations on this mutex will still return
.BR EOWNERDEAD .
.P
Note that the
.I attr
argument of
.BR pthread_mutexattr_getrobust ()
and
.BR pthread_mutexattr_setrobust ()
should refer to a mutex attributes object that was initialized by
.BR pthread_mutexattr_init (3),
otherwise the behavior is undefined.
.SH RETURN VALUE
On success, these functions return 0.
On error, they return a positive error number.
.P
In the glibc implementation,
.BR pthread_mutexattr_getrobust ()
always return zero.
.SH ERRORS
.TP
.B EINVAL
A value other than
.B PTHREAD_MUTEX_STALLED
or
.B PTHREAD_MUTEX_ROBUST
was passed to
.BR pthread_mutexattr_setrobust ().
.SH VERSIONS
In the Linux implementation,
when using process-shared robust mutexes, a waiting thread also receives the
.B EOWNERDEAD
notification if the owner of a robust mutex performs an
.BR execve (2)
without first unlocking the mutex.
POSIX.1 does not specify this detail,
but the same behavior also occurs in at least some
.\" E.g., Solaris, according to its manual page
other implementations.
.SH STANDARDS
POSIX.1-2008.
.SH HISTORY
glibc 2.12.
POSIX.1-2008.
.P
Before the addition of
.BR pthread_mutexattr_getrobust ()
and
.BR pthread_mutexattr_setrobust ()
to POSIX,
glibc defined the following equivalent nonstandard functions if
.B _GNU_SOURCE
was defined:
.P
.nf
.B [[deprecated]]
.BI "int pthread_mutexattr_getrobust_np(const pthread_mutexattr_t *" attr ,
.BI "                                   int *" robustness ");"
.B [[deprecated]]
.BI "int pthread_mutexattr_setrobust_np(const pthread_mutexattr_t *" attr ,
.BI "                                   int " robustness ");"
.fi
.P
Correspondingly, the constants
.B PTHREAD_MUTEX_STALLED_NP
and
.B PTHREAD_MUTEX_ROBUST_NP
were also defined.
.P
These GNU-specific APIs, which first appeared in glibc 2.4,
are nowadays obsolete and should not be used in new programs;
since glibc 2.34 these APIs are marked as deprecated.
.SH EXAMPLES
The program below demonstrates the use of the robustness attribute of a
mutex attributes object.
In this program, a thread holding the mutex
dies prematurely without unlocking the mutex.
The main thread subsequently acquires the mutex
successfully and gets the error
.BR EOWNERDEAD ,
after which it makes the mutex consistent.
.P
The following shell session shows what we see when running this program:
.P
.in +4n
.EX
$ \fB./a.out\fP
[original owner] Setting lock...
[original owner] Locked. Now exiting without unlocking.
[main] Attempting to lock the robust mutex.
[main] pthread_mutex_lock() returned EOWNERDEAD
[main] Now make the mutex consistent
[main] Mutex is now consistent; unlocking
.EE
.in
.SS Program source
.\" SRC BEGIN (pthread_mutexattr_setrobust.c)
.EX
#include <errno.h>
#include <pthread.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
\&
#define handle_error_en(en, msg) \e
        do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
\&
static pthread_mutex_t mtx;
\&
static void *
original_owner_thread(void *ptr)
{
    printf("[original owner] Setting lock...\en");
    pthread_mutex_lock(&mtx);
    printf("[original owner] Locked. Now exiting without unlocking.\en");
    pthread_exit(NULL);
}
\&
int
main(void)
{
    pthread_t thr;
    pthread_mutexattr_t attr;
    int s;
\&
    pthread_mutexattr_init(&attr);
\&
    pthread_mutexattr_setrobust(&attr, PTHREAD_MUTEX_ROBUST);
\&
    pthread_mutex_init(&mtx, &attr);
\&
    pthread_create(&thr, NULL, original_owner_thread, NULL);
\&
    sleep(2);
\&
    /* "original_owner_thread" should have exited by now. */
\&
    printf("[main] Attempting to lock the robust mutex.\en");
    s = pthread_mutex_lock(&mtx);
    if (s == EOWNERDEAD) {
        printf("[main] pthread_mutex_lock() returned EOWNERDEAD\en");
        printf("[main] Now make the mutex consistent\en");
        s = pthread_mutex_consistent(&mtx);
        if (s != 0)
            handle_error_en(s, "pthread_mutex_consistent");
        printf("[main] Mutex is now consistent; unlocking\en");
        s = pthread_mutex_unlock(&mtx);
        if (s != 0)
            handle_error_en(s, "pthread_mutex_unlock");
\&
        exit(EXIT_SUCCESS);
    } else if (s == 0) {
        printf("[main] pthread_mutex_lock() unexpectedly succeeded\en");
        exit(EXIT_FAILURE);
    } else {
        printf("[main] pthread_mutex_lock() unexpectedly failed\en");
        handle_error_en(s, "pthread_mutex_lock");
    }
}
.EE
.\" SRC END
.SH SEE ALSO
.ad l
.nh
.BR get_robust_list (2),
.BR set_robust_list (2),
.BR pthread_mutex_consistent (3),
.BR pthread_mutex_init (3),
.BR pthread_mutex_lock (3),
.BR pthreads (7)