summaryrefslogtreecommitdiffstats
path: root/man3/pthread_mutexattr_setrobust.3
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 19:40:15 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 19:40:15 +0000
commit399644e47874bff147afb19c89228901ac39340e (patch)
tree1c4c0b733f4c16b5783b41bebb19194a9ef62ad1 /man3/pthread_mutexattr_setrobust.3
parentInitial commit. (diff)
downloadmanpages-399644e47874bff147afb19c89228901ac39340e.tar.xz
manpages-399644e47874bff147afb19c89228901ac39340e.zip
Adding upstream version 6.05.01.upstream/6.05.01
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'man3/pthread_mutexattr_setrobust.3')
-rw-r--r--man3/pthread_mutexattr_setrobust.3264
1 files changed, 264 insertions, 0 deletions
diff --git a/man3/pthread_mutexattr_setrobust.3 b/man3/pthread_mutexattr_setrobust.3
new file mode 100644
index 0000000..3612e15
--- /dev/null
+++ b/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 2023-05-03 "Linux man-pages 6.05.01"
+.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>
+.PP
+.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
+.PP
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.PP
+.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 .
+.PP
+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 .
+.PP
+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.
+.PP
+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.
+.PP
+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:
+.PP
+.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
+.PP
+Correspondingly, the constants
+.B PTHREAD_MUTEX_STALLED_NP
+and
+.B PTHREAD_MUTEX_ROBUST_NP
+were also defined.
+.PP
+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.
+.PP
+The following shell session shows what we see when running this program:
+.PP
+.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)