|
|
|
time
Measure Program Resource Use, the `time' command runs another program, then displays information about the resources used by that program, collected by the system while the program was running. You can select which information is reported and the format in which it is shown , or have `time' save the information in a file instead of displaying it on the screen.
SYNTAX
time [option...] COMMAND [ARG...]
OPTIONS
`-o FILE'
`--output=FILE'
Write the resource use statistics to FILE.
`-a'
`--append'
*Append* the resource use information to the output file instead
of overwriting it.
`-f FORMAT'
`--format=FORMAT'
Use FORMAT as the format string.
`--help'
Print a summary of the command line options to `time' and exit.
`-o FILE'
`--output=FILE'
Write the resource use statistics to FILE. By default, this
*overwrites* the file, destroying the file's previous contents.
`-a'
`--append'
*Append* the resource use information to the output file instead
of overwriting it. This option is only useful with the `-o' or
`--output' option.
`-p'
`--portability'
Use the POSIX format.
`-v'
`--verbose'
Use the built-in verbose format, which displays each available
piece of information on the program's resource use on its own
line, with an English description of its meaning.
`-V'
`--version'
Print the version number of `time' and exit.
Options to `time' must appear on the command line before COMMAND.
Anything on the command line after COMMAND is passed as arguments to
COMMAND.
Setting the Output Format
`time' uses a "format string" to determine which information to display about
the resources used by the command it runs. You can specify a format string with
the command line options listed above.
If no format is specified on the command line, but the `TIME' environment variable
is set, its value is used as the format string. Otherwise, the default format
built into `time' is used:
%Uuser %Ssystem %Eelapsed %PCPU (%Xtext+%Ddata %Mmax)k
%Iinputs+%Ooutputs (%Fmajor+%Rminor)pagefaults %Wswaps
The Format String
=================
The "format string" controls the contents of the `time' output. It
consists of "resource specifiers" and "escapes", interspersed with
plain text.
A backslash introduces an "escape", which is translated into a
single printing character upon output. The valid escapes are listed
below. An invalid escape is output as a question mark followed by a
backslash.
`\t' a tab character
`\n' a newline
`\\' a literal backslash
`time' always prints a newline after printing the resource use
information, so normally format strings do not end with a newline
character (or `\n').
A resource specifier consists of a percent sign followed by another
character. An invalid resource specifier is output as a question mark
followed by the invalid character. Use `%%' to output a literal
percent sign.
Time Resources
--------------
`E'
Elapsed real (wall clock) time used by the process, in
[hours:]minutes:seconds.
`e'
Elapsed real (wall clock) time used by the process, in seconds.
`S'
Total number of CPU-seconds used by the system on behalf of the
process (in kernel mode), in seconds.
`U'
Total number of CPU-seconds that the process used directly (in user
mode), in seconds.
`P'
Percentage of the CPU that this job got. This is just user +
system times divied by the total running time.
Memory Resources
----------------
`M'
Maximum resident set size of the process during its lifetime, in
Kilobytes.
`t'
Average resident set size of the process, in Kilobytes.
`K'
Average total (data+stack+text) memory use of the process, in
Kilobytes.
`D'
Average size of the process's unshared data area, in Kilobytes.
`p'
Average size of the process's unshared stack, in Kilobytes.
`X'
Average size of the process's shared text, in Kilobytes.
`Z'
System's page size, in bytes. This is a per-system constant, but
varies between systems.
I/O Resources
-------------
`F'
Number of major, or I/O-requiring, page faults that occurred while
the process was running. These are faults where the page has
actually migrated out of primary memory.
`R'
Number of minor, or recoverable, page faults. These are pages
that are not valid (so they fault) but which have not yet been
claimed by other virtual pages. Thus the data in the page is
still valid but the system tables must be updated.
`W'
Number of times the process was swapped out of main memory.
`c'
Number of times the process was context-switched involuntarily
(because the time slice expired).
`w'
Number of times that the program was context-switched voluntarily,
for instance while waiting for an I/O operation to complete.
`I'
Number of file system inputs by the process.
`O'
Number of file system outputs by the process.
`r'
Number of socket messages received by the process.
`s'
Number of socket messages sent by the process.
`k'
Number of signals delivered to the process.
Command Info
------------
`C'
Name and command line arguments of the command being timed.
`x'
Exit status of the command.
Examples
========
Run the command `wc /etc/hosts' and show the default information:
eg$ time wc /etc/hosts
35 111 1134 /etc/hosts
0.00user 0.01system 0:00.04elapsed 25%CPU (0avgtext+0avgdata 0maxresident)k
1inputs+1outputs (0major+0minor)pagefaults 0swaps
Run the command `ls -Fs' and show just the user, system, and wall-clock
time:
eg$ time -f "\t%E real,\t%U user,\t%S sys" ls -Fs
total 16
1 account/ 1 db/ 1 mail/ 1 run/
1 backups/ 1 emacs/ 1 msgs/ 1 rwho/
1 crash/ 1 games/ 1 preserve/ 1 spool/
1 cron/ 1 log/ 1 quotas/ 1 tmp/
0:00.03 real, 0.00 user, 0.01 sys
Edit the file `.bashrc' and have `time' append the elapsed time and
number of signals to the file `log', reading the format string from the
environment variable `TIME':
eg$ export TIME="\t%E,\t%k" # If using bash or ksh
eg$ setenv TIME "\t%E,\t%k" # If using csh or tcsh
eg$ time -a -o log emacs .bashrc
eg$ cat log
0:16.55, 726
"There is no monument dedicated to the memory of a committee." - Lester J. Pourciau
Related commands:
times - User and system times