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