CRUX-ARM : Home

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