On Tue, Jul 20, 2021 at 06:26:45PM -0600, Theo de Raadt wrote:
> I think this is excessively verbose for such a simple function, especially
> the addition of examples.
>
> There are many APIs which are hundreds of times more complicated which
> don't have this level of detailing, and I would argue such manual pages
> have the correct tone and complexity.
>
> It stops feeling like a historically+adapted BSD manual page.
The only major addition to the length here is the new examples. I
would argue that everything else is either clarified or missing from
the current page.
I'm not wed to keeping all the examples. What if we merge examples 1
and 2 and dumb the result down a bit?
Index: nanosleep.2
===================================================================
RCS file: /cvs/src/lib/libc/sys/nanosleep.2,v
retrieving revision 1.16
diff -u -p -r1.16 nanosleep.2
--- nanosleep.2 31 Dec 2018 18:54:00 -0000 1.16
+++ nanosleep.2 21 Jul 2021 01:02:20 -0000
@@ -41,53 +41,95 @@
.Ft int
.Fn nanosleep "const struct timespec *timeout" "struct timespec *remainder"
.Sh DESCRIPTION
+The
.Fn nanosleep
-suspends execution of the calling process for the duration specified by
+function suspends execution of the calling thread for at least the
+duration specified by
.Fa timeout .
-An unmasked signal will cause it to terminate the sleep early,
-regardless of the
+Delivery of an unmasked signal to the calling thread will terminate the
+sleep early,
+even if
.Dv SA_RESTART
-value on the interrupting signal.
+is set for the interrupting signal.
.Sh RETURN VALUES
-If the
+If
.Fn nanosleep
-function returns because the requested duration has elapsed, the value
-returned will be zero.
+sleeps the full
+.Fa timeout
+without interruption it returns 0.
+If
+.Fa remainder
+is
+.Pf non- Dv NULL
+it is set to zero.
.Pp
-If the
+If
.Fn nanosleep
-function returns due to the delivery of a signal, the value returned
-will be \-1, and the global variable
+is interrupted by a signal it returns -1 and the global variable
.Va errno
-will be set to indicate the interruption.
+is set to
+.Dv EINTR .
If
.Fa remainder
-is non-null, the timespec structure it references is updated to contain the
-unslept amount (the requested duration minus the duration actually slept).
-.Sh ERRORS
-If any of the following conditions occur, the
+is
+.Pf non- Dv NULL
+it is set to the unslept portion of the
+.Fa timeout .
+.Pp
+Otherwise,
.Fn nanosleep
-function shall return \-1 and set
+returns -1 and the global variable
.Va errno
-to the corresponding value.
+is set to indicate the error.
+.Sh EXAMPLES
+Sleep for five and a half seconds:
+.Bd -literal
+ struct timespec timeout;
+
+ timeout.tv_sec = 5;
+ timeout.tv_nsec = 500 * 1000 * 1000;
+ if (nanosleep(&timeout, NULL) == -1)
+ err(1, "nanosleep");
+.Ed
+.Pp
+Sleep for at least sixty seconds and print the time remaining whenever
+a signal interrupts the sleep:
+.Bd -literal
+ struct timespec timeout;
+
+ timeout.tv_sec = 60;
+ timeout.tv_nsec = 0;
+
+ while (nanosleep(&timeout, &timeout) == -1) {
+ if (errno != EINTR)
+ err(1, "nanosleep");
+ printf("time left: %lld.%09ld seconds\\n",
+ (long long)timeout.tv_sec, timeout.tv_nsec);
+ }
+.Ed
+.Sh ERRORS
+.Fn nanosleep
+will fail if:
.Bl -tag -width Er
.It Bq Er EINTR
-.Fn nanosleep
-was interrupted by the delivery of a signal.
+The call is interrupted by the delivery of a signal.
.It Bq Er EINVAL
.Fa timeout
-specified a nanosecond value less than zero or greater than or equal to
-1000 million,
+specifies a nanosecond value less than zero or greater than or equal to
+one billion,
or a second value less than zero.
.It Bq Er EFAULT
-Either
.Fa timeout
-or
-.Fa remainder
points to memory that is not a valid part of the process address space.
+.It Bq Er EFAULT
+.Fa remainder
+is
+.Pf non- Dv NULL
+and points to memory that is not a valid part of the process address space.
.El
.Sh SEE ALSO
.Xr sleep 1 ,
+.Xr sigaction 2 ,
.Xr sleep 3
.Sh STANDARDS
The
@@ -97,17 +139,23 @@ function conforms to
.Sh HISTORY
The predecessor of this system call,
.Fn sleep ,
-appeared in
-.At v3 ,
-but was removed when
+first appeared in
+.At v3 .
+It was removed in
+.At v7
+and replaced with a C library implementation based on
.Xr alarm 3
-was introduced into
-.At v7 .
+and
+.Xr signal 3 .
+.Pp
The
.Fn nanosleep
-system call has been available since
+function first appeared in
+.St -p1003.1b-93 .
+.Pp
+This implementation of
+.Fn nanosleep
+first appeared in
.Nx 1.3
and was ported to
-.Ox 2.1
-and
-.Fx 3.0 .
+.Ox 2.1 .
