man2/nanosleep.2

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