diff --git a/time/.md5sum b/time/.md5sum index 224e24e9..8cf8f831 100644 --- a/time/.md5sum +++ b/time/.md5sum @@ -1,2 +1,2 @@ -e38d2b8b34b1ca259cf7b053caac32b3 time-1.7.tar.gz -99e5fb64056521a3cacb95e74f5e527f time.1 +4e00dcb8c3ab11c7cf5a0d698828ac96 time-1.8.tar.gz +806916903fc6f4dad8b8ca17eea9700f time.1 diff --git a/time/.signature b/time/.signature index 42675d07..6630d8d3 100644 --- a/time/.signature +++ b/time/.signature @@ -1,6 +1,6 @@ untrusted comment: verify with /etc/ports/core.pub -RWRJc1FUaeVeqhSBeZoSrPm47u5UvWTm6Vo1G3RY7Nxqefb7gKFKRWNWQs1yw/DydKeNGFb+OC+RMCfh00bsR2mnS0MEYSf7mQw= -SHA256 (Pkgfile) = 080e86bb02170324fff1f5aeacad619e3ae83f549a3cf5d4619f13dbc16b46d1 +RWRJc1FUaeVeqsj4MZj18SRK4LqJx6D2Llmtwez6gPJw5uRsqWXaozOu92s6ilEMu41RJHoAJEN0VIGuNSKThNtvCCBBohpC7AE= +SHA256 (Pkgfile) = 31924103f46c51400f548cad613820ccda62fc1048e94f3f7af7e501cb4f4903 SHA256 (.footprint) = 8d45d3309f85fd281fdef9758d5d1fa11441e1e9e164dbc8f56fc1cbd3623229 -SHA256 (time-1.7.tar.gz) = e37ea79a253bf85a85ada2f7c632c14e481a5fd262a362f6f4fd58e68601496d -SHA256 (time.1) = 59e5b690d1ba49e9c247b8a21babc250a0fb21f12f8357461b69a30aafbc3818 +SHA256 (time-1.8.tar.gz) = 8a2f540155961a35ba9b84aec5e77e3ae36c74cecb4484db455960601b7a2e1b +SHA256 (time.1) = a67e6b465db538cc8a484431951cf9f0d2fa5399bd5f2fb566f8d440eb18a565 diff --git a/time/Pkgfile b/time/Pkgfile index 3ab18296..1f688c1c 100644 --- a/time/Pkgfile +++ b/time/Pkgfile @@ -3,16 +3,15 @@ # Maintainer: CRUX System Team, core-ports at crux dot nu name=time -version=1.7 -release=3 +version=1.8 +release=1 source=(http://ftpmirror.gnu.org/gnu/$name/$name-$version.tar.gz $name.1) build() { cd $name-$version - autoreconf - ./configure --prefix=/usr --infodir=$PKG/usr/info + ./configure --prefix=/usr make - make prefix=$PKG/usr install - rm -rf $PKG/usr/info + make DESTDIR=$PKG install + rm -r $PKG/usr/share/info install -D -m 0644 $SRC/$name.1 $PKG/usr/share/man/man1/$name.1 } diff --git a/time/time.1 b/time/time.1 index 29d12657..37375efd 100644 --- a/time/time.1 +++ b/time/time.1 @@ -1,270 +1,325 @@ -.\" Copyright Andries Brouwer, 2000 -.\" -.\" This page is distributed under GPL. -.\" Some fragments of text came from the time-1.7 info file. -.\" Inspired by kromJx@crosswinds.net. -.\" -.TH TIME 1 "11 December 2000" "" "" +.\" Man page added by Dirk Eddelbuettel on 15 Apr 1996 +.\" Thanks to Herbert Thielen for a patch +.\" Copyright (C) Dirk Eddelbuettel but freely redistributable +.TH TIME 1 "Debian GNU/Linux" +.\" Always turn off hyphenation; it makes way too many mistakes in +.\" technical documents. +.nh .SH NAME -time \- time a simple command or give resource usage +time \- run programs and summarize system resource usage .SH SYNOPSIS -.BI "time [" options "] " command " [" arguments... "] " -.SH DESCRIPTION -The +.na +.TP .B time -command runs the specified program -.I command -with the given arguments. +[ +.B \-apqvV +] [ +.BI \-f " FORMAT" +] [ +.BI \-o " FILE" +] +.br +[ +.B \-\-append +] [ +.B \-\-verbose +] [ +.B \-\-quiet +] [ +.B \-\-portability +] +.br +[ +.BI \-\-format= "FORMAT" +] [ +.BI \-\-output= "FILE" +] [ +.B \-\-version +] +.br +[ +.B \-\-help +] +.I COMMAND +[ +.I ARGS +] +.ad b +.\" For nroff, turn off justification. +.if n .ad l +.SH DESCRIPTION +.B time +run the program +.I COMMAND +with any given arguments +.IR "ARG..." . When -.I command +.I COMMAND finishes, .B time -writes a message to standard output 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)). -.SH OPTION -.TP -.B \-p -When in the POSIX locale, use the precise traditional format -.br -.in +5 -"real %f\enuser %f\ensys %f\en" -.in -5 -.br -(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 ENVIRONMENT -The variables LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, LC_NUMERIC, -NLSPATH and PATH are used. The last one to search for -.IR command . -The remaining ones for the text and formatting of the output. -.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-125) if something else went wrong. -.SH "SEE ALSO" -.BR times (2), -.sp 2 -.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 \-f option or the TIME environment variable. -.LP -The default format string is -.br -.in +3 -%Uuser %Ssystem %Eelapsed %PCPU (%Xtext+%Ddata %Mmax)k -.br -%Iinputs+%Ooutputs (%Fmajor+%Rminor)pagefaults %Wswaps -.br -.in -3 -.LP -When the \-p option is given the (portable) output format -.br -.in +3 -real %e -.br -user %U -.br -sys %S -.br -.in -3 +displays information about resources used by +.I COMMAND +(on the standard error output, by default). If +.I COMMAND +exits with non\-zero status, +.B time +displays a warning message and the exit status. + +.B time +determines which information to display about the resources used by the +.I COMMAND +from the string +.IR FORMAT . +If no format is specified on the command line, but the +.B TIME +environment variable is set, its value is used as the format. +Otherwise, a default format built into +.B time is used. -.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 + +Options to .B time -will always add a trailing newline itself. -The conversions follow. All of those used by +must appear on the command line before +.IR COMMAND . +Anything on the command line after +.I COMMAND +is passed as arguments to +.IR COMMAND . + +.SH OPTIONS +.TP +.BI \-o " FILE, " \-\-output= "FILE " +Write the resource use statistics to +.I FILE +instead of to the standard error stream. By default, this overwrites the +file, destroying the file's previous contents. This option is useful for +collecting information on interactive programs and programs that produce +output on the standard error stream. +.TP +.BR \-a ", " \-\-append "" +Append the resource use information to the output file instead of overwriting +it. This option is only useful with the `\-o' or `\-\-output' option. +.TP +.BI \-f " FORMAT, " \-\-format " FORMAT " +Use +.I FORMAT +as the format string that controls the output of +.BR time . +See the below more information. +.TP +.B \-\-help +Print a summary of the command line options and exit. +.TP +.BR \-p ", " \-\-portability "" +Use the following format string, for conformance with POSIX standard 1003.2: + real %e + user %U + sys %S +.TP +.BR \-v ", " \-\-verbose "" +Use the built\-in verbose format, which displays each available piece of +information on the program's resource use on its own line, with an English +description of its meaning. +.TP +.B \-\-quiet +Do not report the status of the program even if it is different from zero. +.TP +.BR \-V ", " \-\-version "" +Print the version number of +.B time +and exit. + +.SH "FORMATTING THE OUTPUT" +The format string +.I FORMAT +controls the contents of the +.B time +output. The format string can be set using the `\-f' or `\-\-format', `\-v' or +`\-\-verbose', or `\-p' or `\-\-portability' options. If they are not +given, but the +.I TIME +environment variable is set, its value is used as the format string. +Otherwise, a built\-in default format is used. The default format is: + %Uuser %Ssystem %Eelapsed %PCPU (%Xtext+%Ddata %Mmax)k + %Iinputs+%Ooutputs (%Fmajor+%Rminor)pagefaults %Wswaps + +The format string usually consists of `resource specifiers' +interspersed with plain text. A percent sign (`%') in the format +string causes the following character to be interpreted as a resource +specifier, which is similar to the formatting characters in the +.BR printf (3) +function. + +A backslash (`\\') introduces a `backslash escape', which is +translated into a single printing character upon output. `\\t' outputs +a tab character, `\\n' outputs a newline, and `\\\\' outputs a backslash. +A backslash followed by any other character outputs a question mark +(`?') followed by a backslash, to indicate that an invalid backslash +escape was given. + +Other text in the format string is copied verbatim to the output. +.B time +always prints a newline after printing the resource use +information, so normally format strings do not end with a newline +character (or `\en'). + +There are many resource specifications. Not all resources are +measured by all versions of Unix, so some of the values might be +reported as zero. Any character following a percent sign that is not +listed in the table below causes a question mark (`?') to be output, +followed by that character, to indicate that an invalid resource +specifier was given. + +.\" No blank line between the resource specifiers below so that they +.\" are more compactly listed. +.PD 0 +The resource specifiers, which are a superset of those recognized by the .BR tcsh (1) -are supported. -.LP -.B "Time" -.TP -.B %E -Elapsed real time (in [hours:]minutes:seconds). -.TP -.B %e -(Not in tcsh.) 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. -.LP -.B "Memory" -.TP -.B %M -Maximum resident set size of the process during its lifetime, in Kbytes. -.TP -.B %t -(Not in tcsh.) 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 tcsh.) 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 tcsh.) 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. -.LP -.B "I/O" -.TP -.B %I +builtin `time' command, are: +.RS +.IP % +A literal `%'. +.IP C +Name and command line arguments of the command being timed. +.IP D +Average size of the process's unshared data area, in Kilobytes. +.IP E +Elapsed real (wall clock) time used by the process, in [hours:]minutes:seconds. +.IP F +Number of major, or I/O\-requiring, page faults that occurred while +the process was running. These are faults where the page has +actually migrated out of primary memory. +.IP I Number of file system inputs by the process. -.TP -.B %O +.IP K +Average total (data+stack+text) memory use of the process, in +Kilobytes. +.IP M +Maximum resident set size of the process during its lifetime, in +Kilobytes. +.IP O Number of file system 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 +.IP P +Percentage of the CPU that this job got. This is just user + +system times divided by the total running time. It also prints +a percentage sign. +.IP R +Number of minor, or recoverable, page faults. These are pages +that are not valid (so they fault) 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. +.IP S +Total number of CPU\-seconds used by the system on behalf of the +process (in kernel mode), in seconds. +.IP U +Total number of CPU\-seconds that the process used directly (in user +mode), in seconds. +.IP W +Number of times the process was swapped out of main memory. +.IP X +Average amount of shared text in the process, in Kilobytes. +.IP Z +System's page size, in bytes. This is a per\-system constant, but +varies between systems. +.IP c +Number of times the process was context\-switched involuntarily +(because the time slice expired). +.IP e +Elapsed real (wall clock) time used by the process, in seconds. +.IP k Number of signals delivered to the process. -.TP -.B %C -(Not in tcsh.) Name and command line arguments of the command being timed. -.TP -.B %x -(Not in tcsh.) Exit status of the command. -.SH "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 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. -.SH "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. -.LP -GNU time version 1.7 is not yet localized. -Thus, it does not implement the POSIX requirements. -.LP -The environment variable TIME was badly chosen. -It is not unusual for systems like autoconf or make -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 path names) tend to lead to difficulties. -.LP -It seems unfortunate that \-o overwrites instead of appends. -(That is, the \-a option should be the default.) -.LP -Mail suggestions and bug reports for GNU +.IP p +Average unshared stack size of the process, in Kilobytes. +.IP r +Number of socket messages received by the process. +.IP s +Number of socket messages sent by the process. +.IP t +Average resident set size of the process, in Kilobytes. +.IP w +Number of times that the program was context\-switched voluntarily, +for instance while waiting for an I/O operation to complete. +.IP x +Exit status of the command. +.RS + +.SH EXAMPLES +To run the command `wc /etc/hosts' and show the default information: + time wc /etc/hosts + +To run the command `ls \-Fs' and show just the user, system, and total +time: + time \-f "\et%E real,\et%U user,\et%S sys" ls \-Fs + +To edit the file BORK and have `time' append the elapsed time and +number of signals to the file `log', reading the format string from the +environment variable `TIME': + export TIME="\et%E,\et%k" # If using bash or ksh + setenv TIME "\et%E,\et%k" # If using csh or tcsh + time \-a \-o log emacs bork + +Users of the +.B bash +shell need to use an explicit path in order to run the external .B time -to -.br -.I bug-utils@prep.ai.mit.edu -.br -Please include the version of -.B time , -which you can get by running -.br -.I time --version -.br -and the operating system -and C compiler you used. +command and not the shell builtin variant. On system where +.B time +is installed in +.IR /usr/bin , +the first example would become + /usr/bin/time wc /etc/hosts + +.SH ACCURACY +The elapsed time is not collected atomically with the execution of +the program; as a result, in bizarre circumstances (if the +.B time +command gets stopped or swapped out in between when the program being +timed exits and when +.B time +calculates how long it took to run), it +could be much larger than the actual execution time. + +When the running time of a command is very nearly zero, some values +(e.g., the percentage of CPU used) may be reported as either zero (which +is wrong) or a question mark. + +Most information shown by +.B time +is derived from the +.BR wait3 (2) +system call. The numbers are only as good as +those returned by +.BR wait3 (2). +On systems that do not have a +.BR wait3 (2) +call that returns status information, the +.BR times (2) +system call is used instead. However, it provides much less information than +.BR wait3 (2), +so on those systems +.B time +reports the majority of the resources as zero. + +The `%I' and `%O' values are allegedly only `real' input and output +and do not include those supplied by caching devices. The meaning of +`real' I/O reported by `%I' and `%O' may be muddled for workstations, +especially diskless ones. + +.SH DIAGNOSTICS +The +.B time +command returns when the program exits, stops, or is terminated by a signal. +If the program exited normally, the return value of +.B time +is the return value of the program it executed and measured. Otherwise, the +return value is 128 plus the number of the signal which caused the program to +stop or terminate. +.SH AUTHOR +.B time +was written by David MacKenzie. This man page was added by Dirk Eddelbuettel +, the Debian GNU/Linux maintainer, for use by the Debian +GNU/Linux distribution but may of course be used by others. + .SH "SEE ALSO" .BR tcsh (1), -.BR times (2), -.BR wait3 (2) -.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 +.BR printf (3)