Debian Codegraph @

upstream/opensuse-tumbleweed/man1/time.1

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