1TIME(P) POSIX Programmer's Manual TIME(P)
2
6 time - time a simple command
7
9 time [-p] utility [argument...]
10
12 The time utility shall invoke the utility named by the utility operand
13 with arguments supplied as the argument operands and write a message to
14 standard error that lists timing statistics for the utility. The mes‐
15 sage shall include the following information:
16 * The elapsed (real) time between invocation of utility and its termi‐
18 nation.
19 * The User CPU time, equivalent to the sum of the tms_utime and
21 tms_cutime fields returned by the times() function defined in the
22 System Interfaces volume of IEEE Std 1003.1-2001 for the process in
23 which utility is executed.
24 * The System CPU time, equivalent to the sum of the tms_stime and
26 tms_cstime fields returned by the times() function for the process
27 in which utility is executed.
28 The precision of the timing shall be no less than the granularity
30 defined for the size of the clock tick unit on the system, but the
31 results shall be reported in terms of standard time units (for example,
32 0.02 seconds, 00:00:00.02, 1m33.75s, 365.21 seconds), not numbers of
33 clock ticks.
34 When time is used as part of a pipeline, the times reported are unspec‐
36 ified, except when it is the sole command within a grouping command
37 (see Grouping Commands ) in that pipeline. For example, the commands
38 on the left are unspecified; those on the right report on utilities a
39 and c, respectively:
40 time a | b | c { time a } | b | c
43 a | b | time c a | b | (time c)
44
46 The time utility shall conform to the Base Definitions volume of
47 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
48 The following option shall be supported:
50 -p Write the timing output to standard error in the format shown in
52 the STDERR section.
53
56 The following operands shall be supported:
57 utility
59 The name of a utility that is to be invoked. If the utility op‐
60 erand names any of the special built-in utilities in Special
61 Built-In Utilities , the results are undefined.
62 argument
64 Any string to be supplied as an argument when invoking the util‐
65 ity named by the utility operand.
66
69 Not used.
70
72 None.
73
75 The following environment variables shall affect the execution of time:
76 LANG Provide a default value for the internationalization variables
78 that are unset or null. (See the Base Definitions volume of
79 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
80 ables for the precedence of internationalization variables used
81 to determine the values of locale categories.)
82 LC_ALL If set to a non-empty string value, override the values of all
84 the other internationalization variables.
85 LC_CTYPE
87 Determine the locale for the interpretation of sequences of
88 bytes of text data as characters (for example, single-byte as
89 opposed to multi-byte characters in arguments).
90 LC_MESSAGES
92 Determine the locale that should be used to affect the format
93 and contents of diagnostic and informative messages written to
94 standard error.
95 LC_NUMERIC
97 Determine the locale for numeric formatting.
99 NLSPATH
101 Determine the location of message catalogs for the processing of
102 LC_MESSAGES .
103 PATH Determine the search path that shall be used to locate the util‐
105 ity to be invoked; see the Base Definitions volume of
106 IEEE Std 1003.1-2001, Chapter 8, Environment Variables.
107
110 Default.
111
113 Not used.
114
116 The standard error shall be used to write the timing statistics. If -p
117 is specified, the following format shall be used in the POSIX locale:
118 "real %f\nuser %f\nsys %f\n", <real seconds>, <user seconds>,
121 <system seconds>
122 where each floating-point number shall be expressed in seconds. The
124 precision used may be less than the default six digits of %f , but
125 shall be sufficiently precise to accommodate the size of the clock tick
126 on the system (for example, if there were 60 clock ticks per second, at
127 least two digits shall follow the radix character). The number of dig‐
128 its following the radix character shall be no less than one, even if
129 this always results in a trailing zero. The implementation may append
130 white space and additional information following the format shown here.
131
133 None.
134
136 None.
137
139 If the utility utility is invoked, the exit status of time shall be the
140 exit status of utility; otherwise, the time utility shall exit with one
141 of the following values:
142 1-125 An error occurred in the time utility.
144 126 The utility specified by utility was found but could not be
146 invoked.
147 127 The utility specified by utility could not be found.
149
152 Default.
153 The following sections are informative.
155
157 The command, env, nice, nohup, time, and xargs utilities have been
158 specified to use exit code 127 if an error occurs so that applications
159 can distinguish "failure to find a utility" from "invoked utility
160 exited with an error indication". The value 127 was chosen because it
161 is not commonly used for other meanings; most utilities use small val‐
162 ues for "normal error conditions" and the values above 128 can be con‐
163 fused with termination due to receipt of a signal. The value 126 was
164 chosen in a similar manner to indicate that the utility could be found,
165 but not invoked. Some scripts produce meaningful error messages differ‐
166 entiating the 126 and 127 cases. The distinction between exit codes 126
167 and 127 is based on KornShell practice that uses 127 when all attempts
168 to exec the utility fail with [ENOENT], and uses 126 when any attempt
169 to exec the utility fails for any other reason.
170
172 It is frequently desirable to apply time to pipelines or lists of com‐
173 mands. This can be done by placing pipelines and command lists in a
174 single file; this file can then be invoked as a utility, and the time
175 applies to everything in the file.
176 Alternatively, the following command can be used to apply time to a
178 complex command:
179 time sh -c 'complex-command-line'
182
184 When the time utility was originally proposed to be included in the
185 ISO POSIX-2:1993 standard, questions were raised about its suitability
186 for inclusion on the grounds that it was not useful for conforming
187 applications, specifically:
188 * The underlying CPU definitions from the System Interfaces volume of
190 IEEE Std 1003.1-2001 are vague, so the numeric output could not be
191 compared accurately between systems or even between invocations.
192 * The creation of portable benchmark programs was outside the scope
194 this volume of IEEE Std 1003.1-2001.
195 However, time does fit in the scope of user portability. Human judge‐
197 ment can be applied to the analysis of the output, and it could be very
198 useful in hands-on debugging of applications or in providing subjective
199 measures of system performance. Hence it has been included in this vol‐
200 ume of IEEE Std 1003.1-2001.
201 The default output format has been left unspecified because historical
203 implementations differ greatly in their style of depicting this numeric
204 output. The -p option was invented to provide scripts with a common
205 means of obtaining this information.
206 In the KornShell, time is a shell reserved word that can be used to
208 time an entire pipeline, rather than just a simple command. The POSIX
209 definition has been worded to allow this implementation. Consideration
210 was given to invalidating this approach because of the historical model
211 from the C shell and System V shell. However, since the System V time
212 utility historically has not produced accurate results in pipeline tim‐
213 ing (because the constituent processes are not all owned by the same
214 parent process, as allowed by POSIX), it did not seem worthwhile to
215 break historical KornShell usage.
216 The term utility is used, rather than command, to highlight the fact
218 that shell compound commands, pipelines, special built-ins, and so on,
219 cannot be used directly. However, utility includes user application
220 programs and shell scripts, not just the standard utilities.
221
223 None.
224
226 Shell Command Language , sh , the System Interfaces volume of
227 IEEE Std 1003.1-2001, times()
228
230 Portions of this text are reprinted and reproduced in electronic form
231 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
232 -- Portable Operating System Interface (POSIX), The Open Group Base
233 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
234 Electrical and Electronics Engineers, Inc and The Open Group. In the
235 event of any discrepancy between this version and the original IEEE and
236 The Open Group Standard, the original IEEE and The Open Group Standard
237 is the referee document. The original Standard can be obtained online
238 at http://www.opengroup.org/unix/online.html .
239IEEE/The Open Group 2003 TIME(P)