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).