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