1TIME(1P)                   POSIX Programmer's Manual                  TIME(1P)
2
3
4

PROLOG

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
11

NAME

13       time — time a simple command
14

SYNOPSIS

16       time [−p] utility [argument...]
17

DESCRIPTION

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
24        *  The  elapsed (real) time between invocation of utility and its ter‐
25           mination.
26
27        *  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
32        *  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
36       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
42       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
48           time a | b | c    { time a; } | b | c
49           a | b | time c    a | b | (time c)
50

OPTIONS

52       The  time  utility  shall  conform  to  the  Base Definitions volume of
53       POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
54
55       The following option shall be supported:
56
57       −p        Write the timing output to standard error in the format shown
58                 in the STDERR section.
59

OPERANDS

61       The following operands shall be supported:
62
63       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
68       argument  Any string to be supplied as an argument  when  invoking  the
69                 utility named by the utility operand.
70

STDIN

72       Not used.
73

INPUT FILES

75       None.
76

ENVIRONMENT VARIABLES

78       The following environment variables shall affect the execution of time:
79
80       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
86       LC_ALL    If  set  to  a non-empty string value, override the values of
87                 all the other internationalization variables.
88
89       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
93       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
98       LC_NUMERIC
99                 Determine the locale for numeric formatting.
100
101       NLSPATH   Determine the location of message catalogs for the processing
102                 of LC_MESSAGES.
103
104       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

ASYNCHRONOUS EVENTS

109       Default.
110

STDOUT

112       Not used.
113

STDERR

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
118           "real %f\nuser %f\nsys %f\n", <real seconds>, <user seconds>,
119               <system seconds>
120
121       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

OUTPUT FILES

133       None.
134

EXTENDED DESCRIPTION

136       None.
137

EXIT STATUS

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
143       1‐125   An error occurred in the time utility.
144
145         126   The  utility  specified  by  utility was found but could not be
146               invoked.
147
148         127   The utility specified by utility could not be found.
149

CONSEQUENCES OF ERRORS

151       Default.
152
153       The following sections are informative.
154

APPLICATION USAGE

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

EXAMPLES

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
176       Alternatively,  the  following  command  can be used to apply time to a
177       complex command:
178
179           time sh −c 'complex-command-line'
180

RATIONALE

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
187        *  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
191        *  The  creation  of portable benchmark programs was outside the scope
192           this volume of POSIX.1‐2008.
193
194       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
200       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
205       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
215       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

FUTURE DIRECTIONS

221       None.
222

SEE ALSO

224       Chapter 2, Shell Command Language, sh
225
226       The Base Definitions volume of  POSIX.1‐2008,  Chapter  8,  Environment
227       Variables, Section 12.2, Utility Syntax Guidelines
228
229       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
243       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 .
247
248
249
250IEEE/The Open Group                  2013                             TIME(1P)
Impressum