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
13 time — time a simple command
14
16 time [−p] utility [argument...]
17
19 The time utility shall invoke the utility named by the utility operand
20 with arguments supplied as the argument operands and write a message to
21 standard error that lists timing statistics for the utility. The mes‐
22 sage shall include the following information:
23 * The elapsed (real) time between invocation of utility and its ter‐
25 mination.
26 * The User CPU time, equivalent to the sum of the tms_utime and
28 tms_cutime fields returned by the times() function defined in the
29 System Interfaces volume of POSIX.1‐2008 for the process in which
30 utility is executed.
31 * The System CPU time, equivalent to the sum of the tms_stime and
33 tms_cstime fields returned by the times() function for the process
34 in which utility is executed.
35 The precision of the timing shall be no less than the granularity
37 defined for the size of the clock tick unit on the system, but the
38 results shall be reported in terms of standard time units (for example,
39 0.02 seconds, 00:00:00.02, 1m33.75s, 365.21 seconds), not numbers of
40 clock ticks.
41 When time is used as part of a pipeline, the times reported are unspec‐
43 ified, except when it is the sole command within a grouping command
44 (see Section 2.9.4.1, Grouping Commands) in that pipeline. For example,
45 the commands on the left are unspecified; those on the right report on
46 utilities a and c, respectively:
47 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‐2008, 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‐2008, 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‐2008, Chapter 8, Environment Variables.
107
109 Default.
110
112 Not used.
113
115 The standard error shall be used to write the timing statistics. If −p
116 is specified, the following format shall be used in the POSIX locale:
117 "real %f\nuser %f\nsys %f\n", <real seconds>, <user seconds>,
119 <system seconds>
120 where each floating-point number shall be expressed in seconds. The
122 precision used may be less than the default six digits of %f, but shall
123 be sufficiently precise to accommodate the size of the clock tick on
124 the system (for example, if there were 60 clock ticks per second, at
125 least two digits shall follow the radix character). The number of dig‐
126 its following the radix character shall be no less than one, even if
127 this always results in a trailing zero. The implementation may append
128 white space and additional information following the format shown here.
129 The implementation may also prepend a single empty line before the for‐
130 mat 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
151 Default.
152 The following sections are informative.
154
156 The command, env, nice, nohup, time, and xargs utilities have been
157 specified to use exit code 127 if an error occurs so that applications
158 can distinguish ``failure to find a utility'' from ``invoked utility
159 exited with an error indication''. The value 127 was chosen because it
160 is not commonly used for other meanings; most utilities use small val‐
161 ues for ``normal error conditions'' and the values above 128 can be
162 confused with termination due to receipt of a signal. The value 126 was
163 chosen in a similar manner to indicate that the utility could be found,
164 but not invoked. Some scripts produce meaningful error messages differ‐
165 entiating the 126 and 127 cases. The distinction between exit codes 126
166 and 127 is based on KornShell practice that uses 127 when all attempts
167 to exec the utility fail with [ENOENT], and uses 126 when any attempt
168 to exec the utility fails for any other reason.
169
171 It is frequently desirable to apply time to pipelines or lists of com‐
172 mands. This can be done by placing pipelines and command lists in a
173 single file; this file can then be invoked as a utility, and the time
174 applies to everything in the file.
175 Alternatively, the following command can be used to apply time to a
177 complex command:
178 time sh −c 'complex-command-line'
180
182 When the time utility was originally proposed to be included in the
183 ISO POSIX‐2:1993 standard, questions were raised about its suitability
184 for inclusion on the grounds that it was not useful for conforming
185 applications, specifically:
186 * The underlying CPU definitions from the System Interfaces volume of
188 POSIX.1‐2008 are vague, so the numeric output could not be compared
189 accurately between systems or even between invocations.
190 * The creation of portable benchmark programs was outside the scope
192 this volume of POSIX.1‐2008.
193 However, time does fit in the scope of user portability. Human judge‐
195 ment can be applied to the analysis of the output, and it could be very
196 useful in hands-on debugging of applications or in providing subjective
197 measures of system performance. Hence it has been included in this vol‐
198 ume of POSIX.1‐2008.
199 The default output format has been left unspecified because historical
201 implementations differ greatly in their style of depicting this numeric
202 output. The −p option was invented to provide scripts with a common
203 means of obtaining this information.
204 In the KornShell, time is a shell reserved word that can be used to
206 time an entire pipeline, rather than just a simple command. The POSIX
207 definition has been worded to allow this implementation. Consideration
208 was given to invalidating this approach because of the historical model
209 from the C shell and System V shell. However, since the System V time
210 utility historically has not produced accurate results in pipeline tim‐
211 ing (because the constituent processes are not all owned by the same
212 parent process, as allowed by POSIX), it did not seem worthwhile to
213 break historical KornShell usage.
214 The term utility is used, rather than command, to highlight the fact
216 that shell compound commands, pipelines, special built-ins, and so on,
217 cannot be used directly. However, utility includes user application
218 programs and shell scripts, not just the standard utilities.
219
221 None.
222
224 Chapter 2, Shell Command Language, sh
225 The Base Definitions volume of POSIX.1‐2008, Chapter 8, Environment
227 Variables, Section 12.2, Utility Syntax Guidelines
228 The System Interfaces volume of POSIX.1‐2008, times()
230
232 Portions of this text are reprinted and reproduced in electronic form
233 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
234 -- Portable Operating System Interface (POSIX), The Open Group Base
235 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
236 cal and Electronics Engineers, Inc and The Open Group. (This is
237 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
238 event of any discrepancy between this version and the original IEEE and
239 The Open Group Standard, the original IEEE and The Open Group Standard
240 is the referee document. The original Standard can be obtained online
241 at http://www.unix.org/online.html .
242 Any typographical or formatting errors that appear in this page are
244 most likely to have been introduced during the conversion of the source
245 files to man page format. To report such errors, see https://www.ker‐
246 nel.org/doc/man-pages/reporting_bugs.html .
247IEEE/The Open Group 2013 TIME(1P)