| .\" Copyright Andries Brouwer, 2000 |
| .\" Some fragments of text came from the time-1.7 info file. |
| .\" Inspired by kromJx@crosswinds.net. |
| .\" |
| .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) |
| .\" Distributed under GPL |
| .\" %%%LICENSE_END |
| .\" |
| .TH TIME 1 2019-03-06 "" "Linux User's Manual" |
| .SH NAME |
| time \- time a simple command or give resource usage |
| .SH SYNOPSIS |
| .B time \c |
| .RI [ 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 |
| 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\(en125) 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) |