bce8f29a0e
- Sync patches with Debian and Fedora: * Add man page (time.1). * Less nonverbose output (time-fedora-verbose.patch). * Fix maximal RSS report (time-fedora-ru_maxrss-is-in-kilobytes-on-Linux.patch, bnc#836049, Redhat#702826). * Switch to microsecond accuracy if miliseconds arithmetic rounds to zero (time-fedora-Recompute-CPU-usage-at-microsecond-level.patch, Redhat#527276). * When time exits in a non-normal way, return 128 plus the number of the signal which caused time to stop or abort (time-debian-non-normal-exit.patch). * struct rusage and sys/resource.h portability fix (time-debian-rusage-portability.patch, Debian#144819). * Add -q,--quiet functionality (time-debian-quiet.patch, Debian#56853). * Update bug reporting address (time-debian-bug-address.patch, Debian#542469). * Modernize the configure.in file to current autoconf style (time-debian-configure.patch). * Add a directory entry to the info page (time-debian-info-direntry.patch). - Fix FSF address (time-fsf-address.patch). - Update Summary. - Rename time-1.7.diff to time-alpha.patch. ... And cherry pick changelog entries relevant to time. OBS-URL: https://build.opensuse.org/request/show/198137 OBS-URL: https://build.opensuse.org/package/show/Base:System/time?expand=0&rev=3
326 lines
9.3 KiB
Groff
326 lines
9.3 KiB
Groff
.\" Man page added by Dirk Eddelbuettel <edd@debian.org> on 15 Apr 1996
|
|
.\" Thanks to Herbert Thielen for a patch
|
|
.\" Copyright (C) Dirk Eddelbuettel but freely redistributable
|
|
.TH TIME 1 "Debian GNU/Linux"
|
|
.\" Always turn off hyphenation; it makes way too many mistakes in
|
|
.\" technical documents.
|
|
.nh
|
|
.SH NAME
|
|
time \- run programs and summarize system resource usage
|
|
.SH SYNOPSIS
|
|
.na
|
|
.TP
|
|
.B time
|
|
[
|
|
.B \-apqvV
|
|
] [
|
|
.BI \-f " FORMAT"
|
|
] [
|
|
.BI \-o " FILE"
|
|
]
|
|
.br
|
|
[
|
|
.B \-\-append
|
|
] [
|
|
.B \-\-verbose
|
|
] [
|
|
.B \-\-quiet
|
|
] [
|
|
.B \-\-portability
|
|
]
|
|
.br
|
|
[
|
|
.BI \-\-format= "FORMAT"
|
|
] [
|
|
.BI \-\-output= "FILE"
|
|
] [
|
|
.B \-\-version
|
|
]
|
|
.br
|
|
[
|
|
.B \-\-help
|
|
]
|
|
.I COMMAND
|
|
[
|
|
.I ARGS
|
|
]
|
|
.ad b
|
|
.\" For nroff, turn off justification.
|
|
.if n .ad l
|
|
.SH DESCRIPTION
|
|
.B time
|
|
run the program
|
|
.I COMMAND
|
|
with any given arguments
|
|
.IR "ARG..." .
|
|
When
|
|
.I COMMAND
|
|
finishes,
|
|
.B time
|
|
displays information about resources used by
|
|
.I COMMAND
|
|
(on the standard error output, by default). If
|
|
.I COMMAND
|
|
exits with non\-zero status,
|
|
.B time
|
|
displays a warning message and the exit status.
|
|
|
|
.B time
|
|
determines which information to display about the resources used by the
|
|
.I COMMAND
|
|
from the string
|
|
.IR FORMAT .
|
|
If no format is specified on the command line, but the
|
|
.B TIME
|
|
environment variable is set, its value is used as the format.
|
|
Otherwise, a default format built into
|
|
.B time
|
|
is used.
|
|
|
|
Options to
|
|
.B time
|
|
must appear on the command line before
|
|
.IR COMMAND .
|
|
Anything on the command line after
|
|
.I COMMAND
|
|
is passed as arguments to
|
|
.IR COMMAND .
|
|
|
|
.SH OPTIONS
|
|
.TP
|
|
.BI \-o " FILE, " \-\-output= "FILE "
|
|
Write the resource use statistics to
|
|
.I 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 information on interactive programs and programs that produce
|
|
output on the standard error stream.
|
|
.TP
|
|
.BR \-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.
|
|
.TP
|
|
.BI \-f " FORMAT, " \-\-format " FORMAT "
|
|
Use
|
|
.I FORMAT
|
|
as the format string that controls the output of
|
|
.BR time .
|
|
See the below more information.
|
|
.TP
|
|
.B \-\-help
|
|
Print a summary of the command line options and exit.
|
|
.TP
|
|
.BR \-p ", " \-\-portability ""
|
|
Use the following format string, for conformance with POSIX standard 1003.2:
|
|
real %e
|
|
user %U
|
|
sys %S
|
|
.TP
|
|
.BR \-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.
|
|
.TP
|
|
.B \-\-quiet
|
|
Do not report the status of the program even if it is different from zero.
|
|
.TP
|
|
.BR \-V ", " \-\-version ""
|
|
Print the version number of
|
|
.B time
|
|
and exit.
|
|
|
|
.SH "FORMATTING THE OUTPUT"
|
|
The format string
|
|
.I FORMAT
|
|
controls the contents of the
|
|
.B time
|
|
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
|
|
environment 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 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
|
|
.BR printf (3)
|
|
function.
|
|
|
|
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.
|
|
|
|
Other text in the format string is copied verbatim to the output.
|
|
.B time
|
|
always prints a newline after printing the resource use
|
|
information, so normally format strings do not end with a newline
|
|
character (or `\en').
|
|
|
|
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.
|
|
|
|
.\" No blank line between the resource specifiers below so that they
|
|
.\" are more compactly listed.
|
|
.PD 0
|
|
The resource specifiers, which are a superset of those recognized by the
|
|
.BR tcsh (1)
|
|
builtin `time' command, are:
|
|
.RS
|
|
.IP %
|
|
A literal `%'.
|
|
.IP C
|
|
Name and command line arguments of the command being timed.
|
|
.IP D
|
|
Average size of the process's unshared data area, in Kilobytes.
|
|
.IP E
|
|
Elapsed real (wall clock) time used by the process, in [hours:]minutes:seconds.
|
|
.IP 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.
|
|
.IP I
|
|
Number of file system inputs by the process.
|
|
.IP K
|
|
Average total (data+stack+text) memory use of the process, in
|
|
Kilobytes.
|
|
.IP M
|
|
Maximum resident set size of the process during its lifetime, in
|
|
Kilobytes.
|
|
.IP O
|
|
Number of file system outputs by the process.
|
|
.IP P
|
|
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.
|
|
.IP 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.
|
|
.IP S
|
|
Total number of CPU\-seconds used by the system on behalf of the
|
|
process (in kernel mode), in seconds.
|
|
.IP U
|
|
Total number of CPU\-seconds that the process used directly (in user
|
|
mode), in seconds.
|
|
.IP W
|
|
Number of times the process was swapped out of main memory.
|
|
.IP X
|
|
Average amount of shared text in the process, in Kilobytes.
|
|
.IP Z
|
|
System's page size, in bytes. This is a per\-system constant, but
|
|
varies between systems.
|
|
.IP c
|
|
Number of times the process was context\-switched involuntarily
|
|
(because the time slice expired).
|
|
.IP e
|
|
Elapsed real (wall clock) time used by the process, in seconds.
|
|
.IP k
|
|
Number of signals delivered to the process.
|
|
.IP p
|
|
Average unshared stack size of the process, in Kilobytes.
|
|
.IP r
|
|
Number of socket messages received by the process.
|
|
.IP s
|
|
Number of socket messages sent by the process.
|
|
.IP t
|
|
Average resident set size of the process, in Kilobytes.
|
|
.IP w
|
|
Number of times that the program was context\-switched voluntarily,
|
|
for instance while waiting for an I/O operation to complete.
|
|
.IP x
|
|
Exit status of the command.
|
|
.RS
|
|
|
|
.SH 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, system, and total
|
|
time:
|
|
time \-f "\et%E real,\et%U user,\et%S sys" ls \-Fs
|
|
|
|
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="\et%E,\et%k" # If using bash or ksh
|
|
setenv TIME "\et%E,\et%k" # If using csh or tcsh
|
|
time \-a \-o log emacs bork
|
|
|
|
Users of the
|
|
.B bash
|
|
shell need to use an explicit path in order to run the external
|
|
.B time
|
|
command and not the shell builtin variant. On system where
|
|
.B time
|
|
is installed in
|
|
.IR /usr/bin ,
|
|
the first example would become
|
|
/usr/bin/time wc /etc/hosts
|
|
|
|
.SH ACCURACY
|
|
The elapsed time is not collected atomically with the execution of
|
|
the program; as a result, in bizarre circumstances (if the
|
|
.B time
|
|
command gets stopped or swapped out in between when the program being
|
|
timed exits and when
|
|
.B 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 reported as either zero (which
|
|
is wrong) or a question mark.
|
|
|
|
Most information shown by
|
|
.B time
|
|
is derived from the
|
|
.BR wait3 (2)
|
|
system call. The numbers are only as good as
|
|
those returned by
|
|
.BR wait3 (2).
|
|
On systems that do not have a
|
|
.BR wait3 (2)
|
|
call that returns status information, the
|
|
.BR times (2)
|
|
system call is used instead. However, it provides much less information than
|
|
.BR wait3 (2),
|
|
so on those systems
|
|
.B time
|
|
reports the majority of the resources as zero.
|
|
|
|
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.
|
|
|
|
.SH DIAGNOSTICS
|
|
The
|
|
.B time
|
|
command returns when the program exits, stops, or is terminated by a signal.
|
|
If the program exited normally, the return value of
|
|
.B time
|
|
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.
|
|
.SH AUTHOR
|
|
.B time
|
|
was written by David MacKenzie. This man page was added by Dirk Eddelbuettel
|
|
<edd@debian.org>, the Debian GNU/Linux maintainer, for use by the Debian
|
|
GNU/Linux distribution but may of course be used by others.
|
|
|
|
.SH "SEE ALSO"
|
|
.BR tcsh (1),
|
|
.BR printf (3)
|