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.\" @(#)sleep.3 8.1 (Berkeley) 6/4/93 31.\" 32.Dd November 11, 2016 33.Dt NANOSLEEP 2 34.Os 35.Sh NAME 36.Nm nanosleep 37.Nd high resolution sleep 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In time.h 42.Ft int 43.Fn clock_nanosleep "clockid_t clock_id" "int flags" "const struct timespec *rqtp" "struct timespec *rmtp" 44.Ft int 45.Fn nanosleep "const struct timespec *rqtp" "struct timespec *rmtp" 46.Sh DESCRIPTION 47If the 48.Dv TIMER_ABSTIME 49flag is not set in the 50.Fa flags 51argument, then 52.Fn clock_nanosleep 53suspends execution of the calling thread until either the number of 54seconds and nanoseconds specified in the 55.Fa rqtp 56argument have elapsed using the clock in the 57.Fa clock_id 58argument, or a signal is delivered to the calling process and its 59action is to invoke a signal catching function or to terminate the 60process. 61.Pp 62If the 63.Dv TIMER_ABSTIME 64flag is set in the 65.Fa flags 66argument, then 67.Fn clock_nanosleep 68suspends execution of the calling thread until either the value 69of the clock specified in the 70.Fa clock_id 71argument reaches the value of the 72.Fa rqtp 73argument in seconds and nanoseconds, 74or a signal is delivered to the calling process and its 75action is to invoke a signal catching function or to terminate the 76process. 77.Pp 78The suspension time may be longer than requested due to the 79scheduling of other activity by the system. 80.Pp 81The 82.Fn nanosleep 83function behaves like 84.Fn clock_nanosleep 85with the 86.Fa clock_id 87argument equal to 88.Dv CLOCK_MONOTONIC 89and the 90.Fa flags 91argument having 92.Dv TIMER_ABSTIME 93not set. 94.Pp 95The 96.Em struct timespec 97is described in 98.Xr timespec 3 . 99The 100.Fa clock_id 101specified is the time source, which is described in 102.Xr clock_gettime 2 . 103.Sh RETURN VALUES 104If the 105.Fn clock_nanosleep 106or the 107.Fn nanosleep 108functions return because the requested time has elapsed, the value 109returned will be zero. 110.Pp 111If the 112.Fn clock_nanosleep 113or the 114.Fn nanosleep 115functions return due to the delivery of a signal, then 116.Fn clock_nanosleep 117will return directly the error number, and 118.Fn nanosleep 119will return \-1, and the global variable 120.Va errno 121will be set to indicate the interruption. 122If 123.Fa rmtp 124is 125.Pf non- Dv NULL , 126the timespec structure it references is updated to contain the 127unslept amount (the request time minus the time actually slept), 128unless it is called from 129.Fn clock_nanosleep 130with a 131.Fa flags 132argument of 133.Dv TIMER_ABSTIME . 134In that case, the 135.Fa rmtp 136argument is left unmodified. 137.Sh ERRORS 138If any of the following conditions occur, the 139.Fn nanosleep 140function shall return \-1 and set 141.Va errno 142to the corresponding value, and the 143.Fn clock_nanosleep 144function shall return the error number directly. 145.Bl -tag -width Er 146.It Bq Er EFAULT 147Either 148.Fa rqtp 149or 150.Fa rmtp 151points to memory that is not a valid part of the process 152address space. 153.It Bq Er EINTR 154.Nm 155was interrupted by the delivery of a signal. 156.It Bq Er EINVAL 157.Fa rqtp 158specified a nanosecond value less than zero or greater than 1000 million. 159.It Bq Er ENOSYS 160.Nm 161is not supported by this implementation. 162.It Bq Er ENOTSUP 163for 164.Fn clock_nanosleep , 165the clock specified in the 166.Fa clock_id 167argument is not supported. 168.El 169.Sh SEE ALSO 170.Xr clock_gettime 2 , 171.Xr sleep 3 , 172.Xr timespec 3 173.Sh STANDARDS 174The 175.Fn nanosleep 176function conforms to 177.St -p1003.1b-93 . 178The 179.Fn clock_nanosleep 180function conforms to 181.St -p1003.1j-2000 . 182.Sh BUGS 183The 184.Nx 185kernel is not tickless, so the maximum sleep resolution is determined 186by the value of 187.Dv HZ 188which is by default 189.Dv 100 190in most architectures. 191This means that a request to sleep for less than 192.Dv 10ms 193(1 / 194.Dv HZ 195seconds), is rounded up to that. 196