Upstream-Status: Backport --- time-1.7.orig/configure.in +++ time-1.7/configure.in @@ -1,11 +1,8 @@ dnl Process this file with autoconf to produce a configure script. AC_INIT(time.c) -VERSION=1.7 -AC_SUBST(VERSION) -PACKAGE=time -AC_SUBST(PACKAGE) +AM_INIT_AUTOMAKE(time, 1.7) -AC_ARG_PROGRAM +AM_MAINTAINER_MODE dnl Checks for programs. AC_PROG_CC @@ -15,7 +12,7 @@ dnl Checks for header files. AC_HEADER_STDC AC_HEADER_SYS_WAIT -AC_CHECK_HEADERS(unistd.h string.h sys/rusage.h) +AC_CHECK_HEADERS(unistd.h string.h sys/rusage.h sys/resource.h) dnl Checks for typedefs, structures, and compiler characteristics. AC_C_CONST --- time-1.7.orig/version.texi +++ time-1.7/version.texi @@ -1,3 +1,3 @@ -@set UPDATED 12 June 1996 +@set UPDATED 9 May 2002 @set EDITION 1.7 @set VERSION 1.7 --- time-1.7.orig/time.c +++ time-1.7/time.c @@ -147,6 +147,10 @@ NULL }; + +/* If true, do not show the exit message */ +static boolean quiet; + /* If true, show an English description next to each statistic. */ static boolean verbose; @@ -172,6 +176,7 @@ {"help", no_argument, NULL, 'h'}, {"output-file", required_argument, NULL, 'o'}, {"portability", no_argument, NULL, 'p'}, + {"quiet", no_argument,NULL, 'q'}, {"verbose", no_argument, NULL, 'v'}, {"version", no_argument, NULL, 'V'}, {NULL, no_argument, NULL, 0} @@ -333,7 +338,8 @@ else if (WIFSIGNALED (resp->waitstatus)) fprintf (fp, "Command terminated by signal %d\n", WTERMSIG (resp->waitstatus)); - else if (WIFEXITED (resp->waitstatus) && WEXITSTATUS (resp->waitstatus)) + else if (WIFEXITED (resp->waitstatus) && WEXITSTATUS (resp->waitstatus) + && !quiet) fprintf (fp, "Command exited with non-zero status %d\n", WEXITSTATUS (resp->waitstatus)); @@ -523,6 +529,7 @@ char *format; /* Format found in environment. */ /* Initialize the option flags. */ + quiet = false; verbose = false; outfile = NULL; outfp = stderr; @@ -536,7 +543,7 @@ if (format) output_format = format; - while ((optc = getopt_long (argc, argv, "+af:o:pvV", longopts, (int *) 0)) + while ((optc = getopt_long (argc, argv, "+af:o:pqvV", longopts, (int *) 0)) != EOF) { switch (optc) @@ -555,6 +562,9 @@ case 'p': output_format = posix_format; break; + case 'q': + quiet = true; + break; case 'v': verbose = true; break; @@ -642,9 +652,9 @@ fflush (outfp); if (WIFSTOPPED (res.waitstatus)) - exit (WSTOPSIG (res.waitstatus)); + exit (WSTOPSIG (res.waitstatus) + 128); else if (WIFSIGNALED (res.waitstatus)) - exit (WTERMSIG (res.waitstatus)); + exit (WTERMSIG (res.waitstatus) + 128); else if (WIFEXITED (res.waitstatus)) exit (WEXITSTATUS (res.waitstatus)); } @@ -657,7 +667,7 @@ fprintf (stream, "\ Usage: %s [-apvV] [-f format] [-o file] [--append] [--verbose]\n\ [--portability] [--format=format] [--output=file] [--version]\n\ - [--help] command [arg...]\n", + [--quiet] [--help] command [arg...]\n", program_name); exit (status); } --- time-1.7.orig/resuse.h +++ time-1.7/resuse.h @@ -36,19 +36,8 @@ # include #else # define TV_MSEC tv_usec / 1000 -# if HAVE_WAIT3 +# if HAVE_SYS_RESOURCE_H # include -# else -/* Process resource usage structure. */ -struct rusage -{ - struct timeval ru_utime; /* User time used. */ - struct timeval ru_stime; /* System time used. */ - int ru_maxrss, ru_ixrss, ru_idrss, ru_isrss, - ru_minflt, ru_majflt, ru_nswap, ru_inblock, - ru_oublock, ru_msgsnd, ru_msgrcv, ru_nsignals, - ru_nvcsw, ru_nivcsw; -}; # endif #endif --- time-1.7.orig/time.texi +++ time-1.7/time.texi @@ -11,6 +11,12 @@ @finalout @end iftex +@dircategory Individual utilities +@direntry +* time: (time). Run programs and summarize + system resource usage. +@end direntry + @ifinfo This file documents the the GNU @code{time} command for running programs and summarizing the system resources they use. @@ -185,6 +191,10 @@ sys %S @end example +@item -q +@itemx --quiet +Suppress non-zero error code from the executed program. + @item -v @itemx --verbose @cindex format --- time-1.7.orig/time.info +++ time-1.7/time.info @@ -1,5 +1,10 @@ -This is Info file ./time.info, produced by Makeinfo-1.55 from the input -file time.texi. +This is time.info, produced by makeinfo version 4.1 from time.texi. + +INFO-DIR-SECTION Individual utilities +START-INFO-DIR-ENTRY +* time: (time). Run programs and summarize + system resource usage. +END-INFO-DIR-ENTRY This file documents the the GNU `time' command for running programs and summarizing the system resources they use. @@ -31,7 +36,7 @@ * Resource Measurement:: Measuring program resource use. - -- The Detailed Node Listing -- + --- The Detailed Node Listing --- Measuring Program Resource Use @@ -58,14 +63,14 @@ The `time' command runs another program, then displays information about the resources used by that program, collected by the system while the program was running. You can select which information is reported -and the format in which it is shown (*note Setting Format::.), or have +and the format in which it is shown (*note Setting Format::), or have `time' save the information in a file instead of displaying it on the -screen (*note Redirecting::.). +screen (*note Redirecting::). The resources that `time' can report on fall into the general categories of time, memory, and I/O and IPC calls. Some systems do not provide much information about program resource use; `time' reports -unavailable information as zero values (*note Accuracy::.). +unavailable information as zero values (*note Accuracy::). The format of the `time' command is: @@ -132,6 +137,10 @@ user %U sys %S +`-q' +`--quiet' + Suppress non-zero error code from the executed program. + `-v' `--verbose' Use the built-in verbose format, which displays each available @@ -174,7 +183,7 @@ The resource specifiers, which are a superset of those recognized by the `tcsh' builtin `time' command, are listed below. Not all resources are measured by all versions of Unix, so some of the values might be -reported as zero (*note Accuracy::.). +reported as zero (*note Accuracy::). * Menu: @@ -308,11 +317,11 @@ `-o FILE' `--output=FILE' Write the resource use statistics to FILE. By default, this - *overwrites* the file, destroying the file's previous contents. + _overwrites_ the file, destroying the file's previous contents. `-a' `--append' - *Append* the resource use information to the output file instead + _Append_ the resource use information to the output file instead of overwriting it. This option is only useful with the `-o' or `--output' option. @@ -437,7 +446,7 @@ `-a' `--append' - *Append* the resource use information to the output file instead + _Append_ the resource use information to the output file instead of overwriting it. `-f FORMAT' @@ -462,17 +471,17 @@  Tag Table: -Node: Top934 -Node: Resource Measurement1725 -Node: Setting Format3678 -Node: Format String4907 -Node: Time Resources6214 -Node: Memory Resources6844 -Node: I/O Resources7549 -Node: Command Info8747 -Node: Redirecting8964 -Node: Examples9754 -Node: Accuracy12064 -Node: Invoking time13586 +Node: Top1115 +Node: Resource Measurement1908 +Node: Setting Format3858 +Node: Format String5164 +Node: Time Resources6470 +Node: Memory Resources7100 +Node: I/O Resources7805 +Node: Command Info9003 +Node: Redirecting9220 +Node: Examples10010 +Node: Accuracy12320 +Node: Invoking time13842  End Tag Table --- time-1.7.orig/time.html +++ time-1.7/time.html @@ -0,0 +1,1021 @@ + + + + + +Measuring Program Resource Use + + + + + + + + + + + + + + + + + +
[Top][Contents][Index][ ? ]
+

Measuring Program Resource Use

+ +

+ +This file documents the the GNU time command for running programs +and summarizing the system resources they use. +This is edition 1.7, for version 1.7. +

+

+ +

+ + + + + + + + + + + + + + + + + + + + +
1. Measuring Program Resource Use  Measuring program resource use.
+
-- The Detailed Node Listing --- +
+
Measuring Program Resource Use +
+
1.1 Setting the Output Format  Selecting the information reported by time.
1.2 The Format String  The information time can report.
1.3 Redirecting Output  Writing the information to a file.
1.4 Examples  Examples of using time.
1.5 Accuracy  Limitations on the accuracy of time output.
1.6 Running the time Command  Summary of the options to the time command.
+
The Format String +
+
1.2.1 Time Resources  
1.2.2 Memory Resources  
1.2.3 I/O Resources  
1.2.4 Command Info  
+

+ +

+ + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

1. Measuring Program Resource Use

+ +

+ +The time command runs another program, then displays information +about the resources used by that program, collected by the system while +the program was running. You can select which information is reported +and the format in which it is shown (see section 1.1 Setting the Output Format), or have +time save the information in a file instead of displaying it on the +screen (see section 1.3 Redirecting Output). +

+

+ +The resources that time can report on fall into the general +categories of time, memory, and I/O and IPC calls. Some systems do not +provide much information about program resource use; time +reports unavailable information as zero values (see section 1.5 Accuracy). +

+

+ +The format of the time command is: +

+

+ +
 
time [option...] command [arg...]
+

+ + +time runs the program command, with any given arguments +arg.... When command finishes, time displays +information about resources used by command. +

+

+ +Here is an example of using time to measure the time and other +resources used by running the program grep: +

+

+ +
 
eg$ time grep nobody /etc/aliases
+nobody:/dev/null
+etc-files:nobody
+misc-group:nobody
+0.07user 0.50system 0:06.69elapsed 8%CPU (0avgtext+489avgdata 324maxresident)k
+46inputs+7outputs (43major+251minor)pagefaults 0swaps
+

+ +Mail suggestions and bug reports for GNU time to +bug-gnu-utils@prep.ai.mit.edu. Please include the version of +time, which you can get by running `time --version', and the +operating system and C compiler you used. +

+

+ + + + + + + + +
1.1 Setting the Output Format  Selecting the information reported by time.
1.2 The Format String  The information time can report.
1.3 Redirecting Output  Writing the information to a file.
1.4 Examples  Examples of using time.
1.5 Accuracy  Limitations on the accuracy of time output.
1.6 Running the time Command  Summary of the options to the time command.
+

+ + +

+ + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

1.1 Setting the Output Format

+ +

+ +time uses a format string to determine which information to +display about the resources used by the command it runs. See section 1.2 The Format String, for the interpretation of the format string contents. +

+

+ +You can specify a format string with the command line options listed +below. If no format is specified on the command line, but the +TIME environment variable is set, its value is used as the format +string. Otherwise, the default format built into time is used: +

+

+ +
 
%Uuser %Ssystem %Eelapsed %PCPU (%Xtext+%Ddata %Mmax)k
+%Iinputs+%Ooutputs (%Fmajor+%Rminor)pagefaults %Wswaps
+

+ +The command line options to set the format are: +

+

+ +

+
+
-f format +
--format=format +
Use format as the format string. +

+ +

+
-p +
--portability +
Use the following format string, for conformance with POSIX standard +1003.2: +

+ +
 
real %e
+user %U
+sys %S
+

+ +

+
-q +
--quiet +
Suppress non-zero error code from the executed program. +

+ +

+
-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. +
+

+ + +

+ + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

1.2 The Format String

+ +

+ + + +The format string controls the contents of the time output. +It consists of resource specifiers and escapes, interspersed +with plain text. +

+

+ +A backslash introduces an escape, which is translated +into a single printing character upon output. The valid escapes are +listed below. An invalid escape is output as a question mark followed +by a backslash. +

+

+ +

+
+
\t +
a tab character +

+ +

+
\n +
a newline +

+ +

+
\\ +
a literal backslash +
+

+ +time always prints a newline after printing the resource use +information, so normally format strings do not end with a newline +character (or `\n'). +

+

+ +A resource specifier consists of a percent sign followed by another +character. An invalid resource specifier is output as a question mark +followed by the invalid character. Use `%%' to output a literal +percent sign. +

+

+ +The resource specifiers, which are a superset of those recognized by the +tcsh builtin time command, are listed below. Not all +resources are measured by all versions of Unix, so some of the values +might be reported as zero (see section 1.5 Accuracy). +

+

+ + + + + + +
1.2.1 Time Resources  
1.2.2 Memory Resources  
1.2.3 I/O Resources  
1.2.4 Command Info  
+

+ + +

+ + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

1.2.1 Time Resources

+ +

+ +

+
+
E +
Elapsed real (wall clock) time used by the process, in +[hours:]minutes:seconds. +

+ +

+
e +
Elapsed real (wall clock) time used by the process, in +seconds. +

+ +

+
S +
Total number of CPU-seconds used by the system on behalf of the process +(in kernel mode), in seconds. +

+ +

+
U +
Total number of CPU-seconds that the process used directly (in user +mode), in seconds. +

+ +

+
P +
Percentage of the CPU that this job got. This is just user + system +times divied by the total running time. +
+

+ + +

+ + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

1.2.2 Memory Resources

+ +

+ +

+
+
M +
Maximum resident set size of the process during its lifetime, in +Kilobytes. +

+ +

+
t +
Average resident set size of the process, in Kilobytes. +

+ +

+
K +
Average total (data+stack+text) memory use of the process, in Kilobytes. +

+ +

+
D +
Average size of the process's unshared data area, in Kilobytes. +

+ +

+
p +
Average size of the process's unshared stack, in Kilobytes. +

+ +

+
X +
Average size of the process's shared text, in Kilobytes. +

+ +

+
Z +
System's page size, in bytes. This is a per-system constant, but +varies between systems. +
+

+ + +

+ + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

1.2.3 I/O Resources

+ +

+ +

+
+
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. +

+ +

+
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. +

+ +

+
W +
Number of times the process was swapped out of main memory. +

+ +

+
c +
Number of times the process was context-switched involuntarily (because +the time slice expired). +

+ +

+
w +
Number of times that the program was context-switched voluntarily, for +instance while waiting for an I/O operation to complete. +

+ +

+
I +
Number of file system inputs by the process. +

+ +

+
O +
Number of file system outputs by the process. +

+ +

+
r +
Number of socket messages received by the process. +

+ +

+
s +
Number of socket messages sent by the process. +

+ +

+
k +
Number of signals delivered to the process. +
+

+ + +

+ + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

1.2.4 Command Info

+ +

+ +

+
+
C +
Name and command line arguments of the command being timed. +

+ +

+
x +
Exit status of the command. +
+

+ + +

+ + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

1.3 Redirecting Output

+ +

+ +By default, time writes the resource use statistics to the +standard error stream. The options below make it write the statistics +to a file instead. Doing this can be useful if the program you're +running writes to the standard error or you're running time +noninteractively or in the background. +

+

+ +

+
+
-o file +
--output=file +
Write the resource use statistics to file. By default, this +overwrites the file, destroying the file's previous contents. +

+ +

+
-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. +
+

+ + +

+ + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

1.4 Examples

+ +

+ +Run the command `wc /etc/hosts' and show the default information: +

+

+ +
 
eg$ time wc /etc/hosts
+      35     111    1134 /etc/hosts
+0.00user 0.01system 0:00.04elapsed 25%CPU (0avgtext+0avgdata 0maxresident)k
+1inputs+1outputs (0major+0minor)pagefaults 0swaps
+

+ +Run the command `ls -Fs' and show just the user, system, and +wall-clock time: +

+

+ +
 
eg$ time -f "\t%E real,\t%U user,\t%S sys" ls -Fs
+total 16
+1 account/      1 db/           1 mail/         1 run/
+1 backups/      1 emacs/        1 msgs/         1 rwho/
+1 crash/        1 games/        1 preserve/     1 spool/
+1 cron/         1 log/          1 quotas/       1 tmp/
+        0:00.03 real,   0.00 user,      0.01 sys
+

+ +Edit the file `.bashrc' and have time append the elapsed time +and number of signals to the file `log', reading the format string +from the environment variable TIME: +

+

+ +
 
eg$ export TIME="\t%E,\t%k" # If using bash or ksh
+eg$ setenv TIME "\t%E,\t%k" # If using csh or tcsh
+eg$ time -a -o log emacs .bashrc
+eg$ cat log
+        0:16.55,        726
+

+ +Run the command `sleep 4' and show all of the information about it +verbosely: +

+

+ +
 
eg$ time -v sleep 4
+        Command being timed: "sleep 4"
+        User time (seconds): 0.00
+        System time (seconds): 0.05
+        Percent of CPU this job got: 1%
+        Elapsed (wall clock) time (h:mm:ss or m:ss): 0:04.26
+        Average shared text size (kbytes): 36
+        Average unshared data size (kbytes): 24
+        Average stack size (kbytes): 0
+        Average total size (kbytes): 60
+        Maximum resident set size (kbytes): 32
+        Average resident set size (kbytes): 24
+        Major (requiring I/O) page faults: 3
+        Minor (reclaiming a frame) page faults: 0
+        Voluntary context switches: 11
+        Involuntary context switches: 0
+        Swaps: 0
+        File system inputs: 3
+        File system outputs: 1
+        Socket messages sent: 0
+        Socket messages received: 0
+        Signals delivered: 1
+        Page size (bytes): 4096
+        Exit status: 0
+

+ + +

+ + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

1.5 Accuracy

+ +

+ +The elapsed time is not collected atomically with the execution of the +program; as a result, in bizarre circumstances (if the time +command gets stopped or swapped out in between when the program being +timed exits and when 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 time is derived from the wait3 +system call. The numbers are only as good as those returned by +wait3. Many systems do not measure all of the resources that +time can report on; those resources are reported as zero. The +systems that measure most or all of the resources are based on 4.2 or +4.3BSD. Later BSD releases use different memory management code that +measures fewer resources. +

+

+ +On systems that do not have a wait3 call that returns status +information, the times system call is used instead. It provides +much less information than wait3, so on those systems time +reports most 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. +

+

+ + +

+ + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

1.6 Running the time Command

+ +

+ +The format of the time command is: +

+

+ +
 
time [option...] command [arg...]
+

+ + +time runs the program command, with any given arguments +arg.... When command finishes, time displays +information about resources used by command (on the standard error +output, by default). If command exits with non-zero status or is +terminated by a signal, time displays a warning message and the +exit status or signal number. +

+

+ +Options to time must appear on the command line before +command. Anything on the command line after command is +passed as arguments to command. +

+

+ +

+
+
-o file +
--output=file +
Write the resource use statistics to file. +

+ +

+
-a +
--append +
Append the resource use information to the output file instead +of overwriting it. +

+ +

+
-f format +
--format=format +
Use format as the format string. +

+ +

+
--help +
Print a summary of the command line options to time and exit. +

+ +

+
-p +
--portability +
Use the POSIX format. +

+ +

+
-v +
--verbose +
+Use the built-in verbose format. +

+ +

+
-V +
--version +
+Print the version number of time and exit. +
+

+ +

+ + + + + + +
[Top][Contents][Index][ ? ]
+

Table of Contents

+
+1. Measuring Program Resource Use +
+
+1.1 Setting the Output Format +
+1.2 The Format String +
+
+1.2.1 Time Resources +
+1.2.2 Memory Resources +
+1.2.3 I/O Resources +
+1.2.4 Command Info +
+
+1.3 Redirecting Output +
+1.4 Examples +
+1.5 Accuracy +
+1.6 Running the time Command +
+
+
+
+ + + + + + +
[Top][Contents][Index][ ? ]
+

Short Table of Contents

+
+1. Measuring Program Resource Use +
+ +
+
+ + + + + + +
[Top][Contents][Index][ ? ]
+

About this document

+This document was generated +by +using texi2html +

+The buttons in the navigation panels have the following meaning: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Button Name Go to From 1.2.3 go to
+ [ < ] +Back + +previous section in reading order + +1.2.2 +
+ [ > ] +Forward + +next section in reading order + +1.2.4 +
+ [ << ] +FastBack + +beginning of this chapter or previous chapter + +1 +
+ [ Up ] +Up + +up section + +1.2 +
+ [ >> ] +FastForward + +next chapter + +2 +
+ [Top] +Top + +cover (top) of document + +   +
+ [Contents] +Contents + +table of contents + +   +
+ [Index] +Index + +concept index + +   +
+ [ ? ] +About + +this page + +   +
+

+ where the Example assumes that the current position + is at Subsubsection One-Two-Three of a document of + the following structure:

+ + +
+
+ +This document was generated +by root on September, 1 2003 +using texi2html + + + +