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