time(1) - f38

1time(1)                     General Commands 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 ar‐
13       guments.  When command finishes, time writes a message to standard  er‐
14       ror  giving timing statistics about this program run.  These statistics
15       consist of (i) the elapsed real time between  invocation  and  termina‐
16       tion,  (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.
45

GNU VERSION

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

BUGS

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