1TIME(1)                       Linux User's Manual                      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
21       Note: some shells (e.g., bash(1)) have a  built-in  time  command  that
22       provides  similar  information  on the usage of time and possibly other
23       resources.  To access the real command, you may  need  to  specify  its
24       pathname (something like /usr/bin/time).
25

OPTIONS

27       -p     When in the POSIX locale, use the precise traditional format
28
29                  "real %f\nuser %f\nsys %f\n"
30
31              (with  numbers  in  seconds) where the number of decimals in the
32              output for %f is unspecified but is sufficient  to  express  the
33              clock tick accuracy, and at least one.
34

EXIT STATUS

36       If command was invoked, the exit status is that of command.  Otherwise,
37       it is 127 if command could not be found, 126 if it could be  found  but
38       could not be invoked, and some other nonzero value (1–125) if something
39       else went wrong.
40

ENVIRONMENT

42       The variables LANG,  LC_ALL,  LC_CTYPE,  LC_MESSAGES,  LC_NUMERIC,  and
43       NLSPATH  are  used  for the text and formatting of the output.  PATH is
44       used to search for command.  The remaining ones for the text  and  for‐
45       matting of the output.
46

GNU VERSION

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

BUGS

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

SEE ALSO

197       bash(1), tcsh(1), times(2), wait3(2)
198

COLOPHON

200       This page is part of release 4.15 of the Linux  man-pages  project.   A
201       description  of  the project, information about reporting bugs, and the
202       latest    version    of    this    page,    can     be     found     at
203       https://www.kernel.org/doc/man-pages/.
204
205
206
207                                  2017-09-15                           TIME(1)
Impressum