]>
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 | .\" |
6d322d5f | 9 | .TH TIME 1 2015-02-21 "" "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 . | |
2b9b829d | 70 | Otherwise, it is 127 if |
fea681da MK |
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 | |
481daa31 MK |
144 | (Not in |
145 | .BR tcsh (1).) | |
146 | Elapsed real time (in seconds). | |
fea681da MK |
147 | .TP |
148 | .B %S | |
149 | Total number of CPU-seconds that the process spent in kernel mode. | |
150 | .TP | |
151 | .B %U | |
152 | Total number of CPU-seconds that the process spent in user mode. | |
153 | .TP | |
154 | .B %P | |
155 | Percentage of the CPU that this job got, computed as (%U + %S) / %E. | |
156 | .LP | |
157 | .B "Memory" | |
158 | .TP | |
159 | .B %M | |
160 | Maximum resident set size of the process during its lifetime, in Kbytes. | |
161 | .TP | |
162 | .B %t | |
481daa31 MK |
163 | (Not in |
164 | .BR tcsh (1).) | |
165 | Average resident set size of the process, in Kbytes. | |
fea681da MK |
166 | .TP |
167 | .B %K | |
168 | Average total (data+stack+text) memory use of the process, | |
169 | in Kbytes. | |
170 | .TP | |
171 | .B %D | |
172 | Average size of the process's unshared data area, in Kbytes. | |
173 | .TP | |
174 | .B %p | |
481daa31 MK |
175 | (Not in |
176 | .BR tcsh (1).) | |
177 | Average size of the process's unshared stack space, in Kbytes. | |
fea681da MK |
178 | .TP |
179 | .B %X | |
180 | Average size of the process's shared text space, in Kbytes. | |
181 | .TP | |
182 | .B %Z | |
481daa31 MK |
183 | (Not in |
184 | .BR tcsh (1).) | |
185 | System's page size, in bytes. | |
fea681da MK |
186 | This is a per-system constant, but varies between systems. |
187 | .TP | |
188 | .B %F | |
189 | Number of major page faults that occurred while the process was running. | |
190 | These are faults where the page has to be read in from disk. | |
191 | .TP | |
192 | .B %R | |
193 | Number of minor, or recoverable, page faults. | |
194 | These are faults for pages that are not valid but which have | |
20523df7 MK |
195 | not yet been claimed by other virtual pages. |
196 | Thus the data | |
fea681da MK |
197 | in the page is still valid but the system tables must be updated. |
198 | .TP | |
199 | .B %W | |
200 | Number of times the process was swapped out of main memory. | |
201 | .TP | |
202 | .B %c | |
203 | Number of times the process was context-switched involuntarily | |
204 | (because the time slice expired). | |
205 | .TP | |
206 | .B %w | |
207 | Number of waits: times that the program was context-switched voluntarily, | |
208 | for instance while waiting for an I/O operation to complete. | |
209 | .LP | |
210 | .B "I/O" | |
211 | .TP | |
212 | .B %I | |
9ee4a2b6 | 213 | Number of filesystem inputs by the process. |
fea681da MK |
214 | .TP |
215 | .B %O | |
9ee4a2b6 | 216 | Number of filesystem outputs by the process. |
fea681da MK |
217 | .TP |
218 | .B %r | |
219 | Number of socket messages received by the process. | |
220 | .TP | |
221 | .B %s | |
222 | Number of socket messages sent by the process. | |
223 | .TP | |
224 | .B %k | |
225 | Number of signals delivered to the process. | |
226 | .TP | |
227 | .B %C | |
481daa31 MK |
228 | (Not in |
229 | .BR tcsh (1).) | |
230 | Name and command-line arguments of the command being timed. | |
fea681da MK |
231 | .TP |
232 | .B %x | |
481daa31 MK |
233 | (Not in |
234 | .BR tcsh (1).) | |
235 | Exit status of the command. | |
73d8cece | 236 | .SS GNU options |
fea681da | 237 | .TP |
2bec57c6 | 238 | .BI "\-f " format ", \-\-format=" format |
fea681da MK |
239 | Specify output format, possibly overriding the format specified |
240 | in the environment variable TIME. | |
241 | .TP | |
242 | .B "\-p, \-\-portability" | |
243 | Use the portable output format. | |
244 | .TP | |
2bec57c6 | 245 | .BI "\-o " file ", \-\-output=" file |
c6fa0841 MK |
246 | Do not send the results to |
247 | .IR stderr , | |
248 | but overwrite the specified file. | |
fea681da MK |
249 | .TP |
250 | .B "\-a, \-\-append" | |
251 | (Used together with \-o.) Do not overwrite but append. | |
252 | .TP | |
253 | .B "\-v, \-\-verbose" | |
254 | Give very verbose output about all the program knows about. | |
73d8cece | 255 | .SS GNU standard options |
fea681da MK |
256 | .TP |
257 | .B "\-\-help" | |
258 | Print a usage message on standard output and exit successfully. | |
259 | .TP | |
260 | .B "\-V, \-\-version" | |
261 | Print version information on standard output, then exit successfully. | |
262 | .TP | |
263 | .B "\-\-" | |
264 | Terminate option list. | |
265 | .SH BUGS | |
008f1ecc | 266 | Not all resources are measured by all versions of UNIX, |
fea681da MK |
267 | so some of the values might be reported as zero. |
268 | The present selection was mostly inspired by the data | |
269 | provided by 4.2 or 4.3BSD. | |
270 | .LP | |
271 | GNU time version 1.7 is not yet localized. | |
272 | Thus, it does not implement the POSIX requirements. | |
273 | .LP | |
682edefb | 274 | The environment variable |
0daa9e92 | 275 | .B TIME |
682edefb MK |
276 | was badly chosen. |
277 | It is not unusual for systems like | |
278 | .BR autoconf (1) | |
279 | or | |
280 | .BR make (1) | |
fea681da | 281 | to use environment variables with the name of a utility to override |
ca7b3c18 MK |
282 | the utility to be used. |
283 | Uses like MORE or TIME for options to programs | |
2d7195b8 | 284 | (instead of program pathnames) tend to lead to difficulties. |
fea681da | 285 | .LP |
80d26cef MK |
286 | It seems unfortunate that |
287 | .I \-o | |
288 | overwrites instead of appends. | |
289 | (That is, the | |
290 | .I \-a | |
291 | option should be the default.) | |
fea681da MK |
292 | .LP |
293 | Mail suggestions and bug reports for GNU | |
294 | .B time | |
295 | to | |
296 | .br | |
4d9b6984 | 297 | .I bug\-utils@prep.ai.mit.edu |
fea681da MK |
298 | .br |
299 | Please include the version of | |
14ee3bff | 300 | .BR time , |
fea681da MK |
301 | which you can get by running |
302 | .br | |
4d9b6984 | 303 | .I time \-\-version |
fea681da MK |
304 | .br |
305 | and the operating system | |
306 | and C compiler you used. | |
b24f0008 MK |
307 | .\" .SH AUTHORS |
308 | .\" .TP | |
309 | .\" .IP "David Keppel" | |
310 | .\" Original version | |
311 | .\" .IP "David MacKenzie" | |
312 | .\" POSIXization, autoconfiscation, GNU getoptization, | |
313 | .\" documentation, other bug fixes and improvements. | |
314 | .\" .IP "Arne Henrik Juul" | |
315 | .\" Helped with portability | |
316 | .\" .IP "Francois Pinard" | |
317 | .\" Helped with portability | |
47297adb | 318 | .SH SEE ALSO |
fea681da MK |
319 | .BR tcsh (1), |
320 | .BR times (2), | |
321 | .BR wait3 (2) |