man2/nanosleep.2

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