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
4 .\" %%%LICENSE_START(VERBATIM)
5 .\" Permission is granted to make and distribute verbatim copies of this
6 .\" manual provided the copyright notice and this permission notice are
7 .\" preserved on all copies.
9 .\" Permission is granted to copy and distribute modified versions of this
10 .\" manual under the conditions for verbatim copying, provided that the
11 .\" entire resulting derived work is distributed under the terms of a
12 .\" permission notice identical to this one.
14 .\" Since the Linux kernel and libraries are constantly changing, this
15 .\" manual page may be incorrect or out-of-date. The author(s) assume no
16 .\" responsibility for errors or omissions, or for damages resulting from
17 .\" the use of the information contained herein. The author(s) may not
18 .\" have taken the same level of care in the production of this manual,
19 .\" which is licensed free of charge, as they might when working
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
26 .\" 2003-08-23 Martin Schulze <joey@infodrom.org> improvements
27 .\" 2003-08-24 aeb, large parts rewritten
28 .\" 2004-08-06 Christoph Lameter <clameter@sgi.com>, SMP note
30 .TH CLOCK_GETRES 2 2013-09-04 "" "Linux Programmer's Manual"
32 clock_getres, clock_gettime, clock_settime \- clock and time functions
36 .BI "int clock_getres(clockid_t " clk_id ", struct timespec *" res );
38 .BI "int clock_gettime(clockid_t " clk_id ", struct timespec *" tp );
40 .BI "int clock_settime(clockid_t " clk_id ", const struct timespec *" tp );
42 Link with \fI\-lrt\fP (only for glibc versions before 2.17).
45 Feature Test Macro Requirements for glibc (see
46 .BR feature_test_macros (7)):
54 _POSIX_C_SOURCE\ >=\ 199309L
60 finds the resolution (precision) of the specified clock
64 is non-NULL, stores it in the \fIstruct timespec\fP pointed to by
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
74 then it is truncated to a multiple of
81 retrieve and set the time of the specified clock
90 structures, as specified in
96 time_t tv_sec; /* seconds */
97 long tv_nsec; /* nanoseconds */
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.
108 All implementations support the system-wide real-time clock,
109 which is identified by
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.
115 More clocks may be implemented.
116 The interpretation of the
117 corresponding time values and the effect on timers is unspecified.
119 Sufficiently recent versions of glibc and the Linux kernel
120 support the following clocks:
123 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
131 .BR CLOCK_REALTIME_COARSE " (since Linux 2.6.32; Linux-specific)"
132 .\" Added in commit da15cfdae03351c689736f8d142618592e3cebc3
133 A faster but less precise version of
135 Use when you need very fast, but not fine-grained timestamps.
139 Clock that cannot be set and represents monotonic time since
140 some unspecified starting point.
141 This clock is not affected by discontinuous jumps in the system time
142 (e.g., if the system administrator manually changes the clock),
143 but is affected by the incremental adjustments performed by
147 .BR CLOCK_MONOTONIC_COARSE " (since Linux 2.6.32; Linux-specific)"
148 .\" Added in commit da15cfdae03351c689736f8d142618592e3cebc3
149 A faster but less precise version of
150 .BR CLOCK_MONOTONIC .
151 Use when you need very fast, but not fine-grained timestamps.
153 .BR CLOCK_MONOTONIC_RAW " (since Linux 2.6.28; Linux-specific)"
154 .\" Added in commit 2d42244ae71d6c7b0884b5664cf2eda30fb2ae68, John Stultz
156 .BR CLOCK_MONOTONIC ,
157 but provides access to a raw hardware-based time
158 that is not subject to NTP adjustments or
159 the incremental adjustments performed by
162 .BR CLOCK_BOOTTIME " (since Linux 2.6.39; Linux-specific)"
163 .\" commit 7fdd7f89006dd5a4c702fa0ce0c272345fa44ae0
164 .\" commit 70a08cca1227dc31c784ec930099a4417a06e7d0
166 .BR CLOCK_MONOTONIC ,
167 except it also includes any time that the system is suspended.
168 This allows applications to get a suspend-aware monotonic clock
169 without having to deal with the complications of
171 which may have discontinuities if the time is changed using
172 .BR settimeofday (2).
174 .BR CLOCK_PROCESS_CPUTIME_ID " (since Linux 2.6.12)"
175 High-resolution per-process timer from the CPU.
177 .BR CLOCK_THREAD_CPUTIME_ID " (since Linux 2.6.12)"
178 Thread-specific CPU-time clock.
180 .BR clock_gettime (),
184 return 0 for success, or \-1 for failure (in which case
186 is set appropriately).
191 points outside the accessible address space.
196 specified is not supported on this system.
197 .\" Linux also gives this error on attempts to set CLOCK_PROCESS_CPUTIME_ID
198 .\" and CLOCK_THREAD_CPUTIME_ID, when probably the proper error should be
203 does not have permission to set the clock indicated.
205 These system calls first appeared in Linux 2.6.
209 On POSIX systems on which these functions are available, the symbol
211 is defined in \fI<unistd.h>\fP to a value greater than 0.
213 .BR _POSIX_MONOTONIC_CLOCK ,
215 .B _POSIX_THREAD_CPUTIME
217 .BR CLOCK_MONOTONIC ,
218 .BR CLOCK_PROCESS_CPUTIME_ID ,
219 .B CLOCK_THREAD_CPUTIME_ID
224 .SS Historical note for SMP systems
225 Before Linux added kernel support for
226 .B CLOCK_PROCESS_CPUTIME_ID
228 .BR CLOCK_THREAD_CPUTIME_ID ,
229 glibc implemented these clocks on many platforms using timer
230 registers from the CPUs
231 (TSC on i386, AR.ITC on Itanium).
232 These registers may differ between CPUs and as a consequence
233 these clocks may return
235 if a process is migrated to another CPU.
237 If the CPUs in an SMP system have different clock sources then
238 there is no way to maintain a correlation between the timer registers since
239 each CPU will run at a slightly different frequency.
240 If that is the case then
241 .I clock_getcpuclockid(0)
244 to signify this condition.
245 The two clocks will then be useful only if it
246 can be ensured that a process stays on a certain CPU.
248 The processors in an SMP system do not start all at exactly the same
249 time and therefore the timer registers are typically running at an offset.
250 Some architectures include code that attempts to limit these offsets on bootup.
251 However, the code cannot guarantee to accurately tune the offsets.
252 Glibc contains no provisions to deal with these offsets (unlike the Linux
254 Typically these offsets are small and therefore the effects may be
255 negligible in most cases.
258 the wrapper functions for the system calls described in this page avoid
259 the abovementioned problems by employing the kernel implementation of
260 .B CLOCK_PROCESS_CPUTIME_ID
262 .BR CLOCK_THREAD_CPUTIME_ID ,
263 on systems that provide such an implementation
264 (i.e., Linux 2.6.12 and later).
266 According to POSIX.1-2001, a process with "appropriate privileges" may set the
267 .B CLOCK_PROCESS_CPUTIME_ID
269 .B CLOCK_THREAD_CPUTIME_ID
271 .BR clock_settime ().
272 On Linux, these clocks are not settable
273 (i.e., no process has "appropriate privileges").
274 .\" See http://bugzilla.kernel.org/show_bug.cgi?id=11972
277 .BR gettimeofday (2),
278 .BR settimeofday (2),
281 .BR clock_getcpuclockid (3),
284 .BR pthread_getcpuclockid (3),