Debian Codegraph @

upstream/debian-unstable/man1/time.1

raw
1 .\" Man page added by Dirk Eddelbuettel <[email protected]> on 15 Apr 1996
2 .\" Thanks to Herbert Thielen for a patch
3 .\" Copyright (C) Dirk Eddelbuettel but freely redistributable
4 .TH TIME 1 "Debian GNU/Linux"
5 .\" Always turn off hyphenation; it makes way too many mistakes in
6 .\" technical documents.
7 .nh
8 .SH NAME
9 time \- run programs and summarize system resource usage
10 .SH SYNOPSIS
11 .na
12 .TP
13 .B time
14 [
15 .B \-apqvV
16 ] [
17 .BI \-f " FORMAT"
18 ] [
19 .BI \-o " FILE"
20 ]
21 .br
22 [
23 .B \-\-append
24 ] [
25 .B \-\-verbose
26 ] [
27 .B \-\-quiet
28 ] [
29 .B \-\-portability
30 ]
31 .br
32 [
33 .BI \-\-format= "FORMAT"
34 ] [
35 .BI \-\-output= "FILE"
36 ] [
37 .B \-\-version
38 ]
39 .br
40 [
41 .B \-\-help
42 ]
43 .I COMMAND
44 [
45 .I ARGS
46 ]
47 .ad b
48 .\" For nroff, turn off justification.
49 .if n .ad l
50 .SH DESCRIPTION
51 .B time
52 run the program
53 .I COMMAND
54 with any given arguments
55 .IR "ARG..." .
56 When
57 .I COMMAND
58 finishes,
59 .B time
60 displays information about resources used by
61 .I COMMAND
62 (on the standard error output, by default). If
63 .I COMMAND
64 exits with non\-zero status,
65 .B time
66 displays a warning message and the exit status.
67
68 .B time
69 determines which information to display about the resources used by the
70 .I COMMAND
71 from the string
72 .IR FORMAT .
73 If no format is specified on the command line, but the
74 .B TIME
75 environment variable is set, its value is used as the format.
76 Otherwise, a default format built into
77 .B time
78 is used.
79
80 Options to
81 .B time
82 must appear on the command line before
83 .IR COMMAND .
84 Anything on the command line after
85 .I COMMAND
86 is passed as arguments to
87 .IR COMMAND .
88
89 .SH OPTIONS
90 .TP
91 .BI \-o " FILE, " \-\-output= "FILE "
92 Write the resource use statistics to
93 .I FILE
94 instead of to the standard error stream. By default, this overwrites the
95 file, destroying the file's previous contents. This option is useful for
96 collecting information on interactive programs and programs that produce
97 output on the standard error stream.
98 .TP
99 .BR \-a ", " \-\-append ""
100 Append the resource use information to the output file instead of overwriting
101 it. This option is only useful with the `\-o' or `\-\-output' option.
102 .TP
103 .BI \-f " FORMAT, " \-\-format " FORMAT "
104 Use
105 .I FORMAT
106 as the format string that controls the output of
107 .BR time .
108 See the below more information.
109 .TP
110 .B \-\-help
111 Print a summary of the command line options and exit.
112 .TP
113 .BR \-p ", " \-\-portability ""
114 Use the following format string, for conformance with POSIX standard 1003.2:
115 real %e
116 user %U
117 sys %S
118 .TP
119 .BR \-v ", " \-\-verbose ""
120 Use the built\-in verbose format, which displays each available piece of
121 information on the program's resource use on its own line, with an English
122 description of its meaning.
123 .TP
124 .B \-\-quiet
125 Do not report the status of the program even if it is different from zero.
126 .TP
127 .BR \-V ", " \-\-version ""
128 Print the version number of
129 .B time
130 and exit.
131
132 .SH "FORMATTING THE OUTPUT"
133 The format string
134 .I FORMAT
135 controls the contents of the
136 .B time
137 output. The format string can be set using the `\-f' or `\-\-format', `\-v' or
138 `\-\-verbose', or `\-p' or `\-\-portability' options. If they are not
139 given, but the
140 .I TIME
141 environment variable is set, its value is used as the format string.
142 Otherwise, a built\-in default format is used. The default format is:
143 %Uuser %Ssystem %Eelapsed %PCPU (%Xtext+%Ddata %Mmax)k
144 %Iinputs+%Ooutputs (%Fmajor+%Rminor)pagefaults %Wswaps
145
146 The format string usually consists of `resource specifiers'
147 interspersed with plain text. A percent sign (`%') in the format
148 string causes the following character to be interpreted as a resource
149 specifier, which is similar to the formatting characters in the
150 .BR printf (3)
151 function.
152
153 A backslash (`\\') introduces a `backslash escape', which is
154 translated into a single printing character upon output. `\\t' outputs
155 a tab character, `\\n' outputs a newline, and `\\\\' outputs a backslash.
156 A backslash followed by any other character outputs a question mark
157 (`?') followed by a backslash, to indicate that an invalid backslash
158 escape was given.
159
160 Other text in the format string is copied verbatim to the output.
161 .B time
162 always prints a newline after printing the resource use
163 information, so normally format strings do not end with a newline
164 character (or `\en').
165
166 There are many resource specifications. Not all resources are
167 measured by all versions of Unix, so some of the values might be
168 reported as zero. Any character following a percent sign that is not
169 listed in the table below causes a question mark (`?') to be output,
170 followed by that character, to indicate that an invalid resource
171 specifier was given.
172
173 .\" No blank line between the resource specifiers below so that they
174 .\" are more compactly listed.
175 .PD 0
176 The resource specifiers, which are a superset of those recognized by the
177 .BR tcsh (1)
178 builtin `time' command, are:
179 .RS
180 .IP %
181 A literal `%'.
182 .IP C
183 Name and command line arguments of the command being timed.
184 .IP D
185 Average size of the process's unshared data area, in Kilobytes.
186 .IP E
187 Elapsed real (wall clock) time used by the process, in [hours:]minutes:seconds.
188 .IP F
189 Number of major, or I/O\-requiring, page faults that occurred while
190 the process was running. These are faults where the page has
191 actually migrated out of primary memory.
192 .IP I
193 Number of file system inputs by the process.
194 .IP K
195 Average total (data+stack+text) memory use of the process, in
196 Kilobytes.
197 .IP M
198 Maximum resident set size of the process during its lifetime, in
199 Kilobytes.
200 .IP O
201 Number of file system outputs by the process.
202 .IP P
203 Percentage of the CPU that this job got. This is just user +
204 system times divided by the total running time. It also prints
205 a percentage sign.
206 .IP R
207 Number of minor, or recoverable, page faults. These are pages
208 that are not valid (so they fault) but which have not yet been
209 claimed by other virtual pages. Thus the data in the page is
210 still valid but the system tables must be updated.
211 .IP S
212 Total number of CPU\-seconds used by the system on behalf of the
213 process (in kernel mode), in seconds.
214 .IP U
215 Total number of CPU\-seconds that the process used directly (in user
216 mode), in seconds.
217 .IP W
218 Number of times the process was swapped out of main memory.
219 .IP X
220 Average amount of shared text in the process, in Kilobytes.
221 .IP Z
222 System's page size, in bytes. This is a per\-system constant, but
223 varies between systems.
224 .IP c
225 Number of times the process was context\-switched involuntarily
226 (because the time slice expired).
227 .IP e
228 Elapsed real (wall clock) time used by the process, in seconds.
229 .IP k
230 Number of signals delivered to the process.
231 .IP p
232 Average unshared stack size of the process, in Kilobytes.
233 .IP r
234 Number of socket messages received by the process.
235 .IP s
236 Number of socket messages sent by the process.
237 .IP t
238 Average resident set size of the process, in Kilobytes.
239 .IP w
240 Number of times that the program was context\-switched voluntarily,
241 for instance while waiting for an I/O operation to complete.
242 .IP x
243 Exit status of the command.
244 .RS
245
246 .SH EXAMPLES
247 To run the command `wc /etc/hosts' and show the default information:
248 time wc /etc/hosts
249
250 To run the command `ls \-Fs' and show just the user, system, and total
251 time:
252 time \-f "\et%E real,\et%U user,\et%S sys" ls \-Fs
253
254 To edit the file BORK and have `time' append the elapsed time and
255 number of signals to the file `log', reading the format string from the
256 environment variable `TIME':
257 export TIME="\et%E,\et%k" # If using bash or ksh
258 setenv TIME "\et%E,\et%k" # If using csh or tcsh
259 time \-a \-o log emacs bork
260
261 Users of the
262 .B bash
263 shell need to use an explicit path in order to run the external
264 .B time
265 command and not the shell builtin variant. On system where
266 .B time
267 is installed in
268 .IR /usr/bin ,
269 the first example would become
270 /usr/bin/time wc /etc/hosts
271
272 .SH ACCURACY
273 The elapsed time is not collected atomically with the execution of
274 the program; as a result, in bizarre circumstances (if the
275 .B time
276 command gets stopped or swapped out in between when the program being
277 timed exits and when
278 .B time
279 calculates how long it took to run), it
280 could be much larger than the actual execution time.
281
282 When the running time of a command is very nearly zero, some values
283 (e.g., the percentage of CPU used) may be reported as either zero (which
284 is wrong) or a question mark.
285
286 Most information shown by
287 .B time
288 is derived from the
289 .BR wait3 (2)
290 system call. The numbers are only as good as
291 those returned by
292 .BR wait3 (2).
293 On systems that do not have a
294 .BR wait3 (2)
295 call that returns status information, the
296 .BR times (2)
297 system call is used instead. However, it provides much less information than
298 .BR wait3 (2),
299 so on those systems
300 .B time
301 reports the majority of the resources as zero.
302
303 The `%I' and `%O' values are allegedly only `real' input and output
304 and do not include those supplied by caching devices. The meaning of
305 `real' I/O reported by `%I' and `%O' may be muddled for workstations,
306 especially diskless ones.
307
308 .SH DIAGNOSTICS
309 The
310 .B time
311 command returns when the program exits, stops, or is terminated by a signal.
312 If the program exited normally, the return value of
313 .B time
314 is the return value of the program it executed and measured. Otherwise, the
315 return value is 128 plus the number of the signal which caused the program to
316 stop or terminate.
317 .SH AUTHOR
318 .B time
319 was written by David MacKenzie. This man page was added by Dirk Eddelbuettel
320 <[email protected]>, the Debian GNU/Linux maintainer, for use by the Debian
321 GNU/Linux distribution but may of course be used by others.
322
323 .SH "SEE ALSO"
324 .BR tcsh (1),
325 .BR printf (3)