From ad0ef8fd06d1ac28108685495a9ba1244a20a5ca Mon Sep 17 00:00:00 2001 From: Robert Mustacchi Date: Mon, 22 Dec 2014 15:35:45 +0000 Subject: [PATCH] 5477 Need manual pages for new pthreads robust related functions Reviewed by: Jerry Jelinek Approved by: Richard Lowe --- usr/src/man/man3c/Makefile | 5 + usr/src/man/man3c/pthread_mutex_consistent.3c | 87 ++++++++++++++++ usr/src/man/man3c/pthread_mutexattr_getrobust.3c | 120 +++++++++++++++++++++++ usr/src/pkg/manifests/system-library.man3c.inc | 4 + 4 files changed, 216 insertions(+) create mode 100644 usr/src/man/man3c/pthread_mutex_consistent.3c create mode 100644 usr/src/man/man3c/pthread_mutexattr_getrobust.3c diff --git a/usr/src/man/man3c/Makefile b/usr/src/man/man3c/Makefile index 8702d82265..878f352ce8 100644 --- a/usr/src/man/man3c/Makefile +++ b/usr/src/man/man3c/Makefile @@ -317,6 +317,7 @@ MANFILES= __fbufsize.3c \ pthread_key_create.3c \ pthread_key_delete.3c \ pthread_kill.3c \ + pthread_mutex_consistent.3c \ pthread_mutex_getprioceiling.3c \ pthread_mutex_init.3c \ pthread_mutex_lock.3c \ @@ -324,6 +325,7 @@ MANFILES= __fbufsize.3c \ pthread_mutexattr_getprioceiling.3c \ pthread_mutexattr_getprotocol.3c \ pthread_mutexattr_getpshared.3c \ + pthread_mutexattr_getrobust.3c \ pthread_mutexattr_gettype.3c \ pthread_mutexattr_init.3c \ pthread_once.3c \ @@ -1017,6 +1019,7 @@ MANLINKS= FD_CLR.3c \ pthread_mutexattr_setprioceiling.3c \ pthread_mutexattr_setprotocol.3c \ pthread_mutexattr_setpshared.3c \ + pthread_mutexattr_setrobust.3c \ pthread_mutexattr_settype.3c \ pthread_rwlock_destroy.3c \ pthread_rwlock_reltimedrdlock_np.3c \ @@ -2005,6 +2008,8 @@ pthread_mutexattr_setprotocol.3c := LINKSRC = pthread_mutexattr_getprotocol.3c pthread_mutexattr_setpshared.3c := LINKSRC = pthread_mutexattr_getpshared.3c +pthread_mutexattr_setrobust.3c := LINKSRC = pthread_mutexattr_getrobust.3c + pthread_mutexattr_settype.3c := LINKSRC = pthread_mutexattr_gettype.3c pthread_mutexattr_destroy.3c := LINKSRC = pthread_mutexattr_init.3c diff --git a/usr/src/man/man3c/pthread_mutex_consistent.3c b/usr/src/man/man3c/pthread_mutex_consistent.3c new file mode 100644 index 0000000000..2b6fd0206d --- /dev/null +++ b/usr/src/man/man3c/pthread_mutex_consistent.3c @@ -0,0 +1,87 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2014, Joyent, Inc. +.\" +.Dd "Dec 22, 2014" +.Dt PTHREAD_MUTEX_CONSISTENT 3C +.Os +.Sh NAME +.Nm pthread_mutex_consistent +.Nd mark state protected by robust mutex as consistent +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fo pthread_mutex_consistent +.Fa "pthread_mutex_t *mutex" +.Fc +.Sh DESCRIPTION +The +.Fn pthread_mutex_consistent +function is used to indicate that a robust lock that is in an +inconsistent state no longer is. +.Lp +A robust lock enters into an inconsistent state when a process or thread +holding a robust lock exits, such as by calling +.Xr exit 2 +or +.Xr thr_exit 3C , +or crashes without unlocking the lock. At that point, if another process +or thread is currently in a call, or calls +.Xr pthread_mutex_lock 3C , +it will obtain the lock; however, the error code +.Er EOWNERDEAD +will be returned. In such cases, that thread will own the lock and must +check and clean up any inconsistent state that is protected by the lock. +When finished, it must call +.Fn pthread_mutex_consistent +to indicate that it is in a consistent state again. +.Lp +If a process or thread obtains a robust lock while it is in an +inconsistent state and it crashes or terminates before marking the lock +as consistent, the next process or thread that obtains the lock will +receive +.Er EOWNERDEAD . +.Sh RETURN VALUES +Upon successful completion, the +.Fn pthread_mutex_consistent +returns zero and marks +.Va mutex +as consistent. Callers of +.Fn pthread_mutex_lock +will not have +.Er EOWNERDEAD +returned until another process or thread exits without unlocking. Upon +failure, an error will be returned which corresponds to one of the +errors listed below. +.Sh ERRORS +The +.Fn pthread_mutex_consistent +function will fail if: +.Bl -tag -width Er +.It Er EINVAL +.Va mutex +is an uninitialized mutex, not a robust mutex, or not in an inconsistent +state. +.El +.Sh INTERFACE STABILITY +.Sy Committed +.Sh MT-LEVEL +.Sy MT-Safe +.Sh SEE ALSO +.Xr pthread_mutexattr_getrobust 3C , +.Xr pthread_mutex_destroy 3C , +.Xr pthread_mutex_lock 3C , +.Xr pthread_mutex_init 3C , +.Xr pthread 3HEAD , +.Xr libpthread 3LIB , +.Xr attributes 5 , +.Xr mutex 5 diff --git a/usr/src/man/man3c/pthread_mutexattr_getrobust.3c b/usr/src/man/man3c/pthread_mutexattr_getrobust.3c new file mode 100644 index 0000000000..3f7abffff5 --- /dev/null +++ b/usr/src/man/man3c/pthread_mutexattr_getrobust.3c @@ -0,0 +1,120 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2014, Joyent, Inc. +.\" +.Dd "Dec 22, 2014" +.Dt PTHREAD_MUTEXATTR_GETROBUST 3C +.Os +.Sh NAME +.Nm pthread_mutexattr_getrobust , +.Nm pthrad_mutexattr_setrobust +.Nd get and set the mutex robust attribute +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fo pthread_mutexattr_getrobust +.Fa "const pthread_mutexattr_t *attr" +.Fa "int *robust" +.Fc +.Ft int +.Fo pthread_mutexattr_setrobust +.Fa "pthread_mutexattr_t *attr" +.Fa "int robust" +.Fc +.Sh DESCRIPTION +The +.Fn pthread_mutexattr_getrobust +and +.Fn pthread_mtuexattr_setrobust +functions obtain and set a mutex's +.Em robust +attribute, putting it in, or obtaining it from +.Va robust . +The valid values for +.Va robust +include: +.Bl -tag -width Dv +.It Sy PTHREAD_MUTEX_STALLED +The mutex referred to by +.Va attr +is a traditional mutex. When a thread holding an intra-process lock or a +process holding an inter-process lock crashes or terminates without +unlocking the mutex, then the lock will be +.Sy stalled . +For another thread or process to obtain the lock, something else must +unlock it. +.It Sy PTHREAD_MUTEX_ROBUST +The mutex referred to by +.Va attr +is considered a robust mutex. When a process holding an inter-process +lock crashes or terminates without unlocking the mutex, the attempt to +lock it will return +.Er EOWNERDEAD . +This allows the new owner the chance to fix the internal state and call +.Xr pthread_mutex_consistent 3C +prior to unlocking the lock, allowing normal operation to proceed. Any +crashes while in this state cause the next owner to obtain +.Er EOWNERDEAD . +.El +.Sh RETURN VALUES +Upon successful completion, the +.Fn pthread_mutexattr_getrobust +function will return +.Sy 0 +and update +.Fa robust +with the current value of the robust attribute. Upon successful +completion, the +.Fn pthread_mutexattr_setrobust +function will return +.Sy 0 +and update the robust property of the attributes pointed to by +.Va attr +to +.Va robust . +If either function fails, an error code will be returned to indicate the +error. Valid errors are defined below. +.Sh ERRORS +The +.Fn pthread_mutexattr_getrobust +function will fail if: +.Bl -tag -width Er +.It Er EINVAL +.Va attr +is invalid or a null pointer, +.Va robust +is a null pointer. +.El +.Lp +The +.Fn pthread_mutexattr_setrobust +function will fail if: +.Bl -tag -width Er +.It Er EINVAL +.Va attr +is invalid or a null pointer, +.Va robust +is not one of +.Sy PTHREAD_MUTEX_STALLED +or +.Sy PTHREAD_MUTEX_ROBUST . +.El +.Sh INTERFACE STABILITY +.Sy Committed +.Sh MT-LEVEL +.Sy MT-Safe +.Sh SEE ALSO +.Xr pthread_mutex_consistent 3C , +.Xr pthread 3HEAD , +.Xr libpthread 3LIB , +.Xr attributes 5 , +.Xr mutex 5 diff --git a/usr/src/pkg/manifests/system-library.man3c.inc b/usr/src/pkg/manifests/system-library.man3c.inc index 9cccc7aeeb..dc225459f7 100644 --- a/usr/src/pkg/manifests/system-library.man3c.inc +++ b/usr/src/pkg/manifests/system-library.man3c.inc @@ -314,12 +314,14 @@ file path=usr/share/man/man3c/pthread_key_create.3c file path=usr/share/man/man3c/pthread_key_delete.3c file path=usr/share/man/man3c/pthread_kill.3c file path=usr/share/man/man3c/pthread_mutex_getprioceiling.3c +file path=usr/share/man/man3c/pthread_mutex_consistent.3c file path=usr/share/man/man3c/pthread_mutex_init.3c file path=usr/share/man/man3c/pthread_mutex_lock.3c file path=usr/share/man/man3c/pthread_mutex_timedlock.3c file path=usr/share/man/man3c/pthread_mutexattr_getprioceiling.3c file path=usr/share/man/man3c/pthread_mutexattr_getprotocol.3c file path=usr/share/man/man3c/pthread_mutexattr_getpshared.3c +file path=usr/share/man/man3c/pthread_mutexattr_getrobust.3c file path=usr/share/man/man3c/pthread_mutexattr_gettype.3c file path=usr/share/man/man3c/pthread_mutexattr_init.3c file path=usr/share/man/man3c/pthread_once.3c @@ -1058,6 +1060,8 @@ link path=usr/share/man/man3c/pthread_mutexattr_setprotocol.3c \ target=pthread_mutexattr_getprotocol.3c link path=usr/share/man/man3c/pthread_mutexattr_setpshared.3c \ target=pthread_mutexattr_getpshared.3c +link path=usr/share/man/man3c/pthread_mutexattr_setrobust.3c \ + target=pthread_mutexattr_getrobust.3c link path=usr/share/man/man3c/pthread_mutexattr_settype.3c \ target=pthread_mutexattr_gettype.3c link path=usr/share/man/man3c/pthread_rwlock_destroy.3c \ -- 2.11.4.GIT