From 90b371531a4a9fb2be854685e49d2c4c4c170441 Mon Sep 17 00:00:00 2001 From: Sascha Wildner Date: Thu, 30 Nov 2017 08:26:00 +0100 Subject: [PATCH] libpthread: Document some more functions. Specifically: pthread_condattr_getclock() (Taken-from: FreeBSD) pthread_condattr_getpshared() (Taken-from: FreeBSD) pthread_condattr_setclock() (Taken-from: FreeBSD) pthread_condattr_setpshared() (Taken-from: FreeBSD) pthread_mutex_getprioceiling() (Taken-from: NetBSD) pthread_mutex_setprioceiling() (Taken-from: NetBSD) pthread_mutexattr_getpshared() pthread_mutexattr_setpshared() --- lib/libpthread/Makefile | 8 ++ lib/libpthread/pthread_condattr.3 | 87 +++++++++++++++++++- lib/libpthread/pthread_mutex_getprioceiling.3 | 113 ++++++++++++++++++++++++++ lib/libpthread/pthread_mutexattr.3 | 27 +++++- 4 files changed, 229 insertions(+), 6 deletions(-) create mode 100644 lib/libpthread/pthread_mutex_getprioceiling.3 diff --git a/lib/libpthread/Makefile b/lib/libpthread/Makefile index df3a9119bc..b678e294dc 100644 --- a/lib/libpthread/Makefile +++ b/lib/libpthread/Makefile @@ -39,6 +39,7 @@ MAN+= \ pthread_main_np.3 \ pthread_multi_np.3 \ pthread_mutex_destroy.3 \ + pthread_mutex_getprioceiling.3 \ pthread_mutex_init.3 \ pthread_mutex_lock.3 \ pthread_mutex_timedlock.3 \ @@ -112,15 +113,22 @@ MLINKS+= \ pthread_barrier_destroy.3 pthread_barrier_wait.3 \ pthread_condattr.3 pthread_condattr_destroy.3 \ pthread_condattr.3 pthread_condattr_init.3 \ + pthread_condattr.3 pthread_condattr_getclock.3 \ + pthread_condattr.3 pthread_condattr_getpshared.3 \ + pthread_condattr.3 pthread_condattr_setclock.3 \ + pthread_condattr.3 pthread_condattr_setpshared.3 \ pthread_getconcurrency.3 pthread_setconcurrency.3 \ pthread_multi_np.3 pthread_single_np.3 \ + pthread_mutex_getprioceiling.3 pthread_mutex_setprioceiling.3 \ pthread_mutexattr.3 pthread_mutexattr_destroy.3 \ pthread_mutexattr.3 pthread_mutexattr_getprioceiling.3 \ pthread_mutexattr.3 pthread_mutexattr_getprotocol.3 \ + pthread_mutexattr.3 pthread_mutexattr_getpshared.3 \ pthread_mutexattr.3 pthread_mutexattr_gettype.3 \ pthread_mutexattr.3 pthread_mutexattr_init.3 \ pthread_mutexattr.3 pthread_mutexattr_setprioceiling.3 \ pthread_mutexattr.3 pthread_mutexattr_setprotocol.3 \ + pthread_mutexattr.3 pthread_mutexattr_setpshared.3 \ pthread_mutexattr.3 pthread_mutexattr_settype.3 \ pthread_mutexattr_getkind_np.3 pthread_mutexattr_setkind_np.3 \ pthread_rwlock_rdlock.3 pthread_rwlock_tryrdlock.3 \ diff --git a/lib/libpthread/pthread_condattr.3 b/lib/libpthread/pthread_condattr.3 index 816f737814..3eb1eddd50 100644 --- a/lib/libpthread/pthread_condattr.3 +++ b/lib/libpthread/pthread_condattr.3 @@ -26,13 +26,17 @@ .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD: src/share/man/man3/pthread_condattr.3,v 1.15 2007/10/22 10:08:00 ru Exp $ -.\" $DragonFly: src/lib/libc_r/man/pthread_condattr.3,v 1.3 2004/03/11 12:28:51 hmp Exp $ -.Dd July 10, 2009 +.\" +.Dd November 30, 2017 .Dt PTHREAD_CONDATTR 3 .Os .Sh NAME .Nm pthread_condattr_init , -.Nm pthread_condattr_destroy +.Nm pthread_condattr_destroy , +.Nm pthread_condattr_getclock , +.Nm pthread_condattr_setclock , +.Nm pthread_condattr_getpshared , +.Nm pthread_condattr_setpshared .Nd condition attribute operations .Sh LIBRARY .Lb libpthread @@ -42,6 +46,14 @@ .Fn pthread_condattr_init "pthread_condattr_t *attr" .Ft int .Fn pthread_condattr_destroy "pthread_condattr_t *attr" +.Ft int +.Fn pthread_condattr_getclock "const pthread_condattr_t * restrict attr" "clockid_t * restrict clock_id" +.Ft int +.Fn pthread_condattr_setclock "pthread_condattr_t *attr" "clockid_t clock_id" +.Ft int +.Fn pthread_condattr_getpshared "const pthread_condattr_t * restrict attr" "int * restrict pshared" +.Ft int +.Fn pthread_condattr_setpshared "pthread_condattr_t *attr" "int pshared" .Sh DESCRIPTION Condition attribute objects are used to specify parameters to .Fn pthread_cond_init . @@ -58,6 +70,52 @@ function initializes a condition attribute object with the default attributes. The .Fn pthread_condattr_destroy function destroys a condition attribute object. +.Pp +The +.Fn pthread_condattr_getclock +function will put the value of the clock attribute from +.Fa attr +into the memory area pointed to by +.Fa clock_id . +The +.Fn pthread_condattr_setclock +function will set the clock attribute of +.Fa attr +to the value specified in +.Fa clock_id . +The clock attribute affects the interpretation of +.Fa abstime +in +.Xr pthread_cond_timedwait 3 +and may be set to +.Dv CLOCK_REALTIME +(default) +or +.Dv CLOCK_MONOTONIC . +.Pp +The +.Fn pthread_condattr_getpshared +function will put the value of the process-shared attribute from +.Fa attr +into the memory area pointed to by +.Fa pshared . +The +.Fn pthread_condattr_setpshared +function will set the process-shared attribute of +.Fa attr +to the value specified in +.Fa pshared . +The argument +.Fa pshared +may have the following value: +.Bl -tag -width ".Dv PTHREAD_PROCESS_PRIVATE" +.It Dv PTHREAD_PROCESS_PRIVATE +The condition variable it is attached to may only be accessed by +threads in the same process as the one that created the object. +.\".It Dv PTHREAD_PROCESS_SHARED +.\"The condition variable it is attached to may be accessed by +.\"threads in processes other than the one that created the object. +.El .Sh RETURN VALUES If successful, these functions return 0. Otherwise, an error number is returned to indicate the error. @@ -78,8 +136,29 @@ function will fail if: Invalid value for .Fa attr . .El +.Pp +The +.Fn pthread_condattr_setclock +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified in +.Fa clock_id +is not one of the allowed values. +.El +.Pp +The +.Fn pthread_condattr_setpshared +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified in +.Fa pshared +is not one of the allowed values. +.El .Sh SEE ALSO -.Xr pthread_cond_init 3 +.Xr pthread_cond_init 3 , +.Xr pthread_cond_timedwait 3 .Sh STANDARDS The .Fn pthread_condattr_init diff --git a/lib/libpthread/pthread_mutex_getprioceiling.3 b/lib/libpthread/pthread_mutex_getprioceiling.3 new file mode 100644 index 0000000000..de5dd3c595 --- /dev/null +++ b/lib/libpthread/pthread_mutex_getprioceiling.3 @@ -0,0 +1,113 @@ +.\" $NetBSD: pthread_mutex.3,v 1.10 2017/10/22 16:37:24 abhinav Exp $ +.\" +.\" Copyright (c) 2002, 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (c) 1997 Brian Cully +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd November 31, 2017 +.Dt PTHREAD_MUTEX_GETPRIOCEILING 3 +.Os +.Sh NAME +.Nm pthread_mutex_getprioceiling , +.Nm pthread_mutex_setprioceiling +.Nd get or set the priority ceiling of a mutex +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_mutex_getprioceiling "const pthread_mutex_t * restrict mutex" "int * restrict prioceiling" +.Ft int +.Fn pthread_mutex_setprioceiling "pthread_mutex_t * restrict mutex" "int prioceiling" "int * restrict old_ceiling" +.Sh DESCRIPTION +The +.Fn pthread_mutex_getprioceiling +function shall return the current priority ceiling of the mutex. +.Pp +The +.Fn pthread_mutex_setprioceiling +function shall either lock the mutex if it is unlocked, or block until +it can sucessfully lock the mutex, then it shall change the mutex's priority +ceiling and release the mutex. +When the change is successful, the previous value of the priority ceiling +shall be returned +in +.Fa old_ceiling . +The process of locking the mutex need not adhere to the priority +protect protocol. +If the +.Fn pthread_mutex_setprioceiling +function fails, the mutex priority ceiling shall not be changed. +.Sh RETURN VALUES +If successful, these functions return 0. +Otherwise, an error number is returned to indicate the error. +.Sh ERRORS +The +.Fn pthread_mutex_getprioceiling +and +.Fn pthread_mutex_setprioceiling +functions will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The priority requested by +.Fa prioceiling +is out of range; or +the value specified by +.Fa mutex +does not refer to a currently existing mutex. +.It Bq Er EPERM +The caller does not have the privilege to perform the operation. +.Sh SEE ALSO +.Xr pthread_mutex_destroy 3 , +.Xr pthread_mutex_init 3 , +.Xr pthread_mutex_lock 3 , +.Xr pthread_mutex_timedlock 3 , +.Xr pthread_mutex_trylock 3 , +.Xr pthread_mutex_unlock 3 diff --git a/lib/libpthread/pthread_mutexattr.3 b/lib/libpthread/pthread_mutexattr.3 index e05832484a..dc9722b27c 100644 --- a/lib/libpthread/pthread_mutexattr.3 +++ b/lib/libpthread/pthread_mutexattr.3 @@ -26,7 +26,7 @@ .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD: src/share/man/man3/pthread_mutexattr.3,v 1.13 2007/10/22 10:08:00 ru Exp $ -.\" $DragonFly: src/lib/libc_r/man/pthread_mutexattr.3,v 1.2 2003/06/17 04:26:48 dillon Exp $ +.\" .Dd July 10, 2009 .Dt PTHREAD_MUTEXATTR 3 .Os @@ -38,7 +38,9 @@ .Nm pthread_mutexattr_setprotocol , .Nm pthread_mutexattr_getprotocol , .Nm pthread_mutexattr_settype , -.Nm pthread_mutexattr_gettype +.Nm pthread_mutexattr_gettype , +.Nm pthread_mutexattr_getpshared , +.Nm pthread_mutexattr_setpshared .Nd mutex attribute operations .Sh LIBRARY .Lb libpthread @@ -60,6 +62,10 @@ .Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type" .Ft int .Fn pthread_mutexattr_gettype "pthread_mutexattr_t *attr" "int *type" +.Ft int +.Fn pthread_mutexattr_setpshared "pthread_mutexattr_t *attr" "int pshared" +.Ft int +.Fn pthread_mutexattr_getpshared "const pthread_mutexattr_t * restrict attr" "int * restrict pshared" .Sh DESCRIPTION Mutex attributes are used to specify parameters to .Fn pthread_mutex_init . @@ -81,6 +87,11 @@ function destroys The .Fn pthread_mutexattr_set* functions set the attribute that corresponds to each function name. +Note that the +.Fn pthread_mutexattr_setpshared +function only supports +.Dv PTHREAD_PROCESS_PRIVATE +at the moment. .Pp The .Fn pthread_mutexattr_get* @@ -148,6 +159,18 @@ Invalid value for .El .Pp The +.Fn pthread_mutexattr_getpshared +and +.Fn pthread_mutexattr_setpshared +functions will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.El +.Pp +The .Fn pthread_mutexattr_settype function will fail if: .Bl -tag -width Er -- 2.11.4.GIT