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 .\" %%%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
  60 in
  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).
 109 .IP
 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 .
 116 .PP
 117 Note that the
 118 .IR attr
 119 argument of
 120 .BR pthread_mutexattr_getrobust ()
 121 and
 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.
 129 .PP
 130 In the glibc implementation,
 131 .BR pthread_mutexattr_getrobust ()
 132 always return zero.
 133 .SH ERRORS
 134 .TP
 135 .B EINVAL
 136 A value other than
 137 .B PTHREAD_MUTEX_STALLED
 138 or
 139 .B PTHREAD_MUTEX_ROBUST
 140 was passed to
 141 .BR pthread_mutexattr_setrobust ().
 142 .SH VERSIONS
 143 .BR pthread_mutexattr_getrobust ()
 144 and
 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.
 160 .PP
 161 Before the addition of
 162 .BR pthread_mutexattr_getrobust ()
 163 and
 164 .BR pthread_mutexattr_setrobust ()
 165 to POSIX,
 166 glibc defined the following equivalent nonstandard functions if
 167 .BR _GNU_SOURCE
 168 was defined:
 169 .PP
 170 .nf
 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 ");"
 175 .fi
 176 .PP
 177 Correspondingly, the constants
 178 .B PTHREAD_MUTEX_STALLED_NP
 179 and
 180 .B PTHREAD_MUTEX_ROBUST_NP
 181 were also defined.
 182 .PP
 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.
 195 .PP
 196 The following shell session shows what we see when running this program:
 197 .PP
 198 .in +4n
 199 .EX
 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
 207 .EE
 208 .in
 209 .SS Program source
 210 .EX
 211 #include <stdlib.h>
 212 #include <stdio.h>
 213 #include <unistd.h>
 214 #include <pthread.h>
 215 #include <errno.h>
 216
 217 #define handle_error_en(en, msg) \e
 218         do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
 219
 220 static pthread_mutex_t mtx;
 221
 222 static void *
 223 original_owner_thread(void *ptr)
 224 {
 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);
 229 }
 230
 231 int
 232 main(int argc, char *argv[])
 233 {
 234     pthread_t thr;
 235     pthread_mutexattr_t attr;
 236     int s;
 237
 238     pthread_mutexattr_init(&attr);
 239
 240     pthread_mutexattr_setrobust(&attr, PTHREAD_MUTEX_ROBUST);
 241
 242     pthread_mutex_init(&mtx, &attr);
 243
 244     pthread_create(&thr, NULL, original_owner_thread, NULL);
 245
 246     sleep(2);
 247
 248     /* "original_owner_thread" should have exited by now. */
 249
 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");
 262
 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     }
 271 }
 272 .EE
 273 .SH SEE ALSO
 274 .ad l
 275 .nh
 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)