sleep.3: miscellanous cleanup, rewrites

Highlights:

- Tighten up the NAME.
- "process" -> "thread".
- Tidy up the DESCRIPTION.  In particular, omit discussion of the
  historial SIGALRM-based implementation.
- Simplify RETURN VALUES.
- Add an ERRORS section, note that sleep(3) can set EINTR.
- Update STANDARDS to POSIX.1-2008.
- Note that setting errno is an extension to the spec.

Discussed with and revised by jmc@, deraadt@, millert@, and schwarze@.
With a history lesson from jsg@.

Thread: https://marc.info/?l=openbsd-tech&m=162718445809428&w=2

"the changes read fine to me" jmc@, ok millert@ schwarze@

diff --git a/lib/libc/gen/sleep.3 b/lib/libc/gen/sleep.3
index 8702cb0..ac6bec3 100644 (file)
--- a/lib/libc/gen/sleep.3
+++ b/lib/libc/gen/sleep.3
@@ -1,4 +1,4 @@
-.\"    $OpenBSD: sleep.3,v 1.16 2020/02/08 01:09:57 jsg Exp $
+.\"    $OpenBSD: sleep.3,v 1.17 2021/12/07 03:16:08 cheloha Exp $
 .\"
 .\" Copyright (c) 1986, 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: February 8 2020 $
+.Dd $Mdocdate: December 7 2021 $
 .Dt SLEEP 3
 .Os
 .Sh NAME
 .Nm sleep
-.Nd suspend process execution for interval measured in seconds
+.Nd suspend execution for an interval of seconds
 .Sh SYNOPSIS
 .In unistd.h
 .Ft unsigned int
@@ -40,41 +40,51 @@
 .Sh DESCRIPTION
 The
 .Fn sleep
-function suspends execution of the calling process until either
+function suspends execution of the calling thread until at least the
+given number of
 .Fa seconds
-seconds have elapsed or a signal is delivered to the process and its
-action is to invoke a signal-catching function or to terminate the
-process.
-The suspension time may be longer than requested due to the
-scheduling of other activity by the system.
+have elapsed or an unmasked signal is delivered to the calling thread.
 .Pp
-This function is implemented using
-.Xr nanosleep 2
-by pausing for
-.Fa seconds
-seconds or until a signal occurs.
-Consequently, in this implementation,
-sleeping has no effect on the state of process timers,
-and there is no special handling for
-.Dv SIGALRM .
+This version of
+.Fn sleep
+is implemented with
+.Xr nanosleep 2 ,
+so delivery of any unmasked signal will terminate the sleep early,
+even if
+.Dv SA_RESTART
+is set with
+.Xr sigaction 2
+for the interrupting signal.
 .Sh RETURN VALUES
-If the
+If
+.Fn sleep
+sleeps for the full count of
+.Fa seconds
+it returns 0.
+Otherwise,
 .Fn sleep
-function returns because the requested time has elapsed, the value
-returned will be zero.
-If the
+returns the number of seconds remaining from the original request.
+.Sh ERRORS
+The
 .Fn sleep
-function returns due to the delivery of a signal, the value returned
-will be the unslept amount (the request time minus the time actually
-slept) in seconds.
+function sets
+.Va errno
+to
+.Dv EINTR
+if it is interrupted by the delivery of a signal.
 .Sh SEE ALSO
 .Xr sleep 1 ,
-.Xr nanosleep 2
+.Xr nanosleep 2 ,
+.Xr sigaction 2
 .Sh STANDARDS
 The
 .Fn sleep
 function conforms to
-.St -p1003.1-90 .
+.St -p1003.1-2008 .
+.Pp
+Setting
+.Va errno
+is an extension to that specification.
 .Sh HISTORY
 A
 .Fn sleep