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