original/man2/clock_nanosleep.2

   1 .\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk
   2 .\" <mtk.manpages@gmail.com>
   3 .\"
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\"
  24 .TH CLOCK_NANOSLEEP 2 2010-09-10 "Linux" "Linux Programmer's Manual"
  25 .SH NAME
  26 clock_nanosleep \- high-resolution sleep with specifiable clock
  27 .SH SYNOPSIS
  28 .B #include <time.h>
  29 .nf
  30 .sp
  31 .BI "int clock_nanosleep(clockid_t " clock_id ", int " flags ,
  32 .BI "                    const struct timespec *" request ,
  33 .BI "                    struct timespec *" remain );
  34 .fi
  35 .sp
  36 Link with \fI\-lrt\fP.
  37 .sp
  38 .ad l
  39 .in -4n
  40 Feature Test Macro Requirements for glibc (see
  41 .BR feature_test_macros (7)):
  42 .in
  43 .sp
  44 .BR clock_nanosleep ():
  45 .RS 4
  46 _XOPEN_SOURCE\ >=\ 600 || _POSIX_C_SOURCE\ >=\ 200112L
  47 .RE
  48 .ad
  49 .SH DESCRIPTION
  50 Like
  51 .BR nanosleep (2),
  52 .BR clock_nanosleep ()
  53 allows the caller to sleep for an interval specified
  54 with nanosecond precision.
  55 It differs in allowing the caller to select the clock against
  56 which the sleep interval is to be measured,
  57 and in allowing the sleep interval to be specified as
  58 either an absolute or a relative value.
  59
  60 The time values passed to and returned by this call are specified using
  61 .I timespec
  62 structures, defined as follows:
  63 .sp
  64 .in +4n
  65 .nf
  66 struct timespec {
  67     time_t tv_sec;        /* seconds */
  68     long   tv_nsec;       /* nanoseconds [0 .. 999999999] */
  69 };
  70 .fi
  71 .in
  72
  73 The
  74 .I clock_id
  75 argument specifies the clock against which the sleep interval
  76 is to be measured.
  77 This argument can have one of the following values:
  78 .TP 17
  79 .BR CLOCK_REALTIME
  80 A settable system-wide real-time clock.
  81 .TP
  82 .BR CLOCK_MONOTONIC
  83 A nonsettable, monotonically increasing clock that measures time
  84 since some unspecified point in the past that does not change after
  85 system startup.
  86 .\" On Linux this clock measures time since boot.
  87 .TP
  88 .BR CLOCK_PROCESS_CPUTIME_ID
  89 A settable per-process clock that measures CPU time consumed
  90 by all threads in the process.
  91 .\" There is some trickery between glibc and the kernel
  92 .\" to deal with the CLOCK_PROCESS_CPUTIME_ID case.
  93 .PP
  94 See
  95 .BR clock_getres (2)
  96 for further details on these clocks.
  97
  98 If
  99 .I flags
 100 is 0, then the value specified in
 101 .I request
 102 is interpreted as an interval relative to the current
 103 value of the clock specified by
 104 .IR clock_id .
 105
 106 If
 107 .I flags
 108 is
 109 .BR TIMER_ABSTIME ,
 110 then
 111 .I request
 112 is interpreted as an absolute time as measured by the clock,
 113 .IR clock_id .
 114 If
 115 .I request
 116 is less than or equal to the current value of the clock,
 117 then
 118 .BR clock_nanosleep ()
 119 returns immediately without suspending the calling thread.
 120
 121 .BR clock_nanosleep ()
 122 suspends the execution of the calling thread
 123 until either at least the time specified by
 124 .IR request
 125 has elapsed,
 126 or a signal is delivered that causes a signal handler to be called or
 127 that terminates the process.
 128
 129 If the call is interrupted by a signal handler,
 130 .BR clock_nanosleep ()
 131 fails with the error
 132 .BR EINTR .
 133 In addition, if
 134 .I remain
 135 is not NULL, and
 136 .I flags
 137 was not
 138 .BR TIMER_ABSTIME ,
 139 it returns the remaining unslept time in
 140 .IR remain .
 141 This value can then be used to call
 142 .BR clock_nanosleep ()
 143 again and complete a (relative) sleep.
 144 .SH "RETURN VALUE"
 145 On successfully sleeping for the requested interval,
 146 .BR clock_nanosleep ()
 147 returns 0.
 148 If the call is interrupted by a signal handler or encounters an error,
 149 then it returns one of the positive error number listed in ERRORS.
 150 .SH ERRORS
 151 .TP
 152 .B EFAULT
 153 .I request
 154 or
 155 .I remain
 156 specified an invalid address.
 157 .TP
 158 .B EINTR
 159 The sleep was interrupted by a signal handler.
 160 .TP
 161 .B EINVAL
 162 The value in the
 163 .I tv_nsec
 164 field was not in the range 0 to 999999999 or
 165 .I tv_sec
 166 was negative.
 167 .TP
 168 .B EINVAL
 169 .I clock_id
 170 was invalid.
 171 .RB ( CLOCK_THREAD_CPUTIME_ID
 172 is not a permitted value for
 173 .IR clock_id .)
 174 .SH VERSIONS
 175 The
 176 .BR clock_nanosleep ()
 177 system call first appeared in Linux 2.6.
 178 Support is available in glibc since version 2.1.
 179 .SH "CONFORMING TO"
 180 POSIX.1-2001.
 181 .SH NOTES
 182 If the interval specified in
 183 .I request
 184 is not an exact multiple of the granularity underlying clock (see
 185 .BR time (7)),
 186 then the interval will be rounded up to the next multiple.
 187 Furthermore, after the sleep completes, there may still be a delay before
 188 the CPU becomes free to once again execute the calling thread.
 189
 190 Using an absolute timer is useful for preventing
 191 timer drift problems of the type described in
 192 .BR nanosleep (2).
 193 (Such problems are exacerbated in programs that try to restart
 194 a relative sleep that is repeatedly interrupted by signals.)
 195 To perform a relative sleep that avoids these problems, call
 196 .BR clock_gettime (2)
 197 for the desired clock,
 198 add the desired interval to the returned time value,
 199 and then call
 200 .BR clock_nanosleep ()
 201 with the
 202 .B TIMER_ABSTIME
 203 flag.
 204
 205 .BR clock_nanosleep ()
 206 is never restarted after being interrupted by a signal handler,
 207 regardless of the use of the
 208 .BR sigaction (2)
 209 .B SA_SIGACTION
 210 flag.
 211
 212 The
 213 .I remain
 214 argument is unused, and unnecessary, when
 215 .I flags
 216 is
 217 .BR TIMER_ABSTIME .
 218 (An absolute sleep can be restarted using the same
 219 .I request
 220 argument.)
 221
 222 POSIX.1 specifies that
 223 .BR clock_nanosleep ()
 224 has no effect on signals dispositions or the signal mask.
 225
 226 POSIX.1 specifies that after changing the value of the
 227 .B CLOCK_REALTIME
 228 clock via
 229 .BR clock_settime (2),
 230 the new clock value shall be used to determine the time
 231 at which a thread blocked on an absolute
 232 .BR clock_nanosleep ()
 233 will wake up;
 234 if the new clock value falls past the end of the sleep interval, then the
 235 .BR clock_nanosleep ()
 236 call will return immediately.
 237
 238 POSIX.1 specifies that
 239 changing the value of the
 240 .B CLOCK_REALTIME
 241 clock via
 242 .BR clock_settime (2)
 243 shall have no effect on a thread that is blocked on a relative
 244 .BR clock_nanosleep ().
 245 .SH "SEE ALSO"
 246 .BR nanosleep (2),
 247 .BR timer_create (2),
 248 .BR clock_getres (2),
 249 .BR sleep (3),
 250 .BR usleep (3),
 251 .BR time (7)