1 .\" Copyright Andries Brouwer, 2000
2 .\" Some fragments of text came from the time-1.7 info file.
3 .\" Inspired by kromJx@crosswinds.net.
5 .\" SPDX-License-Identifier: GPL-1.0-or-later
7 .TH TIME 1 2019-03-06 "" "Linux User's Manual"
9 time \- time a simple command or give resource usage
12 .RI [ options ] " command " [ arguments... ]
16 command runs the specified program
18 with the given arguments.
23 writes a message to standard error giving timing statistics
24 about this program run.
25 These statistics consist of (i) the elapsed real time
26 between invocation and termination, (ii) the user CPU time
35 and (iii) the system CPU time (the sum of the
44 Note: some shells (e.g.,
48 command that provides similar information on the usage of time and
49 possibly other resources.
50 To access the real command, you may need to specify its pathname
56 When in the POSIX locale, use the precise traditional format
60 "real %f\enuser %f\ensys %f\en"
64 (with numbers in seconds)
65 where the number of decimals in the output for %f is unspecified
66 but is sufficient to express the clock tick accuracy, and at least one.
70 was invoked, the exit status is that of
72 Otherwise, it is 127 if
74 could not be found, 126 if it could be found but could not be invoked,
75 and some other nonzero value (1\(en125) if something else went wrong.
85 are used for the text and formatting of the output.
90 Below a description of the GNU 1.7 version of
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
100 environment variable.
102 The default format string is:
106 %Uuser %Ssystem %Eelapsed %PCPU (%Xtext+%Ddata %Mmax)k
107 %Iinputs+%Ooutputs (%Fmajor+%Rminor)pagefaults %Wswaps
113 option is given, the (portable) output format is used:
123 .SS The format string
124 The format is interpreted in the usual printf-like way.
125 Ordinary characters are directly copied, tab, newline,
126 and backslash are escaped using \et, \en, and \e\e,
127 a percent sign is represented by %%, and otherwise %
128 indicates a conversion.
131 will always add a trailing newline itself.
132 The conversions follow.
140 Elapsed real time (in [hours:]minutes:seconds).
145 Elapsed real time (in seconds).
148 Total number of CPU-seconds that the process spent in kernel mode.
151 Total number of CPU-seconds that the process spent in user mode.
154 Percentage of the CPU that this job got, computed as (%U + %S) / %E.
159 Maximum resident set size of the process during its lifetime, in Kbytes.
164 Average resident set size of the process, in Kbytes.
167 Average total (data+stack+text) memory use of the process,
171 Average size of the process's unshared data area, in Kbytes.
176 Average size of the process's unshared stack space, in Kbytes.
179 Average size of the process's shared text space, in Kbytes.
184 System's page size, in bytes.
185 This is a per-system constant, but varies between systems.
188 Number of major page faults that occurred while the process was running.
189 These are faults where the page has to be read in from disk.
192 Number of minor, or recoverable, page faults.
193 These are faults for pages that are not valid but which have
194 not yet been claimed by other virtual pages.
196 in the page is still valid but the system tables must be updated.
199 Number of times the process was swapped out of main memory.
202 Number of times the process was context-switched involuntarily
203 (because the time slice expired).
206 Number of waits: times that the program was context-switched voluntarily,
207 for instance while waiting for an I/O operation to complete.
212 Number of filesystem inputs by the process.
215 Number of filesystem outputs by the process.
218 Number of socket messages received by the process.
221 Number of socket messages sent by the process.
224 Number of signals delivered to the process.
229 Name and command-line arguments of the command being timed.
234 Exit status of the command.
237 .BI "\-f " format ", \-\-format=" format
238 Specify output format, possibly overriding the format specified
239 in the environment variable TIME.
241 .B "\-p, \-\-portability"
242 Use the portable output format.
244 .BI "\-o " file ", \-\-output=" file
245 Do not send the results to
247 but overwrite the specified file.
250 (Used together with \-o.) Do not overwrite but append.
252 .B "\-v, \-\-verbose"
253 Give very verbose output about all the program knows about.
256 Don't report abnormal program termination (where
258 is terminated by a signal) or nonzero exit status.
260 .SS GNU standard options
263 Print a usage message on standard output and exit successfully.
265 .B "\-V, \-\-version"
266 Print version information on standard output, then exit successfully.
269 Terminate option list.
271 Not all resources are measured by all versions of UNIX,
272 so some of the values might be reported as zero.
273 The present selection was mostly inspired by the data
274 provided by 4.2 or 4.3BSD.
276 GNU time version 1.7 is not yet localized.
277 Thus, it does not implement the POSIX requirements.
279 The environment variable
282 It is not unusual for systems like
286 to use environment variables with the name of a utility to override
287 the utility to be used.
288 Uses like MORE or TIME for options to programs
289 (instead of program pathnames) tend to lead to difficulties.
291 It seems unfortunate that
293 overwrites instead of appends.
296 option should be the default.)
298 Mail suggestions and bug reports for GNU
301 .IR bug\-time@gnu.org .
302 Please include the version of
304 which you can get by running
312 and the operating system
313 and C compiler you used.
316 .\" .IP "David Keppel"
318 .\" .IP "David MacKenzie"
319 .\" POSIXization, autoconfiscation, GNU getoptization,
320 .\" documentation, other bug fixes and improvements.
321 .\" .IP "Arne Henrik Juul"
322 .\" Helped with portability
323 .\" .IP "Francois Pinard"
324 .\" Helped with portability