diff options
Diffstat (limited to 'man/man3/pthread_mutexattr_setrobust.3')
| -rw-r--r-- | man/man3/pthread_mutexattr_setrobust.3 | 264 |
1 files changed, 264 insertions, 0 deletions
diff --git a/man/man3/pthread_mutexattr_setrobust.3 b/man/man3/pthread_mutexattr_setrobust.3 new file mode 100644 index 000000000..921d9e9c0 --- /dev/null +++ b/man/man3/pthread_mutexattr_setrobust.3 @@ -0,0 +1,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 (date) "Linux man-pages (unreleased)" +.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) |