| .\" Copyright (c) 2003 Nick Clifford (zaf@nrc.co.nz), Jan 25, 2003 |
| .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl), Aug 24, 2003 |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .\" 2003-08-23 Martin Schulze <joey@infodrom.org> improvements |
| .\" 2003-08-24 aeb, large parts rewritten |
| .\" 2004-08-06 Christoph Lameter <clameter@sgi.com>, SMP note |
| .\" |
| .TH CLOCK_GETRES 2 2019-03-06 "" "Linux Programmer's Manual" |
| .SH NAME |
| clock_getres, clock_gettime, clock_settime \- clock and time functions |
| .SH SYNOPSIS |
| .B #include <time.h> |
| .PP |
| .BI "int clock_getres(clockid_t " clk_id ", struct timespec *" res ); |
| .PP |
| .BI "int clock_gettime(clockid_t " clk_id ", struct timespec *" tp ); |
| .PP |
| .BI "int clock_settime(clockid_t " clk_id ", const struct timespec *" tp ); |
| .PP |
| Link with \fI\-lrt\fP (only for glibc versions before 2.17). |
| .PP |
| .in -4n |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .in |
| .PP |
| .ad l |
| .BR clock_getres (), |
| .BR clock_gettime (), |
| .BR clock_settime (): |
| .RS |
| _POSIX_C_SOURCE\ >=\ 199309L |
| .RE |
| .ad b |
| .SH DESCRIPTION |
| The function |
| .BR clock_getres () |
| finds the resolution (precision) of the specified clock |
| .IR clk_id , |
| and, if |
| .I res |
| is non-NULL, stores it in the \fIstruct timespec\fP pointed to by |
| .IR res . |
| The resolution of clocks depends on the implementation and cannot be |
| configured by a particular process. |
| If the time value pointed to by the argument |
| .I tp |
| of |
| .BR clock_settime () |
| is not a multiple of |
| .IR res , |
| then it is truncated to a multiple of |
| .IR res . |
| .PP |
| The functions |
| .BR clock_gettime () |
| and |
| .BR clock_settime () |
| retrieve and set the time of the specified clock |
| .IR clk_id . |
| .PP |
| The |
| .I res |
| and |
| .I tp |
| arguments are |
| .I timespec |
| structures, as specified in |
| .IR <time.h> : |
| .PP |
| .in +4n |
| .EX |
| struct timespec { |
| time_t tv_sec; /* seconds */ |
| long tv_nsec; /* nanoseconds */ |
| }; |
| .EE |
| .in |
| .PP |
| The |
| .I clk_id |
| argument is the identifier of the particular clock on which to act. |
| A clock may be system-wide and hence visible for all processes, or |
| per-process if it measures time only within a single process. |
| .PP |
| All implementations support the system-wide real-time clock, |
| which is identified by |
| .BR CLOCK_REALTIME . |
| Its time represents seconds and nanoseconds since the Epoch. |
| When its time is changed, timers for a relative interval are |
| unaffected, but timers for an absolute point in time are affected. |
| .PP |
| More clocks may be implemented. |
| The interpretation of the |
| corresponding time values and the effect on timers is unspecified. |
| .PP |
| Sufficiently recent versions of glibc and the Linux kernel |
| support the following clocks: |
| .TP |
| .B CLOCK_REALTIME |
| System-wide clock that measures real (i.e., wall-clock) time. |
| Setting this clock requires appropriate privileges. |
| This clock is affected by discontinuous jumps in the system time |
| (e.g., if the system administrator manually changes the clock), |
| and by the incremental adjustments performed by |
| .BR adjtime (3) |
| and NTP. |
| .TP |
| .BR CLOCK_REALTIME_COARSE " (since Linux 2.6.32; Linux-specific)" |
| .\" Added in commit da15cfdae03351c689736f8d142618592e3cebc3 |
| A faster but less precise version of |
| .BR CLOCK_REALTIME . |
| Use when you need very fast, but not fine-grained timestamps. |
| Requires per-architecture support, |
| and probably also architecture support for this flag in the |
| .BR vdso (7). |
| .TP |
| .B CLOCK_MONOTONIC |
| Clock that cannot be set and represents monotonic time since\(emas described |
| by POSIX\(em"some unspecified point in the past". |
| On Linux, that point corresponds to the number of seconds that the system |
| has been running since it was booted. |
| .IP |
| The |
| .B CLOCK_MONOTONIC |
| clock is not affected by discontinuous jumps in the system time |
| (e.g., if the system administrator manually changes the clock), |
| but is affected by the incremental adjustments performed by |
| .BR adjtime (3) |
| and NTP. |
| This clock does not count time that the system is suspended. |
| .TP |
| .BR CLOCK_MONOTONIC_COARSE " (since Linux 2.6.32; Linux-specific)" |
| .\" Added in commit da15cfdae03351c689736f8d142618592e3cebc3 |
| A faster but less precise version of |
| .BR CLOCK_MONOTONIC . |
| Use when you need very fast, but not fine-grained timestamps. |
| Requires per-architecture support, |
| and probably also architecture support for this flag in the |
| .BR vdso (7). |
| .TP |
| .BR CLOCK_MONOTONIC_RAW " (since Linux 2.6.28; Linux-specific)" |
| .\" Added in commit 2d42244ae71d6c7b0884b5664cf2eda30fb2ae68, John Stultz |
| Similar to |
| .BR CLOCK_MONOTONIC , |
| but provides access to a raw hardware-based time |
| that is not subject to NTP adjustments or |
| the incremental adjustments performed by |
| .BR adjtime (3). |
| This clock does not count time that the system is suspended. |
| .TP |
| .BR CLOCK_BOOTTIME " (since Linux 2.6.39; Linux-specific)" |
| .\" commit 7fdd7f89006dd5a4c702fa0ce0c272345fa44ae0 |
| .\" commit 70a08cca1227dc31c784ec930099a4417a06e7d0 |
| Identical to |
| .BR CLOCK_MONOTONIC , |
| except it also includes any time that the system is suspended. |
| This allows applications to get a suspend-aware monotonic clock |
| without having to deal with the complications of |
| .BR CLOCK_REALTIME , |
| which may have discontinuities if the time is changed using |
| .BR settimeofday (2) |
| or similar. |
| .TP |
| .BR CLOCK_PROCESS_CPUTIME_ID " (since Linux 2.6.12)" |
| Per-process CPU-time clock |
| (measures CPU time consumed by all threads in the process). |
| .TP |
| .BR CLOCK_THREAD_CPUTIME_ID " (since Linux 2.6.12)" |
| Thread-specific CPU-time clock. |
| .SH RETURN VALUE |
| .BR clock_gettime (), |
| .BR clock_settime (), |
| and |
| .BR clock_getres () |
| return 0 for success, or \-1 for failure (in which case |
| .I errno |
| is set appropriately). |
| .SH ERRORS |
| .TP |
| .B EFAULT |
| .I tp |
| points outside the accessible address space. |
| .TP |
| .B EINVAL |
| The |
| .I clk_id |
| specified is not supported on this system. |
| .\" Linux also gives this error on attempts to set CLOCK_PROCESS_CPUTIME_ID |
| .\" and CLOCK_THREAD_CPUTIME_ID, when probably the proper error should be |
| .\" EPERM. |
| .TP |
| .B EINVAL |
| .RB ( clock_settime ()): |
| .I tp.tv_sec |
| is negative or |
| .I tp.tv_nsec |
| is outside the range [0..999,999,999]. |
| .TP |
| .BR EINVAL " (since Linux 4.3)" |
| .\" commit e1d7ba8735551ed79c7a0463a042353574b96da3 |
| A call to |
| .BR clock_settime () |
| with a |
| .I clk_id |
| of |
| .B CLOCK_REALTIME |
| attempted to set the time to a value less than |
| the current value of the |
| .B CLOCK_MONOTONIC |
| clock. |
| .TP |
| .B EPERM |
| .BR clock_settime () |
| does not have permission to set the clock indicated. |
| .SH VERSIONS |
| These system calls first appeared in Linux 2.6. |
| .SH ATTRIBUTES |
| For an explanation of the terms used in this section, see |
| .BR attributes (7). |
| .TS |
| allbox; |
| lbw32 lb lb |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR clock_getres (), |
| .BR clock_gettime (), |
| .BR clock_settime () |
| T} Thread safety MT-Safe |
| .TE |
| .sp 1 |
| .SH CONFORMING TO |
| POSIX.1-2001, POSIX.1-2008, SUSv2. |
| .SH AVAILABILITY |
| On POSIX systems on which these functions are available, the symbol |
| .B _POSIX_TIMERS |
| is defined in \fI<unistd.h>\fP to a value greater than 0. |
| The symbols |
| .BR _POSIX_MONOTONIC_CLOCK , |
| .BR _POSIX_CPUTIME , |
| .B _POSIX_THREAD_CPUTIME |
| indicate that |
| .BR CLOCK_MONOTONIC , |
| .BR CLOCK_PROCESS_CPUTIME_ID , |
| .B CLOCK_THREAD_CPUTIME_ID |
| are available. |
| (See also |
| .BR sysconf (3).) |
| .SH NOTES |
| POSIX.1 specifies the following: |
| .RS |
| .PP |
| Setting the value of the |
| .B CLOCK_REALTIME |
| clock via |
| .BR clock_settime () |
| shall have no effect on threads that are blocked waiting for a relative time |
| service based upon this clock, including the |
| .BR nanosleep () |
| function; nor on the expiration of relative timers based upon this clock. |
| Consequently, these time services shall expire when the requested relative |
| interval elapses, independently of the new or old value of the clock. |
| .RE |
| .\" |
| .SS C library/kernel differences |
| On some architectures, an implementation of |
| .BR clock_gettime () |
| is provided in the |
| .BR vdso (7). |
| .\" |
| .SS Historical note for SMP systems |
| Before Linux added kernel support for |
| .B CLOCK_PROCESS_CPUTIME_ID |
| and |
| .BR CLOCK_THREAD_CPUTIME_ID , |
| glibc implemented these clocks on many platforms using timer |
| registers from the CPUs |
| (TSC on i386, AR.ITC on Itanium). |
| These registers may differ between CPUs and as a consequence |
| these clocks may return |
| .B bogus results |
| if a process is migrated to another CPU. |
| .PP |
| If the CPUs in an SMP system have different clock sources, then |
| there is no way to maintain a correlation between the timer registers since |
| each CPU will run at a slightly different frequency. |
| If that is the case, then |
| .I clock_getcpuclockid(0) |
| will return |
| .B ENOENT |
| to signify this condition. |
| The two clocks will then be useful only if it |
| can be ensured that a process stays on a certain CPU. |
| .PP |
| The processors in an SMP system do not start all at exactly the same |
| time and therefore the timer registers are typically running at an offset. |
| Some architectures include code that attempts to limit these offsets on bootup. |
| However, the code cannot guarantee to accurately tune the offsets. |
| Glibc contains no provisions to deal with these offsets (unlike the Linux |
| Kernel). |
| Typically these offsets are small and therefore the effects may be |
| negligible in most cases. |
| .PP |
| Since glibc 2.4, |
| the wrapper functions for the system calls described in this page avoid |
| the abovementioned problems by employing the kernel implementation of |
| .B CLOCK_PROCESS_CPUTIME_ID |
| and |
| .BR CLOCK_THREAD_CPUTIME_ID , |
| on systems that provide such an implementation |
| (i.e., Linux 2.6.12 and later). |
| .SH BUGS |
| According to POSIX.1-2001, a process with "appropriate privileges" may set the |
| .B CLOCK_PROCESS_CPUTIME_ID |
| and |
| .B CLOCK_THREAD_CPUTIME_ID |
| clocks using |
| .BR clock_settime (). |
| On Linux, these clocks are not settable |
| (i.e., no process has "appropriate privileges"). |
| .\" See http://bugzilla.kernel.org/show_bug.cgi?id=11972 |
| .SH SEE ALSO |
| .BR date (1), |
| .BR gettimeofday (2), |
| .BR settimeofday (2), |
| .BR time (2), |
| .BR adjtime (3), |
| .BR clock_getcpuclockid (3), |
| .BR ctime (3), |
| .BR ftime (3), |
| .BR pthread_getcpuclockid (3), |
| .BR sysconf (3), |
| .BR time (7), |
| .BR vdso (7), |
| .BR hwclock (8) |