HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |LIBRARY |SYNOPSIS |DESCRIPTION |RETURN VALUE |ERRORS |VERSIONS |STANDARDS |HISTORY |EXAMPLES |SEE ALSO |COLOPHON | |
pthread_...setrobust(3) Library Functions Manualpthread_...setrobust(3)pthread_mutexattr_getrobust, pthread_mutexattr_setrobust - get and set the robustness attribute of a mutex attributes object
POSIX threads library (libpthread,-lpthread)
#include <pthread.h>int pthread_mutexattr_getrobust(const pthread_mutexattr_t *attr,int *robustness);int pthread_mutexattr_setrobust(pthread_mutexattr_t *attr,introbustness); Feature Test Macro Requirements for glibc (seefeature_test_macros(7)):pthread_mutexattr_getrobust(),pthread_mutexattr_setrobust(): _POSIX_C_SOURCE >= 200809L
Thepthread_mutexattr_getrobust() function places the value of the robustness attribute of the mutex attributes object referred to byattr in*robustness. Thepthread_mutexattr_setrobust() function sets the value of the robustness attribute of the mutex attributes object referred to byattr 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 forrobustness:PTHREAD_MUTEX_STALLED This is the default value for a mutex attributes object. If a mutex is initialized with thePTHREAD_MUTEX_STALLED attribute and its owner dies without unlocking it, the mutex remains locked afterwards and any future attempts to callpthread_mutex_lock(3) on the mutex will block indefinitely.PTHREAD_MUTEX_ROBUST If a mutex is initialized with thePTHREAD_MUTEX_ROBUST attribute and its owner dies without unlocking it, any future attempts to callpthread_mutex_lock(3) on this mutex will succeed and returnEOWNERDEADto indicate that the original owner no longer exists and the mutex is in an inconsistent state. Usually afterEOWNERDEADis returned, the next owner should callpthread_mutex_consistent(3) on the acquired mutex to make it consistent again before using it any further. If the next owner unlocks the mutex usingpthread_mutex_unlock(3) before making it consistent, the mutex will be permanently unusable and any subsequent attempts to lock it usingpthread_mutex_lock(3) will fail with the errorENOTRECOVERABLE. The only permitted operation on such a mutex ispthread_mutex_destroy(3). If the next owner terminates before callingpthread_mutex_consistent(3), furtherpthread_mutex_lock(3) operations on this mutex will still returnEOWNERDEAD. Note that theattr argument ofpthread_mutexattr_getrobust() andpthread_mutexattr_setrobust() should refer to a mutex attributes object that was initialized bypthread_mutexattr_init(3), otherwise the behavior is undefined.
On success, these functions return 0. On error, they return a positive error number. In the glibc implementation,pthread_mutexattr_getrobust() always return zero.
EINVALA value other thanPTHREAD_MUTEX_STALLEDorPTHREAD_MUTEX_ROBUSTwas passed topthread_mutexattr_setrobust().
In the Linux implementation, when using process-shared robust mutexes, a waiting thread also receives theEOWNERDEAD notification if the owner of a robust mutex performs anexecve(2) without first unlocking the mutex. POSIX.1 does not specify this detail, but the same behavior also occurs in at least some other implementations.
POSIX.1-2008.
glibc 2.12. POSIX.1-2008. Before the addition ofpthread_mutexattr_getrobust() andpthread_mutexattr_setrobust() to POSIX, glibc defined the following equivalent nonstandard functions if_GNU_SOURCEwas defined:[[deprecated]]int pthread_mutexattr_getrobust_np(const pthread_mutexattr_t *attr,int *robustness);[[deprecated]]int pthread_mutexattr_setrobust_np(const pthread_mutexattr_t *attr,introbustness); Correspondingly, the constantsPTHREAD_MUTEX_STALLED_NPandPTHREAD_MUTEX_ROBUST_NPwere also defined. 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.
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 errorEOWNERDEAD, after which it makes the mutex consistent. The following shell session shows what we see when running this program: $./a.out; [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; unlockingProgram source #include <errno.h> #include <pthread.h> #include <stdio.h> #include <stdlib.h> #include <unistd.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(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.\n"); s = pthread_mutex_lock(&mtx); if (s == EOWNERDEAD) { printf("[main] pthread_mutex_lock() returned EOWNERDEAD\n"); printf("[main] Now make the mutex consistent\n"); s = pthread_mutex_consistent(&mtx); if (s != 0) handle_error_en(s, "pthread_mutex_consistent"); printf("[main] 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] pthread_mutex_lock() unexpectedly succeeded\n"); exit(EXIT_FAILURE); } else { printf("[main] pthread_mutex_lock() unexpectedly failed\n"); handle_error_en(s, "pthread_mutex_lock"); } }get_robust_list(2),set_robust_list(2),pthread_mutex_consistent(3),pthread_mutex_init(3),pthread_mutex_lock(3),pthreads(7)
This page is part of theman-pages (Linux kernel and C library user-space interface documentation) project. Information about the project can be found at ⟨https://www.kernel.org/doc/man-pages/⟩. If you have a bug report for this manual page, see ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩. This page was obtained from the tarball man-pages-6.15.tar.gz fetched from ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on 2025-08-11. If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up- to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgLinux man-pages 6.15 2025-05-17pthread_...setrobust(3)Pages that refer to this page:get_robust_list(2), pthread_mutexattr_init(3), pthread_mutex_consistent(3)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |