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