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.

5 files changed, 29 insertions, 8 deletions

diff --git a/lib/libc/sys/thr_exit.2 b/lib/libc/sys/thr_exit.2
index 70a07f8..781b07f 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 5f88dd3..04293aa 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 189ca75..1de5f92 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 19c639d..949b600 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 5478d13..d2549e4 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