pause.3: miscellaneous rewrites, cleanup

Eliminate some redundant or extraneous pieces from the pause.3 page.
Say the "thread" "blocks", don't say the "process" "pauses".  No need
to enumerate the ways a signal can be delivered.  Add a few relevant
cross-references.

With input from millert@ and schwarze@.

Link: https://marc.info/?l=openbsd-tech&m=166801212316670&w=2
ok millert@ schwarze@

diff --git a/lib/libc/gen/pause.3 b/lib/libc/gen/pause.3
index 0925d65..969f7b4 100644 (file)
--- a/lib/libc/gen/pause.3
+++ b/lib/libc/gen/pause.3
@@ -1,4 +1,4 @@
-.\"    $OpenBSD: pause.3,v 1.16 2022/11/09 06:48:29 jmc Exp $
+.\"    $OpenBSD: pause.3,v 1.17 2022/12/30 21:21:25 cheloha Exp $
 .\"
 .\" Copyright (c) 1980, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -27,12 +27,12 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 9 2022 $
+.Dd $Mdocdate: December 30 2022 $
 .Dt PAUSE 3
 .Os
 .Sh NAME
 .Nm pause
-.Nd stop until signal
+.Nd wait for a signal
 .Sh SYNOPSIS
 .In unistd.h
 .Ft int
@@ -40,40 +40,30 @@
 .Sh DESCRIPTION
 .Bf -symbolic
 .Fn pause
-is made obsolete by
+is obsoleted by
 .Xr sigsuspend 2 .
 .Ef
 .Pp
-The
 .Fn pause
-function forces a process to pause until a signal is received from either the
-.Xr kill 2
-function or an interval timer
-(see
-.Xr setitimer 2 ) .
-.Pp
-Upon termination of a signal handler started during a
-.Fn pause ,
-the
-.Fn pause
-call will return.
+blocks the calling thread until it receives an unmasked signal.
 .Sh RETURN VALUES
-Always returns \-1.
+.Fn pause
+always returns \-1.
 .Sh ERRORS
-The
 .Fn pause
-function may set the global variable
-.Va errno
-to the following error:
+always sets
+.Xr errno 2
+to the following value:
 .Bl -tag -width Er
 .It Bq Er EINTR
-The call was interrupted.
+The call was interrupted by a signal.
 .El
 .Sh SEE ALSO
 .Xr kill 2 ,
-.Xr select 2 ,
 .Xr setitimer 2 ,
-.Xr sigsuspend 2
+.Xr sigprocmask 2 ,
+.Xr sigsuspend 2 ,
+.Xr signal 3
 .Sh HISTORY
 A
 .Fn pause