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 2017-09-15 "Linux" "Linux Programmer's Manual"
  35 .SH NAME
  36 nanosleep \- high-resolution sleep
  37 .SH SYNOPSIS
  38 .B #include <time.h>
  39 .PP
  40 .BI "int nanosleep(const struct timespec *" req ", struct timespec *" rem );
  41 .PP
  42 .in -4n
  43 Feature Test Macro Requirements for glibc (see
  44 .BR feature_test_macros (7)):
  45 .in
  46 .PP
  47 .BR nanosleep ():
  48 _POSIX_C_SOURCE\ >=\ 199309L
  49 .SH DESCRIPTION
  50 .BR nanosleep ()
  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.
  57 .PP
  58 If the call is interrupted by a signal handler,
  59 .BR nanosleep ()
  60 returns \-1, sets
  61 .I errno
  62 to
  63 .BR EINTR ,
  64 and writes the remaining time into the structure pointed to by
  65 .I rem
  66 unless
  67 .I rem
  68 is NULL.
  69 The value of
  70 .I *rem
  71 can then be used to call
  72 .BR nanosleep ()
  73 again and complete the specified pause (but see NOTES).
  74 .PP
  75 The structure
  76 .I timespec
  77 is used to specify intervals of time with nanosecond precision.
  78 It is defined as follows:
  79 .PP
  80 .in +4n
  81 .EX
  82 struct timespec {
  83     time_t tv_sec;        /* seconds */
  84     long   tv_nsec;       /* nanoseconds */
  85 };
  86 .EE
  87 .in
  88 .PP
  89 The value of the nanoseconds field must be in the range 0 to 999999999.
  90 .PP
  91 Compared to
  92 .BR sleep (3)
  93 and
  94 .BR usleep (3),
  95 .BR nanosleep ()
  96 has the following advantages:
  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.
 102 .SH RETURN VALUE
 103 On successfully sleeping for the requested interval,
 104 .BR nanosleep ()
 105 returns 0.
 106 If the call is interrupted by a signal handler or encounters an error,
 107 then it returns \-1, with
 108 .I errno
 109 set to indicate the error.
 110 .SH ERRORS
 111 .TP
 112 .B EFAULT
 113 Problem with copying information from user space.
 114 .TP
 115 .B EINTR
 116 The pause has been interrupted by a signal that was
 117 delivered to the thread (see
 118 .BR signal (7)).
 119 The remaining sleep time has been written
 120 into
 121 .I *rem
 122 so that the thread can easily call
 123 .BR nanosleep ()
 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.
 132 .SH CONFORMING TO
 133 POSIX.1-2001, POSIX.1-2008.
 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.
 142 .PP
 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.
 152 .PP
 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
 165 .BR clock_settime (2)
 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
 175 .BR clock_settime (2)
 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
 184 .SS Old behavior
 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 ()
 188 would handle pauses of up to 2 milliseconds by busy waiting with microsecond
 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,
 195 and is thus not available in Linux 2.6.0 and later kernels.
 196 .SH BUGS
 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.
 215 .PP
 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
 227 .I not
 228 counted against the sleep interval.
 229 This problem is fixed in Linux 2.6.0 and later kernels.
 230 .SH SEE ALSO
 231 .BR clock_nanosleep (2),
 232 .BR restart_syscall (2),
 233 .BR sched_setscheduler (2),
 234 .BR timer_create (2),
 235 .BR sleep (3),
 236 .BR usleep (3),
 237 .BR time (7)