From 9c671dbd0b15400ade9db3659ffd06087027a1b9 Mon Sep 17 00:00:00 2001
From: Konstantin Belousov <kib@FreeBSD.org>
Date: Thu, 5 May 2016 10:22:19 +0000
Subject: [PATCH] Warn about consequences of suspending threads in arbitrary
 state of execution.

While there, fix minor nits in markup.

Sponsored by:	The FreeBSD Foundation
MFC after:	1 week
---
 share/man/man3/pthread_resume_np.3      |  2 +-
 share/man/man3/pthread_suspend_all_np.3 |  9 ++++++++-
 share/man/man3/pthread_suspend_np.3     | 11 +++++++++--
 3 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/share/man/man3/pthread_resume_np.3 b/share/man/man3/pthread_resume_np.3
index c8444d2dabcd..eba7568c1006 100644
--- a/share/man/man3/pthread_resume_np.3
+++ b/share/man/man3/pthread_resume_np.3
@@ -57,7 +57,7 @@ function will fail if:
 The value specified by the
 .Fa tid
 argument is invalid.
-.It Bq ESRC
+.It Bq Er ESRC
 No thread could be found corresponding to the thread ID specified by the
 .Fa tid
 argument.
diff --git a/share/man/man3/pthread_suspend_all_np.3 b/share/man/man3/pthread_suspend_all_np.3
index 9daedbf7b064..ecedca3ee24d 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 February 13, 2003
+.Dd May 5, 2016
 .Dt PTHREAD_SUSPEND_ALL_NP 3
 .Os
 .Sh NAME
@@ -44,6 +44,13 @@ The only exception is the current thread,
 the thread that called the
 .Fn pthread_suspend_all_np
 function.
+.Pp
+It is not safe for the caller of the
+.Fn pthread_suspend_all_np
+function to use any non-async signal safe functions, besides
+.Xr pthread_resume_all_np 3 ,
+until threads are resumed, unless measures are taken to ensure
+that all threads are suspended at safe points.
 .Sh SEE ALSO
 .Xr pthread_resume_all_np 3 ,
 .Xr pthread_resume_np 3 ,
diff --git a/share/man/man3/pthread_suspend_np.3 b/share/man/man3/pthread_suspend_np.3
index 32138a15a106..e68b317b48aa 100644
--- a/share/man/man3/pthread_suspend_np.3
+++ b/share/man/man3/pthread_suspend_np.3
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd February 13, 2003
+.Dd May 5, 2016
 .Dt PTHREAD_SUSPEND_NP 3
 .Os
 .Sh NAME
@@ -40,6 +40,13 @@
 The
 .Fn pthread_suspend_np
 function, called on an active thread, causes it to suspend.
+.Pp
+It is not safe for the caller of the
+.Fn pthread_suspend_np
+function to use any non-async signal safe functions, except
+.Xr pthread_resume_np 3 ,
+until suspended thread is resumed, unless measures are taken to ensure
+that the thread is suspended at a safe point.
 .Sh RETURN VALUES
 If successful,
 .Fn pthread_suspend_np
@@ -56,7 +63,7 @@ An attempt was made to suspend the current thread.
 The value specified by the
 .Fa tid
 argument is invalid.
-.It Bq ESRC
+.It Bq Er ESRC
 No thread could be found corresponding to the thread ID specified by the
 .Fa tid
 argument.