1 files changed, 283 insertions, 0 deletions
diff --git a/man-pages-posix-2003/man1p/time.1p b/man-pages-posix-2003/man1p/time.1p
new file mode 100644
index 0000000..22bf445
--- /dev/null
+++ b/man-pages-posix-2003/man1p/time.1p
@@ -0,0 +1,283 @@
+.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
+.TH "TIME" 1P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
+.\" time 
+.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 \- 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 .