]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright Andries Brouwer, 2000 |
35a512d8 MK |
2 | .\" Some fragments of text came from the time-1.7 info file. |
3 | .\" Inspired by kromJx@crosswinds.net. | |
fea681da | 4 | .\" |
95fb8859 | 5 | .\" SPDX-License-Identifier: GPL-1.0-or-later |
fea681da | 6 | .\" |
1ae6b2c7 | 7 | .TH TIME 1 2019-03-06 GNU "Linux User's Manual" |
fea681da MK |
8 | .SH NAME |
9 | time \- time a simple command or give resource usage | |
10 | .SH SYNOPSIS | |
7ba3e56f BIG |
11 | .B time \c |
12 | .RI [ options ] " command " [ arguments... ] | |
fea681da MK |
13 | .SH DESCRIPTION |
14 | The | |
15 | .B time | |
16 | command runs the specified program | |
17 | .I command | |
18 | with the given arguments. | |
19 | When | |
20 | .I command | |
21 | finishes, | |
22 | .B time | |
e3535a43 | 23 | writes a message to standard error giving timing statistics |
fea681da MK |
24 | about this program run. |
25 | These statistics consist of (i) the elapsed real time | |
26 | between invocation and termination, (ii) the user CPU time | |
27 | (the sum of the | |
28 | .I tms_utime | |
29 | and | |
30 | .I tms_cutime | |
31 | values in a | |
32 | .I "struct tms" | |
33 | as returned by | |
34 | .BR times (2)), | |
35 | and (iii) the system CPU time (the sum of the | |
36 | .I tms_stime | |
37 | and | |
38 | .I tms_cstime | |
39 | values in a | |
40 | .I "struct tms" | |
41 | as returned by | |
42 | .BR times (2)). | |
2a86152e | 43 | .PP |
a113945f | 44 | Note: some shells (e.g., |
e194cb7c MK |
45 | .BR bash (1)) |
46 | have a built-in | |
47 | .B time | |
bd286578 MK |
48 | command that provides similar information on the usage of time and |
49 | possibly other resources. | |
e194cb7c MK |
50 | To access the real command, you may need to specify its pathname |
51 | (something like | |
52 | .IR /usr/bin/time ). | |
e8d07c73 | 53 | .SH OPTIONS |
fea681da MK |
54 | .TP |
55 | .B \-p | |
56 | When in the POSIX locale, use the precise traditional format | |
088a639b MK |
57 | .IP |
58 | .in +4n | |
7680a98c | 59 | .EX |
31a6818e | 60 | "real %f\enuser %f\ensys %f\en" |
7680a98c | 61 | .EE |
088a639b MK |
62 | .in |
63 | .IP | |
fea681da MK |
64 | (with numbers in seconds) |
65 | where the number of decimals in the output for %f is unspecified | |
66 | but is sufficient to express the clock tick accuracy, and at least one. | |
47297adb | 67 | .SH EXIT STATUS |
fea681da MK |
68 | If |
69 | .I command | |
70 | was invoked, the exit status is that of | |
71 | .IR command . | |
2b9b829d | 72 | Otherwise, it is 127 if |
fea681da MK |
73 | .I command |
74 | could not be found, 126 if it could be found but could not be invoked, | |
d2fdb1e3 | 75 | and some other nonzero value (1\(en125) if something else went wrong. |
f5b03186 | 76 | .SH ENVIRONMENT |
682edefb MK |
77 | The variables |
78 | .BR LANG , | |
66ee0c7e | 79 | .BR LC_ALL , |
682edefb MK |
80 | .BR LC_CTYPE , |
81 | .BR LC_MESSAGES , | |
82 | .BR LC_NUMERIC , | |
682edefb | 83 | and |
a28b73cd | 84 | .B NLSPATH |
f0e173d6 | 85 | are used for the text and formatting of the output. |
682edefb | 86 | .B PATH |
f0e173d6 | 87 | is used to search for |
f5b03186 | 88 | .IR command . |
47297adb | 89 | .SH GNU VERSION |
fea681da MK |
90 | Below a description of the GNU 1.7 version of |
91 | .BR time . | |
92 | Disregarding the name of the utility, GNU makes it output lots of | |
93 | useful information, not only about time used, but also on other | |
94 | resources like memory, I/O and IPC calls (where available). | |
95 | The output is formatted using a format string that can be specified | |
80d26cef MK |
96 | using the |
97 | .I \-f | |
98 | option or the | |
0daa9e92 | 99 | .B TIME |
682edefb | 100 | environment variable. |
dd3568a1 | 101 | .PP |
088a639b MK |
102 | The default format string is: |
103 | .PP | |
104 | .in +4n | |
7680a98c | 105 | .EX |
fea681da | 106 | %Uuser %Ssystem %Eelapsed %PCPU (%Xtext+%Ddata %Mmax)k |
fea681da | 107 | %Iinputs+%Ooutputs (%Fmajor+%Rminor)pagefaults %Wswaps |
7680a98c | 108 | .EE |
088a639b | 109 | .in |
dd3568a1 | 110 | .PP |
80d26cef MK |
111 | When the |
112 | .I \-p | |
c4dc3de6 | 113 | option is given, the (portable) output format is used: |
088a639b MK |
114 | .PP |
115 | .in +4n | |
7680a98c | 116 | .EX |
fea681da | 117 | real %e |
fea681da | 118 | user %U |
fea681da | 119 | sys %S |
7680a98c | 120 | .EE |
088a639b | 121 | .in |
c4dc3de6 | 122 | .\" |
73d8cece | 123 | .SS The format string |
fea681da | 124 | The format is interpreted in the usual printf-like way. |
3d81c05a MK |
125 | Ordinary characters are directly copied, tab, newline, |
126 | and backslash are escaped using \et, \en, and \e\e, | |
fea681da | 127 | a percent sign is represented by %%, and otherwise % |
ca7b3c18 MK |
128 | indicates a conversion. |
129 | The program | |
fea681da MK |
130 | .B time |
131 | will always add a trailing newline itself. | |
ca7b3c18 MK |
132 | The conversions follow. |
133 | All of those used by | |
fea681da MK |
134 | .BR tcsh (1) |
135 | are supported. | |
dd3568a1 | 136 | .PP |
fea681da MK |
137 | .B "Time" |
138 | .TP | |
139 | .B %E | |
140 | Elapsed real time (in [hours:]minutes:seconds). | |
141 | .TP | |
142 | .B %e | |
481daa31 MK |
143 | (Not in |
144 | .BR tcsh (1).) | |
145 | Elapsed real time (in seconds). | |
fea681da MK |
146 | .TP |
147 | .B %S | |
148 | Total number of CPU-seconds that the process spent in kernel mode. | |
149 | .TP | |
150 | .B %U | |
151 | Total number of CPU-seconds that the process spent in user mode. | |
152 | .TP | |
153 | .B %P | |
154 | Percentage of the CPU that this job got, computed as (%U + %S) / %E. | |
dd3568a1 | 155 | .PP |
fea681da MK |
156 | .B "Memory" |
157 | .TP | |
158 | .B %M | |
159 | Maximum resident set size of the process during its lifetime, in Kbytes. | |
160 | .TP | |
161 | .B %t | |
481daa31 MK |
162 | (Not in |
163 | .BR tcsh (1).) | |
164 | Average resident set size of the process, in Kbytes. | |
fea681da MK |
165 | .TP |
166 | .B %K | |
167 | Average total (data+stack+text) memory use of the process, | |
168 | in Kbytes. | |
169 | .TP | |
170 | .B %D | |
171 | Average size of the process's unshared data area, in Kbytes. | |
172 | .TP | |
173 | .B %p | |
481daa31 MK |
174 | (Not in |
175 | .BR tcsh (1).) | |
176 | Average size of the process's unshared stack space, in Kbytes. | |
fea681da MK |
177 | .TP |
178 | .B %X | |
179 | Average size of the process's shared text space, in Kbytes. | |
180 | .TP | |
181 | .B %Z | |
481daa31 MK |
182 | (Not in |
183 | .BR tcsh (1).) | |
184 | System's page size, in bytes. | |
fea681da MK |
185 | This is a per-system constant, but varies between systems. |
186 | .TP | |
187 | .B %F | |
188 | Number of major page faults that occurred while the process was running. | |
189 | These are faults where the page has to be read in from disk. | |
190 | .TP | |
191 | .B %R | |
192 | Number of minor, or recoverable, page faults. | |
193 | These are faults for pages that are not valid but which have | |
20523df7 MK |
194 | not yet been claimed by other virtual pages. |
195 | Thus the data | |
fea681da MK |
196 | in the page is still valid but the system tables must be updated. |
197 | .TP | |
198 | .B %W | |
199 | Number of times the process was swapped out of main memory. | |
200 | .TP | |
201 | .B %c | |
202 | Number of times the process was context-switched involuntarily | |
203 | (because the time slice expired). | |
204 | .TP | |
205 | .B %w | |
206 | Number of waits: times that the program was context-switched voluntarily, | |
207 | for instance while waiting for an I/O operation to complete. | |
dd3568a1 | 208 | .PP |
fea681da MK |
209 | .B "I/O" |
210 | .TP | |
211 | .B %I | |
9ee4a2b6 | 212 | Number of filesystem inputs by the process. |
fea681da MK |
213 | .TP |
214 | .B %O | |
9ee4a2b6 | 215 | Number of filesystem outputs by the process. |
fea681da MK |
216 | .TP |
217 | .B %r | |
218 | Number of socket messages received by the process. | |
219 | .TP | |
220 | .B %s | |
221 | Number of socket messages sent by the process. | |
222 | .TP | |
223 | .B %k | |
224 | Number of signals delivered to the process. | |
225 | .TP | |
226 | .B %C | |
481daa31 MK |
227 | (Not in |
228 | .BR tcsh (1).) | |
229 | Name and command-line arguments of the command being timed. | |
fea681da MK |
230 | .TP |
231 | .B %x | |
481daa31 MK |
232 | (Not in |
233 | .BR tcsh (1).) | |
234 | Exit status of the command. | |
73d8cece | 235 | .SS GNU options |
fea681da | 236 | .TP |
2bec57c6 | 237 | .BI "\-f " format ", \-\-format=" format |
fea681da MK |
238 | Specify output format, possibly overriding the format specified |
239 | in the environment variable TIME. | |
240 | .TP | |
241 | .B "\-p, \-\-portability" | |
242 | Use the portable output format. | |
243 | .TP | |
2bec57c6 | 244 | .BI "\-o " file ", \-\-output=" file |
c6fa0841 MK |
245 | Do not send the results to |
246 | .IR stderr , | |
247 | but overwrite the specified file. | |
fea681da MK |
248 | .TP |
249 | .B "\-a, \-\-append" | |
250 | (Used together with \-o.) Do not overwrite but append. | |
251 | .TP | |
252 | .B "\-v, \-\-verbose" | |
253 | Give very verbose output about all the program knows about. | |
b221633b MK |
254 | .TP |
255 | .B "\-q, \-\-quiet" | |
256 | Don't report abnormal program termination (where | |
257 | .I command | |
258 | is terminated by a signal) or nonzero exit status. | |
259 | .\" | |
73d8cece | 260 | .SS GNU standard options |
fea681da MK |
261 | .TP |
262 | .B "\-\-help" | |
263 | Print a usage message on standard output and exit successfully. | |
264 | .TP | |
265 | .B "\-V, \-\-version" | |
266 | Print version information on standard output, then exit successfully. | |
267 | .TP | |
268 | .B "\-\-" | |
269 | Terminate option list. | |
270 | .SH BUGS | |
008f1ecc | 271 | Not all resources are measured by all versions of UNIX, |
fea681da MK |
272 | so some of the values might be reported as zero. |
273 | The present selection was mostly inspired by the data | |
274 | provided by 4.2 or 4.3BSD. | |
dd3568a1 | 275 | .PP |
fea681da MK |
276 | GNU time version 1.7 is not yet localized. |
277 | Thus, it does not implement the POSIX requirements. | |
dd3568a1 | 278 | .PP |
682edefb | 279 | The environment variable |
0daa9e92 | 280 | .B TIME |
682edefb MK |
281 | was badly chosen. |
282 | It is not unusual for systems like | |
283 | .BR autoconf (1) | |
284 | or | |
285 | .BR make (1) | |
fea681da | 286 | to use environment variables with the name of a utility to override |
ca7b3c18 MK |
287 | the utility to be used. |
288 | Uses like MORE or TIME for options to programs | |
2d7195b8 | 289 | (instead of program pathnames) tend to lead to difficulties. |
dd3568a1 | 290 | .PP |
80d26cef MK |
291 | It seems unfortunate that |
292 | .I \-o | |
293 | overwrites instead of appends. | |
294 | (That is, the | |
295 | .I \-a | |
296 | option should be the default.) | |
dd3568a1 | 297 | .PP |
fea681da MK |
298 | Mail suggestions and bug reports for GNU |
299 | .B time | |
300 | to | |
dff4ddae | 301 | .IR bug\-time@gnu.org . |
fea681da | 302 | Please include the version of |
14ee3bff | 303 | .BR time , |
fea681da | 304 | which you can get by running |
fff098ed MK |
305 | .PP |
306 | .in +4n | |
307 | .EX | |
308 | time \-\-version | |
309 | .EE | |
310 | .in | |
311 | .PP | |
fea681da MK |
312 | and the operating system |
313 | and C compiler you used. | |
b24f0008 MK |
314 | .\" .SH AUTHORS |
315 | .\" .TP | |
316 | .\" .IP "David Keppel" | |
317 | .\" Original version | |
318 | .\" .IP "David MacKenzie" | |
319 | .\" POSIXization, autoconfiscation, GNU getoptization, | |
320 | .\" documentation, other bug fixes and improvements. | |
321 | .\" .IP "Arne Henrik Juul" | |
322 | .\" Helped with portability | |
323 | .\" .IP "Francois Pinard" | |
324 | .\" Helped with portability | |
47297adb | 325 | .SH SEE ALSO |
5fbf4125 | 326 | .BR bash (1), |
fea681da MK |
327 | .BR tcsh (1), |
328 | .BR times (2), | |
329 | .BR wait3 (2) |