diff options
Diffstat (limited to 'man1/time.1')
| -rw-r--r-- | man1/time.1 | 329 |
1 files changed, 329 insertions, 0 deletions
diff --git a/man1/time.1 b/man1/time.1 new file mode 100644 index 0000000..df09106 --- /dev/null +++ b/man1/time.1 @@ -0,0 +1,329 @@ +.\" Copyright Andries Brouwer, 2000 +.\" Some fragments of text came from the time-1.7 info file. +.\" Inspired by kromJx@crosswinds.net. +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH time 1 2023-07-30 "Linux man-pages 6.05.01" +.SH NAME +time \- time a simple command or give resource usage +.SH SYNOPSIS +.B time +.RI [ option \~.\|.\|.\&] " command " [ argument \~.\|.\|.] +.SH DESCRIPTION +The +.B time +command runs the specified program +.I command +with the given arguments. +When +.I command +finishes, +.B time +writes a message to standard error giving timing statistics +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)). +.PP +Note: some shells (e.g., +.BR bash (1)) +have a built-in +.B time +command that provides similar information on the usage of time and +possibly other resources. +To access the real command, you may need to specify its pathname +(something like +.IR /usr/bin/time ). +.SH OPTIONS +.TP +.B \-p +When in the POSIX locale, use the precise traditional format +.IP +.in +4n +.EX +"real %f\enuser %f\ensys %f\en" +.EE +.in +.IP +(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, +and some other nonzero value (1\[en]125) if something else went wrong. +.SH ENVIRONMENT +The variables +.BR LANG , +.BR LC_ALL , +.BR LC_CTYPE , +.BR LC_MESSAGES , +.BR LC_NUMERIC , +and +.B NLSPATH +are used for the text and formatting of the output. +.B PATH +is used to search for +.IR command . +.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 +using the +.I \-f +option or the +.B TIME +environment variable. +.PP +The default format string is: +.PP +.in +4n +.EX +%Uuser %Ssystem %Eelapsed %PCPU (%Xtext+%Ddata %Mmax)k +%Iinputs+%Ooutputs (%Fmajor+%Rminor)pagefaults %Wswaps +.EE +.in +.PP +When the +.I \-p +option is given, the (portable) output format is used: +.PP +.in +4n +.EX +real %e +user %U +sys %S +.EE +.in +.\" +.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 % +indicates a conversion. +The program +.B time +will always add a trailing newline itself. +The conversions follow. +All of those used by +.BR tcsh (1) +are supported. +.PP +.B "Time" +.TP +.B %E +Elapsed real time (in [hours:]minutes:seconds). +.TP +.B %e +(Not in +.BR tcsh (1).) +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. +.PP +.B "Memory" +.TP +.B %M +Maximum resident set size of the process during its lifetime, in Kbytes. +.TP +.B %t +(Not in +.BR tcsh (1).) +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 +.BR tcsh (1).) +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 +.BR tcsh (1).) +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 +not yet been claimed by other virtual pages. +Thus the data +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. +.PP +.B "I/O" +.TP +.B %I +Number of filesystem inputs by the process. +.TP +.B %O +Number of filesystem 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 +(Not in +.BR tcsh (1).) +Name and command-line arguments of the command being timed. +.TP +.B %x +(Not in +.BR tcsh (1).) +Exit status of the command. +.SS GNU options +.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 +Do not send the results to +.IR stderr , +but overwrite the specified file. +.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. +.TP +.B "\-q, \-\-quiet" +Don't report abnormal program termination (where +.I command +is terminated by a signal) or nonzero exit status. +.\" +.SS GNU standard options +.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. +.PP +GNU time version 1.7 is not yet localized. +Thus, it does not implement the POSIX requirements. +.PP +The environment variable +.B TIME +was badly chosen. +It is not unusual for systems like +.BR autoconf (1) +or +.BR make (1) +to use environment variables with the name of a utility to override +the utility to be used. +Uses like MORE or TIME for options to programs +(instead of program pathnames) tend to lead to difficulties. +.PP +It seems unfortunate that +.I \-o +overwrites instead of appends. +(That is, the +.I \-a +option should be the default.) +.PP +Mail suggestions and bug reports for GNU +.B time +to +.IR bug\-time@gnu.org . +Please include the version of +.BR time , +which you can get by running +.PP +.in +4n +.EX +time \-\-version +.EE +.in +.PP +and the operating system +and C compiler you used. +.\" .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 +.SH SEE ALSO +.BR bash (1), +.BR tcsh (1), +.BR times (2), +.BR wait3 (2) |