time(1)
time --
time a command
Synopsis
time [-p] command
Description
The time command invokes the command named by the
command operand with any arguments supplied as the
argument operands and writes a message to standard error
that lists timing statistics for the execution of the command.
The message includes the following information:
-
The elapsed (real) time between invocation of utility and its termination.
-
The User CPU time, equivalent to the sum of the ``tms_utime'' and
``tms_cutime'' fields returned by the
times(2)
function for the process in which command is executed.
-
The System CPU time, equivalent to the sum of the
``tms_stime'' and ``tms_cstime'' fields returned by the
times(2)
function for the process in which command
is executed.
The precision of the timing will be no less than the granularity
defined for the size of the clock tick unit on the system, but the
results will be reported in terms of standard time units (for example,
0.02 seconds, 00:00:00.02, 1m33.75s, 365.21 seconds), not numbers of
clock ticks.
When time is used as part of a pipeline, the times
reported are unspecified, except when find is the sole
command within a grouping command [see
sh(1)]
in that pipeline.
For example, the following two commands are unspecified:
time a | b | c
a | b | time c
The following two command lines report on utilities a
and c, respectively:
a | b | (time c)
{ time a } | b | c
Options
-p-
Write the standard error output in the format shown in ``Output''.
Operands
The following operands are supported:
command-
The name of a command that is to be invoked.
arguments-
Any string to be supplied as an argument when invoking the utility
named by the command operand.
Environment variables
The following environment variables affect the execution of time:
LANG-
Provide a default value for the internationalization variables that
are unset or null.
If LANG is unset or null, the corresponding value from the
implementation-specific default locale will be used.
If any of the internationalization variables contains an invalid
setting, the utility will behave as if none of the variables had been defined.
LC_ALL-
If set to a non-empty string value, override the values of all the
other internationalization variables.
LC_CTYPE-
Determine the locale for the interpretation of sequences of bytes of
text data as characters (for example, single- as opposed to multi-byte
characters in arguments).
LC_MESSAGES-
Determine the locale that should be used to affect the format and
contents of diagnostic and informative messages written to standard error.
LC_NUMERIC-
Determine the locale for numeric formatting.
PATH-
Determine the search path that will be used to locate the utility to
be invoked.
Output
The standard error will be used to write the timing statistics.
If -p is specified, the following format will be used:
real 0m0.00s
user 0m0.00s
sys 0m0.00s
where each floating-point number is expressed in seconds.
Exit codes
If the command is invoked, the exit status of time
is the exit status of the 1command; otherwise, the
time utility will exit with one of the following values:
exit values are returned:
1-125-
An error occurred in the time utility.
126-
The utility specified by command was found but could not be invoked.
127-
The utility specified by command could not be found.
Usage
The command, env, nice, nohup, time,
and xargs
utilities have been specified to use exit code 127 if an error occurs
so that applications can distinguish ``failure to find a utility''
from ``invoked utility exited with an error indication''.
The value
127 was chosen because it is not commonly used for other meanings;
most utilities use small values for ``normal error conditions'' and
the values above 128 can be confused with termination due to receipt
of a signal.
The value 126 was chosen in a similar manner to indicate
that the utility could be found, but not invoked.
Some scripts produce
meaningful error messages differentiating the 126 and 127 cases.
The distinction between exit codes 126 and 127 is based on KornShell
practice that uses 127 when all attempts to exec the utility
fail with ENOENT, and uses 126 when any attempt to exec
the utility fails for any other reason.
Examples
It is frequently desirable to apply time to pipelines or lists
of commands.
This can be done by placing pipelines and command lists in a single
file; this file can then be invoked as a utility, and the time
statistics apply to everything in the file.
Alternatively, backquotes (shell metacharacters) can be used to apply
time to a complex command:
time sh -c 'complex-command-line'
References
time(2),
timex(1),
sh(1)
(the times builtin command).
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004