1TIME(1)                                                                TIME(1)
2
3
4

NAME

6       time - time a simple command or give resource usage
7

SYNOPSIS

9       time [options] command [arguments...]
10

DESCRIPTION

12       The  time  command  runs  the  specified program command with the given
13       arguments.  When command finishes, time writes a  message  to  standard
14       error  giving  timing statistics about this program run.  These statis‐
15       tics consist of (i) the elapsed real time between invocation and termi‐
16       nation, (ii) the user CPU time (the sum of the tms_utime and tms_cutime
17       values in a struct tms as returned by times(2)), and (iii)  the  system
18       CPU  time  (the  sum of the tms_stime and tms_cstime values in a struct
19       tms as returned by times(2)).
20

OPTION

22       -p     When in the POSIX locale, use the precise traditional format
23                   "real %f\nuser %f\nsys %f\n"
24              (with numbers in seconds) where the number of  decimals  in  the
25              output  for  %f  is unspecified but is sufficient to express the
26              clock tick accuracy, and at least one.
27

ENVIRONMENT

29       The variables LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, LC_NUMERIC,  NLSPATH
30       and  PATH  are used. The last one to search for command.  The remaining
31       ones for the text and formatting of the output.
32

EXIT STATUS

34       If command was invoked, the exit status is that of command.   Otherwise
35       it  is  127 if command could not be found, 126 if it could be found but
36       could not be invoked, and some other non-zero value  (1-125)  if  some‐
37       thing else went wrong.
38

SEE ALSO

40       times(2)
41
42
43

GNU VERSION

45       Below  a  description of the GNU 1.7 version of time.  Disregarding the
46       name of the utility, GNU makes it output lots  of  useful  information,
47       not  only about time used, but also on other resources like memory, I/O
48       and IPC calls (where available).  The output is formatted using a  for‐
49       mat  string that can be specified using the -f option or the TIME envi‐
50       ronment variable.
51
52       The default format string is
53          %Uuser %Ssystem %Eelapsed %PCPU (%Xtext+%Ddata %Mmax)k
54          %Iinputs+%Ooutputs (%Fmajor+%Rminor)pagefaults %Wswaps
55
56       When the -p option is given the (portable) output format
57          real %e
58          user %U
59          sys %S
60       is used.
61
62   The format string
63       The format is interpreted in the usual printf-like way.  Ordinary char‐
64       acters  are  directly  copied,  tab,  newline and backslash are escaped
65       using \t, \n and \\, a percent sign is represented by %%, and otherwise
66       %  indicates  a conversion. The program time will always add a trailing
67       newline itself.  The conversions follow. All of those used  by  tcsh(1)
68       are supported.
69
70       Time
71
72       %E     Elapsed real time (in [hours:]minutes:seconds).
73
74       %e     (Not in tcsh.) Elapsed real time (in seconds).
75
76       %S     Total  number  of  CPU-seconds  that the process spent in kernel
77              mode.
78
79       %U     Total number of CPU-seconds that the process spent in user mode.
80
81       %P     Percentage of the CPU that this job got, computed as (%U + %S) /
82              %E.
83
84       Memory
85
86       %M     Maximum resident set size of the process during its lifetime, in
87              Kbytes.
88
89       %t     (Not in tcsh.) Average resident set  size  of  the  process,  in
90              Kbytes.
91
92       %K     Average  total  (data+stack+text)  memory use of the process, in
93              Kbytes.
94
95       %D     Average size of the process's unshared data area, in Kbytes.
96
97       %p     (Not in tcsh.) Average size  of  the  process's  unshared  stack
98              space, in Kbytes.
99
100       %X     Average size of the process's shared text space, in Kbytes.
101
102       %Z     (Not in tcsh.) System's page size, in bytes.  This is a per-sys‐
103              tem constant, but varies between systems.
104
105       %F     Number of major page faults that occurred while the process  was
106              running.  These are faults where the page has to be read in from
107              disk.
108
109       %R     Number of minor, or recoverable, page faults.  These are  faults
110              for pages that are not valid but which have not yet been claimed
111              by other virtual pages.  Thus the data  in  the  page  is  still
112              valid but the system tables must be updated.
113
114       %W     Number of times the process was swapped out of main memory.
115
116       %c     Number  of  times the process was context-switched involuntarily
117              (because the time slice expired).
118
119       %w     Number of waits: times that  the  program  was  context-switched
120              voluntarily,  for instance while waiting for an I/O operation to
121              complete.
122
123       I/O
124
125       %I     Number of file system inputs by the process.
126
127       %O     Number of file system outputs by the process.
128
129       %r     Number of socket messages received by the process.
130
131       %s     Number of socket messages sent by the process.
132
133       %k     Number of signals delivered to the process.
134
135       %C     (Not in tcsh.) Name and command line arguments  of  the  command
136              being timed.
137
138       %x     (Not in tcsh.) Exit status of the command.
139

GNU OPTIONS

141       -f FORMAT, --format=FORMAT
142              Specify  output format, possibly overriding the format specified
143              in the environment variable TIME.
144
145       -p, --portability
146              Use the portable output format.
147
148       -o FILE, --output=FILE
149              Do not send the results to stderr, but overwrite  the  specified
150              file.
151
152       -a, --append
153              (Used together with -o.) Do not overwrite but append.
154
155       -v, --verbose
156              Give very verbose output about all the program knows about.
157

GNU STANDARD OPTIONS

159       --help Print a usage message on standard output and exit successfully.
160
161       -V, --version
162              Print version information on standard output, then exit success‐
163              fully.
164
165       --     Terminate option list.
166

BUGS

168       Not all resources are measured by all versions of Unix, so some of  the
169       values  might  be  reported  as zero.  The present selection was mostly
170       inspired by the data provided by 4.2 or 4.3BSD.
171
172       GNU time version 1.7 is not yet localized.  Thus, it does not implement
173       the POSIX requirements.
174
175       The  environment variable TIME was badly chosen.  It is not unusual for
176       systems like autoconf or make to use  environment  variables  with  the
177       name of a utility to override the utility to be used. Uses like MORE or
178       TIME for options to programs (instead of  program  pathnames)  tend  to
179       lead to difficulties.
180
181       It  seems unfortunate that -o overwrites instead of appends.  (That is,
182       the -a option should be the default.)
183
184       Mail suggestions and bug reports for GNU time to
185       bug-utils@prep.ai.mit.edu
186       Please include the version of time, which you can get by running
187       time --version
188       and the operating system and C compiler you used.
189

SEE ALSO

191       tcsh(1), times(2), wait3(2)
192

AUTHORS

194       David Keppel
195              Original version
196
197       David MacKenzie
198              POSIXization, autoconfiscation, GNU getoptization,  docu‐
199              mentation, other bug fixes and improvements.
200
201       Arne Henrik Juul
202              Helped with portability
203
204       Francois Pinard
205              Helped with portability
206
207
208
209                                  2000-12-11                           TIME(1)