]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright (C) Markus Kuhn, 1996 |
b0040075 MK |
2 | .\" and Copyright (C) Linux Foundation, 2008, written by Michael Kerrisk |
3 | .\" <mtk.manpages@gmail.com> | |
fea681da | 4 | .\" |
e4a74ca8 | 5 | .\" SPDX-License-Identifier: GPL-2.0-or-later |
fea681da MK |
6 | .\" |
7 | .\" 1996-04-10 Markus Kuhn <mskuhn@cip.informatik.uni-erlangen.de> | |
8 | .\" First version written | |
9 | .\" Modified, 2004-10-24, aeb | |
b0040075 MK |
10 | .\" 2008-06-24, mtk |
11 | .\" Minor rewrites of some parts. | |
12 | .\" NOTES: describe case where clock_nanosleep() can be preferable. | |
13 | .\" NOTES: describe CLOCK_REALTIME versus CLOCK_NANOSLEEP | |
8964c1a2 | 14 | .\" Replace crufty discussion of HZ with a pointer to time(7). |
45186a5d | 15 | .TH NANOSLEEP 2 2021-03-22 "Linux man-pages (unreleased)" |
fea681da | 16 | .SH NAME |
b0040075 | 17 | nanosleep \- high-resolution sleep |
a8f83be3 AC |
18 | .SH LIBRARY |
19 | Standard C library | |
8fc3b2cf | 20 | .RI ( libc ", " \-lc ) |
fea681da | 21 | .SH SYNOPSIS |
c7db92b9 | 22 | .nf |
fea681da | 23 | .B #include <time.h> |
68e4db0a | 24 | .PP |
cc4615cc | 25 | .BI "int nanosleep(const struct timespec *" req ", struct timespec *" rem ); |
c7db92b9 | 26 | .fi |
68e4db0a | 27 | .PP |
d39ad78f | 28 | .RS -4 |
cc4615cc MK |
29 | Feature Test Macro Requirements for glibc (see |
30 | .BR feature_test_macros (7)): | |
d39ad78f | 31 | .RE |
68e4db0a | 32 | .PP |
cc4615cc | 33 | .BR nanosleep (): |
1dd0d7b4 | 34 | .nf |
5c10d2c5 | 35 | _POSIX_C_SOURCE >= 199309L |
1dd0d7b4 | 36 | .fi |
fea681da | 37 | .SH DESCRIPTION |
e511ffb6 | 38 | .BR nanosleep () |
b0040075 MK |
39 | suspends the execution of the calling thread |
40 | until either at least the time specified in | |
1ae6b2c7 | 41 | .I *req |
b0040075 MK |
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. | |
efeece04 | 45 | .PP |
b0040075 MK |
46 | If the call is interrupted by a signal handler, |
47 | .BR nanosleep () | |
c6fa0841 MK |
48 | returns \-1, sets |
49 | .I errno | |
50 | to | |
fea681da | 51 | .BR EINTR , |
b0040075 | 52 | and writes the remaining time into the structure pointed to by |
0daa9e92 | 53 | .I rem |
c13182ef | 54 | unless |
fea681da | 55 | .I rem |
8478ee02 | 56 | is NULL. |
fea681da MK |
57 | The value of |
58 | .I *rem | |
c13182ef | 59 | can then be used to call |
e511ffb6 | 60 | .BR nanosleep () |
b0040075 | 61 | again and complete the specified pause (but see NOTES). |
efeece04 | 62 | .PP |
e97e048a | 63 | The |
64 | .BR timespec (3) | |
65 | structure | |
c13182ef | 66 | is used to specify intervals of time with nanosecond precision. |
fea681da MK |
67 | .PP |
68 | The value of the nanoseconds field must be in the range 0 to 999999999. | |
efeece04 | 69 | .PP |
fea681da | 70 | Compared to |
c5ae6d5a | 71 | .BR sleep (3) |
fea681da MK |
72 | and |
73 | .BR usleep (3), | |
e511ffb6 | 74 | .BR nanosleep () |
1b4cf8f4 | 75 | has the following advantages: |
b0040075 MK |
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. | |
47297adb | 81 | .SH RETURN VALUE |
13218d42 | 82 | On successfully sleeping for the requested interval, |
e511ffb6 | 83 | .BR nanosleep () |
13218d42 MK |
84 | returns 0. |
85 | If the call is interrupted by a signal handler or encounters an error, | |
c13182ef | 86 | then it returns \-1, with |
fea681da | 87 | .I errno |
13218d42 MK |
88 | set to indicate the error. |
89 | .SH ERRORS | |
43487dbb | 90 | .TP |
fea681da MK |
91 | .B EFAULT |
92 | Problem with copying information from user space. | |
93 | .TP | |
94 | .B EINTR | |
488007e8 | 95 | The pause has been interrupted by a signal that was |
ea84b0fd | 96 | delivered to the thread (see |
bb14af39 | 97 | .BR signal (7)). |
c13182ef | 98 | The remaining sleep time has been written |
c6fa0841 MK |
99 | into |
100 | .I *rem | |
101 | so that the thread can easily call | |
e511ffb6 | 102 | .BR nanosleep () |
fea681da MK |
103 | again and continue with the pause. |
104 | .TP | |
105 | .B EINVAL | |
106 | The value in the | |
107 | .I tv_nsec | |
108 | field was not in the range 0 to 999999999 or | |
109 | .I tv_sec | |
110 | was negative. | |
3113c7f3 | 111 | .SH STANDARDS |
67651ee6 | 112 | POSIX.1-2001, POSIX.1-2008. |
b0040075 MK |
113 | .SH NOTES |
114 | If the interval specified in | |
115 | .I req | |
116 | is not an exact multiple of the granularity underlying clock (see | |
117 | .BR time (7)), | |
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. | |
efeece04 | 121 | .PP |
b0040075 MK |
122 | The fact that |
123 | .BR nanosleep () | |
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. | |
efeece04 | 131 | .PP |
b0040075 MK |
132 | POSIX.1 specifies that |
133 | .BR nanosleep () | |
134 | should measure time against the | |
135 | .B CLOCK_REALTIME | |
136 | clock. | |
137 | However, Linux measures the time using the | |
138 | .B CLOCK_MONOTONIC | |
139 | clock. | |
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 | |
0b80cf56 | 144 | .BR clock_settime (2) |
b0040075 MK |
145 | says that discontinuous changes in |
146 | .B CLOCK_REALTIME | |
147 | should not affect | |
148 | .BR nanosleep (): | |
149 | .RS | |
150 | .PP | |
151 | Setting the value of the | |
152 | .B CLOCK_REALTIME | |
153 | clock via | |
0b80cf56 | 154 | .BR clock_settime (2) |
b0040075 MK |
155 | shall |
156 | have no effect on threads that are blocked waiting for a relative time | |
157 | service based upon this clock, including the | |
158 | .BR nanosleep () | |
159 | function; ... | |
160 | Consequently, these time services shall expire when the requested relative | |
161 | interval elapses, independently of the new or old value of the clock. | |
162 | .RE | |
73d8cece | 163 | .SS Old behavior |
25768803 MK |
164 | In order to support applications requiring much more precise pauses |
165 | (e.g., in order to control some time-critical hardware), | |
166 | .BR nanosleep () | |
bdcb7056 | 167 | would handle pauses of up to 2 milliseconds by busy waiting with microsecond |
25768803 MK |
168 | precision when called from a thread scheduled under a real-time policy |
169 | like | |
170 | .B SCHED_FIFO | |
171 | or | |
172 | .BR SCHED_RR . | |
173 | This special extension was removed in kernel 2.5.39, | |
760b892c | 174 | and is thus not available in Linux 2.6.0 and later kernels. |
762c2446 | 175 | .SH BUGS |
1186d4c3 MK |
176 | If a program that catches signals and uses |
177 | .BR nanosleep () | |
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 | |
1ae6b2c7 | 181 | .I remain |
1186d4c3 | 182 | value mean that the |
1ae6b2c7 | 183 | .I remain |
1186d4c3 | 184 | value may steadily |
1ae6b2c7 | 185 | .I increase |
1186d4c3 MK |
186 | on successive restarts of the |
187 | .BR nanosleep () | |
188 | call. | |
189 | To avoid such problems, use | |
190 | .BR clock_nanosleep (2) | |
191 | with the | |
1ae6b2c7 | 192 | .B TIMER_ABSTIME |
1186d4c3 | 193 | flag to sleep to an absolute deadline. |
efeece04 | 194 | .PP |
25768803 MK |
195 | In Linux 2.4, if |
196 | .BR nanosleep () | |
197 | is stopped by a signal (e.g., | |
198 | .BR SIGTSTP ), | |
199 | then the call fails with the error | |
200 | .B EINTR | |
201 | after the thread is resumed by a | |
202 | .B SIGCONT | |
203 | signal. | |
204 | If the system call is subsequently restarted, | |
205 | then the time that the thread spent in the stopped state is | |
c6fa0841 MK |
206 | .I not |
207 | counted against the sleep interval. | |
91bf33ff | 208 | This problem is fixed in Linux 2.6.0 and later kernels. |
47297adb | 209 | .SH SEE ALSO |
b0040075 | 210 | .BR clock_nanosleep (2), |
d806bc05 | 211 | .BR restart_syscall (2), |
fea681da | 212 | .BR sched_setscheduler (2), |
804f03e6 | 213 | .BR timer_create (2), |
3e5c319e | 214 | .BR sleep (3), |
e97e048a | 215 | .BR timespec (3), |
0a90178c | 216 | .BR usleep (3), |
60bb61aa | 217 | .BR time (7) |