pthread_np.3: Add a manpage summarizing all of the pthread extensions.

PR:		197299
MFC after:	1 week

18 files changed, 273 insertions, 22 deletions

diff --git a/share/man/man3/Makefile b/share/man/man3/Makefile
index 7312870a17dc..0f371ef427bd 100644
--- a/share/man/man3/Makefile
+++ b/share/man/man3/Makefile
@@ -413,6 +413,7 @@ PTHREAD_MAN=	pthread.3 \
 		pthread_mutex_timedlock.3 \
 		pthread_mutex_trylock.3 \
 		pthread_mutex_unlock.3 \
+		pthread_np.3 \
 		pthread_once.3 \
 		pthread_resume_all_np.3 \
 		pthread_resume_np.3 \
diff --git a/share/man/man3/pthread.3 b/share/man/man3/pthread.3
index 8a437b1cedb4..6b7b82eb27f5 100644
--- a/share/man/man3/pthread.3
+++ b/share/man/man3/pthread.3
@@ -30,7 +30,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd August 17, 2018
+.Dd October 12, 2021
 .Dt PTHREAD 3
 .Os
 .Sh NAME
@@ -67,6 +67,10 @@ Per-Thread Context Routines
 .It
 Cleanup Routines
 .El
+.Pp
+.Fx
+extensions to the POSIX thread functions are summarized in
+.Xr pthread_np 3 .
 .Ss Thread Routines
 .Bl -tag -width indent
 .It Xo
@@ -478,7 +482,6 @@ functions and the thread functions.
 Threaded applications are linked with this library.
 .Sh SEE ALSO
 .Xr libthr 3 ,
-.Xr pthread_affinity_np 3 ,
 .Xr pthread_atfork 3 ,
 .Xr pthread_attr 3 ,
 .Xr pthread_cancel 3 ,
@@ -513,6 +516,7 @@ Threaded applications are linked with this library.
 .Xr pthread_mutexattr_setprioceiling 3 ,
 .Xr pthread_mutexattr_setprotocol 3 ,
 .Xr pthread_mutexattr_settype 3 ,
+.Xr pthread_np 3 ,
 .Xr pthread_once 3 ,
 .Xr pthread_rwlock_destroy 3 ,
 .Xr pthread_rwlock_init 3 ,
diff --git a/share/man/man3/pthread_affinity_np.3 b/share/man/man3/pthread_affinity_np.3
index 24fef03ab4ed..0a52add2ee3c 100644
--- a/share/man/man3/pthread_affinity_np.3
+++ b/share/man/man3/pthread_affinity_np.3
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd March 23, 2010
+.Dd October 12, 2021
 .Dt PTHREAD_AFFINITY_NP 3
 .Os
 .Sh NAME
@@ -124,7 +124,8 @@ operation.
 .Xr cpuset_setid 2 ,
 .Xr pthread 3 ,
 .Xr pthread_attr_getaffinity_np 3 ,
-.Xr pthread_attr_setaffinity_np 3
+.Xr pthread_attr_setaffinity_np 3 ,
+.Xr pthread_np 3
 .Sh STANDARDS
 The
 .Nm pthread_getaffinity_np
diff --git a/share/man/man3/pthread_attr_affinity_np.3 b/share/man/man3/pthread_attr_affinity_np.3
index 4c400b9a17e7..7b1cd3dea0d9 100644
--- a/share/man/man3/pthread_attr_affinity_np.3
+++ b/share/man/man3/pthread_attr_affinity_np.3
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd June 2, 2016
+.Dd October 12, 2021
 .Dt PTHREAD_ATTR_AFFINITY_NP 3
 .Os
 .Sh NAME
@@ -132,6 +132,7 @@ Insufficient memory exists to store the cpuset mask.
 .Xr cpuset_getid 2 ,
 .Xr cpuset_setid 2 ,
 .Xr pthread_getaffinity_np 3 ,
+.Xr pthread_np 3 ,
 .Xr pthread_setaffinity_np 3
 .Sh STANDARDS
 The
diff --git a/share/man/man3/pthread_attr_get_np.3 b/share/man/man3/pthread_attr_get_np.3
index a23cac6997c9..336c3626a27c 100644
--- a/share/man/man3/pthread_attr_get_np.3
+++ b/share/man/man3/pthread_attr_get_np.3
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd January 31, 2003
+.Dd October 12, 2021
 .Dt PTHREAD_ATTR_GET_NP 3
 .Os
 .Sh NAME
@@ -107,7 +107,8 @@ thread ID.
 .Xr pthread_attr_getstack 3 ,
 .Xr pthread_attr_getstackaddr 3 ,
 .Xr pthread_attr_getstacksize 3 ,
-.Xr pthread_attr_init 3
+.Xr pthread_attr_init 3 ,
+.Xr pthread_np 3
 .Sh AUTHORS
 The
 .Fn pthread_attr_get_np
diff --git a/share/man/man3/pthread_attr_setcreatesuspend_np.3 b/share/man/man3/pthread_attr_setcreatesuspend_np.3
index 75408ccefc62..d2c6a6f74694 100644
--- a/share/man/man3/pthread_attr_setcreatesuspend_np.3
+++ b/share/man/man3/pthread_attr_setcreatesuspend_np.3
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd February 13, 2003
+.Dd October 12, 2021
 .Dt PTHREAD_ATTR_SETCREATESUSPEND_NP 3
 .Os
 .Sh NAME
@@ -65,6 +65,7 @@ is invalid.
 .Xr pthread_attr_destroy 3 ,
 .Xr pthread_attr_init 3 ,
 .Xr pthread_create 3 ,
+.Xr pthread_np 3 ,
 .Xr pthread_resume_all_np 3 ,
 .Xr pthread_resume_np 3
 .Sh AUTHORS
diff --git a/share/man/man3/pthread_getthreadid_np.3 b/share/man/man3/pthread_getthreadid_np.3
index a912e7d42efa..562f6a7ae91a 100644
--- a/share/man/man3/pthread_getthreadid_np.3
+++ b/share/man/man3/pthread_getthreadid_np.3
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd February 25, 2012
+.Dd October 12, 2021
 .Dt PTHREAD_GETTHREADID_NP 3
 .Os
 .Sh NAME
@@ -50,6 +50,7 @@ function returns the thread integral ID of the calling thread.
 .Sh ERRORS
 None.
 .Sh SEE ALSO
+.Xr pthread_np 3 ,
 .Xr pthread_self 3
 .Sh AUTHORS
 This manual page was written by
diff --git a/share/man/man3/pthread_join.3 b/share/man/man3/pthread_join.3
index 799f6409fbfa..4cd04eade0aa 100644
--- a/share/man/man3/pthread_join.3
+++ b/share/man/man3/pthread_join.3
@@ -30,7 +30,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd February 13, 2019
+.Dd October 12, 2021
 .Dt PTHREAD_JOIN 3
 .Os
 .Sh NAME
@@ -156,7 +156,9 @@ The specified thread has not yet exited.
 .El
 .Sh SEE ALSO
 .Xr wait 2 ,
-.Xr pthread_create 3
+.Xr pthread 3 ,
+.Xr pthread_create 3 ,
+.Xr pthread_np 3
 .Sh STANDARDS
 The
 .Fn pthread_join
diff --git a/share/man/man3/pthread_main_np.3 b/share/man/man3/pthread_main_np.3
index 81669b786094..c386cb224a9b 100644
--- a/share/man/man3/pthread_main_np.3
+++ b/share/man/man3/pthread_main_np.3
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd February 13, 2003
+.Dd October 12, 2021
 .Dt PTHREAD_MAIN_NP 3
 .Os
 .Sh NAME
@@ -54,6 +54,7 @@ and \-1 if the thread's initialization has not yet completed.
 .Sh SEE ALSO
 .Xr pthread_create 3 ,
 .Xr pthread_equal 3 ,
+.Xr pthread_np 3 ,
 .Xr pthread_self 3
 .Sh AUTHORS
 This manual page was written by
diff --git a/share/man/man3/pthread_multi_np.3 b/share/man/man3/pthread_multi_np.3
index c790d358ca3c..065b53c49b1f 100644
--- a/share/man/man3/pthread_multi_np.3
+++ b/share/man/man3/pthread_multi_np.3
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd February 13, 2003
+.Dd October 12, 2021
 .Dt PTHREAD_MULTI_NP 3
 .Os
 .Sh NAME
@@ -59,6 +59,7 @@ and
 .Nm pthread_single_np
 functions always return 0.
 .Sh SEE ALSO
+.Xr pthread_np 3 ,
 .Xr pthread_resume_all_np 3 ,
 .Xr pthread_suspend_all_np 3
 .Sh AUTHORS
diff --git a/share/man/man3/pthread_mutexattr_getkind_np.3 b/share/man/man3/pthread_mutexattr_getkind_np.3
index fe5435f90c30..cc3cc3df20ae 100644
--- a/share/man/man3/pthread_mutexattr_getkind_np.3
+++ b/share/man/man3/pthread_mutexattr_getkind_np.3
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd February 13, 2003
+.Dd October 12, 2021
 .Dt PTHREAD_MUTEXATTR_GETKIND_NP 3
 .Os
 .Sh NAME
@@ -78,4 +78,5 @@ is invalid.
 .Xr pthread_mutex_destroy 3 ,
 .Xr pthread_mutex_init 3 ,
 .Xr pthread_mutexattr_gettype 3 ,
-.Xr pthread_mutexattr_settype 3
+.Xr pthread_mutexattr_settype 3 ,
+.Xr pthread_np 3
diff --git a/share/man/man3/pthread_np.3 b/share/man/man3/pthread_np.3
new file mode 100644
index 000000000000..caab8cc13209
--- /dev/null
+++ b/share/man/man3/pthread_np.3
@@ -0,0 +1,230 @@
+.\" Copyright (c) 2021 Felix Johnson <felix.the.red@gmail.com>
+.\"
+.\" 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 COPYRIGHT HOLDERS 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 COPYRIGHT
+.\" HOLDER 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 October 12, 2021
+.Dt PTHREAD_NP 3
+.Os
+.Sh NAME
+.Nm pthread_np
+.Nd FreeBSD extensions to POSIX thread functions
+.Sh LIBRARY
+.Lb libpthread
+.Sh SYNOPSIS
+.In pthread_np.h
+.Sh DESCRIPTION
+This manual page documents extensions to the POSIX thread functions.
+These extensions may or may not be portable to other operating systems.
+.Pp
+The POSIX thread functions are summarized in this section in the following
+groups:
+.Pp
+.Bl -bullet -offset indent -compact
+.It
+Thread Routines
+.It
+Attribute Object Routines
+.It
+Mutex Routines
+.El
+.\" .It
+.\" Condition Variable Routines
+.\" .It
+.\" Read/Write Lock Routines
+.\" .It
+.\" Per-Thread Context Routines
+.\" .It
+.\" Cleanup Routines
+.Ss Thread Routines
+.Bl -tag -width indent
+.It Xo
+.Ft int
+.Fo pthread_getaffinity_np
+.Fa "pthread_t td" "size_t cpusetsize" "cpuset_t *cpusetp"
+.Fc
+.Xc
+Get the CPU affinity of a specified thread.
+.It Xo
+.Ft int
+.Fn pthread_get_name_np "pthread_t thread" "char *name" "size_t len"
+.Xc
+Get the name of a specified thread.
+.It Xo
+.Ft int
+.Fn pthread_getname_np "pthread_t thread" "char *name" "size_t len"
+.Xc
+Get the name of a specified thread.
+.It Xo
+.Ft int
+.Fn pthread_getthreadid_np void
+.Xc
+Get the calling thread's integral ID.
+.It Xo
+.Ft int
+.Fn pthread_main_np void
+.Xc
+Identify the initial thread.
+.It Xo
+.Ft int
+.Fn pthread_multi_np void
+.Xc
+Sets the thread's scheduling mode to multi-threaded.
+.It Xo
+.Ft int
+.Fn pthread_peekjoin_np "pthread_t thread" "void **value_ptr"
+.Xc
+Peek into the exit status of a specified thread.
+.It Xo
+.Ft int
+.Fn pthread_resume_all_np void
+.Xc
+Resume all suspended threads.
+.It Xo
+.Ft int
+.Fo pthread_setaffinity_np
+.Fa "pthread_t td" "size_t cpusetsize" "const cpuset_t *cpusetp"
+.Fc
+.Xc
+Set the CPU affinity of a specified thread.
+.It Xo
+.Ft int
+.Fn pthread_set_name_np "pthread_t thread" "char *name"
+.Xc
+Sets the specified thread's name.
+.It Xo
+.Ft int
+.Fn pthread_setname_np "pthread_t thread" "char *name"
+.Xc
+Sets the specified thread's name.
+.It Xo
+.Ft int
+.Fn pthread_single_np void
+.Xc
+Sets the thread's scheduling mode to single-threaded.
+.It Xo
+.Ft int
+.Fn pthread_suspend_np "pthread_t tid"
+.Xc
+Suspend the specified thread.
+.It Xo
+.Ft int
+.Fn pthread_suspend_all_np void
+.Xc
+Suspend all active threads.
+.It Xo
+.Ft int
+.Fn pthread_switch_add_np "pthread_switch_routine_t routine"
+.Xc
+Install a routine that is called every time a thread context switches.
+.It Xo
+.Ft int
+.Fn pthread_switch_delete_np "pthread_switch_routine_t routine"
+.Xc
+Remove a routine that is called every time a thread context switches.
+.It Xo
+.Ft int
+.Fo pthread_timedjoin_np
+.Fa "pthread_t thread" "void **value_ptr" "const struct timespec *abstime"
+.Fc
+.Xc
+A variant of
+.Fn pthread_join
+with a timeout.
+.El
+.Ss Attribute Object Routines
+.Bl -tag -width indent
+.It Xo
+.Ft int
+.Fo pthread_attr_get_np
+.Fa "pthread_t pid" "pthread_attr_t *dst"
+.Fc
+.Xc
+Get the attributes of an existent thread.
+.It Xo
+.Ft int
+.Fo pthread_attr_getaffinity_np
+.Fa "const pthread_attr_t *pattr" "size_t cpusetsize" "cpuset_t *cpusetp"
+.Fc
+.Xc
+Get the CPU affinity mask from the thread attribute object.
+.It Xo
+.Ft int
+.Fo pthread_attr_setaffinity_np
+.Fa "pthread_attr_t *pattr" "size_t cpusetsize" "const cpuset_t *cpusetp"
+.Fc
+.Xc
+Set the CPU affinity mask for the thread attribute object.
+.It Xo
+.Ft int
+.Fn pthread_attr_setcreatesuspend_np "pthread_attr_t *attr"
+.Xc
+Permit creation of suspended threads.
+.El
+.Ss Mutex Routines
+.Bl -tag -width indent
+.It Xo
+.Ft int
+.Fn pthread_mutexattr_getkind_np "pthread_mutexattr_t attr"
+.Xc
+Deprecated, use
+.Xr pthread_mutexattr_gettype 3
+instead.
+.It Xo
+.Ft int
+.Fn pthread_mutexattr_setkind_np "pthread_mutexattr_t *attr"
+.Xc
+Deprecated, use
+.Xr pthread_mutexattr_settype 3
+instead.
+.El
+.\" .Ss Condition Variable Routines
+.\" .Bl -tag -width indent
+.\" .El
+.\" .Ss Read/Write Lock Routines
+.\" .Bl -tag -width indent
+.\" .El
+.\" .Ss Per-Thread Context Routines
+.\" .Bl -tag -width indent
+.\" .El
+.\" .Ss Cleanup Routines
+.\" .Bl -tag -width indent
+.\" .El
+.Sh SEE ALSO
+.Xr libthr 3 ,
+.Xr pthread 3 ,
+.Xr pthread_affinity_np 3 ,
+.Xr pthread_attr_affinity_np 3 ,
+.Xr pthread_attr_get_np 3 ,
+.Xr pthread_attr_setcreatesuspend_np 3 ,
+.Xr pthread_getthreadid_np 3 ,
+.Xr pthread_join 3 ,
+.Xr pthread_main_np 3 ,
+.Xr pthread_multi_np 3 ,
+.Xr pthread_mutexattr_getkind_np 3 ,
+.Xr pthread_resume_all_np 3 ,
+.Xr pthread_resume_np 3 ,
+.Xr pthread_set_name_np 3 ,
+.Xr pthread_suspend_all_np 3 ,
+.Xr pthread_suspend_np 3 ,
+.Xr pthread_switch_add_np 3
+.Sh STANDARDS
+All of these functions are non-portable extensions to POSIX threads.
diff --git a/share/man/man3/pthread_resume_all_np.3 b/share/man/man3/pthread_resume_all_np.3
index 0ac6736a9b74..40df03a07af1 100644
--- a/share/man/man3/pthread_resume_all_np.3
+++ b/share/man/man3/pthread_resume_all_np.3
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd February 13, 2003
+.Dd October 12, 2021
 .Dt PTHREAD_RESUME_ALL_NP 3
 .Os
 .Sh NAME
@@ -43,6 +43,7 @@ function causes all active threads to be scanned
 and resumes those which were previously suspended.
 .Sh SEE ALSO
 .Xr pthread_attr_setcreatesuspend_np 3 ,
+.Xr pthread_np 3 ,
 .Xr pthread_resume_np 3 ,
 .Xr pthread_suspend_all_np 3 ,
 .Xr pthread_suspend_np 3
diff --git a/share/man/man3/pthread_resume_np.3 b/share/man/man3/pthread_resume_np.3
index 898dbf9c0d11..16833872c010 100644
--- a/share/man/man3/pthread_resume_np.3
+++ b/share/man/man3/pthread_resume_np.3
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd February 13, 2003
+.Dd October 12, 2021
 .Dt PTHREAD_RESUME_NP 3
 .Os
 .Sh NAME
@@ -64,6 +64,7 @@ argument.
 .El
 .Sh SEE ALSO
 .Xr pthread_attr_setcreatesuspend_np 3 ,
+.Xr pthread_np 3 ,
 .Xr pthread_resume_all_np 3 ,
 .Xr pthread_suspend_all_np 3 ,
 .Xr pthread_suspend_np 3
diff --git a/share/man/man3/pthread_set_name_np.3 b/share/man/man3/pthread_set_name_np.3
index af668165d91a..5fb627a5a182 100644
--- a/share/man/man3/pthread_set_name_np.3
+++ b/share/man/man3/pthread_set_name_np.3
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd June 3, 2020
+.Dd October 12, 2021
 .Dt PTHREAD_SET_NAME_NP 3
 .Os
 .Sh NAME
@@ -90,6 +90,7 @@ and
 functions, all errors that may
 appear inside are silently ignored.
 .Sh SEE ALSO
+.Xr pthread_np 3 ,
 .Xr thr_set_name 2
 .Sh STANDARDS
 .Fn pthread_set_name_np
diff --git a/share/man/man3/pthread_suspend_all_np.3 b/share/man/man3/pthread_suspend_all_np.3
index ecedca3ee24d..2821c7360786 100644
--- a/share/man/man3/pthread_suspend_all_np.3
+++ b/share/man/man3/pthread_suspend_all_np.3
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd May 5, 2016
+.Dd October 12, 2021
 .Dt PTHREAD_SUSPEND_ALL_NP 3
 .Os
 .Sh NAME
@@ -52,6 +52,7 @@ function to use any non-async signal safe functions, besides
 until threads are resumed, unless measures are taken to ensure
 that all threads are suspended at safe points.
 .Sh SEE ALSO
+.Xr pthread_np 3 ,
 .Xr pthread_resume_all_np 3 ,
 .Xr pthread_resume_np 3 ,
 .Xr pthread_suspend_np 3
diff --git a/share/man/man3/pthread_suspend_np.3 b/share/man/man3/pthread_suspend_np.3
index ca8c72a38c52..58bcf56964b6 100644
--- a/share/man/man3/pthread_suspend_np.3
+++ b/share/man/man3/pthread_suspend_np.3
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd May 5, 2016
+.Dd October 12, 2021
 .Dt PTHREAD_SUSPEND_NP 3
 .Os
 .Sh NAME
@@ -69,6 +69,7 @@ No thread could be found corresponding to the thread ID specified by the
 argument.
 .El
 .Sh SEE ALSO
+.Xr pthread_np 3 ,
 .Xr pthread_resume_all_np 3 ,
 .Xr pthread_resume_np 3 ,
 .Xr pthread_suspend_all_np 3
diff --git a/share/man/man3/pthread_switch_add_np.3 b/share/man/man3/pthread_switch_add_np.3
index e3400e790335..ddfa630ffd9a 100644
--- a/share/man/man3/pthread_switch_add_np.3
+++ b/share/man/man3/pthread_switch_add_np.3
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd February 13, 2003
+.Dd October 12, 2021
 .Dt PTHREAD_SWITCH_ADD_NP 3
 .Os
 .Sh NAME
@@ -81,7 +81,8 @@ argument is different from the argument previously passed to the
 function.
 .El
 .Sh SEE ALSO
-.Xr pthread_create 3
+.Xr pthread_create 3 ,
+.Xr pthread_np 3
 .Sh AUTHORS
 This manual page was written by
 .An Alexey Zelkin Aq Mt phantom@FreeBSD.org .