time/time.1

   1 .\" Copyright Andries Brouwer, 2000
   2 .\"
   3 .\" This page is distributed under GPL.
   4 .\" Some fragments of text came from the time-1.7 info file.
   5 .\" Inspired by kromJx@crosswinds.net.
   6 .\"
   7 .TH TIME 1 "11 December 2000" "" ""
   8 .SH NAME
   9 time \- time a simple command or give resource usage
  10 .SH SYNOPSIS
  11 .BI "time [" options "] " command " [" arguments... "] "
  12 .SH DESCRIPTION
  13 The
  14 .B time
  15 command runs the specified program
  16 .I command
  17 with the given arguments.
  18 When
  19 .I command
  20 finishes,
  21 .B time
  22 writes a message to standard output giving timing statistics
  23 about this program run.
  24 These statistics consist of (i) the elapsed real time
  25 between invocation and termination, (ii) the user CPU time
  26 (the sum of the
  27 .I tms_utime
  28 and
  29 .I tms_cutime
  30 values in a
  31 .I "struct tms"
  32 as returned by
  33 .BR times (2)),
  34 and (iii) the system CPU time (the sum of the
  35 .I  tms_stime
  36 and
  37 .I tms_cstime
  38 values in a
  39 .I "struct tms"
  40 as returned by
  41 .BR times (2)).
  42 .SH OPTION
  43 .TP
  44 .B \-p
  45 When in the POSIX locale, use the precise traditional format
  46 .br
  47 .in +5
  48 "real %f\enuser %f\ensys %f\en"
  49 .in -5
  50 .br
  51 (with numbers in seconds)
  52 where the number of decimals in the output for %f is unspecified
  53 but is sufficient to express the clock tick accuracy, and at least one.
  54 .SH ENVIRONMENT
  55 The variables LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, LC_NUMERIC,
  56 NLSPATH and PATH are used. The last one to search for
  57 .IR command .
  58 The remaining ones for the text and formatting of the output.
  59 .SH "EXIT STATUS"
  60 If
  61 .I command
  62 was invoked, the exit status is that of
  63 .IR command .
  64 Otherwise it is 127 if
  65 .I command
  66 could not be found, 126 if it could be found but could not be invoked,
  67 and some other nonzero value (1-125) if something else went wrong.
  68 .SH "SEE ALSO"
  69 .BR times (2),
  70 .sp 2
  71 .SH "GNU VERSION"
  72 Below a description of the GNU 1.7 version of
  73 .BR time .
  74 Disregarding the name of the utility, GNU makes it output lots of
  75 useful information, not only about time used, but also on other
  76 resources like memory, I/O and IPC calls (where available).
  77 The output is formatted using a format string that can be specified
  78 using the \-f option or the TIME environment variable.
  79 .LP
  80 The default format string is
  81 .br
  82 .in +3
  83 %Uuser %Ssystem %Eelapsed %PCPU (%Xtext+%Ddata %Mmax)k
  84 .br
  85 %Iinputs+%Ooutputs (%Fmajor+%Rminor)pagefaults %Wswaps
  86 .br
  87 .in -3
  88 .LP
  89 When the \-p option is given the (portable) output format
  90 .br
  91 .in +3
  92 real %e
  93 .br
  94 user %U
  95 .br
  96 sys %S
  97 .br
  98 .in -3
  99 is used.
 100 .SS "The format string"
 101 The format is interpreted in the usual printf-like way.
 102 Ordinary characters are directly copied, tab, newline
 103 and backslash are escaped using \et, \en and \e\e,
 104 a percent sign is represented by %%, and otherwise %
 105 indicates a conversion. The program
 106 .B time
 107 will always add a trailing newline itself.
 108 The conversions follow. All of those used by
 109 .BR tcsh (1)
 110 are supported.
 111 .LP
 112 .B "Time"
 113 .TP
 114 .B %E
 115 Elapsed real time (in [hours:]minutes:seconds).
 116 .TP
 117 .B %e
 118 (Not in tcsh.) Elapsed real time (in seconds).
 119 .TP
 120 .B %S
 121 Total number of CPU-seconds that the process spent in kernel mode.
 122 .TP
 123 .B %U
 124 Total number of CPU-seconds that the process spent in user mode.
 125 .TP
 126 .B %P
 127 Percentage of the CPU that this job got, computed as (%U + %S) / %E.
 128 .LP
 129 .B "Memory"
 130 .TP
 131 .B %M
 132 Maximum resident set size of the process during its lifetime, in Kbytes.
 133 .TP
 134 .B %t
 135 (Not in tcsh.) Average resident set size of the process, in Kbytes.
 136 .TP
 137 .B %K
 138 Average total (data+stack+text) memory use of the process,
 139 in Kbytes.
 140 .TP
 141 .B %D
 142 Average size of the process's unshared data area, in Kbytes.
 143 .TP
 144 .B %p
 145 (Not in tcsh.) Average size of the process's unshared stack space, in Kbytes.
 146 .TP
 147 .B %X
 148 Average size of the process's shared text space, in Kbytes.
 149 .TP
 150 .B %Z
 151 (Not in tcsh.) System's page size, in bytes.
 152 This is a per-system constant, but varies between systems.
 153 .TP
 154 .B %F
 155 Number of major page faults that occurred while the process was running.
 156 These are faults where the page has to be read in from disk.
 157 .TP
 158 .B %R
 159 Number of minor, or recoverable, page faults.
 160 These are faults for pages that are not valid but which have
 161 not yet been claimed by other virtual pages.  Thus the data
 162 in the page is still valid but the system tables must be updated.
 163 .TP
 164 .B %W
 165 Number of times the process was swapped out of main memory.
 166 .TP
 167 .B %c
 168 Number of times the process was context-switched involuntarily
 169 (because the time slice expired).
 170 .TP
 171 .B %w
 172 Number of waits: times that the program was context-switched voluntarily,
 173 for instance while waiting for an I/O operation to complete.
 174 .LP
 175 .B "I/O"
 176 .TP
 177 .B %I
 178 Number of file system inputs by the process.
 179 .TP
 180 .B %O
 181 Number of file system outputs by the process.
 182 .TP
 183 .B %r
 184 Number of socket messages received by the process.
 185 .TP
 186 .B %s
 187 Number of socket messages sent by the process.
 188 .TP
 189 .B %k
 190 Number of signals delivered to the process.
 191 .TP
 192 .B %C
 193 (Not in tcsh.) Name and command line arguments of the command being timed.
 194 .TP
 195 .B %x
 196 (Not in tcsh.) Exit status of the command.
 197 .SH "GNU OPTIONS"
 198 .TP
 199 .BI "\-f " FORMAT ", \-\-format=" FORMAT
 200 Specify output format, possibly overriding the format specified
 201 in the environment variable TIME.
 202 .TP
 203 .B "\-p, \-\-portability"
 204 Use the portable output format.
 205 .TP
 206 .BI "\-o " FILE ", \-\-output=" FILE
 207 Do not send the results to stderr, but overwrite the specified file.
 208 .TP
 209 .B "\-a, \-\-append"
 210 (Used together with \-o.) Do not overwrite but append.
 211 .TP
 212 .B "\-v, \-\-verbose"
 213 Give very verbose output about all the program knows about.
 214 .SH "GNU STANDARD OPTIONS"
 215 .TP
 216 .B "\-\-help"
 217 Print a usage message on standard output and exit successfully.
 218 .TP
 219 .B "\-V, \-\-version"
 220 Print version information on standard output, then exit successfully.
 221 .TP
 222 .B "\-\-"
 223 Terminate option list.
 224 .SH BUGS
 225 Not all resources are measured by all versions of Unix,
 226 so some of the values might be reported as zero.
 227 The present selection was mostly inspired by the data
 228 provided by 4.2 or 4.3BSD.
 229 .LP
 230 GNU time version 1.7 is not yet localized.
 231 Thus, it does not implement the POSIX requirements.
 232 .LP
 233 The environment variable TIME was badly chosen.
 234 It is not unusual for systems like autoconf or make
 235 to use environment variables with the name of a utility to override
 236 the utility to be used. Uses like MORE or TIME for options to programs
 237 (instead of program path names) tend to lead to difficulties.
 238 .LP
 239 It seems unfortunate that \-o overwrites instead of appends.
 240 (That is, the \-a option should be the default.)
 241 .LP
 242 Mail suggestions and bug reports for GNU
 243 .B time
 244 to
 245 .br
 246 .I bug-utils@prep.ai.mit.edu
 247 .br
 248 Please include the version of
 249 .B time ,
 250 which you can get by running
 251 .br
 252 .I time --version
 253 .br
 254 and the operating system
 255 and C compiler you used.
 256 .SH "SEE ALSO"
 257 .BR tcsh (1),
 258 .BR times (2),
 259 .BR wait3 (2)
 260 .SH AUTHORS
 261 .TP
 262 .IP "David Keppel"
 263 Original version
 264 .IP "David MacKenzie"
 265 POSIXization, autoconfiscation, GNU getoptization,
 266 documentation, other bug fixes and improvements.
 267 .IP "Arne Henrik Juul"
 268 Helped with portability
 269 .IP "Francois Pinard"
 270 Helped with portability