mirror of https://github.com/mkerrisk/man-pages
279 lines
9.4 KiB
Groff
279 lines
9.4 KiB
Groff
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "TIME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" time
|
|
.SH NAME
|
|
time \- time a simple command
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fBtime\fP \fB[\fP\fB-p\fP\fB]\fP \fIutility\fP
|
|
\fB[\fP\fIargument\fP\fB...\fP\fB]\fP\fB\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fItime\fP utility shall invoke the utility named by the \fIutility\fP
|
|
operand with arguments supplied as the
|
|
\fIargument\fP operands and write a message to standard error that
|
|
lists timing statistics for the utility. The message shall
|
|
include the following information:
|
|
.IP " *" 3
|
|
The elapsed (real) time between invocation of \fIutility\fP and its
|
|
termination.
|
|
.LP
|
|
.IP " *" 3
|
|
The User CPU time, equivalent to the sum of the \fItms_utime\fP and
|
|
\fItms_cutime\fP fields returned by the \fItimes\fP() function defined
|
|
in the System Interfaces volume of IEEE\ Std\ 1003.1-2001 for
|
|
the process in which \fIutility\fP is executed.
|
|
.LP
|
|
.IP " *" 3
|
|
The System CPU time, equivalent to the sum of the \fItms_stime\fP
|
|
and \fItms_cstime\fP fields returned by the \fItimes\fP() function
|
|
for the process in which \fIutility\fP is executed.
|
|
.LP
|
|
.LP
|
|
The precision of the timing shall be no less than the granularity
|
|
defined for the size of the clock tick unit on the system, but
|
|
the results shall 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.
|
|
.LP
|
|
When \fItime\fP is used as part of a pipeline, the times reported
|
|
are unspecified, except when it is the sole command within a
|
|
grouping command (see \fIGrouping Commands\fP ) in that pipeline.
|
|
For example, the
|
|
commands on the left are unspecified; those on the right report on
|
|
utilities \fBa\fP and \fBc\fP, respectively:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBtime a | b | c { time a } | b | c
|
|
a | b | time c a | b | (time c)
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.SH OPTIONS
|
|
.LP
|
|
The \fItime\fP utility shall conform to the Base Definitions volume
|
|
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
|
|
.LP
|
|
The following option shall be supported:
|
|
.TP 7
|
|
\fB-p\fP
|
|
Write the timing output to standard error in the format shown in the
|
|
STDERR section.
|
|
.sp
|
|
.SH OPERANDS
|
|
.LP
|
|
The following operands shall be supported:
|
|
.TP 7
|
|
\fIutility\fP
|
|
The name of a utility that is to be invoked. If the \fIutility\fP
|
|
operand names any of the special built-in utilities in \fISpecial
|
|
Built-In Utilities\fP , the results are undefined.
|
|
.TP 7
|
|
\fIargument\fP
|
|
Any string to be supplied as an argument when invoking the utility
|
|
named by the \fIutility\fP operand.
|
|
.sp
|
|
.SH STDIN
|
|
.LP
|
|
Not used.
|
|
.SH INPUT FILES
|
|
.LP
|
|
None.
|
|
.SH ENVIRONMENT VARIABLES
|
|
.LP
|
|
The following environment variables shall affect the execution of
|
|
\fItime\fP:
|
|
.TP 7
|
|
\fILANG\fP
|
|
Provide a default value for the internationalization variables that
|
|
are unset or null. (See the Base Definitions volume of
|
|
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
|
|
for
|
|
the precedence of internationalization variables used to determine
|
|
the values of locale categories.)
|
|
.TP 7
|
|
\fILC_ALL\fP
|
|
If set to a non-empty string value, override the values of all the
|
|
other internationalization variables.
|
|
.TP 7
|
|
\fILC_CTYPE\fP
|
|
Determine the locale for the interpretation of sequences of bytes
|
|
of text data as characters (for example, single-byte as
|
|
opposed to multi-byte characters in arguments).
|
|
.TP 7
|
|
\fILC_MESSAGES\fP
|
|
Determine the locale that should be used to affect the format and
|
|
contents of diagnostic and informative messages written to
|
|
standard error.
|
|
.TP 7
|
|
\fILC_NUMERIC\fP
|
|
.sp
|
|
Determine the locale for numeric formatting.
|
|
.TP 7
|
|
\fINLSPATH\fP
|
|
Determine the location of message catalogs for the processing of \fILC_MESSAGES
|
|
\&.\fP
|
|
.TP 7
|
|
\fIPATH\fP
|
|
Determine the search path that shall be used to locate the utility
|
|
to be invoked; see the Base Definitions volume of
|
|
IEEE\ Std\ 1003.1-2001, Chapter 8, Environment Variables.
|
|
.sp
|
|
.SH ASYNCHRONOUS EVENTS
|
|
.LP
|
|
Default.
|
|
.SH STDOUT
|
|
.LP
|
|
Not used.
|
|
.SH STDERR
|
|
.LP
|
|
The standard error shall be used to write the timing statistics. If
|
|
\fB-p\fP is specified, the following format shall be used
|
|
in the POSIX locale:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB"real %f\\nuser %f\\nsys %f\\n", <\fP\fIreal seconds\fP\fB>, <\fP\fIuser seconds\fP\fB>,
|
|
<\fP\fIsystem seconds\fP\fB>
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
where each floating-point number shall be expressed in seconds. The
|
|
precision used may be less than the default six digits of
|
|
\fB%f\fP , but shall be sufficiently precise to accommodate the size
|
|
of the clock tick on the system (for example, if there were
|
|
60 clock ticks per second, at least two digits shall follow the radix
|
|
character). The number of digits following the radix
|
|
character shall be no less than one, even if this always results in
|
|
a trailing zero. The implementation may append white space and
|
|
additional information following the format shown here.
|
|
.SH OUTPUT FILES
|
|
.LP
|
|
None.
|
|
.SH EXTENDED DESCRIPTION
|
|
.LP
|
|
None.
|
|
.SH EXIT STATUS
|
|
.LP
|
|
If the \fIutility\fP utility is invoked, the exit status of \fItime\fP
|
|
shall be the exit status of \fIutility\fP; otherwise,
|
|
the \fItime\fP utility shall exit with one of the following values:
|
|
.TP 7
|
|
1-125
|
|
An error occurred in the \fItime\fP utility.
|
|
.TP 7
|
|
\ \ 126
|
|
The utility specified by \fIutility\fP was found but could not be
|
|
invoked.
|
|
.TP 7
|
|
\ \ 127
|
|
The utility specified by \fIutility\fP could not be found.
|
|
.sp
|
|
.SH CONSEQUENCES OF ERRORS
|
|
.LP
|
|
Default.
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
The \fIcommand\fP, \fIenv\fP, \fInice\fP, \fInohup\fP, \fItime\fP,
|
|
and \fIxargs\fP 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
|
|
\fIexec\fP the utility fail with [ENOENT], and uses 126 when any attempt
|
|
to \fIexec\fP the utility fails for any other
|
|
reason.
|
|
.SH EXAMPLES
|
|
.LP
|
|
It is frequently desirable to apply \fItime\fP 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 \fItime\fP applies to everything in the
|
|
file.
|
|
.LP
|
|
Alternatively, the following command can be used to apply \fItime\fP
|
|
to a complex command:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBtime sh -c '\fP\fIcomplex-command-line\fP\fB'
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.SH RATIONALE
|
|
.LP
|
|
When the \fItime\fP utility was originally proposed to be included
|
|
in the ISO\ POSIX-2:1993 standard, questions were raised
|
|
about its suitability for inclusion on the grounds that it was not
|
|
useful for conforming applications, specifically:
|
|
.IP " *" 3
|
|
The underlying CPU definitions from the System Interfaces volume of
|
|
IEEE\ Std\ 1003.1-2001 are vague, so the numeric
|
|
output could not be compared accurately between systems or even between
|
|
invocations.
|
|
.LP
|
|
.IP " *" 3
|
|
The creation of portable benchmark programs was outside the scope
|
|
this volume of IEEE\ Std\ 1003.1-2001.
|
|
.LP
|
|
.LP
|
|
However, \fItime\fP does fit in the scope of user portability. Human
|
|
judgement can be applied to the analysis of the output,
|
|
and it could be very useful in hands-on debugging of applications
|
|
or in providing subjective measures of system performance. Hence
|
|
it has been included in this volume of IEEE\ Std\ 1003.1-2001.
|
|
.LP
|
|
The default output format has been left unspecified because historical
|
|
implementations differ greatly in their style of
|
|
depicting this numeric output. The \fB-p\fP option was invented to
|
|
provide scripts with a common means of obtaining this
|
|
information.
|
|
.LP
|
|
In the KornShell, \fItime\fP is a shell reserved word that can be
|
|
used to time an entire pipeline, rather than just a simple
|
|
command. The POSIX definition has been worded to allow this implementation.
|
|
Consideration was given to invalidating this approach
|
|
because of the historical model from the C shell and System V shell.
|
|
However, since the System V \fItime\fP utility historically
|
|
has not produced accurate results in pipeline timing (because the
|
|
constituent processes are not all owned by the same parent
|
|
process, as allowed by POSIX), it did not seem worthwhile to break
|
|
historical KornShell usage.
|
|
.LP
|
|
The term \fIutility\fP is used, rather than \fIcommand\fP, to highlight
|
|
the fact that shell compound commands, pipelines,
|
|
special built-ins, and so on, cannot be used directly. However, \fIutility\fP
|
|
includes user application programs and shell
|
|
scripts, not just the standard utilities.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIShell Command Language\fP , \fIsh\fP , the System Interfaces
|
|
volume of IEEE\ Std\ 1003.1-2001, \fItimes\fP()
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
event of any discrepancy between this version and the original IEEE and
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
is the referee document. The original Standard can be obtained online at
|
|
http://www.opengroup.org/unix/online.html .
|