Debian Codegraph @

upstream/debian-unstable/man7/time.7

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