diff options
Diffstat (limited to 'man-pages-posix-2017/man1p/time.1p')
-rw-r--r-- | man-pages-posix-2017/man1p/time.1p | 331 |
1 files changed, 331 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man1p/time.1p b/man-pages-posix-2017/man1p/time.1p new file mode 100644 index 0000000..790b2f2 --- /dev/null +++ b/man-pages-posix-2017/man1p/time.1p @@ -0,0 +1,331 @@ +'\" et +.TH TIME "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +time +\(em time a simple command +.SH SYNOPSIS +.LP +.nf +time \fB[\fR-p\fB] \fIutility \fB[\fIargument\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR time +utility shall invoke the utility named by the +.IR utility +operand with arguments supplied as the +.IR argument +operands and write a message to standard error that lists timing +statistics for the utility. The message shall include the following +information: +.IP " *" 4 +The elapsed (real) time between invocation of +.IR utility +and its termination. +.IP " *" 4 +The User CPU time, equivalent to the sum of the +.IR tms_utime +and +.IR tms_cutime +fields returned by the +\fItimes\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2017 for the process in which +.IR utility +is executed. +.IP " *" 4 +The System CPU time, equivalent to the sum of the +.IR tms_stime +and +.IR tms_cstime +fields returned by the +\fItimes\fR() +function for the process in which +.IR utility +is executed. +.P +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. +.P +When +.IR time +is used as part of a pipeline, the times reported are unspecified, +except when it is the sole command within a grouping command (see +.IR "Section 2.9.4.1" ", " "Grouping Commands") +in that pipeline. For example, the commands on the left are +unspecified; those on the right report on utilities +.BR a +and +.BR c , +respectively: +.sp +.RS 4 +.nf + +time a | b | c { time a; } | b | c +a | b | time c a | b | (time c) +.fi +.P +.RE +.SH OPTIONS +The +.IR time +utility shall conform to the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\-p\fP" 10 +Write the timing output to standard error in the format shown in the +STDERR section. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIutility\fR" 10 +The name of a utility that is to be invoked. If the +.IR utility +operand names any of the special built-in utilities in +.IR "Section 2.14" ", " "Special Built-In Utilities", +the results are undefined. +.IP "\fIargument\fR" 10 +Any string to be supplied as an argument when invoking the utility +named by the +.IR utility +operand. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR time : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +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). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic and informative messages written to standard +error. +.IP "\fILC_NUMERIC\fP" 10 +.br +Determine the locale for numeric formatting. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPATH\fP" 10 +Determine the search path that shall be used to locate the utility to +be invoked; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 8" ", " "Environment Variables". +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +If the +.IR utility +utility is invoked, the standard error shall be used to write the +timing statistics and may be used to write a diagnostic message if the +utility terminates abnormally; otherwise, the standard error shall be +used to write diagnostic messages and may also be used to write the +timing statistics. +.P +If +.BR \-p +is specified, the following format shall be used for the timing +statistics in the POSIX locale: +.sp +.RS 4 +.nf + +"real %f\enuser %f\ensys %f\en", <\fIreal seconds\fR>, <\fIuser seconds\fR>, + <\fIsystem seconds\fR> +.fi +.P +.RE +.P +where each floating-point number shall be expressed in seconds. The +precision used may be less than the default six digits of +.BR %f , +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. The implementation may also prepend a single empty line +before the format shown here. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +If the +.IR utility +utility is invoked, the exit status of +.IR time +shall be the exit status of +.IR utility ; +otherwise, the +.IR time +utility shall exit with one of the following values: +.IP "1\(hy125" 8 +An error occurred in the +.IR time +utility. +.IP "\0\0126" 8 +The utility specified by +.IR utility +was found but could not be invoked. +.IP "\0\0127" 8 +The utility specified by +.IR utility +could not be found. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR command , +.IR env , +.IR nice , +.IR nohup , +.IR time , +and +.IR 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 +.IR exec +the utility fail with +.BR [ENOENT] , +and uses 126 when any attempt to +.IR exec +the utility fails for any other reason. +.SH EXAMPLES +It is frequently desirable to apply +.IR 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 +.IR time +applies to everything in the file. +.P +Alternatively, the following command can be used to apply +.IR time +to a complex command: +.sp +.RS 4 +.nf + +time sh -c \(aq\fIcomplex-command-line\fP\(aq +.fi +.P +.RE +.SH RATIONALE +When the +.IR time +utility was originally proposed to be included in the ISO\ POSIX\(hy2:\|1993 standard, +questions were raised about its suitability for inclusion on +the grounds that it was not useful for conforming applications, +specifically: +.IP " *" 4 +The underlying CPU definitions from the System Interfaces volume of POSIX.1\(hy2017 are +vague, so the numeric output could not be compared accurately between +systems or even between invocations. +.IP " *" 4 +The creation of portable benchmark programs was outside the scope this volume of POSIX.1\(hy2017. +.P +However, +.IR time +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 POSIX.1\(hy2017. +.P +The default output format has been left unspecified because historical +implementations differ greatly in their style of depicting this numeric +output. The +.BR \-p +option was invented to provide scripts with a common means of obtaining +this information. +.P +In the KornShell, +.IR time +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 +.IR time +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. +.P +The term +.IR utility +is used, rather than +.IR command , +to highlight the fact that shell compound commands, pipelines, special +built-ins, and so on, cannot be used directly. +However, +.IR utility +includes user application programs and shell scripts, not just the +standard utilities. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIsh\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2017, +.IR "\fItimes\fR\^(\|)" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 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 . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |