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 29, 2025 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. 90An unmasked signal will terminate the sleep early, regardless of the 91.Dv SA_RESTART 92value on the interrupting signal. 93The 94.Fa rqtp 95and 96.Fa rmtp 97arguments can point to the same object. 98.Pp 99The following 100.Fa clock_id 101values are supported: 102.Pp 103.Bl -item -compact -offset indent 104.It 105CLOCK_MONOTONIC 106.It 107CLOCK_MONOTONIC_FAST 108.It 109CLOCK_MONOTONIC_PRECISE 110.It 111CLOCK_REALTIME 112.It 113CLOCK_REALTIME_FAST 114.It 115CLOCK_REALTIME_PRECISE 116.It 117CLOCK_SECOND 118.It 119CLOCK_UPTIME 120.It 121CLOCK_UPTIME_FAST 122.It 123CLOCK_UPTIME_PRECISE 124.El 125.Pp 126The suspension time may be longer than requested due to the 127scheduling of other activity by the system. 128The clocks with the 129.Dv _FAST 130suffix and the 131.Dv CLOCK_SECOND 132are subject to the allowed time interval deviation specified by the 133.Va kern.timecounter.alloweddeviation 134.Xr sysctl 8 135variable. 136The clocks with the 137.Dv _PRECISE 138suffix are always as precise as possible. 139The 140.Dv CLOCK_MONOTONIC , 141.Dv CLOCK_REALTIME 142and 143.Dv CLOCK_UPTIME 144are precise by default. 145Setting the 146.Va kern.timecounter.nanosleep_precise 147.Xr sysctl 8 148to a false value would make those clocks to behave like the 149.Dv _FAST 150clocks. 151.Pp 152The 153.Fn nanosleep 154function behaves like 155.Fn clock_nanosleep 156with a 157.Fa clock_id 158argument of 159.Dv CLOCK_REALTIME 160and without the 161.Dv TIMER_ABSTIME 162flag in the 163.Fa flags 164argument. 165.Sh RETURN VALUES 166These functions return zero when the requested time has elapsed. 167.Pp 168If these functions return for any other reason, then 169.Fn clock_nanosleep 170will directly return the error number, and 171.Fn nanosleep 172will return \-1 with the global variable 173.Va errno 174set to indicate the error. 175If a relative sleep is interrupted by a signal and 176.Fa rmtp 177is 178.Pf non- Dv NULL , 179the timespec structure it references is updated to contain the 180unslept amount (the request time minus the time actually slept). 181.Sh ERRORS 182These functions can fail with the following errors. 183.Bl -tag -width Er 184.It Bq Er EFAULT 185Either 186.Fa rqtp 187or 188.Fa rmtp 189points to memory that is not a valid part of the process 190address space. 191.It Bq Er EINTR 192The function was interrupted by the delivery of a signal. 193.It Bq Er EINVAL 194The 195.Fa rqtp 196argument specified a nanosecond value less than zero 197or greater than or equal to 1000 million. 198.It Bq Er EINVAL 199The 200.Fa flags 201argument contained an invalid flag. 202.It Bq Er EINVAL 203The 204.Fa clock_id 205argument was 206.Dv CLOCK_THREAD_CPUTIME_ID 207or an unrecognized value. 208.It Bq Er ENOTSUP 209The 210.Fa clock_id 211argument was valid but not supported by this implementation of 212.Fn clock_nanosleep . 213.El 214.Sh SEE ALSO 215.Xr clock_gettime 2 , 216.Xr sigaction 2 , 217.Xr sleep 3 218.Sh STANDARDS 219These functions conform to 220.St -p1003.1-2008 . 221.Sh HISTORY 222The predecessor of this system call, 223.Fn sleep , 224appeared in 225.At v3 , 226but was removed when 227.Xr alarm 3 228was introduced into 229.At v7 . 230The 231.Fn nanosleep 232system call has been available since 233.Nx 1.3 234and was ported to 235.Ox 2.1 236and 237.Fx 3.0 . 238The 239.Fn clock_nanosleep 240system call has been available since 241.Fx 11.1 . 242.Pp 243In 244.Fx 15.0 245the default behavior of 246.Fn clock_nanosleep 247with 248.Dv CLOCK_MONOTONIC , 249.Dv CLOCK_REALTIME , 250.Dv CLOCK_UPTIME 251clocks and 252.Fn nanosleep 253has been switched to use precise clock. 254