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