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