1 .\" Copyright (C) Markus Kuhn, 1996
2 .\" and Copyright (C) Linux Foundation, 2008, written by Michael Kerrisk
3 .\" <mtk.manpages@gmail.com>
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
7 .\" 1996-04-10 Markus Kuhn <mskuhn@cip.informatik.uni-erlangen.de>
8 .\" First version written
9 .\" Modified, 2004-10-24, aeb
11 .\" Minor rewrites of some parts.
12 .\" NOTES: describe case where clock_nanosleep() can be preferable.
13 .\" NOTES: describe CLOCK_REALTIME versus CLOCK_NANOSLEEP
14 .\" Replace crufty discussion of HZ with a pointer to time(7).
15 .TH nanosleep 2 (date) "Linux man-pages (unreleased)"
17 nanosleep \- high-resolution sleep
20 .RI ( libc ", " \-lc )
25 .BI "int nanosleep(const struct timespec *" req ", struct timespec *" rem );
29 Feature Test Macro Requirements for glibc (see
30 .BR feature_test_macros (7)):
35 _POSIX_C_SOURCE >= 199309L
39 suspends the execution of the calling thread
40 until either at least the time specified in
42 has elapsed, or the delivery of a signal
43 that triggers the invocation of a handler in the calling thread or
44 that terminates the process.
46 If the call is interrupted by a signal handler,
52 and writes the remaining time into the structure pointed to by
59 can then be used to call
61 again and complete the specified pause (but see NOTES).
66 is used to specify intervals of time with nanosecond precision.
68 The value of the nanoseconds field must be in the range 0 to 999999999.
75 has the following advantages:
76 it provides a higher resolution for specifying the sleep interval;
77 POSIX.1 explicitly specifies that it
78 does not interact with signals;
79 and it makes the task of resuming a sleep that has been
80 interrupted by a signal handler easier.
82 On successfully sleeping for the requested interval,
85 If the call is interrupted by a signal handler or encounters an error,
86 then it returns \-1, with
88 set to indicate the error.
92 Problem with copying information from user space.
95 The pause has been interrupted by a signal that was
96 delivered to the thread (see
98 The remaining sleep time has been written
101 so that the thread can easily call
103 again and continue with the pause.
108 field was not in the range 0 to 999999999 or
112 POSIX.1-2001, POSIX.1-2008.
114 If the interval specified in
116 is not an exact multiple of the granularity underlying clock (see
118 then the interval will be rounded up to the next multiple.
119 Furthermore, after the sleep completes, there may still be a delay before
120 the CPU becomes free to once again execute the calling thread.
124 sleeps for a relative interval can be problematic if the call
125 is repeatedly restarted after being interrupted by signals,
126 since the time between the interruptions and restarts of the call
127 will lead to drift in the time when the sleep finally completes.
128 This problem can be avoided by using
129 .BR clock_nanosleep (2)
130 with an absolute time value.
132 POSIX.1 specifies that
134 should measure time against the
137 However, Linux measures the time using the
140 .\" See also http://thread.gmane.org/gmane.linux.kernel/696854/
141 .\" Subject: nanosleep() uses CLOCK_MONOTONIC, should be CLOCK_REALTIME?
142 .\" Date: 2008-06-22 07:35:41 GMT
143 This probably does not matter, since the POSIX.1 specification for
144 .BR clock_settime (2)
145 says that discontinuous changes in
151 Setting the value of the
154 .BR clock_settime (2)
156 have no effect on threads that are blocked waiting for a relative time
157 service based upon this clock, including the
160 Consequently, these time services shall expire when the requested relative
161 interval elapses, independently of the new or old value of the clock.
164 In order to support applications requiring much more precise pauses
165 (e.g., in order to control some time-critical hardware),
167 would handle pauses of up to 2 milliseconds by busy waiting with microsecond
168 precision when called from a thread scheduled under a real-time policy
173 This special extension was removed in kernel 2.5.39,
174 and is thus not available in Linux 2.6.0 and later kernels.
176 If a program that catches signals and uses
178 receives signals at a very high rate,
179 then scheduling delays and rounding errors in the kernel's
180 calculation of the sleep interval and the returned
186 on successive restarts of the
189 To avoid such problems, use
190 .BR clock_nanosleep (2)
193 flag to sleep to an absolute deadline.
197 is stopped by a signal (e.g.,
199 then the call fails with the error
201 after the thread is resumed by a
204 If the system call is subsequently restarted,
205 then the time that the thread spent in the stopped state is
207 counted against the sleep interval.
208 This problem is fixed in Linux 2.6.0 and later kernels.
210 .BR clock_nanosleep (2),
211 .BR restart_syscall (2),
212 .BR sched_setscheduler (2),
213 .BR timer_create (2),