Message-ID: <20081221205941.GA11805@Chamillionaire.breakpoint.cc>
Date:	Sun, 21 Dec 2008 21:59:41 +0100
From:	Sebastian Andrzej Siewior <sebastian@...akpoint.cc>
To:	mtk.manpages@...il.com
Cc:	linux-man@...r.kernel.org, linux-kernel@...r.kernel.org,
	Thomas Gleixner <tglx@...utronix.de>,
	Ulrich Drepper <drepper@...hat.com>
Subject: [PATCH v2] add man-page for pthread_mutexattr_setrobust_np()

* Michael Kerrisk | 2008-12-07 11:44:54 [-0500]:

>Sebastian,
Michael,

>I will have more comments later, but a few quick comments now.  Could
>you revise your page in the light of these comments?
Yup. Here is version two. I somehow mixed up the IEEE man-pages with
yours. So first I didn't understand most of you comments :) Once I
figured that out I tried to address all of your comments and I've also
rephrased everything. Be prepared :)

Signed-off-by: Sebastian Andrzej Siewior <sebastian@...akpoint.cc>
---
 man3/pthread_mutex_consistent_np.3    |    1 +
 man3/pthread_mutexattr_getrobust_np.3 |    1 +
 man3/pthread_mutexattr_setrobust_np.3 |  255 +++++++++++++++++++++++++++++++++
 3 files changed, 257 insertions(+), 0 deletions(-)
 create mode 100644 man3/pthread_mutex_consistent_np.3
 create mode 100644 man3/pthread_mutexattr_getrobust_np.3
 create mode 100644 man3/pthread_mutexattr_setrobust_np.3

diff --git a/man3/pthread_mutex_consistent_np.3 b/man3/pthread_mutex_consistent_np.3
new file mode 100644
index 0000000..a92edb9
--- /dev/null
+++ b/man3/pthread_mutex_consistent_np.3
@@ -0,0 +1 @@
+.so man3/pthread_mutexattr_setrobust_np.3
diff --git a/man3/pthread_mutexattr_getrobust_np.3 b/man3/pthread_mutexattr_getrobust_np.3
new file mode 100644
index 0000000..a92edb9
--- /dev/null
+++ b/man3/pthread_mutexattr_getrobust_np.3
@@ -0,0 +1 @@
+.so man3/pthread_mutexattr_setrobust_np.3
diff --git a/man3/pthread_mutexattr_setrobust_np.3 b/man3/pthread_mutexattr_setrobust_np.3
new file mode 100644
index 0000000..34dbd6e
--- /dev/null
+++ b/man3/pthread_mutexattr_setrobust_np.3
@@ -0,0 +1,255 @@
+.\" Copyright (c) 2008 Sebastian Andrzej Siewior
+.\" Copyright (c) 2008 Linux Foundation, Michael Kerrisk
+.\"    <mtk.manpages@...il.com>
+.\"
+.\" 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.
+
+.TH "ROBUST MUTEXES" 3 2008-12-18 "GNU C Library" "Linux Programmer's Manual"
+.SH NAME
+pthread_mutexattr_setrobust_np, pthread_mutexattr_getrobust_np \- set or get
+the robustness of a mutex.
+.SH SYNOPSIS
+.nf
+.B #define _GNU_SOURCE
+.B #include <pthread.h>
+.sp
+.BI "int pthread_mutexattr_getrobust_np(pthread_mutexattr_t " *attr ",
+.BI "                    int " robustness ");"
+.BI "int pthread_mutexattr_setrobust_np(pthread_mutexattr_t " *attr ",
+.BI "                    int " robustness ");"
+.BI "int pthread_mutex_consistent_np(pthread_mutex_t " *mutex ");"
+.fi
+.sp
+Compile and link with \fI\-pthread\fP.
+.SH DESCRIPTION
+The
+.BR pthread_mutexattr_getrobust_np ()
+sets the robustness of the mutex attribute object referred to by
+.I attr
+to the value specified in
+.IR robustness .
+The
+.BR pthread_mutexattr_getrobust_np ()
+retrieves the current values of robustness of mutex attribute object referred
+to by
+.IR attr .
+The following values may be specified in
+.IR robustness :
+.TP
+.B PTHREAD_MUTEX_STALLED_NP
+Mutexes created using
+.I attr
+will stall if the owner dies while owning the lock.
+.PP
+The default setting of the robustness attribute in a newly initialized mutex
+object is
+.BR PTHREAD_MUTEX_STALLED_NP .
+.TP
+.B PTHREAD_MUTEX_ROBUST_NP
+Mutexes created using
+.I attr
+will be reboots. If the owner dies while holding the lock
+.BR pthread_mutex_lock ()
+will return
+.BR EOWNERDEAD
+.B and
+the caller is holding lock.
+This return value shall signalize the caller that the resource which is
+protected by the mutex may be in an inconsistent state and should be verified
+before used.
+Once the lock holder sanitized the protected resource he should invoke
+.BR pthread_mutex_consistent_np ()
+on the mutex object to mark that mutex as consistent.
+If this is not done, future locking requests will return
+.B EOWNERDEAD
+although the previous owner did not die.
+.SH "RETURN VALUE"
+On success, these functions return 0;
+on error, they return a non-zero error number.
+.SH ERRORS
+.BR pthread_mutexattr_setrobust_np ()
+can fail with the following error:
+.TP
+.B EINVAL
+Invalid value in
+.IR robustness .
+.PP
+.BR pthread_mutexattr_getrobust_np ()
+can fail with the following error:
+.TP
+.B EINVAL
+Invalid value in
+.IR robustness .
+.PP
+.BR pthread_mutex_consistent_np ()
+can fail with the following error:
+.TP
+.B EINVAL
+The mutex object specified by
+.I mutex
+is either not
+.B PTHREAD_MUTEX_ROBUST_NP
+or is in a consistent state.
+.PP
+.SH EXAMPLE
+The code example shows how to share a lock between two applications without
+System V IPC.
+An advantage over System V semaphores is that the kernel is not invoked in
+case the lock is not hold.
+If one of the applications dies while holding the lock or the system reboots
+unexpectedly, the new owner of lock marks the lock state consistent.
+In this example the lock owner does not need to perform any validation of the
+resource protected by the lock.
+
+.nf
+#define _GNU_SOURCE
+
+#include <errno.h>
+#include <fcntl.h>
+#include <pthread.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+
+#include <sys/mman.h>
+#include <sys/stat.h>
+#include <sys/types.h>
+
+static const char *lock_name = "/dev/shm/limi_lock";
+static pthread_mutex_t *limi_mutex;
+
+static int open_existing_lock(void)
+{
+    int fd;
+    int ret;
+    struct stat buf;
+    int retry = 5;
+
+    fd = open(lock_name, O_RDWR);
+    if (fd < 0)
+        return fd;
+    do {
+        ret = fstat(fd, &buf);
+        if (ret < 0)
+            return ret;
+
+        if (buf.st_size == sizeof(*limi_mutex))
+            return fd;
+
+        close(fd);
+        sleep(1);
+        retry\-\-;
+    } while (retry);
+
+    close(fd);
+    return \-1;
+}
+
+static int create_new_lock(void)
+{
+    int fd;
+    pthread_mutex_t cmutex = PTHREAD_MUTEX_INITIALIZER;
+    pthread_mutexattr_t attr;
+    int ret;
+
+    pthread_mutexattr_init(&attr);
+    pthread_mutexattr_setrobust_np(&attr, PTHREAD_MUTEX_ROBUST_NP);
+    pthread_mutex_init(&cmutex, &attr);
+
+    fd = open(lock_name, O_RDWR | O_CREAT | O_EXCL, S_IRUSR | S_IWUSR |
+            S_IRGRP | S_IWGRP);
+    if (fd < 0)
+        return fd;
+
+    ret = write(fd, &cmutex, sizeof(cmutex));
+    if (ret < 0) {
+        fprintf(stderr, "Write to %s failed: %s\\n",
+                lock_name, strerror(errno));
+        exit(1);
+    }
+    return fd;
+}
+
+void limi_lock_init(void)
+{
+    void *limi_lock_mmap;
+    int lock_fd;
+
+    lock_fd = open_existing_lock();
+    if (lock_fd < 0) {
+        lock_fd = create_new_lock();
+        if (lock_fd < 0) {
+            lock_fd = open_existing_lock();
+            if (lock_fd < 0) {
+                fprintf(stderr, "Can't open %s: %s\\n",
+                        lock_name, strerror(errno));
+                exit(1);
+            }
+        }
+    }
+
+    limi_lock_mmap = mmap(NULL, sizeof(*limi_mutex),
+            PROT_READ | PROT_WRITE, MAP_SHARED, lock_fd, 0);
+    close(lock_fd);
+    if (limi_lock_mmap == MAP_FAILED) {
+        fprintf(stderr, "failed to mmap limi lock: %s\\n",
+                strerror(errno));
+        exit(1);
+    }
+    limi_mutex = limi_lock_mmap;
+}
+
+void limi_lock(void)
+{
+    int ret;
+
+    ret = pthread_mutex_lock(limi_mutex);
+    if (!ret)
+        return;
+
+    if (ret == EOWNERDEAD) {
+        pthread_mutex_consistent_np(limi_mutex);
+        return;
+    }
+
+    fprintf(stderr, "Can not grab lock: %s\\n", strerror(ret));
+    exit(1);
+}
+
+void limi_unlock(void)
+{
+    int ret;
+
+    ret = pthread_mutex_unlock(limi_mutex);
+    if (!ret)
+        return;
+
+    fprintf(stderr, "Can not unlock: %s\\n", strerror(ret));
+    exit(1);
+}
+
+.fi
+.SH "SEE ALSO"
+.BR pthread_mutex_create (3),
+.BR pthread_mutexattr_init (3),
+.BR pthread_mutex_lock (3),
+.BR pthread_mutex_unlock (3)
-- 
1.6.0.4

--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

Powered by blists - more mailing lists