Debian Codegraph @

upstream/debian-unstable/man2/nanosleep.2

raw
1 .\" Copyright 1996, Markus Kuhn <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: GPL-2.0-or-later
5 .\"
6 .TH nanosleep 2 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 nanosleep \- high-resolution sleep
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .B #include <time.h>
15 .P
16 .BI "int nanosleep(const struct timespec *" duration ,
17 .BI " struct timespec *_Nullable " rem );
18 .fi
19 .P
20 .RS -4
21 Feature Test Macro Requirements for glibc (see
22 .BR feature_test_macros (7)):
23 .RE
24 .P
25 .BR nanosleep ():
26 .nf
27 _POSIX_C_SOURCE >= 199309L
28 .fi
29 .SH DESCRIPTION
30 .BR nanosleep ()
31 suspends the execution of the calling thread
32 until either at least the time specified in
33 .I *duration
34 has elapsed, or the delivery of a signal
35 that triggers the invocation of a handler in the calling thread or
36 that terminates the process.
37 .P
38 If the call is interrupted by a signal handler,
39 .BR nanosleep ()
40 returns \-1, sets
41 .I errno
42 to
43 .BR EINTR ,
44 and writes the remaining time into the structure pointed to by
45 .I rem
46 unless
47 .I rem
48 is NULL.
49 The value of
50 .I *rem
51 can then be used to call
52 .BR nanosleep ()
53 again and complete the specified pause (but see NOTES).
54 .P
55 The
56 .BR timespec (3)
57 structure
58 is used to specify intervals of time with nanosecond precision.
59 .P
60 The value of the nanoseconds field must be in the range [0, 999999999].
61 .P
62 Compared to
63 .BR sleep (3)
64 and
65 .BR usleep (3),
66 .BR nanosleep ()
67 has the following advantages:
68 it provides a higher resolution for specifying the sleep interval;
69 POSIX.1 explicitly specifies that it
70 does not interact with signals;
71 and it makes the task of resuming a sleep that has been
72 interrupted by a signal handler easier.
73 .SH RETURN VALUE
74 On successfully sleeping for the requested duration,
75 .BR nanosleep ()
76 returns 0.
77 If the call is interrupted by a signal handler or encounters an error,
78 then it returns \-1, with
79 .I errno
80 set to indicate the error.
81 .SH ERRORS
82 .TP
83 .B EFAULT
84 Problem with copying information from user space.
85 .TP
86 .B EINTR
87 The pause has been interrupted by a signal that was
88 delivered to the thread (see
89 .BR signal (7)).
90 The remaining sleep time has been written
91 into
92 .I *rem
93 so that the thread can easily call
94 .BR nanosleep ()
95 again and continue with the pause.
96 .TP
97 .B EINVAL
98 The value in the
99 .I tv_nsec
100 field was not in the range [0, 999999999] or
101 .I tv_sec
102 was negative.
103 .SH VERSIONS
104 POSIX.1 specifies that
105 .BR nanosleep ()
106 should measure time against the
107 .B CLOCK_REALTIME
108 clock.
109 However, Linux measures the time using the
110 .B CLOCK_MONOTONIC
111 clock.
112 .\" See also http://thread.gmane.org/gmane.linux.kernel/696854/
113 .\" Subject: nanosleep() uses CLOCK_MONOTONIC, should be CLOCK_REALTIME?
114 .\" Date: 2008-06-22 07:35:41 GMT
115 This probably does not matter, since the POSIX.1 specification for
116 .BR clock_settime (2)
117 says that discontinuous changes in
118 .B CLOCK_REALTIME
119 should not affect
120 .BR nanosleep ():
121 .RS
122 .P
123 Setting the value of the
124 .B CLOCK_REALTIME
125 clock via
126 .BR clock_settime (2)
127 shall
128 have no effect on threads that are blocked waiting for a relative time
129 service based upon this clock, including the
130 .BR nanosleep ()
131 function.
132 Consequently,
133 these time services shall expire when the requested duration elapses,
134 independently of the new or old value of the clock.
135 .RE
136 .SH STANDARDS
137 POSIX.1-2024.
138 .SH HISTORY
139 POSIX.1-2001.
140 .P
141 In order to support applications requiring much more precise pauses
142 (e.g., in order to control some time-critical hardware),
143 .BR nanosleep ()
144 would handle pauses of up to 2 milliseconds by busy waiting with microsecond
145 precision when called from a thread scheduled under a real-time policy
146 like
147 .B SCHED_FIFO
148 or
149 .BR SCHED_RR .
150 This special extension was removed in Linux 2.5.39,
151 and is thus not available in Linux 2.6.0 and later kernels.
152 .SH NOTES
153 If the
154 .I duration
155 is not an exact multiple of the granularity underlying clock (see
156 .BR time (7)),
157 then the interval will be rounded up to the next multiple.
158 Furthermore, after the sleep completes, there may still be a delay before
159 the CPU becomes free to once again execute the calling thread.
160 .P
161 The fact that
162 .BR nanosleep ()
163 sleeps for a relative interval can be problematic if the call
164 is repeatedly restarted after being interrupted by signals,
165 since the time between the interruptions and restarts of the call
166 will lead to drift in the time when the sleep finally completes.
167 This problem can be avoided by using
168 .BR clock_nanosleep (2)
169 with an absolute time value.
170 .SH BUGS
171 If a program that catches signals and uses
172 .BR nanosleep ()
173 receives signals at a very high rate,
174 then scheduling delays and rounding errors in the kernel's
175 calculation of the sleep interval and the returned
176 .I remain
177 value mean that the
178 .I remain
179 value may steadily
180 .I increase
181 on successive restarts of the
182 .BR nanosleep ()
183 call.
184 To avoid such problems, use
185 .BR clock_nanosleep (2)
186 with the
187 .B TIMER_ABSTIME
188 flag to sleep to an absolute deadline.
189 .P
190 In Linux 2.4, if
191 .BR nanosleep ()
192 is stopped by a signal (e.g.,
193 .BR SIGTSTP ),
194 then the call fails with the error
195 .B EINTR
196 after the thread is resumed by a
197 .B SIGCONT
198 signal.
199 If the system call is subsequently restarted,
200 then the time that the thread spent in the stopped state is
201 .I not
202 counted against the sleep interval.
203 This problem is fixed in Linux 2.6.0 and later kernels.
204 .SH SEE ALSO
205 .BR clock_nanosleep (2),
206 .BR restart_syscall (2),
207 .BR sched_setscheduler (2),
208 .BR timer_create (2),
209 .BR sleep (3),
210 .BR timespec (3),
211 .BR usleep (3),
212 .BR time (7)