summaryrefslogtreecommitdiffstats
path: root/man3/pthread_mutexattr_setrobust.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/pthread_mutexattr_setrobust.3')
-rw-r--r--man3/pthread_mutexattr_setrobust.3264
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 802b400..0000000
--- 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 2023-10-31 "Linux man-pages 6.7"
-.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)