Minix Man Pages
home | helpx minix x x minixx PTHREAD_MUTEXATTR_SETROBUSTLinux Programmer's MaPTHREAD_MUTEXATTR_SETROBUST(3) NAME pthread_mutexattr_getrobust, pthread_mutexattr_setrobust - get and set the robustness attribute of a mutex attributes object SYNOPSIS #include <pthread.h> int pthread_mutexattr_getrobust(const pthread_mutexattr_t *attr, int *robustness); int pthread_mutexattr_setrobust(const pthread_mutexattr_t *attr, int robustness); Compile and link with -pthread. Feature Test Macro Requirements for glibc (see feature_test_macros(7)): pthread_mutexattr_getrobust(), pthread_mutexattr_setrobust(): _POSIX_C_SOURCE >= 200809L DESCRIPTION The pthread_mutexattr_getrobust() function places the value of the ro- bustness attribute of the mutex attributes object referred to by attr in *robustness. The pthread_mutexattr_setrobust() function sets the value of the robustness attribute of the mutex attributes object re- ferred to by attr to the value specified in *robustness. The robustness attribute specifies the behavior of the mutex when the owning thread dies without unlocking the mutex. The following values are valid for robustness: PTHREAD_MUTEX_STALLED This is the default value for a mutex attributes object. If a mutex is initialized with the PTHREAD_MUTEX_STALLED attribute and its owner dies without unlocking it, the mutex remains locked afterwards and any future attempts to call pthread_mu- tex_lock(3) on the mutex will block indefinitely. PTHREAD_MUTEX_ROBUST If a mutex is initialized with the PTHREAD_MUTEX_ROBUST attri- bute and its owner dies without unlocking it, any future at- tempts to call pthread_mutex_lock(3) on this mutex will succeed and return EOWNERDEAD to indicate that the original owner no longer exists and the mutex is in an inconsistent state. Usu- ally after EOWNERDEAD is returned, the next owner should call pthread_mutex_consistent(3) on the acquired mutex to make it consistent again before using it any further. If the next owner unlocks the mutex using pthread_mutex_un- lock(3) before making it consistent, the mutex will be perma- nently unusable and any subsequent attempts to lock it using pthread_mutex_lock(3) will fail with the error ENOTRECOVERABLE. The only permitted operation on such a mutex is pthread_mu- tex_destroy(3). If the next owner terminates before calling pthread_mutex_con- sistent(3), further pthread_mutex_lock(3) operations on this mu- tex will still return EOWNERDEAD. Note that the attr argument of pthread_mutexattr_getrobust() and pthread_mutexattr_setrobust() should refer to a mutex attributes object that was initialized by pthread_mutexattr_init(3), otherwise the behav- ior is undefined. RETURN VALUE On success, these functions return 0. On error, they return a positive error number. In the glibc implementation, pthread_mutexattr_getrobust() always re- turn zero. ERRORS EINVAL A value other than PTHREAD_MUTEX_STALLED or PTHREAD_MUTEX_ROBUST was passed to pthread_mutexattr_setrobust(). VERSIONS pthread_mutexattr_getrobust() and pthread_mutexattr_setrobust() were added to glibc in version 2.12. CONFORMING TO POSIX.1-2008. NOTES In the Linux implementation, when using process-shared robust mutexes, a waiting thread also receives the EOWNERDEAD notification if the owner of a robust mutex performs an execve(2) without first unlocking the mu- tex. POSIX.1 does not specify this detail, but the same behavior also occurs in at least some other implementations. Before the addition of pthread_mutexattr_getrobust() and pthread_mutex- attr_setrobust() to POSIX, glibc defined the following equivalent non- standard functions if _GNU_SOURCE was defined: int pthread_mutexattr_getrobust_np(const pthread_mutexattr_t *attr, int *robustness); int pthread_mutexattr_setrobust_np(const pthread_mutexattr_t *attr, int robustness); Correspondingly, the constants PTHREAD_MUTEX_STALLED_NP and PTHREAD_MU- TEX_ROBUST_NP were also defined. These GNU-specific APIs, which first appeared in glibc 2.4, are nowa- days obsolete and should not be used in new programs. EXAMPLE 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 subse- quently acquires the mutex successfully and gets the error EOWNERDEAD, after which it makes the mutex consistent. The following shell session shows what we see when running this pro- gram: $ ./a.out [original owner] Setting lock... [original owner] Locked. Now exiting without unlocking. [main thread] Attempting to lock the robust mutex. [main thread] pthread_mutex_lock() returned EOWNERDEAD [main thread] Now make the mutex consistent [main thread] Mutex is now consistent; unlocking Program source #include <stdlib.h> #include <stdio.h> #include <unistd.h> #include <pthread.h> #include <errno.h> #define handle_error_en(en, msg) \ 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...\n"); pthread_mutex_lock(&mtx); printf("[original owner] Locked. Now exiting without unlocking.\n"); pthread_exit(NULL); } int main(int argc, char *argv[]) { pthread_t thr; pthread_mutexattr_t attr; int s; pthread_mutexattr_init(&attr); /* initialize the attributes object */ pthread_mutexattr_setrobust(&attr, PTHREAD_MUTEX_ROBUST); /* set robustness */ pthread_mutex_init(&mtx, &attr); /* initialize the mutex */ pthread_create(&thr, NULL, original_owner_thread, NULL); sleep(2); /* "original_owner_thread" should have exited by now */ printf("[main thread] Attempting to lock the robust mutex.\n"); s = pthread_mutex_lock(&mtx); if (s == EOWNERDEAD) { printf("[main thread] pthread_mutex_lock() returned EOWNERDEAD\n"); printf("[main thread] Now make the mutex consistent\n"); s = pthread_mutex_consistent(&mtx); if (s != 0) handle_error_en(s, "pthread_mutex_consistent"); printf("[main thread] Mutex is now consistent; unlocking\n"); s = pthread_mutex_unlock(&mtx); if (s != 0) handle_error_en(s, "pthread_mutex_unlock"); exit(EXIT_SUCCESS); } else if (s == 0) { printf("[main thread] pthread_mutex_lock() unexpectedly succeeded\n"); exit(EXIT_FAILURE); } else { printf("[main thread] pthread_mutex_lock() unexpectedly failed\n"); handle_error_en(s, "pthread_mutex_lock"); } } SEE ALSO get_robust_list(2), set_robust_list(2), pthread_mutex_consistent(3), pthread_mutex_init(3), pthread_mutex_lock(3), pthreads(7) COLOPHON This page is part of release 5.05 of the Linux man-pages project. A description of the project, information about reporting bugs, and the latest version of this page, can be found at https://www.kernel.org/doc/man-pages/. Linux 2019-10-10 PTHREAD_MUTEXATTR_SETROBUST(3)
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON