Debian Codegraph @

upstream/fedora-44/man1/time.1

raw
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)