View Source: time(1) - Waikato Linux Users Group

Edit PageHistory Diff Info LikePages
TIME
!!!TIME
NAME
SYNOPSIS
DESCRIPTION
OPTIONS
FORMATTING THE OUTPUT
EXAMPLES
ACCURACY
AUTHOR
SEE ALSO
----
!!NAME


time - run programs and summarize system resource usage
!!SYNOPSIS


__time__


[[ __-apqvV__ ] [[ __-f__ ''FORMAT'' ] [[ __-o__
''FILE'' ]
[[ __--append__ ] [[ __--verbose__ ] [[ __--quiet__ ]
[[ __--portability__ ]
[[ __--format=__''FORMAT'' ] [[
__--output=__''FILE'' ] [[ __--version__ ]
[[ __--help__ ] ''COMMAND'' [[ ''ARGS''
]
!!DESCRIPTION


__time__ run the program ''COMMAND'' with any given
arguments ''ARG...''. When ''COMMAND'' finishes,
__time__ displays information about resources used by
''COMMAND'' (on the standard error output, by default).
If ''COMMAND'' exits with non-zero sta- tus, __time__
displays a warning message and the exit status.


__time__ determines which information to display about
the re- sources used by the ''COMMAND'' from the string
''FORMAT''. If no format is specified on the command
line, but the __TIME__ en- vironment variable is set, its
value is used as the for- mat. Otherwise, a default format
built into __time__ is used.


Options to __time__ must appear on the command line
before ''COMMAND''. Anything on the command line after
''COMMAND'' is passed as arguments to
''COMMAND''.
!!OPTIONS


__-o__ ''FILE,''
__--output=__''FILE''


Write the resource use statistics to ''FILE'' 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 in- formation on interactive
programs and programs that produce output on the standard
error stream.


__-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.


__-f__ ''FORMAT,'' __--format__
''FORMAT''


Use ''FORMAT'' as the format string that controls the
output of __time__. See the below more
information.


__--help__


Print a summary of the command line options and ex-
it.


__-p__, __--portability__


Use the following format string, for conformance with POSIX
standard 1003.2: real %e user %U sys %S


__-v__, __--verbose__


Use the built-in verbose format, which displays each
available piece of information on the pro- gram's resource
use on its own line, with an En- glish description of its
meaning.


__--quiet__


Do not report the status of the program even if it is
different from zero.


__-V__, __--version__


Print the version number of __time__ and
exit.
!!FORMATTING THE OUTPUT


The format string ''FORMAT'' controls the contents of the
__time__ output. The format string can be set using the
`-f' or `--format', `-v' or `--verbose', or `-p' or
`--portabili- ty' options. If they are not given, but the
''TIME'' environ- ment variable is set, its value is used
as the format string. Otherwise, a built-in default format
is used. The default format is: %Uuser %Ssystem %Eelapsed
%PCPU (%Xtext+%Ddata %Mmax)k %Iinputs+%Ooutputs
(%Fmajor+%Rminor)pagefaults %Wswaps


The format string usually consists of `resource speci-
fiers' 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 printf(3)
function.


A backslash (`') introduces a `backslash escape', which is
translated into a single printing character upon out- put.
`t' outputs a tab character, `n' outputs a new- line, and
`\' outputs a backslash. A backslash followed by any other
character outputs a question mark (`?') fol- lowed by a
backslash, to indicate that an invalid back- slash escape
was given.


Other text in the format string is copied verbatim to the
output. __time__ always prints a newline after printing
the resource use information, so normally format strings do
not end with a newline character (or `0).


There are many resource specifications. Not all resources
are measured by all versions of Unix, so some of the val-
ues 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 char-
acter, to indicate that an invalid resource 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.


The resource specifiers, which are a superset of those
recognized by the tcsh(1) builtin `time' command,
are:


%


A literal `%'.


C


Name and command line arguments of the com- mand being
timed.


D


Average size of the process's unshared data area, in
Kilobytes.


E


Elapsed real (wall clock) time used by the process, in
[[hours:]minutes:seconds.


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.


I


Number of file system inputs by the process.


K


Average total (data+stack+text) memory use of the process,
in Kilobytes.


M


Maximum resident set size of the process during its
lifetime, in Kilobytes.


O


Number of file system outputs by the pro- cess.


P


Percentage of the CPU that this job got. This is just user +
system times divied by the total running time.


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 sys- tem tables must be
updated.


S


Total number of CPU-seconds used by the sys- tem 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.


W


Number of times the process was swapped out of main
memory.


X


Average amount of shared text in the pro- cess, in
Kilobytes.


Z


System's page size, in bytes. This is a per-system constant,
but varies between sys- tems.


c


Number of times the process was con- text-switched
involuntarily (because the time slice expired).


e


Elapsed real (wall clock) time used by the process, in
seconds.


k


Number of signals delivered to the process.


p


Average unshared stack size of the process, in
Kilobytes.


r


Number of socket messages received by the
process.


s


Number of socket messages sent by the pro-
cess.


t


Average resident set size of the process, in
Kilobytes.


w


Number of times that the program was con- text-switched
voluntarily, for instance while waiting for an I/O operation
to com- plete.


x


Exit status of the command.
!!EXAMPLES


To run the command `wc /etc/hosts' and show the default
information: time wc /etc/hosts


To run the command `ls -Fs' and show just the user, sys-
tem, and total time: time -f


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': export
TIME=
!!ACCURACY


The elapsed time is not collected atomically with the exe-
cution of the program; as a result, in bizarre circum-
stances (if the __time__ command gets stopped or swapped
out in between when the program being timed exits and when
__time__ calculates how long it took to run), it could be
much larger than the actual execution time.


When the running time of a command is very nearly zero, some
values (e.g., the percentage of CPU used) may be re- ported
as either zero (which is wrong) or a question
mark.


Most information shown by __time__ is derived from the
wait3(2) system call. The numbers are only as good as
those returned by wait3(2). On systems that do not
have a wait3(2) call that returns status information,
the times(2) system call is used instead. However, it
pro- vides much less information than wait3(2), so on
those systems __time__ reports the majority of the
resources as ze- ro.


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.
!!AUTHOR


__time__ was written by David !MacKenzie. This man page
was added by Dirk Eddelbuettel
__
!!SEE ALSO


tcsh(1), printf(3)
----
4 pages link to time(1):
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.
Last edited on Tuesday, June 4, 2002 12:22:57 am by "perry"
Edit PageHistory Diff Info LikePages