2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright Andries Brouwer, 2000
|
|
|
|
.\"
|
|
|
|
.\" This page is distributed under GPL.
|
|
|
|
.\" Some fragments of text came from the time-1.7 info file.
|
|
|
|
.\" Inspired by kromJx@crosswinds.net.
|
|
|
|
.\"
|
2008-11-14 14:05:47 +00:00
|
|
|
.TH TIME 1 2008-11-14 "" "Linux User's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
time \- time a simple command or give resource usage
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.BI "time [" options "] " command " [" arguments... "] "
|
|
|
|
.SH DESCRIPTION
|
|
|
|
The
|
|
|
|
.B time
|
|
|
|
command runs the specified program
|
|
|
|
.I command
|
|
|
|
with the given arguments.
|
|
|
|
When
|
|
|
|
.I command
|
|
|
|
finishes,
|
|
|
|
.B time
|
2005-09-15 12:56:56 +00:00
|
|
|
writes a message to standard error giving timing statistics
|
2004-11-03 13:51:07 +00:00
|
|
|
about this program run.
|
|
|
|
These statistics consist of (i) the elapsed real time
|
|
|
|
between invocation and termination, (ii) the user CPU time
|
|
|
|
(the sum of the
|
|
|
|
.I tms_utime
|
|
|
|
and
|
|
|
|
.I tms_cutime
|
|
|
|
values in a
|
|
|
|
.I "struct tms"
|
|
|
|
as returned by
|
|
|
|
.BR times (2)),
|
|
|
|
and (iii) the system CPU time (the sum of the
|
|
|
|
.I tms_stime
|
|
|
|
and
|
|
|
|
.I tms_cstime
|
|
|
|
values in a
|
|
|
|
.I "struct tms"
|
|
|
|
as returned by
|
|
|
|
.BR times (2)).
|
2008-11-14 14:05:47 +00:00
|
|
|
|
2008-11-26 02:44:53 +00:00
|
|
|
Note: some shells (e.g.,
|
2008-11-14 14:05:47 +00:00
|
|
|
.BR bash (1))
|
|
|
|
have a built-in
|
|
|
|
.B time
|
|
|
|
command that provides less functionality than the command described here.
|
|
|
|
To access the real command, you may need to specify its pathname
|
|
|
|
(something like
|
|
|
|
.IR /usr/bin/time ).
|
2007-06-15 20:22:25 +00:00
|
|
|
.SH OPTIONS
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B \-p
|
|
|
|
When in the POSIX locale, use the precise traditional format
|
2007-12-19 06:57:44 +00:00
|
|
|
.IP
|
|
|
|
.in +4n
|
2004-11-03 13:51:07 +00:00
|
|
|
"real %f\enuser %f\ensys %f\en"
|
2007-12-19 06:57:44 +00:00
|
|
|
.in
|
|
|
|
.IP
|
2004-11-03 13:51:07 +00:00
|
|
|
(with numbers in seconds)
|
|
|
|
where the number of decimals in the output for %f is unspecified
|
|
|
|
but is sufficient to express the clock tick accuracy, and at least one.
|
|
|
|
.SH "EXIT STATUS"
|
|
|
|
If
|
|
|
|
.I command
|
|
|
|
was invoked, the exit status is that of
|
|
|
|
.IR command .
|
|
|
|
Otherwise it is 127 if
|
|
|
|
.I command
|
|
|
|
could not be found, 126 if it could be found but could not be invoked,
|
intro.1, time.1, adjtimex.2, capget.2, eventfd.2, fcntl.2, getrlimit.2, getsockopt.2, gettimeofday.2, intro.2, ioctl_list.2, ioperm.2, mlock.2, pivot_root.2, poll.2, prctl.2, ptrace.2, sched_setscheduler.2, select_tut.2, semget.2, sigaltstack.2, signalfd.2, sysctl.2, timer_settime.2, timerfd_create.2, wait.2, CPU_SET.3, argz_add.3, assert_perror.3, atexit.3, backtrace.3, bcmp.3, clearenv.3, ctime.3, dl_iterate_phdr.3, dlopen.3, ecvt.3, errno.3, error.3, ether_aton.3, exit.3, fenv.3, ferror.3, finite.3, flockfile.3, fnmatch.3, fpathconf.3, fpclassify.3, ftime.3, ftok.3, ftw.3, fwide.3, getaddrinfo.3, gethostbyname.3, getlogin.3, getnameinfo.3, getnetent.3, getopt.3, getprotoent.3, getrpcent.3, getservent.3, glob.3, hsearch.3, inet.3, isalpha.3, iswalnum.3, iswalpha.3, iswblank.3, iswcntrl.3, iswctype.3, iswdigit.3, iswgraph.3, iswlower.3, iswprint.3, iswpunct.3, iswspace.3, iswupper.3, iswxdigit.3, longjmp.3, lsearch.3, malloc.3, matherr.3, mblen.3, mbsinit.3, mbtowc.3, on_exit.3, printf.3, pthread_attr_init.3, pthread_attr_setaffinity_np.3, pthread_attr_setdetachstate.3, pthread_attr_setguardsize.3, pthread_attr_setinheritsched.3, pthread_attr_setschedparam.3, pthread_attr_setschedpolicy.3, pthread_attr_setscope.3, pthread_attr_setstack.3, pthread_attr_setstackaddr.3, pthread_attr_setstacksize.3, pthread_cancel.3, pthread_cleanup_push.3, pthread_equal.3, pthread_getattr_np.3, pthread_getcpuclockid.3, pthread_setaffinity_np.3, pthread_setcancelstate.3, pthread_setconcurrency.3, pthread_setschedparam.3, pthread_setschedprio.3, ptsname.3, putenv.3, putgrent.3, raise.3, rcmd.3, regex.3, rexec.3, rpc.3, rpmatch.3, rtnetlink.3, scandir.3, sem_init.3, setaliasent.3, setbuf.3, setenv.3, setjmp.3, signbit.3, stdio_ext.3, strtod.3, strtol.3, strtoul.3, system.3, termios.3, timeradd.3, tzset.3, ualarm.3, wctomb.3, xdr.3, st.4, tty_ioctl.4, core.5, elf.5, proc.5, bootparam.7, capabilities.7, icmp.7, ip.7, ipv6.7, math_error.7, mdoc.samples.7, mq_overview.7, pthreads.7, raw.7, regex.7, socket.7, tcp.7, tzselect.8: Global fix: s/non-zero/nonzero/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "non-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 16:40:55 +00:00
|
|
|
and some other nonzero value (1-125) if something else went wrong.
|
2007-06-14 06:31:39 +00:00
|
|
|
.SH ENVIRONMENT
|
2007-06-22 17:16:20 +00:00
|
|
|
The variables
|
|
|
|
.BR LANG ,
|
2007-06-23 07:19:07 +00:00
|
|
|
.BR LC_ALL ,
|
2007-06-22 17:16:20 +00:00
|
|
|
.BR LC_CTYPE ,
|
|
|
|
.BR LC_MESSAGES ,
|
|
|
|
.BR LC_NUMERIC ,
|
2007-09-04 06:30:39 +00:00
|
|
|
.BR NLSPATH ,
|
2007-06-22 17:16:20 +00:00
|
|
|
and
|
|
|
|
.B PATH
|
|
|
|
are used.
|
2007-06-14 06:31:39 +00:00
|
|
|
The last one to search for
|
|
|
|
.IR command .
|
|
|
|
The remaining ones for the text and formatting of the output.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "GNU VERSION"
|
|
|
|
Below a description of the GNU 1.7 version of
|
|
|
|
.BR time .
|
|
|
|
Disregarding the name of the utility, GNU makes it output lots of
|
|
|
|
useful information, not only about time used, but also on other
|
|
|
|
resources like memory, I/O and IPC calls (where available).
|
|
|
|
The output is formatted using a format string that can be specified
|
2008-06-26 13:28:19 +00:00
|
|
|
using the
|
|
|
|
.I \-f
|
|
|
|
option or the
|
2007-09-20 16:26:31 +00:00
|
|
|
.B TIME
|
2007-06-22 17:16:20 +00:00
|
|
|
environment variable.
|
2004-11-03 13:51:07 +00:00
|
|
|
.LP
|
2007-12-19 06:57:44 +00:00
|
|
|
The default format string is:
|
|
|
|
.PP
|
|
|
|
.in +4n
|
2004-11-03 13:51:07 +00:00
|
|
|
%Uuser %Ssystem %Eelapsed %PCPU (%Xtext+%Ddata %Mmax)k
|
|
|
|
.br
|
|
|
|
%Iinputs+%Ooutputs (%Fmajor+%Rminor)pagefaults %Wswaps
|
|
|
|
.br
|
2007-12-19 06:57:44 +00:00
|
|
|
.in
|
2004-11-03 13:51:07 +00:00
|
|
|
.LP
|
2008-06-26 13:28:19 +00:00
|
|
|
When the
|
|
|
|
.I \-p
|
|
|
|
option is given the (portable) output format
|
2007-12-19 06:57:44 +00:00
|
|
|
.PP
|
|
|
|
.in +4n
|
2004-11-03 13:51:07 +00:00
|
|
|
real %e
|
|
|
|
.br
|
|
|
|
user %U
|
|
|
|
.br
|
|
|
|
sys %S
|
|
|
|
.br
|
2007-12-19 06:57:44 +00:00
|
|
|
.in
|
|
|
|
.PP
|
2004-11-03 13:51:07 +00:00
|
|
|
is used.
|
|
|
|
.SS "The format string"
|
|
|
|
The format is interpreted in the usual printf-like way.
|
|
|
|
Ordinary characters are directly copied, tab, newline
|
|
|
|
and backslash are escaped using \et, \en and \e\e,
|
|
|
|
a percent sign is represented by %%, and otherwise %
|
2007-06-08 11:25:04 +00:00
|
|
|
indicates a conversion.
|
|
|
|
The program
|
2004-11-03 13:51:07 +00:00
|
|
|
.B time
|
|
|
|
will always add a trailing newline itself.
|
2007-06-08 11:25:04 +00:00
|
|
|
The conversions follow.
|
|
|
|
All of those used by
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR tcsh (1)
|
|
|
|
are supported.
|
|
|
|
.LP
|
|
|
|
.B "Time"
|
|
|
|
.TP
|
|
|
|
.B %E
|
|
|
|
Elapsed real time (in [hours:]minutes:seconds).
|
|
|
|
.TP
|
|
|
|
.B %e
|
|
|
|
(Not in tcsh.) Elapsed real time (in seconds).
|
|
|
|
.TP
|
|
|
|
.B %S
|
|
|
|
Total number of CPU-seconds that the process spent in kernel mode.
|
|
|
|
.TP
|
|
|
|
.B %U
|
|
|
|
Total number of CPU-seconds that the process spent in user mode.
|
|
|
|
.TP
|
|
|
|
.B %P
|
|
|
|
Percentage of the CPU that this job got, computed as (%U + %S) / %E.
|
|
|
|
.LP
|
|
|
|
.B "Memory"
|
|
|
|
.TP
|
|
|
|
.B %M
|
|
|
|
Maximum resident set size of the process during its lifetime, in Kbytes.
|
|
|
|
.TP
|
|
|
|
.B %t
|
|
|
|
(Not in tcsh.) Average resident set size of the process, in Kbytes.
|
|
|
|
.TP
|
|
|
|
.B %K
|
|
|
|
Average total (data+stack+text) memory use of the process,
|
|
|
|
in Kbytes.
|
|
|
|
.TP
|
|
|
|
.B %D
|
|
|
|
Average size of the process's unshared data area, in Kbytes.
|
|
|
|
.TP
|
|
|
|
.B %p
|
|
|
|
(Not in tcsh.) Average size of the process's unshared stack space, in Kbytes.
|
|
|
|
.TP
|
|
|
|
.B %X
|
|
|
|
Average size of the process's shared text space, in Kbytes.
|
|
|
|
.TP
|
|
|
|
.B %Z
|
|
|
|
(Not in tcsh.) System's page size, in bytes.
|
|
|
|
This is a per-system constant, but varies between systems.
|
|
|
|
.TP
|
|
|
|
.B %F
|
|
|
|
Number of major page faults that occurred while the process was running.
|
|
|
|
These are faults where the page has to be read in from disk.
|
|
|
|
.TP
|
|
|
|
.B %R
|
|
|
|
Number of minor, or recoverable, page faults.
|
|
|
|
These are faults for pages that are not valid but which have
|
2008-06-12 06:09:19 +00:00
|
|
|
not yet been claimed by other virtual pages.
|
|
|
|
Thus the data
|
2004-11-03 13:51:07 +00:00
|
|
|
in the page is still valid but the system tables must be updated.
|
|
|
|
.TP
|
|
|
|
.B %W
|
|
|
|
Number of times the process was swapped out of main memory.
|
|
|
|
.TP
|
|
|
|
.B %c
|
|
|
|
Number of times the process was context-switched involuntarily
|
|
|
|
(because the time slice expired).
|
|
|
|
.TP
|
|
|
|
.B %w
|
|
|
|
Number of waits: times that the program was context-switched voluntarily,
|
|
|
|
for instance while waiting for an I/O operation to complete.
|
|
|
|
.LP
|
|
|
|
.B "I/O"
|
|
|
|
.TP
|
|
|
|
.B %I
|
|
|
|
Number of file system inputs by the process.
|
|
|
|
.TP
|
|
|
|
.B %O
|
|
|
|
Number of file system outputs by the process.
|
|
|
|
.TP
|
|
|
|
.B %r
|
|
|
|
Number of socket messages received by the process.
|
|
|
|
.TP
|
|
|
|
.B %s
|
|
|
|
Number of socket messages sent by the process.
|
|
|
|
.TP
|
|
|
|
.B %k
|
|
|
|
Number of signals delivered to the process.
|
|
|
|
.TP
|
|
|
|
.B %C
|
2008-03-19 08:37:35 +00:00
|
|
|
(Not in tcsh.) Name and command-line arguments of the command being timed.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B %x
|
|
|
|
(Not in tcsh.) Exit status of the command.
|
2007-06-15 19:11:58 +00:00
|
|
|
.SS "GNU Options"
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.BI "\-f " FORMAT ", \-\-format=" FORMAT
|
|
|
|
Specify output format, possibly overriding the format specified
|
|
|
|
in the environment variable TIME.
|
|
|
|
.TP
|
|
|
|
.B "\-p, \-\-portability"
|
|
|
|
Use the portable output format.
|
|
|
|
.TP
|
|
|
|
.BI "\-o " FILE ", \-\-output=" FILE
|
2008-07-16 08:21:37 +00:00
|
|
|
Do not send the results to \fIstderr\fP, but overwrite the specified file.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B "\-a, \-\-append"
|
|
|
|
(Used together with \-o.) Do not overwrite but append.
|
|
|
|
.TP
|
|
|
|
.B "\-v, \-\-verbose"
|
|
|
|
Give very verbose output about all the program knows about.
|
2007-06-15 19:11:58 +00:00
|
|
|
.SS "GNU Standard Options"
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B "\-\-help"
|
|
|
|
Print a usage message on standard output and exit successfully.
|
|
|
|
.TP
|
|
|
|
.B "\-V, \-\-version"
|
|
|
|
Print version information on standard output, then exit successfully.
|
|
|
|
.TP
|
|
|
|
.B "\-\-"
|
|
|
|
Terminate option list.
|
|
|
|
.SH BUGS
|
|
|
|
Not all resources are measured by all versions of Unix,
|
|
|
|
so some of the values might be reported as zero.
|
|
|
|
The present selection was mostly inspired by the data
|
|
|
|
provided by 4.2 or 4.3BSD.
|
|
|
|
.LP
|
|
|
|
GNU time version 1.7 is not yet localized.
|
|
|
|
Thus, it does not implement the POSIX requirements.
|
|
|
|
.LP
|
2007-06-22 17:16:20 +00:00
|
|
|
The environment variable
|
2007-09-20 16:26:31 +00:00
|
|
|
.B TIME
|
2007-06-22 17:16:20 +00:00
|
|
|
was badly chosen.
|
|
|
|
It is not unusual for systems like
|
|
|
|
.BR autoconf (1)
|
|
|
|
or
|
|
|
|
.BR make (1)
|
2004-11-03 13:51:07 +00:00
|
|
|
to use environment variables with the name of a utility to override
|
2007-06-08 11:25:04 +00:00
|
|
|
the utility to be used.
|
|
|
|
Uses like MORE or TIME for options to programs
|
2006-02-12 22:19:08 +00:00
|
|
|
(instead of program pathnames) tend to lead to difficulties.
|
2004-11-03 13:51:07 +00:00
|
|
|
.LP
|
2008-06-26 13:28:19 +00:00
|
|
|
It seems unfortunate that
|
|
|
|
.I \-o
|
|
|
|
overwrites instead of appends.
|
|
|
|
(That is, the
|
|
|
|
.I \-a
|
|
|
|
option should be the default.)
|
2004-11-03 13:51:07 +00:00
|
|
|
.LP
|
|
|
|
Mail suggestions and bug reports for GNU
|
|
|
|
.B time
|
|
|
|
to
|
|
|
|
.br
|
2005-07-06 07:41:37 +00:00
|
|
|
.I bug\-utils@prep.ai.mit.edu
|
2004-11-03 13:51:07 +00:00
|
|
|
.br
|
|
|
|
Please include the version of
|
2005-07-19 15:38:39 +00:00
|
|
|
.BR time ,
|
2004-11-03 13:51:07 +00:00
|
|
|
which you can get by running
|
|
|
|
.br
|
2005-07-06 07:41:37 +00:00
|
|
|
.I time \-\-version
|
2004-11-03 13:51:07 +00:00
|
|
|
.br
|
|
|
|
and the operating system
|
|
|
|
and C compiler you used.
|
2007-05-18 14:24:10 +00:00
|
|
|
.\" .SH AUTHORS
|
|
|
|
.\" .TP
|
|
|
|
.\" .IP "David Keppel"
|
|
|
|
.\" Original version
|
|
|
|
.\" .IP "David MacKenzie"
|
|
|
|
.\" POSIXization, autoconfiscation, GNU getoptization,
|
|
|
|
.\" documentation, other bug fixes and improvements.
|
|
|
|
.\" .IP "Arne Henrik Juul"
|
|
|
|
.\" Helped with portability
|
|
|
|
.\" .IP "Francois Pinard"
|
|
|
|
.\" Helped with portability
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR tcsh (1),
|
|
|
|
.BR times (2),
|
|
|
|
.BR wait3 (2)
|