man3/pthread_mutexattr_setrobust.3

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