1.\" $NetBSD: nanosleep.2,v 1.23 2016/11/14 10:40:59 wiz Exp $ 2.\" 3.\" Copyright (c) 1986, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.Dd April 3, 2022 31.Dt NANOSLEEP 2 32.Os 33.Sh NAME 34.Nm nanosleep 35.Nd high resolution sleep 36.Sh LIBRARY 37.Lb libc 38.Sh SYNOPSIS 39.In time.h 40.Ft int 41.Fo clock_nanosleep 42.Fa "clockid_t clock_id" 43.Fa "int flags" 44.Fa "const struct timespec *rqtp" 45.Fa "struct timespec *rmtp" 46.Fc 47.Ft int 48.Fo nanosleep 49.Fa "const struct timespec *rqtp" 50.Fa "struct timespec *rmtp" 51.Fc 52.Sh DESCRIPTION 53If the 54.Dv TIMER_ABSTIME 55flag is not set in the 56.Fa flags 57argument, then 58.Fn clock_nanosleep 59suspends execution of the calling thread until either the 60time interval specified by the 61.Fa rqtp 62argument has elapsed, 63or a signal is delivered to the calling process and its 64action is to invoke a signal-catching function or to terminate the 65process. 66The clock used to measure the time is specified by the 67.Fa clock_id 68argument. 69.Pp 70If the 71.Dv TIMER_ABSTIME 72flag is set in the 73.Fa flags 74argument, then 75.Fn clock_nanosleep 76suspends execution of the calling thread until either the value 77of the clock specified by the 78.Fa clock_id 79argument reaches the absolute time specified by the 80.Fa rqtp 81argument, 82or a signal is delivered to the calling process and its 83action is to invoke a signal-catching function or to terminate the 84process. 85If, at the time of the call, the time value specified by 86.Fa rqtp 87is less than or equal to the time value of the specified clock, then 88.Fn clock_nanosleep 89returns immediately and the calling thread is not suspended. 90.Pp 91The suspension time may be longer than requested due to the 92scheduling of other activity by the system. 93It is also subject to the allowed time interval deviation 94specified by the 95.Va kern.timecounter.alloweddeviation 96.Xr sysctl 8 97variable. 98An unmasked signal will terminate the sleep early, regardless of the 99.Dv SA_RESTART 100value on the interrupting signal. 101The 102.Fa rqtp 103and 104.Fa rmtp 105arguments can point to the same object. 106.Pp 107The following 108.Fa clock_id 109values are supported: 110.Pp 111.Bl -item -compact -offset indent 112.It 113CLOCK_MONOTONIC 114.It 115CLOCK_MONOTONIC_FAST 116.It 117CLOCK_MONOTONIC_PRECISE 118.It 119CLOCK_REALTIME 120.It 121CLOCK_REALTIME_FAST 122.It 123CLOCK_REALTIME_PRECISE 124.It 125CLOCK_SECOND 126.It 127CLOCK_UPTIME 128.It 129CLOCK_UPTIME_FAST 130.It 131CLOCK_UPTIME_PRECISE 132.El 133.Pp 134The 135.Fn nanosleep 136function behaves like 137.Fn clock_nanosleep 138with a 139.Fa clock_id 140argument of 141.Dv CLOCK_REALTIME 142and without the 143.Dv TIMER_ABSTIME 144flag in the 145.Fa flags 146argument. 147.Sh RETURN VALUES 148These functions return zero when the requested time has elapsed. 149.Pp 150If these functions return for any other reason, then 151.Fn clock_nanosleep 152will directly return the error number, and 153.Fn nanosleep 154will return \-1 with the global variable 155.Va errno 156set to indicate the error. 157If a relative sleep is interrupted by a signal and 158.Fa rmtp 159is 160.Pf non- Dv NULL , 161the timespec structure it references is updated to contain the 162unslept amount (the request time minus the time actually slept). 163.Sh ERRORS 164These functions can fail with the following errors. 165.Bl -tag -width Er 166.It Bq Er EFAULT 167Either 168.Fa rqtp 169or 170.Fa rmtp 171points to memory that is not a valid part of the process 172address space. 173.It Bq Er EINTR 174The function was interrupted by the delivery of a signal. 175.It Bq Er EINVAL 176The 177.Fa rqtp 178argument specified a nanosecond value less than zero 179or greater than or equal to 1000 million. 180.It Bq Er EINVAL 181The 182.Fa flags 183argument contained an invalid flag. 184.It Bq Er EINVAL 185The 186.Fa clock_id 187argument was 188.Dv CLOCK_THREAD_CPUTIME_ID 189or an unrecognized value. 190.It Bq Er ENOTSUP 191The 192.Fa clock_id 193argument was valid but not supported by this implementation of 194.Fn clock_nanosleep . 195.El 196.Sh SEE ALSO 197.Xr clock_gettime 2 , 198.Xr sigaction 2 , 199.Xr sleep 3 200.Sh STANDARDS 201These functions conform to 202.St -p1003.1-2008 . 203.Sh HISTORY 204The predecessor of this system call, 205.Fn sleep , 206appeared in 207.At v3 , 208but was removed when 209.Xr alarm 3 210was introduced into 211.At v7 . 212The 213.Fn nanosleep 214system call has been available since 215.Nx 1.3 216and was ported to 217.Ox 2.1 218and 219.Fx 3.0 . 220