Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 329 insertions, 0 deletions

diff --git a/man/man1/time.1 b/man/man1/time.1
new file mode 100644
index 0000000..eb80248
--- /dev/null
+++ b/man/man1/time.1
@@ -0,0 +1,329 @@
+.\" Copyright Andries Brouwer, 2000
+.\" Some fragments of text came from the time-1.7 info file.
+.\" Inspired by kromJx@crosswinds.net.
+.\"
+.\" SPDX-License-Identifier: GPL-1.0-or-later
+.\"
+.TH time 1 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+time \- time a simple command or give resource usage
+.SH SYNOPSIS
+.B time
+.RI [ option \~.\|.\|.\&] " command " [ argument \~.\|.\|.]
+.SH DESCRIPTION
+The
+.B time
+command runs the specified program
+.I command
+with the given arguments.
+When
+.I command
+finishes,
+.B time
+writes a message to standard error giving timing statistics
+about this program run.
+These statistics consist of (i) the elapsed real time
+between invocation and termination, (ii) the user CPU time
+(the sum of the
+.I tms_utime
+and
+.I tms_cutime
+values in a
+.I "struct tms"
+as returned by
+.BR times (2)),
+and (iii) the system CPU time (the sum of the
+.I  tms_stime
+and
+.I tms_cstime
+values in a
+.I "struct tms"
+as returned by
+.BR times (2)).
+.P
+Note: some shells (e.g.,
+.BR bash (1))
+have a built-in
+.B time
+command that provides similar information on the usage of time and
+possibly other resources.
+To access the real command, you may need to specify its pathname
+(something like
+.IR /usr/bin/time ).
+.SH OPTIONS
+.TP
+.B \-p
+When in the POSIX locale, use the precise traditional format
+.IP
+.in +4n
+.EX
+"real %f\enuser %f\ensys %f\en"
+.EE
+.in
+.IP
+(with numbers in seconds)
+where the number of decimals in the output for %f is unspecified
+but is sufficient to express the clock tick accuracy, and at least one.
+.SH EXIT STATUS
+If
+.I command
+was invoked, the exit status is that of
+.IR command .
+Otherwise, it is 127 if
+.I command
+could not be found, 126 if it could be found but could not be invoked,
+and some other nonzero value (1\[en]125) if something else went wrong.
+.SH ENVIRONMENT
+The variables
+.BR LANG ,
+.BR LC_ALL ,
+.BR LC_CTYPE ,
+.BR LC_MESSAGES ,
+.BR LC_NUMERIC ,
+and
+.B NLSPATH
+are used for the text and formatting of the output.
+.B PATH
+is used to search for
+.IR command .
+.SH GNU VERSION
+Below a description of the GNU 1.7 version of
+.BR time .
+Disregarding the name of the utility, GNU makes it output lots of
+useful information, not only about time used, but also on other
+resources like memory, I/O and IPC calls (where available).
+The output is formatted using a format string that can be specified
+using the
+.I \-f
+option or the
+.B TIME
+environment variable.
+.P
+The default format string is:
+.P
+.in +4n
+.EX
+%Uuser %Ssystem %Eelapsed %PCPU (%Xtext+%Ddata %Mmax)k
+%Iinputs+%Ooutputs (%Fmajor+%Rminor)pagefaults %Wswaps
+.EE
+.in
+.P
+When the
+.I \-p
+option is given, the (portable) output format is used:
+.P
+.in +4n
+.EX
+real %e
+user %U
+sys %S
+.EE
+.in
+.\"
+.SS The format string
+The format is interpreted in the usual printf-like way.
+Ordinary characters are directly copied, tab, newline,
+and backslash are escaped using \et, \en, and \e\e,
+a percent sign is represented by %%, and otherwise %
+indicates a conversion.
+The program
+.B time
+will always add a trailing newline itself.
+The conversions follow.
+All of those used by
+.BR tcsh (1)
+are supported.
+.P
+.B "Time"
+.TP
+.B %E
+Elapsed real time (in [hours:]minutes:seconds).
+.TP
+.B %e
+(Not in
+.BR tcsh (1).)
+Elapsed real time (in seconds).
+.TP
+.B %S
+Total number of CPU-seconds that the process spent in kernel mode.
+.TP
+.B %U
+Total number of CPU-seconds that the process spent in user mode.
+.TP
+.B %P
+Percentage of the CPU that this job got, computed as (%U + %S) / %E.
+.P
+.B "Memory"
+.TP
+.B %M
+Maximum resident set size of the process during its lifetime, in Kbytes.
+.TP
+.B %t
+(Not in
+.BR tcsh (1).)
+Average resident set size of the process, in Kbytes.
+.TP
+.B %K
+Average total (data+stack+text) memory use of the process,
+in Kbytes.
+.TP
+.B %D
+Average size of the process's unshared data area, in Kbytes.
+.TP
+.B %p
+(Not in
+.BR tcsh (1).)
+Average size of the process's unshared stack space, in Kbytes.
+.TP
+.B %X
+Average size of the process's shared text space, in Kbytes.
+.TP
+.B %Z
+(Not in
+.BR tcsh (1).)
+System's page size, in bytes.
+This is a per-system constant, but varies between systems.
+.TP
+.B %F
+Number of major page faults that occurred while the process was running.
+These are faults where the page has to be read in from disk.
+.TP
+.B %R
+Number of minor, or recoverable, page faults.
+These are faults for pages that are not valid but which have
+not yet been claimed by other virtual pages.
+Thus the data
+in the page is still valid but the system tables must be updated.
+.TP
+.B %W
+Number of times the process was swapped out of main memory.
+.TP
+.B %c
+Number of times the process was context-switched involuntarily
+(because the time slice expired).
+.TP
+.B %w
+Number of waits: times that the program was context-switched voluntarily,
+for instance while waiting for an I/O operation to complete.
+.P
+.B "I/O"
+.TP
+.B %I
+Number of filesystem inputs by the process.
+.TP
+.B %O
+Number of filesystem outputs by the process.
+.TP
+.B %r
+Number of socket messages received by the process.
+.TP
+.B %s
+Number of socket messages sent by the process.
+.TP
+.B %k
+Number of signals delivered to the process.
+.TP
+.B %C
+(Not in
+.BR tcsh (1).)
+Name and command-line arguments of the command being timed.
+.TP
+.B %x
+(Not in
+.BR tcsh (1).)
+Exit status of the command.
+.SS GNU options
+.TP
+.BI "\-f " format ", \-\-format=" format
+Specify output format, possibly overriding the format specified
+in the environment variable TIME.
+.TP
+.B "\-p, \-\-portability"
+Use the portable output format.
+.TP
+.BI "\-o " file ", \-\-output=" file
+Do not send the results to
+.IR stderr ,
+but overwrite the specified file.
+.TP
+.B "\-a, \-\-append"
+(Used together with \-o.) Do not overwrite but append.
+.TP
+.B "\-v, \-\-verbose"
+Give very verbose output about all the program knows about.
+.TP
+.B "\-q, \-\-quiet"
+Don't report abnormal program termination (where
+.I command
+is terminated by a signal) or nonzero exit status.
+.\"
+.SS GNU standard options
+.TP
+.B "\-\-help"
+Print a usage message on standard output and exit successfully.
+.TP
+.B "\-V, \-\-version"
+Print version information on standard output, then exit successfully.
+.TP
+.B "\-\-"
+Terminate option list.
+.SH BUGS
+Not all resources are measured by all versions of UNIX,
+so some of the values might be reported as zero.
+The present selection was mostly inspired by the data
+provided by 4.2 or 4.3BSD.
+.P
+GNU time version 1.7 is not yet localized.
+Thus, it does not implement the POSIX requirements.
+.P
+The environment variable
+.B TIME
+was badly chosen.
+It is not unusual for systems like
+.BR autoconf (1)
+or
+.BR make (1)
+to use environment variables with the name of a utility to override
+the utility to be used.
+Uses like MORE or TIME for options to programs
+(instead of program pathnames) tend to lead to difficulties.
+.P
+It seems unfortunate that
+.I \-o
+overwrites instead of appends.
+(That is, the
+.I \-a
+option should be the default.)
+.P
+Mail suggestions and bug reports for GNU
+.B time
+to
+.IR bug\-time@gnu.org .
+Please include the version of
+.BR time ,
+which you can get by running
+.P
+.in +4n
+.EX
+time \-\-version
+.EE
+.in
+.P
+and the operating system
+and C compiler you used.
+.\" .SH AUTHORS
+.\" .TP
+.\" .IP "David Keppel"
+.\" Original version
+.\" .IP "David MacKenzie"
+.\" POSIXization, autoconfiscation, GNU getoptization,
+.\" documentation, other bug fixes and improvements.
+.\" .IP "Arne Henrik Juul"
+.\" Helped with portability
+.\" .IP "Francois Pinard"
+.\" Helped with portability
+.SH SEE ALSO
+.BR bash (1),
+.BR tcsh (1),
+.BR times (2),
+.BR wait3 (2)