Penguin
Recent Changes
Annotated edit history of time(1) version 3, including all changes. View license author blame.
Rev Author # Line
1 perry 1 TIME
2 !!!TIME
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 OPTIONS
7 FORMATTING THE OUTPUT
8 EXAMPLES
9 ACCURACY
10 AUTHOR
11 SEE ALSO
12 ----
13 !!NAME
14
15
16 time - run programs and summarize system resource usage
17 !!SYNOPSIS
18
19
20 __time__
21
22
23 [[ __-apqvV__ ] [[ __-f__ ''FORMAT'' ] [[ __-o__
24 ''FILE'' ]
25 [[ __--append__ ] [[ __--verbose__ ] [[ __--quiet__ ]
26 [[ __--portability__ ]
27 [[ __--format=__''FORMAT'' ] [[
28 __--output=__''FILE'' ] [[ __--version__ ]
29 [[ __--help__ ] ''COMMAND'' [[ ''ARGS''
30 ]
31 !!DESCRIPTION
32
33
34 __time__ run the program ''COMMAND'' with any given
35 arguments ''ARG...''. When ''COMMAND'' finishes,
36 __time__ displays information about resources used by
37 ''COMMAND'' (on the standard error output, by default).
38 If ''COMMAND'' exits with non-zero sta- tus, __time__
39 displays a warning message and the exit status.
40
41
42 __time__ determines which information to display about
43 the re- sources used by the ''COMMAND'' from the string
44 ''FORMAT''. If no format is specified on the command
45 line, but the __TIME__ en- vironment variable is set, its
46 value is used as the for- mat. Otherwise, a default format
47 built into __time__ is used.
48
49
50 Options to __time__ must appear on the command line
51 before ''COMMAND''. Anything on the command line after
52 ''COMMAND'' is passed as arguments to
53 ''COMMAND''.
54 !!OPTIONS
55
56
57 __-o__ ''FILE,''
58 __--output=__''FILE''
59
60
61 Write the resource use statistics to ''FILE'' instead of
62 to the standard error stream. By default, this overwrites
63 the file, destroying the file's previous contents. This
64 option is useful for collecting in- formation on interactive
65 programs and programs that produce output on the standard
66 error stream.
67
68
69 __-a__, __--append__
70
71
72 Append the resource use information to the output file
73 instead of overwriting it. This option is only useful with
74 the `-o' or `--output' option.
75
76
77 __-f__ ''FORMAT,'' __--format__
78 ''FORMAT''
79
80
81 Use ''FORMAT'' as the format string that controls the
82 output of __time__. See the below more
83 information.
84
85
86 __--help__
87
88
89 Print a summary of the command line options and ex-
90 it.
91
92
93 __-p__, __--portability__
94
95
96 Use the following format string, for conformance with POSIX
97 standard 1003.2: real %e user %U sys %S
98
99
100 __-v__, __--verbose__
101
102
103 Use the built-in verbose format, which displays each
104 available piece of information on the pro- gram's resource
105 use on its own line, with an En- glish description of its
106 meaning.
107
108
109 __--quiet__
110
111
112 Do not report the status of the program even if it is
113 different from zero.
114
115
116 __-V__, __--version__
117
118
119 Print the version number of __time__ and
120 exit.
121 !!FORMATTING THE OUTPUT
122
123
124 The format string ''FORMAT'' controls the contents of the
125 __time__ output. The format string can be set using the
126 `-f' or `--format', `-v' or `--verbose', or `-p' or
127 `--portabili- ty' options. If they are not given, but the
128 ''TIME'' environ- ment variable is set, its value is used
129 as the format string. Otherwise, a built-in default format
130 is used. The default format is: %Uuser %Ssystem %Eelapsed
131 %PCPU (%Xtext+%Ddata %Mmax)k %Iinputs+%Ooutputs
132 (%Fmajor+%Rminor)pagefaults %Wswaps
133
134
135 The format string usually consists of `resource speci-
136 fiers' interspersed with plain text. A percent sign (`%') in
137 the format string causes the following character to be
138 interpreted as a resource specifier, which is similar to the
139 formatting characters in the printf(3)
140 function.
141
142
143 A backslash (`') introduces a `backslash escape', which is
144 translated into a single printing character upon out- put.
145 `t' outputs a tab character, `n' outputs a new- line, and
146 `\' outputs a backslash. A backslash followed by any other
147 character outputs a question mark (`?') fol- lowed by a
148 backslash, to indicate that an invalid back- slash escape
149 was given.
150
151
152 Other text in the format string is copied verbatim to the
153 output. __time__ always prints a newline after printing
154 the resource use information, so normally format strings do
155 not end with a newline character (or `0).
156
157
158 There are many resource specifications. Not all resources
159 are measured by all versions of Unix, so some of the val-
160 ues might be reported as zero. Any character following a
161 percent sign that is not listed in the table below causes a
162 question mark (`?') to be output, followed by that char-
163 acter, to indicate that an invalid resource listed in the
164 table below causes a question mark (`?') to be output,
165 followed by that character, to indicate that an invalid
166 resource specifier was given.
167
168
169 The resource specifiers, which are a superset of those
170 recognized by the tcsh(1) builtin `time' command,
171 are:
172
173
174 %
175
176
177 A literal `%'.
178
179
180 C
181
182
183 Name and command line arguments of the com- mand being
184 timed.
185
186
187 D
188
189
190 Average size of the process's unshared data area, in
191 Kilobytes.
192
193
194 E
195
196
197 Elapsed real (wall clock) time used by the process, in
198 [[hours:]minutes:seconds.
199
200
201 F
202
203
204 Number of major, or I/O-requiring, page faults that occurred
205 while the process was running. These are faults where the
206 page has actually migrated out of primary
207 memory.
208
209
210 I
211
212
213 Number of file system inputs by the process.
214
215
216 K
217
218
219 Average total (data+stack+text) memory use of the process,
220 in Kilobytes.
221
222
223 M
224
225
226 Maximum resident set size of the process during its
227 lifetime, in Kilobytes.
228
229
230 O
231
232
233 Number of file system outputs by the pro- cess.
234
235
236 P
237
238
239 Percentage of the CPU that this job got. This is just user +
240 system times divied by the total running time.
241
242
243 R
244
245
246 Number of minor, or recoverable, page faults. These are
247 pages that are not valid (so they fault) but which have not
248 yet been claimed by other virtual pages. Thus the data in
249 the page is still valid but the sys- tem tables must be
250 updated.
251
252
253 S
254
255
256 Total number of CPU-seconds used by the sys- tem on behalf
257 of the process (in kernel mode), in seconds.
258
259
260 U
261
262
263 Total number of CPU-seconds that the process used directly
264 (in user mode), in seconds.
265
266
267 W
268
269
270 Number of times the process was swapped out of main
271 memory.
272
273
274 X
275
276
277 Average amount of shared text in the pro- cess, in
278 Kilobytes.
279
280
281 Z
282
283
284 System's page size, in bytes. This is a per-system constant,
285 but varies between sys- tems.
286
287
288 c
289
290
291 Number of times the process was con- text-switched
292 involuntarily (because the time slice expired).
293
294
295 e
296
297
298 Elapsed real (wall clock) time used by the process, in
299 seconds.
300
301
302 k
303
304
305 Number of signals delivered to the process.
306
307
308 p
309
310
311 Average unshared stack size of the process, in
312 Kilobytes.
313
314
315 r
316
317
318 Number of socket messages received by the
319 process.
320
321
322 s
323
324
325 Number of socket messages sent by the pro-
326 cess.
327
328
329 t
330
331
332 Average resident set size of the process, in
333 Kilobytes.
334
335
336 w
337
338
339 Number of times that the program was con- text-switched
340 voluntarily, for instance while waiting for an I/O operation
341 to com- plete.
342
343
344 x
345
346
347 Exit status of the command.
348 !!EXAMPLES
349
350
351 To run the command `wc /etc/hosts' and show the default
352 information: time wc /etc/hosts
353
354
355 To run the command `ls -Fs' and show just the user, sys-
356 tem, and total time: time -f
357
358
359 To edit the file BORK and have `time' append the elapsed
360 time and number of signals to the file `log', reading the
361 format string from the environment variable `TIME': export
362 TIME=
363 !!ACCURACY
364
365
366 The elapsed time is not collected atomically with the exe-
367 cution of the program; as a result, in bizarre circum-
368 stances (if the __time__ command gets stopped or swapped
369 out in between when the program being timed exits and when
370 __time__ calculates how long it took to run), it could be
371 much larger than the actual execution time.
372
373
374 When the running time of a command is very nearly zero, some
375 values (e.g., the percentage of CPU used) may be re- ported
376 as either zero (which is wrong) or a question
377 mark.
378
379
380 Most information shown by __time__ is derived from the
3 perry 381 wait3(2) system call. The numbers are only as good as
382 those returned by wait3(2). On systems that do not
383 have a wait3(2) call that returns status information,
1 perry 384 the times(2) system call is used instead. However, it
3 perry 385 pro- vides much less information than wait3(2), so on
1 perry 386 those systems __time__ reports the majority of the
387 resources as ze- ro.
388
389
390 The `%I' and `%O' values are allegedly only `real' input and
391 output and do not include those supplied by caching devices.
392 The meaning of `real' I/O reported by `%I' and `%O' may be
393 muddled for workstations, especially diskless
394 ones.
395 !!AUTHOR
396
397
2 perry 398 __time__ was written by David !MacKenzie. This man page
1 perry 399 was added by Dirk Eddelbuettel
400 __
401 !!SEE ALSO
402
403
404 tcsh(1), printf(3)
405 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.