2017-08-26 21:05:53 +00:00
|
|
|
.\" Copyright (c) 2017, Yubin Ruan <ablacktshirt@gmail.com>
|
|
|
|
.\"
|
|
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
|
|
.\" preserved on all copies.
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
|
|
.\" permission notice identical to this one.
|
|
|
|
.\"
|
|
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
|
|
.\" have taken the same level of care in the production of this manual,
|
|
|
|
.\" which is licensed free of charge, as they might when working
|
|
|
|
.\" professionally.
|
|
|
|
.\"
|
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
|
|
.\" %%%LICENSE_END
|
|
|
|
.\"
|
|
|
|
.TH PTHREAD_MUTEXATTR_SETROBUST 3 2017-08-20 "Linux" "Linux Programmer's Manual"
|
|
|
|
.SH NAME
|
|
|
|
pthread_mutexattr_getrobust, pthread_mutexattr_setrobust,
|
|
|
|
pthread_mutexattr_getrobust_np, pthread_mutexattr_setrobust_np
|
2017-09-11 12:23:41 +00:00
|
|
|
\- get and set the robustness attribute of a mutex attribute object
|
2017-08-26 21:05:53 +00:00
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
|
|
|
.B #include <pthread.h>
|
|
|
|
.PP
|
2017-09-11 12:13:59 +00:00
|
|
|
.BI "int pthread_mutexattr_getrobust(const pthread_mutexattr_t *" attr ,
|
|
|
|
.BI " int *" robustness ");"
|
|
|
|
.BI "int pthread_mutexattr_setrobust(const pthread_mutexattr_t *" attr ,
|
2017-09-11 14:38:09 +00:00
|
|
|
.BI " int " robustness ");"
|
2017-09-11 12:13:59 +00:00
|
|
|
.BI "int pthread_mutexattr_getrobust_np(const pthread_mutexattr_t *" attr ,
|
|
|
|
.BI " int *" robustness ");"
|
|
|
|
.BI "int pthread_mutexattr_setrobust_np(const pthread_mutexattr_t *" attr ,
|
2017-09-11 14:38:09 +00:00
|
|
|
.BI " int " robustness ");"
|
2017-08-26 21:05:53 +00:00
|
|
|
.fi
|
|
|
|
.PP
|
|
|
|
Compile and link with \fI\-pthread\fP.
|
|
|
|
.SH DESCRIPTION
|
|
|
|
The
|
2017-09-11 12:13:59 +00:00
|
|
|
.BR pthread_mutexattr_getrobust ()
|
2017-08-26 21:05:53 +00:00
|
|
|
and
|
2017-09-11 12:13:59 +00:00
|
|
|
.BR pthread_mutexattr_setrobust ()
|
2017-09-11 12:41:09 +00:00
|
|
|
functions get and set the robustness attribute of an
|
|
|
|
initialized mutex attribute object.
|
2017-08-26 21:05:53 +00:00
|
|
|
The robustness attribute specifies the behavior of the mutex
|
2017-09-11 12:25:07 +00:00
|
|
|
when its owner dies without unlocking it.
|
|
|
|
These two functions are specified in POSIX.
|
|
|
|
Glibc's NPTL has
|
2017-08-26 21:05:53 +00:00
|
|
|
.BR pthread_mutexattr_getrobust_np (3)
|
|
|
|
and
|
|
|
|
.BR pthread_mutexattr_setrobust_np (3)
|
|
|
|
respectively but they are just aliases, with the "np" standing for "Native Posix".
|
|
|
|
See
|
2017-09-11 12:23:41 +00:00
|
|
|
.BR NPTL (7).
|
2017-08-26 21:05:53 +00:00
|
|
|
.PP
|
2017-09-11 12:23:41 +00:00
|
|
|
Currently there are only two possible values for the
|
2017-08-26 21:05:53 +00:00
|
|
|
.IR robustness
|
|
|
|
attribute:
|
2017-09-11 12:23:41 +00:00
|
|
|
.TP
|
2017-08-26 21:05:53 +00:00
|
|
|
.BR PTHREAD_MUTEX_STALLED
|
2017-09-11 12:41:09 +00:00
|
|
|
This is the default value for a mutex attribute object.
|
2017-09-11 12:25:07 +00:00
|
|
|
If a mutex is initialized with a
|
2017-08-26 21:05:53 +00:00
|
|
|
.BR PTHREAD_MUTEX_STALLED
|
|
|
|
attribute object and its owner dies without unlocking it, it is kept locked
|
|
|
|
afterwards and any future attempts to call
|
2017-09-11 12:13:59 +00:00
|
|
|
.BR pthread_mutex_lock (3)
|
2017-09-11 12:23:41 +00:00
|
|
|
on this mutex will block indefinitely.
|
2017-08-26 21:05:53 +00:00
|
|
|
.TP
|
|
|
|
.B PTHREAD_MUTEX_ROBUST
|
|
|
|
can be set on a mutex attribute object so that when the owner of the mutex
|
|
|
|
dies or when the process containing such a locked mutex performs
|
2017-09-11 12:13:59 +00:00
|
|
|
.BR execve (2),
|
|
|
|
any future attempts to call
|
|
|
|
.BR pthread_mutex_lock (3)
|
2017-09-11 12:35:32 +00:00
|
|
|
on this mutex will succeed and return
|
2017-08-26 21:05:53 +00:00
|
|
|
.B EOWNERDEAD
|
|
|
|
to indicate that the original owner no longer exists and the mutex is left in
|
2017-09-11 12:25:07 +00:00
|
|
|
an inconsistent state.
|
|
|
|
Usually after
|
2017-08-26 21:05:53 +00:00
|
|
|
.B EOWNERDEAD
|
|
|
|
is returned, the next owner should call
|
2017-09-11 12:13:59 +00:00
|
|
|
.BR pthread_mutex_consistent (3)
|
2017-08-26 21:05:53 +00:00
|
|
|
on the acquired mutex to make it consistent again before using it any further.
|
2017-09-11 12:41:09 +00:00
|
|
|
If the next owner unlocks it using
|
2017-09-11 12:13:59 +00:00
|
|
|
.BR pthread_mutex_unlock (3)
|
2017-08-26 21:05:53 +00:00
|
|
|
before making it consistent, the mutex will be unusable permanently and any
|
|
|
|
subsequent attempts to lock it using
|
2017-09-11 12:13:59 +00:00
|
|
|
.BR pthread_mutex_lock (3)
|
2017-09-11 12:41:09 +00:00
|
|
|
will fail with the error
|
2017-09-11 12:13:59 +00:00
|
|
|
.BR ENOTRECOVERABLE .
|
2017-08-26 21:05:53 +00:00
|
|
|
If the next owner terminates before calling
|
2017-09-11 12:13:59 +00:00
|
|
|
.BR pthread_mutex_consistent (3),
|
2017-09-11 12:35:32 +00:00
|
|
|
further
|
2017-09-11 12:13:59 +00:00
|
|
|
.BR pthread_mutex_lock (3)
|
2017-08-26 21:05:53 +00:00
|
|
|
on this mutex will still return
|
2017-09-11 12:23:41 +00:00
|
|
|
.BR EOWNERDEAD .
|
2017-09-11 12:13:59 +00:00
|
|
|
.PP
|
2017-08-26 21:05:53 +00:00
|
|
|
Glibc defines
|
|
|
|
.B PTHREAD_MUTEX_STALLED_NP
|
|
|
|
and
|
|
|
|
.B PTHREAD_MUTEX_ROBUST_NP
|
2017-09-11 12:23:41 +00:00
|
|
|
as aliases of
|
2017-08-26 21:05:53 +00:00
|
|
|
.B PTHREAD_MUTEX_STALLED
|
2017-09-11 12:23:41 +00:00
|
|
|
and
|
2017-08-26 21:05:53 +00:00
|
|
|
.B PTHREAD_MUTEX_ROBUST
|
|
|
|
respectively.
|
2017-09-11 12:13:59 +00:00
|
|
|
.PP
|
2017-08-26 21:05:53 +00:00
|
|
|
Note that the
|
|
|
|
.IR attr
|
|
|
|
argument of
|
2017-09-11 12:13:59 +00:00
|
|
|
.BR pthread_mutexattr_getrobust ()
|
2017-09-11 12:23:41 +00:00
|
|
|
and
|
2017-09-11 12:13:59 +00:00
|
|
|
.BR pthread_mutexattr_setrobust ()
|
2017-08-26 21:05:53 +00:00
|
|
|
should refer to a mutex attribute object that was initialized by
|
2017-09-11 12:13:59 +00:00
|
|
|
.BR pthread_mutexattr_init (3),
|
2017-09-11 12:23:41 +00:00
|
|
|
otherwise the behavior is undefined.
|
2017-08-26 21:05:53 +00:00
|
|
|
.SH RETURN VALUE
|
2017-09-11 12:23:41 +00:00
|
|
|
On success, zero is returned by
|
2017-09-11 12:13:59 +00:00
|
|
|
.BR pthread_mutexattr_getrobust ()
|
2017-08-26 21:05:53 +00:00
|
|
|
and the value pointed to by the
|
2017-09-11 12:23:41 +00:00
|
|
|
.IR robustness
|
2017-08-26 21:05:53 +00:00
|
|
|
parameter is set to the robustness attribute of
|
2017-09-11 14:43:00 +00:00
|
|
|
.IR attr .
|
2017-09-11 12:25:07 +00:00
|
|
|
Otherwise, an error number shall be returned.
|
2017-09-11 12:41:09 +00:00
|
|
|
On success,
|
2017-09-11 12:13:59 +00:00
|
|
|
.BR pthread_mutexattr_setrobust()
|
2017-09-11 12:41:09 +00:00
|
|
|
sets the robustness attribute into the mutex attribute object
|
2017-08-26 21:05:53 +00:00
|
|
|
.IR attr
|
2017-09-11 12:41:09 +00:00
|
|
|
and returns zero, otherwise an error number is returned to indicate the error.
|
2017-09-11 12:35:32 +00:00
|
|
|
.SS Glibc\-specified features
|
2017-08-26 21:05:53 +00:00
|
|
|
In glibc's implementation,
|
2017-09-11 12:13:59 +00:00
|
|
|
.BR pthread_mutexattr_getrobust ()
|
2017-08-26 21:05:53 +00:00
|
|
|
always return zero.
|
|
|
|
.SH ERRORS
|
|
|
|
.TP
|
|
|
|
.B EINVAL
|
|
|
|
A value other than
|
|
|
|
.B PTHREAD_MUTEX_STALLED
|
|
|
|
or
|
|
|
|
.B PTHREAD_MUTEX_ROBUST
|
2017-09-11 12:41:09 +00:00
|
|
|
was passed to
|
2017-09-11 12:23:41 +00:00
|
|
|
.BR pthread_mutexattr_setrobust ().
|
2017-08-26 21:05:53 +00:00
|
|
|
.SH EXAMPLE
|
|
|
|
.PP
|
2017-09-11 14:43:00 +00:00
|
|
|
The program demonstrates a simple use of the robustness attribute of a
|
2017-09-11 12:25:07 +00:00
|
|
|
pthread mutex attribute object.
|
|
|
|
In this program, a thread holding the mutex
|
2017-09-11 12:35:32 +00:00
|
|
|
dies prematurely without unlocking the mutex.
|
2017-09-11 12:25:07 +00:00
|
|
|
Another thread acquires it
|
2017-09-11 12:41:09 +00:00
|
|
|
successfully and gets the error
|
|
|
|
.BR EOWNERDEAD .
|
2017-08-26 21:05:53 +00:00
|
|
|
.SS Program source
|
|
|
|
.EX
|
2017-09-11 12:45:31 +00:00
|
|
|
#include <stdlib.h>
|
2017-08-26 21:05:53 +00:00
|
|
|
#include <stdio.h>
|
|
|
|
#include <unistd.h>
|
|
|
|
#include <pthread.h>
|
|
|
|
#include <errno.h>
|
|
|
|
|
2017-09-11 12:45:31 +00:00
|
|
|
static pthread_mutex_t lock;
|
2017-08-26 21:05:53 +00:00
|
|
|
|
2017-09-11 12:45:31 +00:00
|
|
|
static void *
|
|
|
|
original_owner_thread(void *ptr)
|
2017-08-26 21:05:53 +00:00
|
|
|
{
|
|
|
|
printf("[original owner] Setting lock...\\n");
|
|
|
|
pthread_mutex_lock(&lock);
|
|
|
|
printf("[original owner] Locked. Now exiting without unlocking.\\n");
|
|
|
|
pthread_exit(NULL);
|
|
|
|
}
|
|
|
|
|
2017-09-11 12:45:31 +00:00
|
|
|
int
|
|
|
|
main(int argc, char *argv[])
|
2017-08-26 21:05:53 +00:00
|
|
|
{
|
|
|
|
pthread_t lock_getter;
|
|
|
|
pthread_mutexattr_t attr;
|
2017-09-11 12:45:31 +00:00
|
|
|
int ret_code;
|
|
|
|
|
2017-08-26 21:05:53 +00:00
|
|
|
pthread_mutexattr_init(&attr); /* initialize the attribute object */
|
2017-09-11 12:45:31 +00:00
|
|
|
pthread_mutexattr_setrobust(&attr, PTHREAD_MUTEX_ROBUST);
|
|
|
|
/* set robustness */
|
2017-08-26 21:05:53 +00:00
|
|
|
|
2017-09-11 12:45:31 +00:00
|
|
|
pthread_mutex_init(&lock, &attr); /* initialize the mutex */
|
2017-08-26 21:05:53 +00:00
|
|
|
|
|
|
|
pthread_create(&lock_getter, NULL, original_owner_thread, NULL);
|
2017-09-11 12:45:31 +00:00
|
|
|
|
|
|
|
sleep(2);
|
|
|
|
|
|
|
|
/* Original_owner_thread should have exited by now */
|
2017-08-26 21:05:53 +00:00
|
|
|
|
|
|
|
printf("Attempting to acquire the unlocked robust mutex.\\n");
|
2017-09-11 12:45:31 +00:00
|
|
|
ret_code = pthread_mutex_lock(&lock);
|
|
|
|
if (EOWNERDEAD == ret_code) {
|
2017-08-26 21:05:53 +00:00
|
|
|
printf("EOWNERDEAD returned. Make the mutex consistent now\\n");
|
|
|
|
pthread_mutex_consistent(&lock);
|
|
|
|
}
|
|
|
|
|
|
|
|
pthread_mutex_unlock(&lock);
|
|
|
|
|
2017-09-11 12:45:31 +00:00
|
|
|
exit(EXIT_SUCCESS);
|
2017-08-26 21:05:53 +00:00
|
|
|
}
|
|
|
|
.EE
|
|
|
|
.SH SEE ALSO
|
|
|
|
.ad l
|
|
|
|
.nh
|
|
|
|
.BR pthread_mutex_init (3),
|
|
|
|
.BR pthread_mutex_consistent (3),
|
2017-09-11 12:41:09 +00:00
|
|
|
.BR pthread_mutex_lock (3),
|
2017-08-26 21:05:53 +00:00
|
|
|
.BR pthreads (7)
|