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 .\" This is free documentation; you can redistribute it and/or
   6 .\" modify it under the terms of the GNU General Public License as
   7 .\" published by the Free Software Foundation; either version 2 of
   8 .\" the License, or (at your option) any later version.
   9 .\"
  10 .\" The GNU General Public License's references to "object code"
  11 .\" and "executables" are to be interpreted as the output of any
  12 .\" document formatting or typesetting system, including
  13 .\" intermediate and printed output.
  14 .\"
  15 .\" This manual is distributed in the hope that it will be useful,
  16 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 .\" GNU General Public License for more details.
  19 .\"
  20 .\" You should have received a copy of the GNU General Public
  21 .\" License along with this manual; if not, see
  22 .\" <http://www.gnu.org/licenses/>.
  23 .\"
  24 .\" 1996-04-10  Markus Kuhn <mskuhn@cip.informatik.uni-erlangen.de>
  25 .\"             First version written
  26 .\" Modified, 2004-10-24, aeb
  27 .\" 2008-06-24, mtk
  28 .\"     Minor rewrites of some parts.
  29 .\"     NOTES: describe case where clock_nanosleep() can be preferable.
  30 .\"     NOTES: describe CLOCK_REALTIME versus CLOCK_NANOSLEEP
  31 .\"     Replace crufty discussion of HZ with a pointer to time(7).
  32 .TH NANOSLEEP 2 2009-01-19 "Linux" "Linux Programmer's Manual"
  33 .SH NAME
  34 nanosleep \- high-resolution sleep
  35 .SH SYNOPSIS
  36 .B #include <time.h>
  37 .sp
  38 .BI "int nanosleep(const struct timespec *" req ", struct timespec *" rem );
  39 .sp
  40 .in -4n
  41 Feature Test Macro Requirements for glibc (see
  42 .BR feature_test_macros (7)):
  43 .in
  44 .sp
  45 .BR nanosleep ():
  46 _POSIX_C_SOURCE\ >=\ 199309L
  47 .SH DESCRIPTION
  48 .BR nanosleep ()
  49 suspends the execution of the calling thread
  50 until either at least the time specified in
  51 .IR *req
  52 has elapsed, or the delivery of a signal
  53 that triggers the invocation of a handler in the calling thread or
  54 that terminates the process.
  55
  56 If the call is interrupted by a signal handler,
  57 .BR nanosleep ()
  58 returns \-1, sets \fIerrno\fP to
  59 .BR EINTR ,
  60 and writes the remaining time into the structure pointed to by
  61 .I rem
  62 unless
  63 .I rem
  64 is NULL.
  65 The value of
  66 .I *rem
  67 can then be used to call
  68 .BR nanosleep ()
  69 again and complete the specified pause (but see NOTES).
  70
  71 The structure
  72 .I timespec
  73 is used to specify intervals of time with nanosecond precision.
  74 It is defined as follows:
  75 .sp
  76 .in +4n
  77 .nf
  78 struct timespec {
  79     time_t tv_sec;        /* seconds */
  80     long   tv_nsec;       /* nanoseconds */
  81 };
  82 .fi
  83 .in
  84 .PP
  85 The value of the nanoseconds field must be in the range 0 to 999999999.
  86
  87 Compared to
  88 .BR sleep  (3)
  89 and
  90 .BR usleep (3),
  91 .BR nanosleep ()
  92 has the following advantages:
  93 it provides a higher resolution for specifying the sleep interval;
  94 POSIX.1 explicitly specifies that it
  95 does not interact with signals;
  96 and it makes the task of resuming a sleep that has been
  97 interrupted by a signal handler easier.
  98 .SH RETURN VALUE
  99 On successfully sleeping for the requested interval,
 100 .BR nanosleep ()
 101 returns 0.
 102 If the call is interrupted by a signal handler or encounters an error,
 103 then it returns \-1, with
 104 .I errno
 105 set to indicate the error.
 106 .SH ERRORS
 107 .TP
 108 .B EFAULT
 109 Problem with copying information from user space.
 110 .TP
 111 .B EINTR
 112 The pause has been interrupted by a signal that was
 113 delivered to the thread.
 114 The remaining sleep time has been written
 115 into \fI*rem\fP so that the thread can easily call
 116 .BR nanosleep ()
 117 again and continue with the pause.
 118 .TP
 119 .B EINVAL
 120 The value in the
 121 .I tv_nsec
 122 field was not in the range 0 to 999999999 or
 123 .I tv_sec
 124 was negative.
 125 .SH CONFORMING TO
 126 POSIX.1-2001.
 127 .SH NOTES
 128 If the interval specified in
 129 .I req
 130 is not an exact multiple of the granularity underlying clock (see
 131 .BR time (7)),
 132 then the interval will be rounded up to the next multiple.
 133 Furthermore, after the sleep completes, there may still be a delay before
 134 the CPU becomes free to once again execute the calling thread.
 135
 136 The fact that
 137 .BR nanosleep ()
 138 sleeps for a relative interval can be problematic if the call
 139 is repeatedly restarted after being interrupted by signals,
 140 since the time between the interruptions and restarts of the call
 141 will lead to drift in the time when the sleep finally completes.
 142 This problem can be avoided by using
 143 .BR clock_nanosleep (2)
 144 with an absolute time value.
 145
 146 POSIX.1 specifies that
 147 .BR nanosleep ()
 148 should measure time against the
 149 .B CLOCK_REALTIME
 150 clock.
 151 However, Linux measures the time using the
 152 .B CLOCK_MONOTONIC
 153 clock.
 154 .\" See also http://thread.gmane.org/gmane.linux.kernel/696854/
 155 .\" Subject: nanosleep() uses CLOCK_MONOTONIC, should be CLOCK_REALTIME?
 156 .\" Date: 2008-06-22 07:35:41 GMT
 157 This probably does not matter, since the POSIX.1 specification for
 158 .BR clock_settime (2)
 159 says that discontinuous changes in
 160 .B CLOCK_REALTIME
 161 should not affect
 162 .BR nanosleep ():
 163 .RS
 164 .PP
 165 Setting the value of the
 166 .B CLOCK_REALTIME
 167 clock via
 168 .BR clock_settime (2)
 169 shall
 170 have no effect on threads that are blocked waiting for a relative time
 171 service based upon this clock, including the
 172 .BR nanosleep ()
 173 function; ...
 174 Consequently, these time services shall expire when the requested relative
 175 interval elapses, independently of the new or old value of the clock.
 176 .RE
 177 .SS Old behavior
 178 In order to support applications requiring much more precise pauses
 179 (e.g., in order to control some time-critical hardware),
 180 .BR nanosleep ()
 181 would handle pauses of up to 2\ ms by busy waiting with microsecond
 182 precision when called from a thread scheduled under a real-time policy
 183 like
 184 .B SCHED_FIFO
 185 or
 186 .BR SCHED_RR .
 187 This special extension was removed in kernel 2.5.39,
 188 hence is still present in
 189 current 2.4 kernels, but not in 2.6 kernels.
 190 .SH BUGS
 191 In Linux 2.4, if
 192 .BR nanosleep ()
 193 is stopped by a signal (e.g.,
 194 .BR SIGTSTP ),
 195 then the call fails with the error
 196 .B EINTR
 197 after the thread is resumed by a
 198 .B SIGCONT
 199 signal.
 200 If the system call is subsequently restarted,
 201 then the time that the thread spent in the stopped state is
 202 \fInot\fP counted against the sleep interval.
 203 .SH SEE ALSO
 204 .BR clock_nanosleep (2),
 205 .BR sched_setscheduler (2),
 206 .BR timer_create (2),
 207 .BR sleep (3),
 208 .BR usleep (3),
 209 .BR time (7)