summaryrefslogtreecommitdiff
path: root/lib/libc/sys
diff options
context:
space:
mode:
authorcheloha <cheloha@cvs.openbsd.org>2021-07-23 12:47:22 +0000
committercheloha <cheloha@cvs.openbsd.org>2021-07-23 12:47:22 +0000
commited3d193137361231ef59952d009c7a5a478bb4b4 (patch)
treeb5ebf12f2793df9ec72c122a77fd548cde4e93dd /lib/libc/sys
parent861cbdd3459ee4740cf37f27d9316f1f24695494 (diff)
nanosleep.2: miscellaneous cleanup and rewrites
Clean up the nanosleep(2) manpage. Correct errors and rewrite the clunky parts. Lots of input and suggestions from schwarze@ and deraadt@. Thread: https://marc.info/?l=openbsd-tech&m=162681970507360&w=2 ok schwarze@
Diffstat (limited to 'lib/libc/sys')
-rw-r--r--lib/libc/sys/nanosleep.294
1 files changed, 58 insertions, 36 deletions
diff --git a/lib/libc/sys/nanosleep.2 b/lib/libc/sys/nanosleep.2
index 63e4e4e365b..fc2bffb9a9d 100644
--- a/lib/libc/sys/nanosleep.2
+++ b/lib/libc/sys/nanosleep.2
@@ -1,4 +1,4 @@
-.\" $OpenBSD: nanosleep.2,v 1.16 2018/12/31 18:54:00 cheloha Exp $
+.\" $OpenBSD: nanosleep.2,v 1.17 2021/07/23 12:47:21 cheloha Exp $
.\" $NetBSD: nanosleep.2,v 1.1 1997/04/17 18:12:02 jtc Exp $
.\"
.\" Copyright (c) 1986, 1991, 1993
@@ -30,7 +30,7 @@
.\"
.\" @(#)sleep.3 8.1 (Berkeley) 6/4/93
.\"
-.Dd $Mdocdate: December 31 2018 $
+.Dd $Mdocdate: July 23 2021 $
.Dt NANOSLEEP 2
.Os
.Sh NAME
@@ -41,53 +41,69 @@
.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 given
.Fa timeout .
-An unmasked signal will cause it to terminate the sleep early,
-regardless of the
+Delivery of an unmasked signal terminates this sleep early,
+even if
.Dv SA_RESTART
-value on the interrupting signal.
+is set with
+.Xr sigaction 2
+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.
+Unless
+.Fa remainder
+is
+.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.
-If
+is set to
+.Dv EINTR .
+Unless
.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
+.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 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 not
+.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 +113,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 .