From 534c9c78f3e1ea966e0301afe836cf70c7c61e3b Mon Sep 17 00:00:00 2001
From: jilles <jilles@FreeBSD.org>
Date: Wed, 1 Jun 2016 21:58:13 +0000
Subject: [PATCH] thr_*(2): Add xrefs to what libthr implements using each
 syscall.

Add text to thr_exit(2) and thr_new(2) discouraging their use in
applications since calling these in a process with libthr loaded will
confuse libthr and is likely to cause hangs or crashes.

The thr_kill2(2) call is not used by libthr and may be useful in special
applications.

The other calls can be used in applications but it should not be necessary.
---
 lib/libc/sys/thr_exit.2     | 12 ++++++++++--
 lib/libc/sys/thr_kill.2     |  4 +++-
 lib/libc/sys/thr_new.2      | 12 ++++++++++--
 lib/libc/sys/thr_self.2     |  6 ++++--
 lib/libc/sys/thr_set_name.2 |  3 ++-
 5 files changed, 29 insertions(+), 8 deletions(-)

diff --git a/lib/libc/sys/thr_exit.2 b/lib/libc/sys/thr_exit.2
index 70a07f88ab6d..781b07fde7e8 100644
--- a/lib/libc/sys/thr_exit.2
+++ b/lib/libc/sys/thr_exit.2
@@ -28,7 +28,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd May 5, 2016
+.Dd June 1, 2016
 .Dt THR_EXIT 2
 .Os
 .Sh NAME
@@ -41,6 +41,13 @@
 .Ft void
 .Fn thr_exit "long *state"
 .Sh DESCRIPTION
+.Bf -symbolic
+This function is intended for implementing threading.
+Normal applications should call
+.Xr pthread_exit 3
+instead.
+.Ef
+.Pp
 The
 .Fn thr_exit
 system call terminates the current kernel-scheduled thread.
@@ -70,7 +77,8 @@ last one in the process.
 .Xr thr_new 2 ,
 .Xr thr_self 2 ,
 .Xr thr_set_name 2 ,
-.Xr _umtx_op 2
+.Xr _umtx_op 2 ,
+.Xr pthread_exit 3
 .Sh STANDARDS
 The
 .Fn thr_exit
diff --git a/lib/libc/sys/thr_kill.2 b/lib/libc/sys/thr_kill.2
index 5f88dd3cba61..04293aa59ee7 100644
--- a/lib/libc/sys/thr_kill.2
+++ b/lib/libc/sys/thr_kill.2
@@ -28,7 +28,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd May 5, 2016
+.Dd June 1, 2016
 .Dt THR_kill 2
 .Os
 .Sh NAME
@@ -112,11 +112,13 @@ The current process does not have sufficient privilege to check existence or
 send a signal to the specified process.
 .El
 .Sh SEE ALSO
+.Xr kill 2 ,
 .Xr thr_exit 2 ,
 .Xr thr_new 2 ,
 .Xr thr_self 2 ,
 .Xr thr_set_name 2 ,
 .Xr _umtx_op 2 ,
+.Xr pthread_kill 3 ,
 .Xr signal 3
 .Sh STANDARDS
 The
diff --git a/lib/libc/sys/thr_new.2 b/lib/libc/sys/thr_new.2
index 189ca7512e89..1de5f92ad56c 100644
--- a/lib/libc/sys/thr_new.2
+++ b/lib/libc/sys/thr_new.2
@@ -28,7 +28,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd May 5, 2016
+.Dd June 1, 2016
 .Dt THR_NEW 2
 .Os
 .Sh NAME
@@ -41,6 +41,13 @@
 .Ft int
 .Fn thr_new "struct thr_param *param" "int param_size"
 .Sh DESCRIPTION
+.Bf -symbolic
+This function is intended for implementing threading.
+Normal applications should call
+.Xr pthread_create 3
+instead.
+.Ef
+.Pp
 The
 .Fn thr_new
 system call creates a new kernel-scheduled thread of execution in the context
@@ -220,7 +227,8 @@ No kernel memory to allocate for the new thread structures.
 .Xr thr_kill2 2 ,
 .Xr thr_self 2 ,
 .Xr thr_set_name 2 ,
-.Xr _umtx_op 2
+.Xr _umtx_op 2 ,
+.Xr pthread_create 3
 .Sh STANDARDS
 The
 .Fn thr_new
diff --git a/lib/libc/sys/thr_self.2 b/lib/libc/sys/thr_self.2
index 19c639d1909b..949b600a17f7 100644
--- a/lib/libc/sys/thr_self.2
+++ b/lib/libc/sys/thr_self.2
@@ -28,7 +28,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd May 5, 2016
+.Dd June 1, 2016
 .Dt THR_SELF 2
 .Os
 .Sh NAME
@@ -76,7 +76,9 @@ argument is not valid.
 .Xr thr_kill2 2 ,
 .Xr thr_new 2 ,
 .Xr thr_set_name 2 ,
-.Xr _umtx_op 2
+.Xr _umtx_op 2 ,
+.Xr pthread_getthreadid_np 3 ,
+.Xr pthread_self 3
 .Sh STANDARDS
 The
 .Fn thr_self
diff --git a/lib/libc/sys/thr_set_name.2 b/lib/libc/sys/thr_set_name.2
index 5478d1306ca5..d2549e408cb6 100644
--- a/lib/libc/sys/thr_set_name.2
+++ b/lib/libc/sys/thr_set_name.2
@@ -28,7 +28,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd May 5, 2016
+.Dd June 1, 2016
 .Dt THR_SET_NAME 2
 .Os
 .Sh NAME
@@ -87,6 +87,7 @@ does not exist in the current process.
 .Xr thr_new 2 ,
 .Xr thr_self 2 ,
 .Xr _umtx_op 2 ,
+.Xr pthread_set_name_np 3 ,
 .Xr ddb 4 ,
 .Xr ktr 9
 .Sh STANDARDS