[net.sources] csh time command help

jerryp@tektools.UUCP (10/24/86)

In article <1760@tektools.UUCP>, I wrote:
> In article <219@mipos3.UUCP> pinkas@mipos3.UUCP (Israel Pinkas) writes:
> >Can anyone tell me what all the fields that the csh time command prints out
> >are?  When I do something like 'time ls' in csh, I get:
> >
> >	1.3u 0.7s 0:11 19% 23+79k 3+0io 2pf+0w
> 
> A year or two ago, David Brown ({zehntel,amd,fortune,resonex}!varian!david)
> posted a manual page for the csh "time" command.  The man page was actually
> written by Mark Wittenberg ({zehntel,varian}!rtech!mark).
> 
> Among the neat, undocumented stuff in it was the fact that you can change the
> output format of the "time" command by setting a shell variable named "time".
> 
> The man page was written for 4.1bsd csh; I don't know if it much has changed
> for 4.[23]bsd.

Here it is.  Only one note:  Dan Klein pointed out in another posting 
(<359@aw.sei.cmu.edu.sei.cmu.edu>) that the %M has a bug:  The value it prints
is only *half* of the maximum image size.  This is true.  [But can we complain
about bugs in undocumented features? :-)]

--Jerry Peek, Tektronix, Inc.
US Mail:    MS 74-900, P.O. Box 500, Beaverton, OR 97077
uucp:       {allegra,decvax,hplabs,ihnp4,ucbvax}!tektronix!tektools!jerryp
CS,ARPAnet: jerryp%tektools@tektronix.csnet
Phone:      +1 503 627-1603

---------------------------------------------------------------------------

# This is a shell archive.  Remove anything before this line,
# then unpack it by saving it in a file and typing "sh file".
#
# Wrapped by tektools!jerryp on Fri Oct 24 08:44:47 PDT 1986
# Contents:  csh_time.7
 
echo extracting - csh_time.7
sed 's/^X//' > "csh_time.7" <<'X//E*O*F csh_time.7//'
X.TH TIME 7 
X.UC 4
X.SH NAME
Xtime \- time a command
X.SH SYNOPSIS
X.B time
Xcommand
X.SH DESCRIPTION
XThe
Xgiven command is executed; after it is complete,
X.I time
Xprints the elapsed time during the command, the time
Xspent in the system, and the time spent in execution
Xof the command.
XTimes are reported in seconds.
X.PP
XOn a PDP-11, the execution time can depend on what kind of memory
Xthe program happens to land in;
Xthe user time in MOS is often half what it is in core.
X.PP
XThe times are printed on the diagnostic output stream.
X.PP
X.I Time
Xis built in to
X.I csh(1),
Xusing a different output format.
X.SH LOCAL\ CSH
X.PP
XThe output format is selectable by the user
X(this feature is undocumented by UCB, and so may not be supported later).
XIf the
X.I time
Xshell variable has two components
Xthen the second component is taken to be an output specification string
Xreminiscent of
X.IR printf (III).
X.de mI
X.ti -4
X\\$1\ \ 
X..
XA percent sign introduces a conversion operator;
Xthe next character specifies the desired conversion.
XOther characters are simply printed.
XThe conversion characters and their meanings are:
X.sp
X.in +6
X.mI U
XUser time in seconds.
X.mI S
XSystem time in seconds.
X.mI E
XElapsed time in seconds.
X.mI P
XPercentage of the CPU.
X.mI X
XAverage kilobytes of resident text pages.
X.mI D
XAverage kilobytes of resident data+stack pages.
X.mI K
XAverage kilobytes of resident text+data+stack pages.
X.mI M
XMaximum kilobytes of resident text+data+stack pages.
X.mI I
XThe number of filesystem input events
X(reads that came from the disk).
X.mI O
XThe number of filesystem output events
X(writes that went to the disk).
X.mI F
XThe number of page faults which resulted in disk activity.
X.mI R
XThe number of page faults resulting from the simulation of reference bits.
X.mI W
XThe number of swaps which occurred.
X.in -6
X.ne 7
X.PP
XThe default format is
X.ti +2
X.nf
X"%Uu %Ss %E %P %X+%Dk %I+%Oio %Fpf+%Ww".
X.fi
XYou might want to try
X.ti +2
X.nf
X"%Uu %s %E %P (%Xt+%Dds+%Kavg+%Mmax)k %Ii+%Oo (%Fmaj+%Rmin)pf %Wswaps"
X.fi
Xif you want more information and more mnemonic identifiers.
X.PP
XNote that if the format string has any special characters
X(including spaces) then they must be protected by quoting.
X.SH BUGS
XElapsed time is accurate to the second,
Xwhile the CPU times are measured
Xto the 60th second.
XThus the sum of the CPU times can be up to a second larger
Xthan the elapsed time.
X.PP
X.I Time
Xis a built-in command to
X.IR csh (1),
Xwith a much different syntax.  This command is available as
X``/bin/time'' to
X.I csh
Xusers.
X.SH EXAMPLE
X.nf
Xset x="%Uu %Ss %E %P (%Xt+%Dds+%Kavg+%Mmax)k %Ii+%Oo (%Fmaj+%Rmin)pf %Wswaps"
Xset time=(60 "$x")
X.fi
X.SH SEE\ ALSO
X.IR vtimes (2V)
X.SH MANUAL-PAGE HISTORY
XWritten by Mark Wittenberg ({zehntel,varian}!rtech!mark).
XWritten for 4.1bsd csh; I don't know if it much has changed
Xfor 4.2bsd.  Copied via USENET from David Brown, (415) 945-2199,
XVarian Instruments, 2700 Mitchell Dr.,  Walnut Creek, CA 94598,
X{zehntel,amd,fortune,resonex}!varian!david
X//E*O*F csh_time.7//
chmod u=rw,g=r,o=r csh_time.7
 
echo Inspecting for damage in transit...
temp=/tmp/shar$$; dtemp=/tmp/.shar$$
trap "rm -f $temp $dtemp; exit" 0 1 2 3 15
cat > $temp <<\!!!
     118     510    2963 csh_time.7
!!!
wc  csh_time.7 | sed 's/^X//' | diff -b $temp - >$dtemp
if [ -s $dtemp ]
then echo "Ouch [diff of wc output]:" ; cat $dtemp
else echo "No problems found."
fi
exit 0