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 ter‐
24 mination.
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 POSIX.1‐2017 for the process in which
29 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 Section 2.9.4.1, Grouping Commands) in that pipeline. For example,
44 the commands on the left are unspecified; those on the right report on
45 utilities a 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 POSIX.1‐2017, 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
58 in the STDERR section.
59
61 The following operands shall be supported:
62 utility The name of a utility that is to be invoked. If the utility
64 operand names any of the special built-in utilities in Sec‐
65 tion 2.14, Special Built-In Utilities, the results are unde‐
66 fined.
67 argument Any string to be supplied as an argument when invoking the
69 utility named by the utility operand.
70
72 Not used.
73
75 None.
76
78 The following environment variables shall affect the execution of time:
79 LANG Provide a default value for the internationalization vari‐
81 ables that are unset or null. (See the Base Definitions vol‐
82 ume of POSIX.1‐2017, Section 8.2, Internationalization Vari‐
83 ables for the precedence of internationalization variables
84 used to determine the values of locale categories.)
85 LC_ALL If set to a non-empty string value, override the values of
87 all the other internationalization variables.
88 LC_CTYPE Determine the locale for the interpretation of sequences of
90 bytes of text data as characters (for example, single-byte as
91 opposed to multi-byte characters in arguments).
92 LC_MESSAGES
94 Determine the locale that should be used to affect the format
95 and contents of diagnostic and informative messages written
96 to standard error.
97 LC_NUMERIC
99 Determine the locale for numeric formatting.
100 NLSPATH Determine the location of message catalogs for the processing
102 of LC_MESSAGES.
103 PATH Determine the search path that shall be used to locate the
105 utility to be invoked; see the Base Definitions volume of
106 POSIX.1‐2017, Chapter 8, Environment Variables.
107
109 Default.
110
112 Not used.
113
115 If the utility utility is invoked, the standard error shall be used to
116 write the timing statistics and may be used to write a diagnostic mes‐
117 sage if the utility terminates abnormally; otherwise, the standard
118 error shall be used to write diagnostic messages and may also be used
119 to write the timing statistics.
120 If -p is specified, the following format shall be used for the timing
122 statistics in the POSIX locale:
123 "real %f\nuser %f\nsys %f\n", <real seconds>, <user seconds>,
126 <system seconds>
127 where each floating-point number shall be expressed in seconds. The
129 precision used may be less than the default six digits of %f, but shall
130 be sufficiently precise to accommodate the size of the clock tick on
131 the system (for example, if there were 60 clock ticks per second, at
132 least two digits shall follow the radix character). The number of dig‐
133 its following the radix character shall be no less than one, even if
134 this always results in a trailing zero. The implementation may append
135 white space and additional information following the format shown here.
136 The implementation may also prepend a single empty line before the for‐
137 mat shown here.
138
140 None.
141
143 None.
144
146 If the utility utility is invoked, the exit status of time shall be the
147 exit status of utility; otherwise, the time utility shall exit with one
148 of the following values:
149 1‐125 An error occurred in the time utility.
151 126 The utility specified by utility was found but could not be
153 invoked.
154 127 The utility specified by utility could not be found.
156
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
169 confused 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 POSIX.1‐2017 are vague, so the numeric output could not be compared
197 accurately between systems or even between invocations.
198 * The creation of portable benchmark programs was outside the scope
200 this volume of POSIX.1‐2017.
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 POSIX.1‐2017.
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 Chapter 2, Shell Command Language, sh
233 The Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment
235 Variables, Section 12.2, Utility Syntax Guidelines
236 The System Interfaces volume of POSIX.1‐2017, times()
238
240 Portions of this text are reprinted and reproduced in electronic form
241 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
242 table Operating System Interface (POSIX), The Open Group Base Specifi‐
243 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
244 Electrical and Electronics Engineers, Inc and The Open Group. In the
245 event of any discrepancy between this version and the original IEEE and
246 The Open Group Standard, the original IEEE and The Open Group Standard
247 is the referee document. The original Standard can be obtained online
248 at http://www.opengroup.org/unix/online.html .
249 Any typographical or formatting errors that appear in this page are
251 most likely to have been introduced during the conversion of the source
252 files to man page format. To report such errors, see https://www.ker‐
253 nel.org/doc/man-pages/reporting_bugs.html .
254IEEE/The Open Group 2017 TIME(1P)