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