man2/clock_getres.2

   1 .\" Copyright (c) 2003 Nick Clifford (zaf@nrc.co.nz), Jan 25, 2003
   2 .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl), Aug 24, 2003
   3 .\" Copyright (c) 2020 Michael Kerrisk <mtk.manpages@gmail.com>
   4 .\"
   5 .\" %%%LICENSE_START(VERBATIM)
   6 .\" Permission is granted to make and distribute verbatim copies of this
   7 .\" manual provided the copyright notice and this permission notice are
   8 .\" preserved on all copies.
   9 .\"
  10 .\" Permission is granted to copy and distribute modified versions of this
  11 .\" manual under the conditions for verbatim copying, provided that the
  12 .\" entire resulting derived work is distributed under the terms of a
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" Since the Linux kernel and libraries are constantly changing, this
  16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  17 .\" responsibility for errors or omissions, or for damages resulting from
  18 .\" the use of the information contained herein.  The author(s) may not
  19 .\" have taken the same level of care in the production of this manual,
  20 .\" which is licensed free of charge, as they might when working
  21 .\" professionally.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\" %%%LICENSE_END
  26 .\"
  27 .\" 2003-08-23 Martin Schulze <joey@infodrom.org> improvements
  28 .\" 2003-08-24 aeb, large parts rewritten
  29 .\" 2004-08-06 Christoph Lameter <clameter@sgi.com>, SMP note
  30 .\"
  31 .TH CLOCK_GETRES 2 2021-03-22 "" "Linux Programmer's Manual"
  32 .SH NAME
  33 clock_getres, clock_gettime, clock_settime \- clock and time functions
  34 .SH SYNOPSIS
  35 .nf
  36 .B #include <time.h>
  37 .PP
  38 .BI "int clock_getres(clockid_t " clockid ", struct timespec *" res );
  39 .PP
  40 .BI "int clock_gettime(clockid_t " clockid ", struct timespec *" tp );
  41 .BI "int clock_settime(clockid_t " clockid ", const struct timespec *" tp );
  42 .fi
  43 .PP
  44 Link with \fI\-lrt\fP (only for glibc versions before 2.17).
  45 .PP
  46 .RS -4
  47 Feature Test Macro Requirements for glibc (see
  48 .BR feature_test_macros (7)):
  49 .RE
  50 .PP
  51 .BR clock_getres (),
  52 .BR clock_gettime (),
  53 .BR clock_settime ():
  54 .nf
  55     _POSIX_C_SOURCE >= 199309L
  56 .fi
  57 .SH DESCRIPTION
  58 The function
  59 .BR clock_getres ()
  60 finds the resolution (precision) of the specified clock
  61 .IR clockid ,
  62 and, if
  63 .I res
  64 is non-NULL, stores it in the \fIstruct timespec\fP pointed to by
  65 .IR res .
  66 The resolution of clocks depends on the implementation and cannot be
  67 configured by a particular process.
  68 If the time value pointed to by the argument
  69 .I tp
  70 of
  71 .BR clock_settime ()
  72 is not a multiple of
  73 .IR res ,
  74 then it is truncated to a multiple of
  75 .IR res .
  76 .PP
  77 The functions
  78 .BR clock_gettime ()
  79 and
  80 .BR clock_settime ()
  81 retrieve and set the time of the specified clock
  82 .IR clockid .
  83 .PP
  84 The
  85 .I res
  86 and
  87 .I tp
  88 arguments are
  89 .I timespec
  90 structures, as specified in
  91 .IR <time.h> :
  92 .PP
  93 .in +4n
  94 .EX
  95 struct timespec {
  96     time_t   tv_sec;        /* seconds */
  97     long     tv_nsec;       /* nanoseconds */
  98 };
  99 .EE
 100 .in
 101 .PP
 102 The
 103 .I clockid
 104 argument is the identifier of the particular clock on which to act.
 105 A clock may be system-wide and hence visible for all processes, or
 106 per-process if it measures time only within a single process.
 107 .PP
 108 All implementations support the system-wide real-time clock,
 109 which is identified by
 110 .BR CLOCK_REALTIME .
 111 Its time represents seconds and nanoseconds since the Epoch.
 112 When its time is changed, timers for a relative interval are
 113 unaffected, but timers for an absolute point in time are affected.
 114 .PP
 115 More clocks may be implemented.
 116 The interpretation of the
 117 corresponding time values and the effect on timers is unspecified.
 118 .PP
 119 Sufficiently recent versions of glibc and the Linux kernel
 120 support the following clocks:
 121 .TP
 122 .B CLOCK_REALTIME
 123 A settable system-wide clock that measures real (i.e., wall-clock) time.
 124 Setting this clock requires appropriate privileges.
 125 This clock is affected by discontinuous jumps in the system time
 126 (e.g., if the system administrator manually changes the clock),
 127 and by the incremental adjustments performed by
 128 .BR adjtime (3)
 129 and NTP.
 130 .TP
 131 .BR CLOCK_REALTIME_ALARM " (since Linux 3.0; Linux-specific)"
 132 Like
 133 .BR CLOCK_REALTIME ,
 134 but not settable.
 135 See
 136 .BR timer_create (2)
 137 for further details.
 138 .TP
 139 .BR CLOCK_REALTIME_COARSE " (since Linux 2.6.32; Linux-specific)"
 140 .\" Added in commit da15cfdae03351c689736f8d142618592e3cebc3
 141 A faster but less precise version of
 142 .BR CLOCK_REALTIME .
 143 This clock is not settable.
 144 Use when you need very fast, but not fine-grained timestamps.
 145 Requires per-architecture support,
 146 and probably also architecture support for this flag in the
 147 .BR vdso (7).
 148 .TP
 149 .BR CLOCK_TAI " (since Linux 3.10; Linux-specific)"
 150 .\" commit 1ff3c9677bff7e468e0c487d0ffefe4e901d33f4
 151 A nonsettable system-wide clock derived from wall-clock time
 152 but ignoring leap seconds.
 153 This clock does
 154 not experience discontinuities and backwards jumps caused by NTP
 155 inserting leap seconds as
 156 .BR CLOCK_REALTIME
 157 does.
 158 .IP
 159 The acronym TAI refers to International Atomic Time.
 160 .TP
 161 .B CLOCK_MONOTONIC
 162 A nonsettable system-wide clock that
 163 represents monotonic time since\(emas described
 164 by POSIX\(em"some unspecified point in the past".
 165 On Linux, that point corresponds to the number of seconds that the system
 166 has been running since it was booted.
 167 .IP
 168 The
 169 .B CLOCK_MONOTONIC
 170 clock is not affected by discontinuous jumps in the system time
 171 (e.g., if the system administrator manually changes the clock),
 172 but is affected by the incremental adjustments performed by
 173 .BR adjtime (3)
 174 and NTP.
 175 This clock does not count time that the system is suspended.
 176 All
 177 .B CLOCK_MONOTONIC
 178 variants guarantee that the time returned by consecutive calls will not go
 179 backwards, but successive calls may\(emdepending on the architecture\(emreturn
 180 identical (not-increased) time values.
 181 .TP
 182 .BR CLOCK_MONOTONIC_COARSE " (since Linux 2.6.32; Linux-specific)"
 183 .\" Added in commit da15cfdae03351c689736f8d142618592e3cebc3
 184 A faster but less precise version of
 185 .BR CLOCK_MONOTONIC .
 186 Use when you need very fast, but not fine-grained timestamps.
 187 Requires per-architecture support,
 188 and probably also architecture support for this flag in the
 189 .BR vdso (7).
 190 .TP
 191 .BR CLOCK_MONOTONIC_RAW " (since Linux 2.6.28; Linux-specific)"
 192 .\" Added in commit 2d42244ae71d6c7b0884b5664cf2eda30fb2ae68, John Stultz
 193 Similar to
 194 .BR CLOCK_MONOTONIC ,
 195 but provides access to a raw hardware-based time
 196 that is not subject to NTP adjustments or
 197 the incremental adjustments performed by
 198 .BR adjtime (3).
 199 This clock does not count time that the system is suspended.
 200 .TP
 201 .BR CLOCK_BOOTTIME " (since Linux 2.6.39; Linux-specific)"
 202 .\" commit 7fdd7f89006dd5a4c702fa0ce0c272345fa44ae0
 203 .\" commit 70a08cca1227dc31c784ec930099a4417a06e7d0
 204 A nonsettable system-wide clock that is identical to
 205 .BR CLOCK_MONOTONIC ,
 206 except that it also includes any time that the system is suspended.
 207 This allows applications to get a suspend-aware monotonic clock
 208 without having to deal with the complications of
 209 .BR CLOCK_REALTIME ,
 210 which may have discontinuities if the time is changed using
 211 .BR settimeofday (2)
 212 or similar.
 213 .TP
 214 .BR CLOCK_BOOTTIME_ALARM " (since Linux 3.0; Linux-specific)"
 215 Like
 216 .BR CLOCK_BOOTTIME .
 217 See
 218 .BR timer_create (2)
 219 for further details.
 220 .TP
 221 .BR CLOCK_PROCESS_CPUTIME_ID " (since Linux 2.6.12)"
 222 This is a clock that measures CPU time consumed by this process
 223 (i.e., CPU time consumed by all threads in the process).
 224 On Linux, this clock is not settable.
 225 .TP
 226 .BR CLOCK_THREAD_CPUTIME_ID " (since Linux 2.6.12)"
 227 This is a clock that measures CPU time consumed by this thread.
 228 On Linux, this clock is not settable.
 229 .PP
 230 Linux also implements dynamic clock instances as described below.
 231 .SS Dynamic clocks
 232 In addition to the hard-coded System-V style clock IDs described above,
 233 Linux also supports
 234 POSIX clock operations on certain character devices.
 235 Such devices are
 236 called "dynamic" clocks, and are supported since Linux 2.6.39.
 237 .PP
 238 Using the appropriate macros, open file
 239 descriptors may be converted into clock IDs and passed to
 240 .BR clock_gettime (),
 241 .BR clock_settime (),
 242 and
 243 .BR clock_adjtime (2).
 244 The following example shows how to convert a file descriptor into a
 245 dynamic clock ID.
 246 .PP
 247 .in +4n
 248 .EX
 249 #define CLOCKFD 3
 250 #define FD_TO_CLOCKID(fd)   ((\(ti(clockid_t) (fd) << 3) | CLOCKFD)
 251 #define CLOCKID_TO_FD(clk)  ((unsigned int) \(ti((clk) >> 3))
 252
 253 struct timespec ts;
 254 clockid_t clkid;
 255 int fd;
 256
 257 fd = open("/dev/ptp0", O_RDWR);
 258 clkid = FD_TO_CLOCKID(fd);
 259 clock_gettime(clkid, &ts);
 260 .EE
 261 .in
 262 .SH RETURN VALUE
 263 .BR clock_gettime (),
 264 .BR clock_settime (),
 265 and
 266 .BR clock_getres ()
 267 return 0 for success.
 268 On error, \-1 is returned and
 269 .I errno
 270 is set to indicate the error.
 271 .SH ERRORS
 272 .TP
 273 .B EACCES
 274 .BR clock_settime ()
 275 does not have write permission for the dynamic POSIX
 276 clock device indicated.
 277 .TP
 278 .B EFAULT
 279 .I tp
 280 points outside the accessible address space.
 281 .TP
 282 .B EINVAL
 283 The
 284 .I clockid
 285 specified is invalid for one of two reasons.
 286 Either the System-V style
 287 hard coded positive value is out of range, or the dynamic clock ID
 288 does not refer to a valid instance of a clock object.
 289 .\" Linux also gives this error on attempts to set CLOCK_PROCESS_CPUTIME_ID
 290 .\" and CLOCK_THREAD_CPUTIME_ID, when probably the proper error should be
 291 .\" EPERM.
 292 .TP
 293 .B EINVAL
 294 .RB ( clock_settime ()):
 295 .I tp.tv_sec
 296 is negative or
 297 .I tp.tv_nsec
 298 is outside the range [0..999,999,999].
 299 .TP
 300 .B EINVAL
 301 The
 302 .I clockid
 303 specified in a call to
 304 .BR clock_settime ()
 305 is not a settable clock.
 306 .TP
 307 .BR EINVAL " (since Linux 4.3)"
 308 .\" commit e1d7ba8735551ed79c7a0463a042353574b96da3
 309 A call to
 310 .BR clock_settime ()
 311 with a
 312 .I clockid
 313 of
 314 .B CLOCK_REALTIME
 315 attempted to set the time to a value less than
 316 the current value of the
 317 .B CLOCK_MONOTONIC
 318 clock.
 319 .TP
 320 .B ENODEV
 321 The hot-pluggable device (like USB for example) represented by a
 322 dynamic
 323 .I clk_id
 324 has disappeared after its character device was opened.
 325 .TP
 326 .B ENOTSUP
 327 The operation is not supported by the dynamic POSIX clock device
 328 specified.
 329 .TP
 330 .B EPERM
 331 .BR clock_settime ()
 332 does not have permission to set the clock indicated.
 333 .SH VERSIONS
 334 These system calls first appeared in Linux 2.6.
 335 .SH ATTRIBUTES
 336 For an explanation of the terms used in this section, see
 337 .BR attributes (7).
 338 .ad l
 339 .nh
 340 .TS
 341 allbox;
 342 lbx lb lb
 343 l l l.
 344 Interface       Attribute       Value
 345 T{
 346 .BR clock_getres (),
 347 .BR clock_gettime (),
 348 .BR clock_settime ()
 349 T}      Thread safety   MT-Safe
 350 .TE
 351 .hy
 352 .ad
 353 .sp 1
 354 .SH CONFORMING TO
 355 POSIX.1-2001, POSIX.1-2008, SUSv2.
 356 .PP
 357 On POSIX systems on which these functions are available, the symbol
 358 .B _POSIX_TIMERS
 359 is defined in \fI<unistd.h>\fP to a value greater than 0.
 360 The symbols
 361 .BR _POSIX_MONOTONIC_CLOCK ,
 362 .BR _POSIX_CPUTIME ,
 363 .B _POSIX_THREAD_CPUTIME
 364 indicate that
 365 .BR CLOCK_MONOTONIC ,
 366 .BR CLOCK_PROCESS_CPUTIME_ID ,
 367 .B CLOCK_THREAD_CPUTIME_ID
 368 are available.
 369 (See also
 370 .BR sysconf (3).)
 371 .SH NOTES
 372 POSIX.1 specifies the following:
 373 .RS
 374 .PP
 375 Setting the value of the
 376 .B CLOCK_REALTIME
 377 clock via
 378 .BR clock_settime ()
 379 shall have no effect on threads that are blocked waiting for a relative time
 380 service based upon this clock, including the
 381 .BR nanosleep ()
 382 function; nor on the expiration of relative timers based upon this clock.
 383 Consequently, these time services shall expire when the requested relative
 384 interval elapses, independently of the new or old value of the clock.
 385 .RE
 386 .PP
 387 According to POSIX.1-2001, a process with "appropriate privileges" may set the
 388 .B CLOCK_PROCESS_CPUTIME_ID
 389 and
 390 .B CLOCK_THREAD_CPUTIME_ID
 391 clocks using
 392 .BR clock_settime ().
 393 On Linux, these clocks are not settable
 394 (i.e., no process has "appropriate privileges").
 395 .\" See http://bugzilla.kernel.org/show_bug.cgi?id=11972
 396 .\"
 397 .SS C library/kernel differences
 398 On some architectures, an implementation of
 399 .BR clock_gettime ()
 400 is provided in the
 401 .BR vdso (7).
 402 .\"
 403 .SS Historical note for SMP systems
 404 Before Linux added kernel support for
 405 .B CLOCK_PROCESS_CPUTIME_ID
 406 and
 407 .BR CLOCK_THREAD_CPUTIME_ID ,
 408 glibc implemented these clocks on many platforms using timer
 409 registers from the CPUs
 410 (TSC on i386, AR.ITC on Itanium).
 411 These registers may differ between CPUs and as a consequence
 412 these clocks may return
 413 .B bogus results
 414 if a process is migrated to another CPU.
 415 .PP
 416 If the CPUs in an SMP system have different clock sources, then
 417 there is no way to maintain a correlation between the timer registers since
 418 each CPU will run at a slightly different frequency.
 419 If that is the case, then
 420 .I clock_getcpuclockid(0)
 421 will return
 422 .B ENOENT
 423 to signify this condition.
 424 The two clocks will then be useful only if it
 425 can be ensured that a process stays on a certain CPU.
 426 .PP
 427 The processors in an SMP system do not start all at exactly the same
 428 time and therefore the timer registers are typically running at an offset.
 429 Some architectures include code that attempts to limit these offsets on bootup.
 430 However, the code cannot guarantee to accurately tune the offsets.
 431 Glibc contains no provisions to deal with these offsets (unlike the Linux
 432 Kernel).
 433 Typically these offsets are small and therefore the effects may be
 434 negligible in most cases.
 435 .PP
 436 Since glibc 2.4,
 437 the wrapper functions for the system calls described in this page avoid
 438 the abovementioned problems by employing the kernel implementation of
 439 .B CLOCK_PROCESS_CPUTIME_ID
 440 and
 441 .BR CLOCK_THREAD_CPUTIME_ID ,
 442 on systems that provide such an implementation
 443 (i.e., Linux 2.6.12 and later).
 444 .SH EXAMPLES
 445 The program below demonstrates the use of
 446 .BR clock_gettime ()
 447 and
 448 .BR clock_getres ()
 449 with various clocks.
 450 This is an example of what we might see when running the program:
 451 .PP
 452 .in +4n
 453 .EX
 454 $ \fB./clock_times x\fP
 455 CLOCK_REALTIME : 1585985459.446 (18356 days +  7h 30m 59s)
 456      resolution:          0.000000001
 457 CLOCK_TAI      : 1585985496.447 (18356 days +  7h 31m 36s)
 458      resolution:          0.000000001
 459 CLOCK_MONOTONIC:      52395.722 (14h 33m 15s)
 460      resolution:          0.000000001
 461 CLOCK_BOOTTIME :      72691.019 (20h 11m 31s)
 462      resolution:          0.000000001
 463 .EE
 464 .in
 465 .SS Program source
 466 \&
 467 .EX
 468 /* clock_times.c
 469
 470    Licensed under GNU General Public License v2 or later.
 471 */
 472 #define _XOPEN_SOURCE 600
 473 #include <time.h>
 474 #include <stdint.h>
 475 #include <stdio.h>
 476 #include <stdlib.h>
 477 #include <stdbool.h>
 478 #include <unistd.h>
 479
 480 #define SECS_IN_DAY (24 * 60 * 60)
 481
 482 static void
 483 displayClock(clockid_t clock, const char *name, bool showRes)
 484 {
 485     struct timespec ts;
 486
 487     if (clock_gettime(clock, &ts) == \-1) {
 488         perror("clock_gettime");
 489         exit(EXIT_FAILURE);
 490     }
 491
 492     printf("%\-15s: %10jd.%03ld (", name,
 493             (intmax_t) ts.tv_sec, ts.tv_nsec / 1000000);
 494
 495     long days = ts.tv_sec / SECS_IN_DAY;
 496     if (days > 0)
 497         printf("%ld days + ", days);
 498
 499     printf("%2dh %2dm %2ds",
 500             (int) (ts.tv_sec % SECS_IN_DAY) / 3600,
 501             (int) (ts.tv_sec % 3600) / 60,
 502             (int) ts.tv_sec % 60);
 503     printf(")\en");
 504
 505     if (clock_getres(clock, &ts) == \-1) {
 506         perror("clock_getres");
 507         exit(EXIT_FAILURE);
 508     }
 509
 510     if (showRes)
 511         printf("     resolution: %10jd.%09ld\en",
 512                 (intmax_t) ts.tv_sec, ts.tv_nsec);
 513 }
 514
 515 int
 516 main(int argc, char *argv[])
 517 {
 518     bool showRes = argc > 1;
 519
 520     displayClock(CLOCK_REALTIME, "CLOCK_REALTIME", showRes);
 521 #ifdef CLOCK_TAI
 522     displayClock(CLOCK_TAI, "CLOCK_TAI", showRes);
 523 #endif
 524     displayClock(CLOCK_MONOTONIC, "CLOCK_MONOTONIC", showRes);
 525 #ifdef CLOCK_BOOTTIME
 526     displayClock(CLOCK_BOOTTIME, "CLOCK_BOOTTIME", showRes);
 527 #endif
 528     exit(EXIT_SUCCESS);
 529 }
 530 .EE
 531 .SH SEE ALSO
 532 .BR date (1),
 533 .BR gettimeofday (2),
 534 .BR settimeofday (2),
 535 .BR time (2),
 536 .BR adjtime (3),
 537 .BR clock_getcpuclockid (3),
 538 .BR ctime (3),
 539 .BR ftime (3),
 540 .BR pthread_getcpuclockid (3),
 541 .BR sysconf (3),
 542 .BR time (7),
 543 .BR time_namespaces (7),
 544 .BR vdso (7),
 545 .BR hwclock (8)