just re-sending this to see whether anybody is still interested.
Yubin
2017-08-27 5:05 GMT+08:00 Yubin Ruan <ablacktshirt@xxxxxxxxx>:
> On Tue, Aug 22, 2017 at 10:19:48AM +0800, Yubin Ruan wrote:
>> 2017-08-22 8:33 GMT+08:00 Michael Kerrisk (man-pages) <mtk.manpages@xxxxxxxxx>:
>> > Hello Yubin
>> >
>> > On 08/20/2017 11:42 AM, Yubin Ruan wrote:
>> >> Hi Michael,
>> >> This patch series introduce three pthread functions for linux-man:
>> >> * pthread_mutexattr_setrobust()
>> >> * pthread_mutexattr_getrobust()
>> >> * pthread_mutex_consistent()
>> >>
>> >> I put pthread_mutexattr_setrobust() and pthread_mutexattr_getrobust()
>> >> altogether since they are related.
>> >>
>> >> I obtain my information about these functions mainly from reading the
>> >> glibc source code and do some testing. There might be some mistake,
>> >> but they are mostly correct (95% or so).
>> >>
>> >> Following this email would be those man pages in plain text and nroff
>> >> format. I have tested those nroff file on my Linux box using man, and
>> >> it look pretty well. Please point out if there are any mistake in
>> >> formatting.
>> >
>> > Thanks for the drafts. Could I ask you to review the man-pages(7)
>> > page. There's a number of details described in that page
>> > which should be fixed in the drafts. Also, please try rendering
>> > your pages with "man -l <page>". This will show problems with
>> > the example code. See the chown(2) man page example for
>> > the required escape sequences for "\n" and the single quote.
>>
>> No problem. I would fix the formatting issues.
>
> Hi Michael,
>
> Sorry that it took so long.
>
> Following is the renew patch. I have corrected several formatting issues (i.e.,
> \n , - , but I can't find anything wrong with ' ) and some typos. The only
> issue I cannot solve is that the new `pthread_mutex_consistent(3)` page is too
> short that it shows at the very bottom... please help with this.
>
> Also, please find attached three verification snippets.
>
>
> Signed-off-by: Yubin Ruan <ablacktshirt@xxxxxxxxx>
> ---
> man3/pthread_mutex_consistent.3 | 60 +++++++++++
> man3/pthread_mutexattr_setrobust.3 | 199 +++++++++++++++++++++++++++++++++++++
> 2 files changed, 259 insertions(+)
> create mode 100644 man3/pthread_mutex_consistent.3
> create mode 100644 man3/pthread_mutexattr_setrobust.3
>
> diff --git a/man3/pthread_mutex_consistent.3 b/man3/pthread_mutex_consistent.3
> new file mode 100644
> index 0000000..6d5bc81
> --- /dev/null
> +++ b/man3/pthread_mutex_consistent.3
> @@ -0,0 +1,60 @@
> +.\" Copyright (c) 2017, Yubin Ruan <ablacktshirt@xxxxxxxxx>
> +.\"
> +.\" %%%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_mutex_consistent \- make the robust mutex consistent
> +.SH SYNOPSIS
> +.nf
> +.B #include <pthread.h>
> +.PP
> +.BI "int pthread_mute_consistent(pthread_mute_t *" mutex ");"
> +.fi
> +.PP
> +Compile and link with \fI\-pthread\fP.
> +.SH DESCRIPTION
> +This function make a robust mutex consistent if it is in a inconsistent
> +state. A mutex can be left in a inconsistent state if its owner terminate
> +while holding the mutex, in which situation the next owner who acquire the
> +mutex will succeed and be notified by the return value of
> +.B EOWNERDEAD.
> +
> +.SH RETURN VALUE
> +On success,
> +.IR pthread_mutex_consistent()
> +return 0. Otherwise an error value is returned to indicate the error.
> +
> +.SH ERRORS
> +.TP
> +.B EINVAL
> +The mutex is either not robust or it is not in a inconsistent state.
> +
> +.SH SEE ALSO
> +.ad l
> +.nh
> +.BR pthread_mutexattr_init (3),
> +.BR pthread_mutex_lock (3),
> +.BR pthread_mutexattr_setrobust (3),
> +.BR pthread_mutexattr_getrobust (3),
> +.BR pthreads (7)
> diff --git a/man3/pthread_mutexattr_setrobust.3 b/man3/pthread_mutexattr_setrobust.3
> new file mode 100644
> index 0000000..3add496
> --- /dev/null
> +++ b/man3/pthread_mutexattr_setrobust.3
> @@ -0,0 +1,199 @@
> +.\" Copyright (c) 2017, Yubin Ruan <ablacktshirt@xxxxxxxxx>
> +.\"
> +.\" %%%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
> +\- get and set the robustness attribute of a mutex attribute object
> +.SH SYNOPSIS
> +.nf
> +.B #include <pthread.h>
> +.PP
> +.BI "int pthread_mutexattr_getrobust(const pthread_mutexattr_t *" attr, "int *" robustness ");"
> +.BI "int pthread_mutexattr_setrobust(const pthread_mutexattr_t *" attr, "int *" robustness ");"
> +.BI "int pthread_mutexattr_getrobust_np(const pthread_mutexattr_t *" attr, "int *" robustness ");"
> +.BI "int pthread_mutexattr_setrobust_np(const pthread_mutexattr_t *" attr, "int *" robustness ");"
> +.fi
> +.PP
> +Compile and link with \fI\-pthread\fP.
> +.SH DESCRIPTION
> +The
> +.BR pthread_mutexattr_getrobust()
> +and
> +.BR pthread_mutexattr_setrobust()
> +functions get and set the robustness attribute of a
> +initialized mutex attribute object, respectively.
> +The robustness attribute specifies the behavior of the mutex
> +when its owner dies without unlocking it. These two
> +functions are specified in POSIX. Glibc's NPTL has
> +.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
> +.BR NPTL (7).
> +.PP
> +Currently there are only two possible values for the
> +.IR robustness
> +attribute:
> +.TP
> +.BR PTHREAD_MUTEX_STALLED
> +is the default value for a mutex attribute object. If a mutex is initialized
> +with a
> +.BR PTHREAD_MUTEX_STALLED
> +attribute object and its owner dies without unlocking it, it is kept locked
> +afterwards and any future attempts to call
> +.IR pthread_mutex_lock (3)
> +on this mutex will block indefinitely.
> +.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
> +.IR execve (2)
> +, any future attempts to call
> +.IR pthread_mutex_lock (3)
> +on this mutex will suceed and return
> +.B EOWNERDEAD
> +to indicate that the original owner no longer exists and the mutex is left in
> +an inconsistent state. Usually after
> +.B EOWNERDEAD
> +is returned, the next owner should call
> +.IR pthread_mutex_consistent (3)
> +on the acquired mutex to make it consistent again before using it any further.
> +If the next owner unlock it using
> +.IR pthread_mutex_unlock (3)
> +before making it consistent, the mutex will be unusable permanently and any
> +subsequent attempts to lock it using
> +.IR pthread_mutex_lock (3)
> +will return
> +.B ENOTRECOVERABLE.
> +If the next owner terminates before calling
> +.IR pthread_mutex_consistent (3)
> +, furture
> +.IR pthread_mutex_lock (3)
> +on this mutex will still return
> +.B EOWNERDEAD.
> +
> +
> +Glibc defines
> +.B PTHREAD_MUTEX_STALLED_NP
> +and
> +.B PTHREAD_MUTEX_ROBUST_NP
> +as aliases of
> +.B PTHREAD_MUTEX_STALLED
> +and
> +.B PTHREAD_MUTEX_ROBUST
> +respectively.
> +
> +Note that the
> +.IR attr
> +argument of
> +.IR pthread_mutexattr_getrobust()
> +and
> +.IR pthread_mutexattr_setrobust()
> +should refer to a mutex attribute object that was initialized by
> +.IR pthread_mutexattr_init (3)
> +, otherwise the behavior is undefined.
> +.SH RETURN VALUE
> +On success, zero is returned by
> +.IR pthread_mutexattr_getrobust()
> +and the value pointed to by the
> +.IR robustness
> +parameter is set to the robustness attribute of
> +.IR attr.
> +Otherwise, an error number shall be returned. On success
> +.IR pthread_mutexattr_setrobust()
> +set the robustness attribute into the mutex attribute object
> +.IR attr
> +and return zero, otherwise a error number is returned to indicate the error.
> +.SS Glibc\-specificed features
> +In glibc's implementation,
> +.IR pthread_mutexattr_getrobust()
> +always return zero.
> +.SH ERRORS
> +.TP
> +.B EINVAL
> +A value other than
> +.B PTHREAD_MUTEX_STALLED
> +or
> +.B PTHREAD_MUTEX_ROBUST
> +is passed into
> +.IR pthread_mutexattr_setrobust().
> +
> +.SH EXAMPLE
> +.PP
> +The program demonstrate a simple usecase of the robustness attribute of a
> +pthread mutex attribute object. In this program, a thread holding the mutex
> +dies prematurely withough unlocking the mutex. Another thread acquires it
> +successfully and get EOWNERDEAD.
> +
> +.SS Program source
> +.EX
> +#include <stdio.h>
> +#include <unistd.h>
> +#include <pthread.h>
> +#include <errno.h>
> +
> +pthread_mutex_t lock;
> +
> +void *original_owner_thread(void *ptr)
> +{
> + printf("[original owner] Setting lock...\\n");
> + pthread_mutex_lock(&lock);
> + printf("[original owner] Locked. Now exiting without unlocking.\\n");
> + pthread_exit(NULL);
> +}
> +
> +int main(int argc, char *argv[])
> +{
> + pthread_t lock_getter;
> + pthread_mutexattr_t attr;
> + pthread_mutexattr_init(&attr); /* initialize the attribute object */
> + pthread_mutexattr_setrobust(&attr, PTHREAD_MUTEX_ROBUST); /* set robustness */
> +
> + pthread_mutex_init(&lock, &attr); /* initialize the lock */
> +
> + pthread_create(&lock_getter, NULL, original_owner_thread, NULL);
> + sleep(2); /* original_owner_thread should have exited now */
> +
> + printf("Attempting to acquire the unlocked robust mutex.\\n");
> + int ret_code = pthread_mutex_lock(&lock);
> + if(EOWNERDEAD == ret_code) {
> + printf("EOWNERDEAD returned. Make the mutex consistent now\\n");
> + pthread_mutex_consistent(&lock);
> + }
> +
> + pthread_mutex_unlock(&lock);
> +
> + return 0;
> +}
> +.EE
> +.SH SEE ALSO
> +.ad l
> +.nh
> +.BR pthread_mutex_init (3),
> +.BR pthread_mutex_consistent (3),
> +.BR pthread_mutex_lock (3)
> +.BR pthreads (7)
> --
> 2.7.4
>
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
