452 lines
12 KiB
HTML
452 lines
12 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of TIME</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>TIME</H1>
|
|
Section: User Commands (1)<BR>Updated: Debian GNU/Linux<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
time - run programs and summarize system resource usage
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="1"><B>time</B>
|
|
|
|
<DD>
|
|
[
|
|
<B>-apqvV</B>
|
|
|
|
] [
|
|
<B>-f</B><I> FORMAT</I>
|
|
|
|
] [
|
|
<B>-o</B><I> FILE</I>
|
|
|
|
]
|
|
<BR>
|
|
|
|
[
|
|
<B>--append</B>
|
|
|
|
] [
|
|
<B>--verbose</B>
|
|
|
|
] [
|
|
<B>--quiet</B>
|
|
|
|
] [
|
|
<B>--portability</B>
|
|
|
|
]
|
|
<BR>
|
|
|
|
[
|
|
<B>--format=</B><I>FORMAT</I>
|
|
|
|
] [
|
|
<B>--output=</B><I>FILE</I>
|
|
|
|
] [
|
|
<B>--version</B>
|
|
|
|
]
|
|
<BR>
|
|
|
|
[
|
|
<B>--help</B>
|
|
|
|
]
|
|
<I>COMMAND</I>
|
|
|
|
[
|
|
<I>ARGS</I>
|
|
|
|
]
|
|
|
|
|
|
|
|
|
|
</DL>
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
<B>time</B>
|
|
|
|
run the program
|
|
<I>COMMAND</I>
|
|
|
|
with any given arguments
|
|
<I>ARG...</I>.
|
|
|
|
When
|
|
<I>COMMAND</I>
|
|
|
|
finishes,
|
|
<B>time</B>
|
|
|
|
displays information about resources used by
|
|
<I>COMMAND</I>
|
|
|
|
(on the standard error output, by default). If
|
|
<I>COMMAND</I>
|
|
|
|
exits with non-zero status,
|
|
<B>time</B>
|
|
|
|
displays a warning message and the exit status.
|
|
<P>
|
|
<B>time</B>
|
|
|
|
determines which information to display about the resources used by the
|
|
<I>COMMAND</I>
|
|
|
|
from the string
|
|
<I>FORMAT</I>.
|
|
|
|
If no format is specified on the command line, but the
|
|
<B>TIME</B>
|
|
|
|
environment variable is set, its value is used as the format.
|
|
Otherwise, a default format built into
|
|
<B>time</B>
|
|
|
|
is used.
|
|
<P>
|
|
Options to
|
|
<B>time</B>
|
|
|
|
must appear on the command line before
|
|
<I>COMMAND</I>.
|
|
|
|
Anything on the command line after
|
|
<I>COMMAND</I>
|
|
|
|
is passed as arguments to
|
|
<I>COMMAND</I>.
|
|
|
|
<P>
|
|
<A NAME="lbAE"> </A>
|
|
<H2>OPTIONS</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="2"><B>-o</B><I> FILE, </I><B>--output=</B><I>FILE </I>
|
|
|
|
<DD>
|
|
Write the resource use statistics to
|
|
<I>FILE</I>
|
|
|
|
instead of to the standard error stream. By default, this overwrites the
|
|
file, destroying the file's previous contents. This option is useful for
|
|
collecting information on interactive programs and programs that produce
|
|
output on the standard error stream.
|
|
<DT id="3"><B>-a</B>, <B>--append</B>
|
|
|
|
<DD>
|
|
Append the resource use information to the output file instead of overwriting
|
|
it. This option is only useful with the `-o' or `--output' option.
|
|
<DT id="4"><B>-f</B><I> FORMAT, </I><B>--format</B><I> FORMAT </I>
|
|
|
|
<DD>
|
|
Use
|
|
<I>FORMAT</I>
|
|
|
|
as the format string that controls the output of
|
|
<B>time</B>.
|
|
|
|
See the below more information.
|
|
<DT id="5"><B>--help</B>
|
|
|
|
<DD>
|
|
Print a summary of the command line options and exit.
|
|
<DT id="6"><B>-p</B>, <B>--portability</B>
|
|
|
|
<DD>
|
|
Use the following format string, for conformance with POSIX standard 1003.2:
|
|
<BR> real %e
|
|
<BR> user %U
|
|
<BR> sys %S
|
|
<DT id="7"><B>-v</B>, <B>--verbose</B>
|
|
|
|
<DD>
|
|
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.
|
|
<DT id="8"><B>--quiet</B>
|
|
|
|
<DD>
|
|
Do not report the status of the program even if it is different from zero.
|
|
<DT id="9"><B>-V</B>, <B>--version</B>
|
|
|
|
<DD>
|
|
Print the version number of
|
|
<B>time</B>
|
|
|
|
and exit.
|
|
<P>
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>FORMATTING THE OUTPUT</H2>
|
|
|
|
The format string
|
|
<I>FORMAT</I>
|
|
|
|
controls the contents of the
|
|
<B>time</B>
|
|
|
|
output. The format string can be set using the `-f' or `--format', `-v' or
|
|
`--verbose', or `-p' or `--portability' options. If they are not
|
|
given, but the
|
|
<I>TIME</I>
|
|
|
|
environment variable is set, its value is used as the format string.
|
|
Otherwise, a built-in default format is used. The default format is:
|
|
<BR> %Uuser %Ssystem %Eelapsed %PCPU (%Xtext+%Ddata %Mmax)k
|
|
<BR> %Iinputs+%Ooutputs (%Fmajor+%Rminor)pagefaults %Wswaps
|
|
<P>
|
|
The format string usually consists of `resource specifiers'
|
|
interspersed with plain text. A percent sign (`%') in the format
|
|
string causes the following character to be interpreted as a resource
|
|
specifier, which is similar to the formatting characters in the
|
|
<B><A HREF="/cgi-bin/man/man2html?3+printf">printf</A></B>(3)
|
|
|
|
function.
|
|
<P>
|
|
A backslash (`\') introduces a `backslash escape', which is
|
|
translated into a single printing character upon output. `\t' outputs
|
|
a tab character, `\n' outputs a newline, and `\\' outputs a backslash.
|
|
A backslash followed by any other character outputs a question mark
|
|
(`?') followed by a backslash, to indicate that an invalid backslash
|
|
escape was given.
|
|
<P>
|
|
Other text in the format string is copied verbatim to the output.
|
|
<B>time</B>
|
|
|
|
always prints a newline after printing the resource use
|
|
information, so normally format strings do not end with a newline
|
|
character (or `\n').
|
|
<P>
|
|
There are many resource specifications. Not all resources are
|
|
measured by all versions of Unix, so some of the values might be
|
|
reported as zero. Any character following a percent sign that is not
|
|
listed in the table below causes a question mark (`?') to be output,
|
|
followed by that character, to indicate that an invalid resource
|
|
specifier was given.
|
|
<P>
|
|
|
|
|
|
|
|
The resource specifiers, which are a superset of those recognized by the
|
|
<B><A HREF="/cgi-bin/man/man2html?1+tcsh">tcsh</A></B>(1)
|
|
|
|
builtin `time' command, are:
|
|
<DL COMPACT><DT id="10"><DD>
|
|
<DL COMPACT>
|
|
<DT id="11">%<DD>
|
|
A literal `%'.
|
|
<DT id="12">C<DD>
|
|
Name and command line arguments of the command being timed.
|
|
<DT id="13">D<DD>
|
|
Average size of the process's unshared data area, in Kilobytes.
|
|
<DT id="14">E<DD>
|
|
Elapsed real (wall clock) time used by the process, in [hours:]minutes:seconds.
|
|
<DT id="15">F<DD>
|
|
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.
|
|
<DT id="16">I<DD>
|
|
Number of file system inputs by the process.
|
|
<DT id="17">K<DD>
|
|
Average total (data+stack+text) memory use of the process, in
|
|
Kilobytes.
|
|
<DT id="18">M<DD>
|
|
Maximum resident set size of the process during its lifetime, in
|
|
Kilobytes.
|
|
<DT id="19">O<DD>
|
|
Number of file system outputs by the process.
|
|
<DT id="20">P<DD>
|
|
Percentage of the CPU that this job got. This is just user +
|
|
system times divided by the total running time. It also prints
|
|
a percentage sign.
|
|
<DT id="21">R<DD>
|
|
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.
|
|
<DT id="22">S<DD>
|
|
Total number of CPU-seconds used by the system on behalf of the
|
|
process (in kernel mode), in seconds.
|
|
<DT id="23">U<DD>
|
|
Total number of CPU-seconds that the process used directly (in user
|
|
mode), in seconds.
|
|
<DT id="24">W<DD>
|
|
Number of times the process was swapped out of main memory.
|
|
<DT id="25">X<DD>
|
|
Average amount of shared text in the process, in Kilobytes.
|
|
<DT id="26">Z<DD>
|
|
System's page size, in bytes. This is a per-system constant, but
|
|
varies between systems.
|
|
<DT id="27">c<DD>
|
|
Number of times the process was context-switched involuntarily
|
|
(because the time slice expired).
|
|
<DT id="28">e<DD>
|
|
Elapsed real (wall clock) time used by the process, in seconds.
|
|
<DT id="29">k<DD>
|
|
Number of signals delivered to the process.
|
|
<DT id="30">p<DD>
|
|
Average unshared stack size of the process, in Kilobytes.
|
|
<DT id="31">r<DD>
|
|
Number of socket messages received by the process.
|
|
<DT id="32">s<DD>
|
|
Number of socket messages sent by the process.
|
|
<DT id="33">t<DD>
|
|
Average resident set size of the process, in Kilobytes.
|
|
<DT id="34">w<DD>
|
|
Number of times that the program was context-switched voluntarily,
|
|
for instance while waiting for an I/O operation to complete.
|
|
<DT id="35">x<DD>
|
|
Exit status of the command.
|
|
<DL COMPACT><DT id="36"><DD>
|
|
<P>
|
|
</DL>
|
|
</DL>
|
|
</DL>
|
|
<A NAME="lbAG"> </A>
|
|
<H2>EXAMPLES</H2>
|
|
|
|
To run the command `wc /etc/hosts' and show the default information:
|
|
<BR> time wc /etc/hosts
|
|
<P>
|
|
To run the command `ls -Fs' and show just the user, system, and total
|
|
time:
|
|
<BR> time -f "\t%E real,\t%U user,\t%S sys" ls -Fs
|
|
<P>
|
|
To edit the file BORK and have `time' append the elapsed time and
|
|
number of signals to the file `log', reading the format string from the
|
|
environment variable `TIME':
|
|
<BR> export TIME="\t%E,\t%k" # If using bash or ksh
|
|
<BR> setenv TIME "\t%E,\t%k" # If using csh or tcsh
|
|
<BR> time -a -o log emacs bork
|
|
<P>
|
|
Users of the
|
|
<B>bash</B>
|
|
|
|
shell need to use an explicit path in order to run the external
|
|
<B>time</B>
|
|
|
|
command and not the shell builtin variant. On system where
|
|
<B>time</B>
|
|
|
|
is installed in
|
|
<I>/usr/bin</I>,
|
|
|
|
the first example would become
|
|
<BR> /usr/bin/time wc /etc/hosts
|
|
<P>
|
|
<A NAME="lbAH"> </A>
|
|
<H2>ACCURACY</H2>
|
|
|
|
The elapsed time is not collected atomically with the execution of
|
|
the program; as a result, in bizarre circumstances (if the
|
|
<B>time</B>
|
|
|
|
command gets stopped or swapped out in between when the program being
|
|
timed exits and when
|
|
<B>time</B>
|
|
|
|
calculates how long it took to run), it
|
|
could be much larger than the actual execution time.
|
|
<P>
|
|
When the running time of a command is very nearly zero, some values
|
|
(e.g., the percentage of CPU used) may be reported as either zero (which
|
|
is wrong) or a question mark.
|
|
<P>
|
|
Most information shown by
|
|
<B>time</B>
|
|
|
|
is derived from the
|
|
<B><A HREF="/cgi-bin/man/man2html?2+wait3">wait3</A></B>(2)
|
|
|
|
system call. The numbers are only as good as
|
|
those returned by
|
|
<B><A HREF="/cgi-bin/man/man2html?2+wait3">wait3</A></B>(2).
|
|
|
|
On systems that do not have a
|
|
<B><A HREF="/cgi-bin/man/man2html?2+wait3">wait3</A></B>(2)
|
|
|
|
call that returns status information, the
|
|
<B><A HREF="/cgi-bin/man/man2html?2+times">times</A></B>(2)
|
|
|
|
system call is used instead. However, it provides much less information than
|
|
<B><A HREF="/cgi-bin/man/man2html?2+wait3">wait3</A></B>(2),
|
|
|
|
so on those systems
|
|
<B>time</B>
|
|
|
|
reports the majority of the resources as zero.
|
|
<P>
|
|
The `%I' and `%O' values are allegedly only `real' input and output
|
|
and do not include those supplied by caching devices. The meaning of
|
|
`real' I/O reported by `%I' and `%O' may be muddled for workstations,
|
|
especially diskless ones.
|
|
<P>
|
|
<A NAME="lbAI"> </A>
|
|
<H2>DIAGNOSTICS</H2>
|
|
|
|
The
|
|
<B>time</B>
|
|
|
|
command returns when the program exits, stops, or is terminated by a signal.
|
|
If the program exited normally, the return value of
|
|
<B>time</B>
|
|
|
|
is the return value of the program it executed and measured. Otherwise, the
|
|
return value is 128 plus the number of the signal which caused the program to
|
|
stop or terminate.
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
<B>time</B>
|
|
|
|
was written by David MacKenzie. This man page was added by Dirk Eddelbuettel
|
|
<<A HREF="mailto:edd@debian.org">edd@debian.org</A>>, the Debian GNU/Linux maintainer, for use by the Debian
|
|
GNU/Linux distribution but may of course be used by others.
|
|
<P>
|
|
<A NAME="lbAK"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+tcsh">tcsh</A></B>(1),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+printf">printf</A></B>(3)
|
|
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="37"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="38"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="39"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="40"><A HREF="#lbAE">OPTIONS</A><DD>
|
|
<DT id="41"><A HREF="#lbAF">FORMATTING THE OUTPUT</A><DD>
|
|
<DT id="42"><A HREF="#lbAG">EXAMPLES</A><DD>
|
|
<DT id="43"><A HREF="#lbAH">ACCURACY</A><DD>
|
|
<DT id="44"><A HREF="#lbAI">DIAGNOSTICS</A><DD>
|
|
<DT id="45"><A HREF="#lbAJ">AUTHOR</A><DD>
|
|
<DT id="46"><A HREF="#lbAK">SEE ALSO</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:28 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|