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