1 .\" Copyright (C) Markus Kuhn, 1996
2 .\" and Copyright (C) Linux Foundation, 2008, written by Michael Kerrisk
3 .\" <mtk.manpages@gmail.com>
5 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
6 .\" This is free documentation; you can redistribute it and/or
7 .\" modify it under the terms of the GNU General Public License as
8 .\" published by the Free Software Foundation; either version 2 of
9 .\" the License, or (at your option) any later version.
11 .\" The GNU General Public License's references to "object code"
12 .\" and "executables" are to be interpreted as the output of any
13 .\" document formatting or typesetting system, including
14 .\" intermediate and printed output.
16 .\" This manual is distributed in the hope that it will be useful,
17 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
18 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 .\" GNU General Public License for more details.
21 .\" You should have received a copy of the GNU General Public
22 .\" License along with this manual; if not, see
23 .\" <http://www.gnu.org/licenses/>.
26 .\" 1996-04-10 Markus Kuhn <mskuhn@cip.informatik.uni-erlangen.de>
27 .\" First version written
28 .\" Modified, 2004-10-24, aeb
30 .\" Minor rewrites of some parts.
31 .\" NOTES: describe case where clock_nanosleep() can be preferable.
32 .\" NOTES: describe CLOCK_REALTIME versus CLOCK_NANOSLEEP
33 .\" Replace crufty discussion of HZ with a pointer to time(7).
34 .TH NANOSLEEP 2 2013-07-30 "Linux" "Linux Programmer's Manual"
36 nanosleep \- high-resolution sleep
40 .BI "int nanosleep(const struct timespec *" req ", struct timespec *" rem );
43 Feature Test Macro Requirements for glibc (see
44 .BR feature_test_macros (7)):
48 _POSIX_C_SOURCE\ >=\ 199309L
51 suspends the execution of the calling thread
52 until either at least the time specified in
54 has elapsed, or the delivery of a signal
55 that triggers the invocation of a handler in the calling thread or
56 that terminates the process.
58 If the call is interrupted by a signal handler,
64 and writes the remaining time into the structure pointed to by
71 can then be used to call
73 again and complete the specified pause (but see NOTES).
77 is used to specify intervals of time with nanosecond precision.
78 It is defined as follows:
83 time_t tv_sec; /* seconds */
84 long tv_nsec; /* nanoseconds */
89 The value of the nanoseconds field must be in the range 0 to 999999999.
96 has the following advantages:
97 it provides a higher resolution for specifying the sleep interval;
98 POSIX.1 explicitly specifies that it
99 does not interact with signals;
100 and it makes the task of resuming a sleep that has been
101 interrupted by a signal handler easier.
103 On successfully sleeping for the requested interval,
106 If the call is interrupted by a signal handler or encounters an error,
107 then it returns \-1, with
109 set to indicate the error.
113 Problem with copying information from user space.
116 The pause has been interrupted by a signal that was
117 delivered to the thread.
118 The remaining sleep time has been written
121 so that the thread can easily call
123 again and continue with the pause.
128 field was not in the range 0 to 999999999 or
134 If the interval specified in
136 is not an exact multiple of the granularity underlying clock (see
138 then the interval will be rounded up to the next multiple.
139 Furthermore, after the sleep completes, there may still be a delay before
140 the CPU becomes free to once again execute the calling thread.
144 sleeps for a relative interval can be problematic if the call
145 is repeatedly restarted after being interrupted by signals,
146 since the time between the interruptions and restarts of the call
147 will lead to drift in the time when the sleep finally completes.
148 This problem can be avoided by using
149 .BR clock_nanosleep (2)
150 with an absolute time value.
152 POSIX.1 specifies that
154 should measure time against the
157 However, Linux measures the time using the
160 .\" See also http://thread.gmane.org/gmane.linux.kernel/696854/
161 .\" Subject: nanosleep() uses CLOCK_MONOTONIC, should be CLOCK_REALTIME?
162 .\" Date: 2008-06-22 07:35:41 GMT
163 This probably does not matter, since the POSIX.1 specification for
164 .BR clock_settime (2)
165 says that discontinuous changes in
171 Setting the value of the
174 .BR clock_settime (2)
176 have no effect on threads that are blocked waiting for a relative time
177 service based upon this clock, including the
180 Consequently, these time services shall expire when the requested relative
181 interval elapses, independently of the new or old value of the clock.
184 In order to support applications requiring much more precise pauses
185 (e.g., in order to control some time-critical hardware),
187 would handle pauses of up to 2\ ms by busy waiting with microsecond
188 precision when called from a thread scheduled under a real-time policy
193 This special extension was removed in kernel 2.5.39,
194 hence is still present in
195 current 2.4 kernels, but not in 2.6 kernels.
199 is stopped by a signal (e.g.,
201 then the call fails with the error
203 after the thread is resumed by a
206 If the system call is subsequently restarted,
207 then the time that the thread spent in the stopped state is
209 counted against the sleep interval.
211 .BR clock_nanosleep (2),
212 .BR restart_syscall (2),
213 .BR sched_setscheduler (2),
214 .BR timer_create (2),
219 This page is part of release 3.79 of the Linux
222 A description of the project,
223 information about reporting bugs,
224 and the latest version of this page,
226 \%http://www.kernel.org/doc/man\-pages/.