libpthread: Document some more functions.
authorSascha Wildner <saw@online.de>
Thu, 30 Nov 2017 07:26:00 +0000 (08:26 +0100)
committerSascha Wildner <saw@online.de>
Thu, 30 Nov 2017 07:26:00 +0000 (08:26 +0100)
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
lib/libpthread/pthread_condattr.3
lib/libpthread/pthread_mutex_getprioceiling.3 [new file with mode: 0644]
lib/libpthread/pthread_mutexattr.3

index df3a911..b678e29 100644 (file)
@@ -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 \
index 816f737..3eb1edd 100644 (file)
 .\" 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
 .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 (file)
index 0000000..de5dd3c
--- /dev/null
@@ -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 <shmit@kublai.com>
+.\" 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
index e058324..dc9722b 100644 (file)
@@ -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
 .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