]>
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 | .\" |
1dd72f9c | 5 | .\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
fea681da MK |
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. | |
10 | .\" | |
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. | |
15 | .\" | |
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. | |
20 | .\" | |
21 | .\" You should have received a copy of the GNU General Public | |
c715f741 MK |
22 | .\" License along with this manual; if not, see |
23 | .\" <http://www.gnu.org/licenses/>. | |
6a8d8745 | 24 | .\" %%%LICENSE_END |
fea681da MK |
25 | .\" |
26 | .\" 1996-04-10 Markus Kuhn <mskuhn@cip.informatik.uni-erlangen.de> | |
27 | .\" First version written | |
28 | .\" Modified, 2004-10-24, aeb | |
b0040075 MK |
29 | .\" 2008-06-24, mtk |
30 | .\" Minor rewrites of some parts. | |
31 | .\" NOTES: describe case where clock_nanosleep() can be preferable. | |
32 | .\" NOTES: describe CLOCK_REALTIME versus CLOCK_NANOSLEEP | |
8964c1a2 | 33 | .\" Replace crufty discussion of HZ with a pointer to time(7). |
31a1b45e | 34 | .TH NANOSLEEP 2 2017-03-13 "Linux" "Linux Programmer's Manual" |
fea681da | 35 | .SH NAME |
b0040075 | 36 | nanosleep \- high-resolution sleep |
fea681da MK |
37 | .SH SYNOPSIS |
38 | .B #include <time.h> | |
68e4db0a | 39 | .PP |
cc4615cc | 40 | .BI "int nanosleep(const struct timespec *" req ", struct timespec *" rem ); |
68e4db0a | 41 | .PP |
cc4615cc MK |
42 | .in -4n |
43 | Feature Test Macro Requirements for glibc (see | |
44 | .BR feature_test_macros (7)): | |
45 | .in | |
68e4db0a | 46 | .PP |
cc4615cc MK |
47 | .BR nanosleep (): |
48 | _POSIX_C_SOURCE\ >=\ 199309L | |
fea681da | 49 | .SH DESCRIPTION |
e511ffb6 | 50 | .BR nanosleep () |
b0040075 MK |
51 | suspends the execution of the calling thread |
52 | until either at least the time specified in | |
53 | .IR *req | |
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. | |
efeece04 | 57 | .PP |
b0040075 MK |
58 | If the call is interrupted by a signal handler, |
59 | .BR nanosleep () | |
c6fa0841 MK |
60 | returns \-1, sets |
61 | .I errno | |
62 | to | |
fea681da | 63 | .BR EINTR , |
b0040075 | 64 | and writes the remaining time into the structure pointed to by |
0daa9e92 | 65 | .I rem |
c13182ef | 66 | unless |
fea681da | 67 | .I rem |
8478ee02 | 68 | is NULL. |
fea681da MK |
69 | The value of |
70 | .I *rem | |
c13182ef | 71 | can then be used to call |
e511ffb6 | 72 | .BR nanosleep () |
b0040075 | 73 | again and complete the specified pause (but see NOTES). |
efeece04 | 74 | .PP |
fea681da MK |
75 | The structure |
76 | .I timespec | |
c13182ef | 77 | is used to specify intervals of time with nanosecond precision. |
b0040075 | 78 | It is defined as follows: |
51f5698d | 79 | .PP |
3ad4ddcd | 80 | .in +4n |
b8302363 | 81 | .EX |
0483625f MK |
82 | struct timespec { |
83 | time_t tv_sec; /* seconds */ | |
84 | long tv_nsec; /* nanoseconds */ | |
fea681da | 85 | }; |
b8302363 | 86 | .EE |
3ad4ddcd | 87 | .in |
fea681da MK |
88 | .PP |
89 | The value of the nanoseconds field must be in the range 0 to 999999999. | |
efeece04 | 90 | .PP |
fea681da | 91 | Compared to |
c5ae6d5a | 92 | .BR sleep (3) |
fea681da MK |
93 | and |
94 | .BR usleep (3), | |
e511ffb6 | 95 | .BR nanosleep () |
1b4cf8f4 | 96 | has the following advantages: |
b0040075 MK |
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. | |
47297adb | 102 | .SH RETURN VALUE |
13218d42 | 103 | On successfully sleeping for the requested interval, |
e511ffb6 | 104 | .BR nanosleep () |
13218d42 MK |
105 | returns 0. |
106 | If the call is interrupted by a signal handler or encounters an error, | |
c13182ef | 107 | then it returns \-1, with |
fea681da | 108 | .I errno |
13218d42 MK |
109 | set to indicate the error. |
110 | .SH ERRORS | |
43487dbb | 111 | .TP |
fea681da MK |
112 | .B EFAULT |
113 | Problem with copying information from user space. | |
114 | .TP | |
115 | .B EINTR | |
488007e8 | 116 | The pause has been interrupted by a signal that was |
ea84b0fd | 117 | delivered to the thread (see |
bb14af39 | 118 | .BR signal (7)). |
c13182ef | 119 | The remaining sleep time has been written |
c6fa0841 MK |
120 | into |
121 | .I *rem | |
122 | so that the thread can easily call | |
e511ffb6 | 123 | .BR nanosleep () |
fea681da MK |
124 | again and continue with the pause. |
125 | .TP | |
126 | .B EINVAL | |
127 | The value in the | |
128 | .I tv_nsec | |
129 | field was not in the range 0 to 999999999 or | |
130 | .I tv_sec | |
131 | was negative. | |
47297adb | 132 | .SH CONFORMING TO |
67651ee6 | 133 | POSIX.1-2001, POSIX.1-2008. |
b0040075 MK |
134 | .SH NOTES |
135 | If the interval specified in | |
136 | .I req | |
137 | is not an exact multiple of the granularity underlying clock (see | |
138 | .BR time (7)), | |
139 | then the interval will be rounded up to the next multiple. | |
140 | Furthermore, after the sleep completes, there may still be a delay before | |
141 | the CPU becomes free to once again execute the calling thread. | |
efeece04 | 142 | .PP |
b0040075 MK |
143 | The fact that |
144 | .BR nanosleep () | |
145 | sleeps for a relative interval can be problematic if the call | |
146 | is repeatedly restarted after being interrupted by signals, | |
147 | since the time between the interruptions and restarts of the call | |
148 | will lead to drift in the time when the sleep finally completes. | |
149 | This problem can be avoided by using | |
150 | .BR clock_nanosleep (2) | |
151 | with an absolute time value. | |
efeece04 | 152 | .PP |
b0040075 MK |
153 | POSIX.1 specifies that |
154 | .BR nanosleep () | |
155 | should measure time against the | |
156 | .B CLOCK_REALTIME | |
157 | clock. | |
158 | However, Linux measures the time using the | |
159 | .B CLOCK_MONOTONIC | |
160 | clock. | |
161 | .\" See also http://thread.gmane.org/gmane.linux.kernel/696854/ | |
162 | .\" Subject: nanosleep() uses CLOCK_MONOTONIC, should be CLOCK_REALTIME? | |
163 | .\" Date: 2008-06-22 07:35:41 GMT | |
164 | This probably does not matter, since the POSIX.1 specification for | |
0b80cf56 | 165 | .BR clock_settime (2) |
b0040075 MK |
166 | says that discontinuous changes in |
167 | .B CLOCK_REALTIME | |
168 | should not affect | |
169 | .BR nanosleep (): | |
170 | .RS | |
171 | .PP | |
172 | Setting the value of the | |
173 | .B CLOCK_REALTIME | |
174 | clock via | |
0b80cf56 | 175 | .BR clock_settime (2) |
b0040075 MK |
176 | shall |
177 | have no effect on threads that are blocked waiting for a relative time | |
178 | service based upon this clock, including the | |
179 | .BR nanosleep () | |
180 | function; ... | |
181 | Consequently, these time services shall expire when the requested relative | |
182 | interval elapses, independently of the new or old value of the clock. | |
183 | .RE | |
73d8cece | 184 | .SS Old behavior |
25768803 MK |
185 | In order to support applications requiring much more precise pauses |
186 | (e.g., in order to control some time-critical hardware), | |
187 | .BR nanosleep () | |
bdcb7056 | 188 | would handle pauses of up to 2 milliseconds by busy waiting with microsecond |
25768803 MK |
189 | precision when called from a thread scheduled under a real-time policy |
190 | like | |
191 | .B SCHED_FIFO | |
192 | or | |
193 | .BR SCHED_RR . | |
194 | This special extension was removed in kernel 2.5.39, | |
760b892c | 195 | and is thus not available in Linux 2.6.0 and later kernels. |
762c2446 | 196 | .SH BUGS |
1186d4c3 MK |
197 | If a program that catches signals and uses |
198 | .BR nanosleep () | |
199 | receives signals at a very high rate, | |
200 | then scheduling delays and rounding errors in the kernel's | |
201 | calculation of the sleep interval and the returned | |
202 | .IR remain | |
203 | value mean that the | |
204 | .IR remain | |
205 | value may steadily | |
206 | .IR increase | |
207 | on successive restarts of the | |
208 | .BR nanosleep () | |
209 | call. | |
210 | To avoid such problems, use | |
211 | .BR clock_nanosleep (2) | |
212 | with the | |
213 | .BR TIMER_ABSTIME | |
214 | flag to sleep to an absolute deadline. | |
efeece04 | 215 | .PP |
25768803 MK |
216 | In Linux 2.4, if |
217 | .BR nanosleep () | |
218 | is stopped by a signal (e.g., | |
219 | .BR SIGTSTP ), | |
220 | then the call fails with the error | |
221 | .B EINTR | |
222 | after the thread is resumed by a | |
223 | .B SIGCONT | |
224 | signal. | |
225 | If the system call is subsequently restarted, | |
226 | then the time that the thread spent in the stopped state is | |
c6fa0841 MK |
227 | .I not |
228 | counted against the sleep interval. | |
91bf33ff | 229 | This problem is fixed in Linux 2.6.0 and later kernels. |
47297adb | 230 | .SH SEE ALSO |
b0040075 | 231 | .BR clock_nanosleep (2), |
d806bc05 | 232 | .BR restart_syscall (2), |
fea681da | 233 | .BR sched_setscheduler (2), |
804f03e6 | 234 | .BR timer_create (2), |
3e5c319e | 235 | .BR sleep (3), |
0a90178c | 236 | .BR usleep (3), |
60bb61aa | 237 | .BR time (7) |