original/man1/time.1

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