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