]>
Commit | Line | Data |
---|---|---|
c11b1abf | 1 | .\" Copyright (c) 2006 by Michael Kerrisk <mtk.manpages@gmail.com> |
4a04071a | 2 | .\" |
93015253 | 3 | .\" %%%LICENSE_START(VERBATIM) |
4a04071a MK |
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 | |
10d76543 MK |
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. | |
4a04071a MK |
20 | .\" |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 23 | .\" %%%LICENSE_END |
4a04071a | 24 | .\" |
46f14bc7 MK |
25 | .\" 2008-06-24, mtk: added some details about where jiffies come into |
26 | .\" play; added section on high-resolution timers. | |
27 | .\" | |
09b8afdc | 28 | .TH TIME 7 2018-04-30 "Linux" "Linux Programmer's Manual" |
4a04071a | 29 | .SH NAME |
46f14bc7 | 30 | time \- overview of time and timers |
4a04071a | 31 | .SH DESCRIPTION |
73d8cece | 32 | .SS Real time and process time |
4a04071a MK |
33 | .I "Real time" |
34 | is defined as time measured from some fixed point, | |
c13182ef | 35 | either from a standard point in the past |
4a04071a MK |
36 | (see the description of the Epoch and calendar time below), |
37 | or from some point (e.g., the start) in the life of a process | |
38 | .RI ( "elapsed time" ). | |
a721e8b2 | 39 | .PP |
4a04071a MK |
40 | .I "Process time" |
41 | is defined as the amount of CPU time used by a process. | |
c13182ef | 42 | This is sometimes divided into |
4a04071a MK |
43 | .I user |
44 | and | |
45 | .I system | |
46 | components. | |
47 | User CPU time is the time spent executing code in user mode. | |
48 | System CPU time is the time spent by the kernel executing | |
49 | in system mode on behalf of the process (e.g., executing system calls). | |
50 | The | |
51 | .BR time (1) | |
c13182ef | 52 | command can be used to determine the amount of CPU time consumed |
4a04071a MK |
53 | during the execution of a program. |
54 | A program can determine the amount of CPU time it has consumed using | |
55 | .BR times (2), | |
56 | .BR getrusage (2), | |
57 | or | |
58 | .BR clock (3). | |
73d8cece | 59 | .SS The hardware clock |
4a04071a MK |
60 | Most computers have a (battery-powered) hardware clock which the kernel |
61 | reads at boot time in order to initialize the software clock. | |
62 | For further details, see | |
63 | .BR rtc (4) | |
64 | and | |
65 | .BR hwclock (8). | |
73d8cece | 66 | .SS The software clock, HZ, and jiffies |
46f14bc7 MK |
67 | The accuracy of various system calls that set timeouts, |
68 | (e.g., | |
69 | .BR select (2), | |
70 | .BR sigtimedwait (2)) | |
71 | .\" semtimedop(), mq_timedwait(), io_getevents(), poll() are the same | |
72 | .\" futexes and thus sem_timedwait() seem to use high-res timers. | |
73 | and measure CPU time (e.g., | |
74 | .BR getrusage (2)) | |
75 | is limited by the resolution of the | |
4a04071a | 76 | .IR "software clock" , |
c13182ef | 77 | a clock maintained by the kernel which measures time in |
4a04071a MK |
78 | .IR jiffies . |
79 | The size of a jiffy is determined by the value of the kernel constant | |
80 | .IR HZ . | |
a721e8b2 | 81 | .PP |
4a04071a MK |
82 | The value of |
83 | .I HZ | |
84 | varies across kernel versions and hardware platforms. | |
34ccb744 | 85 | On i386 the situation is as follows: |
c13182ef | 86 | on kernels up to and including 2.4.x, HZ was 100, |
4a04071a | 87 | giving a jiffy value of 0.01 seconds; |
a12ee81d | 88 | starting with 2.6.0, HZ was raised to 1000, giving a jiffy of |
46f14bc7 MK |
89 | 0.001 seconds. |
90 | Since kernel 2.6.13, the HZ value is a kernel | |
4a04071a MK |
91 | configuration parameter and can be 100, 250 (the default) or 1000, |
92 | yielding a jiffies value of, respectively, 0.01, 0.004, or 0.001 seconds. | |
c13182ef MK |
93 | Since kernel 2.6.20, a further frequency is available: |
94 | 300, a number that divides evenly for the common video | |
c7c740cb | 95 | frame rates (PAL, 25 HZ; NTSC, 30 HZ). |
a721e8b2 | 96 | .PP |
73858a07 MK |
97 | The |
98 | .BR times (2) | |
99 | system call is a special case. | |
100 | It reports times with a granularity defined by the kernel constant | |
101 | .IR USER_HZ . | |
7fac88a9 | 102 | User-space applications can determine the value of this constant using |
73858a07 MK |
103 | .IR sysconf(_SC_CLK_TCK) . |
104 | .\" glibc gets this info with a little help from the ELF loader; | |
105 | .\" see glibc elf/dl-support.c and kernel fs/binfmt_elf.c. | |
106 | .\" | |
73d8cece | 107 | .SS High-resolution timers |
73858a07 | 108 | Before Linux 2.6.21, the accuracy of timer and sleep system calls |
46f14bc7 | 109 | (see below) was also limited by the size of the jiffy. |
a721e8b2 | 110 | .PP |
73858a07 MK |
111 | Since Linux 2.6.21, Linux supports high-resolution timers (HRTs), |
112 | optionally configurable via | |
113 | .BR CONFIG_HIGH_RES_TIMERS . | |
46f14bc7 MK |
114 | On a system that supports HRTs, the accuracy of sleep and timer |
115 | system calls is no longer constrained by the jiffy, | |
116 | but instead can be as accurate as the hardware allows | |
117 | (microsecond accuracy is typical of modern hardware). | |
73858a07 MK |
118 | You can determine whether high-resolution timers are supported by |
119 | checking the resolution returned by a call to | |
0eb44391 | 120 | .BR clock_getres (2) |
73858a07 MK |
121 | or looking at the "resolution" entries in |
122 | .IR /proc/timer_list . | |
a721e8b2 | 123 | .PP |
9bb26f2d MK |
124 | HRTs are not supported on all hardware architectures. |
125 | (Support is provided on x86, arm, and powerpc, among others.) | |
73d8cece | 126 | .SS The Epoch |
008f1ecc | 127 | UNIX systems represent time in seconds since the |
4a04071a | 128 | .IR Epoch , |
f49c451a | 129 | 1970-01-01 00:00:00 +0000 (UTC). |
a721e8b2 | 130 | .PP |
c13182ef | 131 | A program can determine the |
0daa9e92 | 132 | .I "calendar time" |
39ad4669 MK |
133 | via the |
134 | .BR clock_gettime (2) | |
135 | .BR CLOCK_REALTIME | |
136 | clock, | |
137 | which returns time (in seconds and nanoseconds) that have | |
c13182ef | 138 | elapsed since the Epoch; |
4a04071a | 139 | .BR time (2) |
c13182ef | 140 | provides similar information, but only with accuracy to the |
4a04071a MK |
141 | nearest second. |
142 | The system time can be changed using | |
39ad4669 MK |
143 | .BR clock_settime (2). |
144 | .\" | |
73d8cece | 145 | .SS Broken-down time |
4a04071a | 146 | Certain library functions use a structure of |
c13182ef | 147 | type |
4a04071a | 148 | .I tm |
c13182ef | 149 | to represent |
4a04071a | 150 | .IR "broken-down time" , |
c13182ef | 151 | which stores time value separated out into distinct components |
4a04071a MK |
152 | (year, month, day, hour, minute, second, etc.). |
153 | This structure is described in | |
154 | .BR ctime (3), | |
c13182ef | 155 | which also describes functions that convert between calendar time and |
4a04071a | 156 | broken-down time. |
c13182ef | 157 | Functions for converting between broken-down time and printable |
4a04071a MK |
158 | string representations of the time are described in |
159 | .BR ctime (3), | |
160 | .BR strftime (3), | |
161 | and | |
162 | .BR strptime (3). | |
73d8cece | 163 | .SS Sleeping and setting timers |
c13182ef MK |
164 | Various system calls and functions allow a program to sleep |
165 | (suspend execution) for a specified period of time; see | |
46f14bc7 MK |
166 | .BR nanosleep (2), |
167 | .BR clock_nanosleep (2), | |
4a04071a MK |
168 | and |
169 | .BR sleep (3). | |
a721e8b2 | 170 | .PP |
4a04071a MK |
171 | Various system calls allow a process to set a timer that expires |
172 | at some point in the future, and optionally at repeated intervals; | |
173 | see | |
174 | .BR alarm (2), | |
175 | .BR getitimer (2), | |
46f14bc7 | 176 | .BR timerfd_create (2), |
4a04071a | 177 | and |
804f03e6 | 178 | .BR timer_create (2). |
c634028a | 179 | .SS Timer slack |
f8090b56 MK |
180 | Since Linux 2.6.28, it is possible to control the "timer slack" |
181 | value for a thread. | |
182 | The timer slack is the length of time by | |
183 | which the kernel may delay the wake-up of certain | |
184 | system calls that block with a timeout. | |
3685fa98 | 185 | Permitting this delay allows the kernel to coalesce wake-up events, |
f8090b56 MK |
186 | thus possibly reducing the number of system wake-ups and saving power. |
187 | For more details, see the description of | |
188 | .B PR_SET_TIMERSLACK | |
189 | in | |
190 | .BR prctl (2). | |
47297adb | 191 | .SH SEE ALSO |
ca8a0bd2 MK |
192 | .ad l |
193 | .nh | |
4a04071a MK |
194 | .BR date (1), |
195 | .BR time (1), | |
17c42872 | 196 | .BR timeout (1), |
4a04071a MK |
197 | .BR adjtimex (2), |
198 | .BR alarm (2), | |
0eb44391 | 199 | .BR clock_gettime (2), |
46f14bc7 | 200 | .BR clock_nanosleep (2), |
4a04071a MK |
201 | .BR getitimer (2), |
202 | .BR getrlimit (2), | |
203 | .BR getrusage (2), | |
204 | .BR gettimeofday (2), | |
205 | .BR nanosleep (2), | |
206 | .BR stat (2), | |
207 | .BR time (2), | |
8699ebd9 | 208 | .BR timer_create (2), |
c33a62d8 | 209 | .BR timerfd_create (2), |
4a04071a MK |
210 | .BR times (2), |
211 | .BR utime (2), | |
4c9efdfd | 212 | .BR adjtime (3), |
4a04071a | 213 | .BR clock (3), |
edf60acb | 214 | .BR clock_getcpuclockid (3), |
4a04071a | 215 | .BR ctime (3), |
97816cb9 MK |
216 | .BR ntp_adjtime (3), |
217 | .BR ntp_gettime (3), | |
30b6304c | 218 | .BR pthread_getcpuclockid (3), |
f0c34053 | 219 | .BR sleep (3), |
4a04071a MK |
220 | .BR strftime (3), |
221 | .BR strptime (3), | |
f0c34053 | 222 | .BR timeradd (3), |
4a04071a MK |
223 | .BR usleep (3), |
224 | .BR rtc (4), | |
ccd2b351 | 225 | .BR hwclock (8) |