]>
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 | .\" |
4b8c67d9 | 9 | .TH TIME 1 2017-09-15 "" "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)). | |
2a86152e | 44 | .PP |
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 | |
7680a98c | 60 | .EX |
31a6818e | 61 | "real %f\enuser %f\ensys %f\en" |
7680a98c | 62 | .EE |
088a639b MK |
63 | .in |
64 | .IP | |
fea681da MK |
65 | (with numbers in seconds) |
66 | where the number of decimals in the output for %f is unspecified | |
67 | but is sufficient to express the clock tick accuracy, and at least one. | |
47297adb | 68 | .SH EXIT STATUS |
fea681da MK |
69 | If |
70 | .I command | |
71 | was invoked, the exit status is that of | |
72 | .IR command . | |
2b9b829d | 73 | Otherwise, it is 127 if |
fea681da MK |
74 | .I command |
75 | could not be found, 126 if it could be found but could not be invoked, | |
d2fdb1e3 | 76 | and some other nonzero value (1\(en125) if something else went wrong. |
f5b03186 | 77 | .SH ENVIRONMENT |
682edefb MK |
78 | The variables |
79 | .BR LANG , | |
66ee0c7e | 80 | .BR LC_ALL , |
682edefb MK |
81 | .BR LC_CTYPE , |
82 | .BR LC_MESSAGES , | |
83 | .BR LC_NUMERIC , | |
682edefb | 84 | and |
a28b73cd | 85 | .B NLSPATH |
f0e173d6 | 86 | are used for the text and formatting of the output. |
682edefb | 87 | .B PATH |
f0e173d6 | 88 | is used to search for |
f5b03186 MK |
89 | .IR command . |
90 | The remaining ones for the text and formatting of the output. | |
47297adb | 91 | .SH GNU VERSION |
fea681da MK |
92 | Below a description of the GNU 1.7 version of |
93 | .BR time . | |
94 | Disregarding the name of the utility, GNU makes it output lots of | |
95 | useful information, not only about time used, but also on other | |
96 | resources like memory, I/O and IPC calls (where available). | |
97 | The output is formatted using a format string that can be specified | |
80d26cef MK |
98 | using the |
99 | .I \-f | |
100 | option or the | |
0daa9e92 | 101 | .B TIME |
682edefb | 102 | environment variable. |
dd3568a1 | 103 | .PP |
088a639b MK |
104 | The default format string is: |
105 | .PP | |
106 | .in +4n | |
7680a98c | 107 | .EX |
fea681da | 108 | %Uuser %Ssystem %Eelapsed %PCPU (%Xtext+%Ddata %Mmax)k |
fea681da | 109 | %Iinputs+%Ooutputs (%Fmajor+%Rminor)pagefaults %Wswaps |
7680a98c | 110 | .EE |
088a639b | 111 | .in |
dd3568a1 | 112 | .PP |
80d26cef MK |
113 | When the |
114 | .I \-p | |
c4dc3de6 | 115 | option is given, the (portable) output format is used: |
088a639b MK |
116 | .PP |
117 | .in +4n | |
7680a98c | 118 | .EX |
fea681da | 119 | real %e |
fea681da | 120 | user %U |
fea681da | 121 | sys %S |
7680a98c | 122 | .EE |
088a639b | 123 | .in |
c4dc3de6 | 124 | .\" |
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. | |
dd3568a1 | 138 | .PP |
fea681da MK |
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. | |
dd3568a1 | 157 | .PP |
fea681da MK |
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. | |
dd3568a1 | 210 | .PP |
fea681da MK |
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. | |
b221633b MK |
256 | .TP |
257 | .B "\-q, \-\-quiet" | |
258 | Don't report abnormal program termination (where | |
259 | .I command | |
260 | is terminated by a signal) or nonzero exit status. | |
261 | .\" | |
73d8cece | 262 | .SS GNU standard options |
fea681da MK |
263 | .TP |
264 | .B "\-\-help" | |
265 | Print a usage message on standard output and exit successfully. | |
266 | .TP | |
267 | .B "\-V, \-\-version" | |
268 | Print version information on standard output, then exit successfully. | |
269 | .TP | |
270 | .B "\-\-" | |
271 | Terminate option list. | |
272 | .SH BUGS | |
008f1ecc | 273 | Not all resources are measured by all versions of UNIX, |
fea681da MK |
274 | so some of the values might be reported as zero. |
275 | The present selection was mostly inspired by the data | |
276 | provided by 4.2 or 4.3BSD. | |
dd3568a1 | 277 | .PP |
fea681da MK |
278 | GNU time version 1.7 is not yet localized. |
279 | Thus, it does not implement the POSIX requirements. | |
dd3568a1 | 280 | .PP |
682edefb | 281 | The environment variable |
0daa9e92 | 282 | .B TIME |
682edefb MK |
283 | was badly chosen. |
284 | It is not unusual for systems like | |
285 | .BR autoconf (1) | |
286 | or | |
287 | .BR make (1) | |
fea681da | 288 | to use environment variables with the name of a utility to override |
ca7b3c18 MK |
289 | the utility to be used. |
290 | Uses like MORE or TIME for options to programs | |
2d7195b8 | 291 | (instead of program pathnames) tend to lead to difficulties. |
dd3568a1 | 292 | .PP |
80d26cef MK |
293 | It seems unfortunate that |
294 | .I \-o | |
295 | overwrites instead of appends. | |
296 | (That is, the | |
297 | .I \-a | |
298 | option should be the default.) | |
dd3568a1 | 299 | .PP |
fea681da MK |
300 | Mail suggestions and bug reports for GNU |
301 | .B time | |
302 | to | |
dff4ddae | 303 | .IR bug\-time@gnu.org . |
fea681da | 304 | Please include the version of |
14ee3bff | 305 | .BR time , |
fea681da | 306 | which you can get by running |
fff098ed MK |
307 | .PP |
308 | .in +4n | |
309 | .EX | |
310 | time \-\-version | |
311 | .EE | |
312 | .in | |
313 | .PP | |
fea681da MK |
314 | and the operating system |
315 | and C compiler you used. | |
b24f0008 MK |
316 | .\" .SH AUTHORS |
317 | .\" .TP | |
318 | .\" .IP "David Keppel" | |
319 | .\" Original version | |
320 | .\" .IP "David MacKenzie" | |
321 | .\" POSIXization, autoconfiscation, GNU getoptization, | |
322 | .\" documentation, other bug fixes and improvements. | |
323 | .\" .IP "Arne Henrik Juul" | |
324 | .\" Helped with portability | |
325 | .\" .IP "Francois Pinard" | |
326 | .\" Helped with portability | |
47297adb | 327 | .SH SEE ALSO |
5fbf4125 | 328 | .BR bash (1), |
fea681da MK |
329 | .BR tcsh (1), |
330 | .BR times (2), | |
331 | .BR wait3 (2) |