]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Hey Emacs! This file is -*- nroff -*- source. |
2 | .\" | |
3 | .\" Copyright (C) Markus Kuhn, 1996 | |
4 | .\" | |
5 | .\" This is free documentation; you can redistribute it and/or | |
6 | .\" modify it under the terms of the GNU General Public License as | |
7 | .\" published by the Free Software Foundation; either version 2 of | |
8 | .\" the License, or (at your option) any later version. | |
9 | .\" | |
10 | .\" The GNU General Public License's references to "object code" | |
11 | .\" and "executables" are to be interpreted as the output of any | |
12 | .\" document formatting or typesetting system, including | |
13 | .\" intermediate and printed output. | |
14 | .\" | |
15 | .\" This manual is distributed in the hope that it will be useful, | |
16 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
17 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
18 | .\" GNU General Public License for more details. | |
19 | .\" | |
20 | .\" You should have received a copy of the GNU General Public | |
21 | .\" License along with this manual; if not, write to the Free | |
22 | .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, | |
23 | .\" USA. | |
24 | .\" | |
25 | .\" 1996-04-10 Markus Kuhn <mskuhn@cip.informatik.uni-erlangen.de> | |
26 | .\" First version written | |
27 | .\" Modified, 2004-10-24, aeb | |
cc4615cc | 28 | .TH NANOSLEEP 2 2007-07-26 "Linux" "Linux Programmer's Manual" |
fea681da MK |
29 | .SH NAME |
30 | nanosleep \- pause execution for a specified time | |
31 | .SH SYNOPSIS | |
32 | .B #include <time.h> | |
33 | .sp | |
cc4615cc MK |
34 | .BI "int nanosleep(const struct timespec *" req ", struct timespec *" rem ); |
35 | .sp | |
36 | .in -4n | |
37 | Feature Test Macro Requirements for glibc (see | |
38 | .BR feature_test_macros (7)): | |
39 | .in | |
40 | .sp | |
41 | .BR nanosleep (): | |
42 | _POSIX_C_SOURCE\ >=\ 199309L | |
fea681da | 43 | .SH DESCRIPTION |
e511ffb6 | 44 | .BR nanosleep () |
fea681da MK |
45 | delays the execution of the program for at least the time specified in |
46 | .IR *req . | |
47 | The function can return earlier if a signal has been delivered to the | |
c13182ef | 48 | process. |
a8d55537 | 49 | In this case, it returns \-1, sets \fIerrno\fP to |
fea681da MK |
50 | .BR EINTR , |
51 | and writes the | |
52 | 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 () |
fea681da MK |
61 | again and complete the specified pause. |
62 | ||
63 | The structure | |
64 | .I timespec | |
c13182ef MK |
65 | is used to specify intervals of time with nanosecond precision. |
66 | It is | |
fea681da MK |
67 | specified in |
68 | .I <time.h> | |
69 | and has the form | |
70 | .sp | |
71 | .RS | |
72 | .nf | |
0483625f MK |
73 | struct timespec { |
74 | time_t tv_sec; /* seconds */ | |
75 | long tv_nsec; /* nanoseconds */ | |
fea681da | 76 | }; |
fea681da MK |
77 | .fi |
78 | .RE | |
79 | .PP | |
80 | The value of the nanoseconds field must be in the range 0 to 999999999. | |
81 | ||
82 | Compared to | |
83 | .BR sleep (3) | |
84 | and | |
85 | .BR usleep (3), | |
e511ffb6 | 86 | .BR nanosleep () |
fea681da MK |
87 | has the advantage of not affecting any signals, it is standardized by |
88 | POSIX, it provides higher timing resolution, and it allows to continue | |
89 | a sleep that has been interrupted by a signal more easily. | |
13218d42 MK |
90 | .SH "RETURN VALUE" |
91 | On successfully sleeping for the requested interval, | |
e511ffb6 | 92 | .BR nanosleep () |
13218d42 MK |
93 | returns 0. |
94 | If the call is interrupted by a signal handler or encounters an error, | |
c13182ef | 95 | then it returns \-1, with |
fea681da | 96 | .I errno |
13218d42 MK |
97 | set to indicate the error. |
98 | .SH ERRORS | |
43487dbb | 99 | .TP |
fea681da MK |
100 | .B EFAULT |
101 | Problem with copying information from user space. | |
102 | .TP | |
103 | .B EINTR | |
104 | The pause has been interrupted by a non-blocked signal that was | |
c13182ef MK |
105 | delivered to the process. |
106 | The remaining sleep time has been written | |
a8d55537 | 107 | into *\fIrem\fP so that the process can easily call |
e511ffb6 | 108 | .BR nanosleep () |
fea681da MK |
109 | again and continue with the pause. |
110 | .TP | |
111 | .B EINVAL | |
112 | The value in the | |
113 | .I tv_nsec | |
114 | field was not in the range 0 to 999999999 or | |
115 | .I tv_sec | |
116 | was negative. | |
a1d5f77c MK |
117 | .SH "CONFORMING TO" |
118 | POSIX.1-2001. | |
fea681da MK |
119 | .SH BUGS |
120 | The current implementation of | |
e511ffb6 | 121 | .BR nanosleep () |
fea681da | 122 | is based on the normal kernel timer mechanism, which has a resolution |
a8d55537 | 123 | of 1/\fIHZ\fP\ s (see |
eafd5ce1 | 124 | .BR time (7)). |
fea681da | 125 | Therefore, |
e511ffb6 | 126 | .BR nanosleep () |
fea681da MK |
127 | pauses always for at least the specified time, however it can take up |
128 | to 10 ms longer than specified until the process becomes runnable | |
c13182ef MK |
129 | again. |
130 | For the same reason, the value returned in case of a delivered | |
a8d55537 MK |
131 | signal in *\fIrem\fP is usually rounded to the next larger multiple of |
132 | 1/\fIHZ\fP\ s. | |
d9bfdb9c | 133 | .SS "Old behavior" |
fea681da MK |
134 | In order to support applications requiring much more precise pauses |
135 | (e.g., in order to control some time-critical hardware), | |
e511ffb6 | 136 | .BR nanosleep () |
fea681da MK |
137 | would handle pauses of up to 2\ ms by busy waiting with microsecond |
138 | precision when called from a process scheduled under a real-time policy | |
139 | like | |
7b2b5ea4 | 140 | .B SCHED_FIFO |
fea681da | 141 | or |
7b2b5ea4 | 142 | .BR SCHED_RR . |
c13182ef | 143 | This special extension was removed in kernel 2.5.39, |
2b5cefe8 | 144 | hence is still present in |
fea681da | 145 | current 2.4 kernels, but not in 2.6 kernels. |
2b5cefe8 MK |
146 | .PP |
147 | In Linux 2.4, if | |
148 | .BR nanosleep () | |
8bd58774 MK |
149 | is stopped by a signal (e.g., |
150 | .BR SIGTSTP ), | |
2b5cefe8 | 151 | then the call fails with the error |
0daa9e92 | 152 | .B EINTR |
8bd58774 MK |
153 | after the process is resumed by a |
154 | .B SIGCONT | |
155 | signal. | |
c13182ef MK |
156 | If the system call is subsequently restarted, |
157 | then the time that the process spent in the stopped state is | |
2b5cefe8 | 158 | \fInot\fP counted against the sleep interval. |
fea681da MK |
159 | .SH "SEE ALSO" |
160 | .BR sched_setscheduler (2), | |
fea681da | 161 | .BR sleep (3), |
e82e185f | 162 | .BR timer_create (3), |
0a90178c | 163 | .BR usleep (3), |
60bb61aa | 164 | .BR time (7) |