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