manual/LDP_man-pages/original/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 crufty discussion of HZ with a pointer to time(7).
  35 .TH NANOSLEEP 2 2009-01-19 "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 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 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 NOTES
 131 If the interval specified in
 132 .I req
 133 is not an exact multiple of the granularity underlying clock (see
 134 .BR time (7)),
 135 then the interval will be rounded up to the next multiple.
 136 Furthermore, after the sleep completes, there may still be a delay before
 137 the CPU becomes free to once again execute the calling thread.
 138
 139 The fact that
 140 .BR nanosleep ()
 141 sleeps for a relative interval can be problematic if the call
 142 is repeatedly restarted after being interrupted by signals,
 143 since the time between the interruptions and restarts of the call
 144 will lead to drift in the time when the sleep finally completes.
 145 This problem can be avoided by using
 146 .BR clock_nanosleep (2)
 147 with an absolute time value.
 148
 149 POSIX.1 specifies that
 150 .BR nanosleep ()
 151 should measure time against the
 152 .B CLOCK_REALTIME
 153 clock.
 154 However, Linux measures the time using the
 155 .B CLOCK_MONOTONIC
 156 clock.
 157 .\" See also http://thread.gmane.org/gmane.linux.kernel/696854/
 158 .\" Subject: nanosleep() uses CLOCK_MONOTONIC, should be CLOCK_REALTIME?
 159 .\" Date: 2008-06-22 07:35:41 GMT
 160 This probably does not matter, since the POSIX.1 specification for
 161 .BR clock_settime ()
 162 says that discontinuous changes in
 163 .B CLOCK_REALTIME
 164 should not affect
 165 .BR nanosleep ():
 166 .RS
 167 .PP
 168 Setting the value of the
 169 .B CLOCK_REALTIME
 170 clock via
 171 .BR clock_settime ()
 172 shall
 173 have no effect on threads that are blocked waiting for a relative time
 174 service based upon this clock, including the
 175 .BR nanosleep ()
 176 function; ...
 177 Consequently, these time services shall expire when the requested relative
 178 interval elapses, independently of the new or old value of the clock.
 179 .RE
 180 .SS "Old behavior"
 181 In order to support applications requiring much more precise pauses
 182 (e.g., in order to control some time-critical hardware),
 183 .BR nanosleep ()
 184 would handle pauses of up to 2\ ms by busy waiting with microsecond
 185 precision when called from a thread scheduled under a real-time policy
 186 like
 187 .B SCHED_FIFO
 188 or
 189 .BR SCHED_RR .
 190 This special extension was removed in kernel 2.5.39,
 191 hence is still present in
 192 current 2.4 kernels, but not in 2.6 kernels.
 193 .SH BUGS
 194 In Linux 2.4, if
 195 .BR nanosleep ()
 196 is stopped by a signal (e.g.,
 197 .BR SIGTSTP ),
 198 then the call fails with the error
 199 .B EINTR
 200 after the thread is resumed by a
 201 .B SIGCONT
 202 signal.
 203 If the system call is subsequently restarted,
 204 then the time that the thread spent in the stopped state is
 205 \fInot\fP counted against the sleep interval.
 206 .SH "SEE ALSO"
 207 .BR clock_nanosleep (2),
 208 .BR sched_setscheduler (2),
 209 .BR sleep (3),
 210 .BR timer_create (2),
 211 .BR usleep (3),
 212 .BR time (7)