xref: /freebsd/usr.bin/time/time.1 (revision 2e3f49888ec8851bafb22011533217487764fdb0) 
1.\" Copyright (c) 1980, 1991, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 3. Neither the name of the University nor the names of its contributors
13.\"    may be used to endorse or promote products derived from this software
14.\"    without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.Dd July 7, 2020
29.Dt TIME 1
30.Os
31.Sh NAME
32.Nm time
33.Nd time command execution
34.Sh SYNOPSIS
35.Nm
36.Op Fl al
37.Op Fl h | Fl p
38.Op Fl o Ar file
39.Ar utility Op Ar argument ...
40.Sh DESCRIPTION
41The
42.Nm
43utility
44executes and
45times the specified
46.Ar utility .
47After the
48.Ar utility
49finishes,
50.Nm
51writes to the standard error stream,
52(in seconds):
53the total time elapsed,
54the time used to execute the
55.Ar utility
56process and the time consumed by system overhead.
57.Pp
58The following options are available:
59.Bl -tag -width indent
60.It Fl a
61If the
62.Fl o
63flag is used, append to the specified file rather than overwriting
64it.
65Otherwise, this option has no effect.
66.It Fl h
67Print times in a human friendly format.
68Times are printed in minutes, hours,
69etc.\& as appropriate.
70.It Fl l
71The contents of the
72.Em rusage
73structure are printed as well.
74.It Fl o Ar file
75Write the output to
76.Ar file
77instead of stderr.
78If
79.Ar file
80exists and the
81.Fl a
82flag is not specified, the file will be overwritten.
83.It Fl p
84Makes
85.Nm
86output POSIX.2 compliant (each time is printed on its own line).
87.El
88.Pp
89Some shells may provide a builtin
90.Nm
91command which is similar or identical to this utility.
92Consult the
93.Xr builtin 1
94manual page.
95.Pp
96If
97.Nm
98receives a
99.Dv SIGINFO
100(see the status argument for
101.Xr stty 1 )
102signal, the current time the given command is running will be written to the
103standard output.
104.Sh ENVIRONMENT
105The
106.Ev PATH
107environment variable is used to locate the requested
108.Ar utility
109if the name contains no
110.Ql /
111characters.
112.Sh EXIT STATUS
113If
114.Ar utility
115could be timed successfully, its exit status is returned.
116If
117.Ar utility
118terminated abnormally, a warning message is output to stderr.
119If the
120.Ar utility
121was found but could not be run, the exit status is 126.
122If no
123.Ar utility
124could be found at all, the exit status is 127.
125If
126.Nm
127encounters any other error, the exit status is between 1 and 125
128included.
129.Sh EXAMPLES
130Time the execution of
131.Xr ls 1
132on an empty directory:
133.Bd -literal -offset indent
134$ /usr/bin/time ls
135        0.00 real         0.00 user         0.00 sys
136.Ed
137.Pp
138Time the execution of the
139.Xr cp 1
140command and store the result in the
141.Pa times.txt
142file.
143Then execute the command again to make a new copy and add the result to the same
144file:
145.Bd -literal -offset indent
146$ /usr/bin/time -o times.txt cp FreeBSD-12.1-RELEASE-amd64-bootonly.iso copy1.iso
147$ /usr/bin/time -a -o times.txt cp FreeBSD-12.1-RELEASE-amd64-bootonly.iso copy2.iso
148.Ed
149.Pp
150The
151.Pa times.txt
152file will contain the times of both commands:
153.Bd -literal -offset indent
154$ cat times.txt
155        0.68 real         0.00 user         0.22 sys
156        0.67 real         0.00 user         0.21 sys
157.Ed
158.Pp
159Time the
160.Xr sleep 1
161command and show the results in a human friendly format.
162Show the contents of the
163.Em rusage
164structure too:
165.Bd -literal -offset indent
166$ /usr/bin/time -l -h -p sleep 5
167real 5.01
168user 0.00
169sys 0.00
170         0  maximum resident set size
171         0  average shared memory size
172         0  average unshared data size
173         0  average unshared stack size
174        80  page reclaims
175         0  page faults
176         0  swaps
177         1  block input operations
178         0  block output operations
179         0  messages sent
180         0  messages received
181         0  signals received
182         3  voluntary context switches
183         0  involuntary context switches
184.Ed
185.Sh SEE ALSO
186.Xr builtin 1 ,
187.Xr csh 1 ,
188.Xr getrusage 2 ,
189.Xr wait 2
190.Sh STANDARDS
191The
192.Nm
193utility is expected to conform to ISO/IEC 9945-2:1993 (``POSIX'').
194.Sh HISTORY
195A
196.Nm
197utility appeared in
198.At v3 .
199