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