What does csh 'time' tell the user

[David Brown]

> What do the fields printed by the csh time command tell the user?

The following time.1 manual page (modified for csh) was put together
by Mark Wittenberg ({zehntel,varian}!rtech!mark).
This was written for 4.1bsd csh; I don't know if it much has changed
for 4.2bsd.


.TH TIME 1 
.UC 4
.SH NAME
time \- time a command
.SH SYNOPSIS
.B time
command
.SH DESCRIPTION
The
given command is executed; after it is complete,
.I time
prints the elapsed time during the command, the time
spent in the system, and the time spent in execution
of the command.
Times are reported in seconds.
.PP
On a PDP-11, the execution time can depend on what kind of memory
the program happens to land in;
the user time in MOS is often half what it is in core.
.PP
The times are printed on the diagnostic output stream.
.PP
.I Time
is built in to
.I csh(1),
using a different output format.
.SH LOCAL\ CSH
.PP
The output format is selectable by the user
(this feature is undocumented by UCB, and so may not be supported later).
If the
.I time
shell variable has two components
then the second component is taken to be an output specification string
reminiscent of
.IR printf (III).
.de mI
.ti -4
\\$1\ \ 
..
A percent sign introduces a conversion operator;
the next character specifies the desired conversion.
Other characters are simply printed.
The conversion characters and their meanings are:
.sp
.in +6
.mI U
User time in seconds.
.mI S
System time in seconds.
.mI E
Elapsed time in seconds.
.mI P
Percentage of the CPU.
.mI X
Average kilobytes of resident text pages.
.mI D
Average kilobytes of resident data+stack pages.
.mI K
Average kilobytes of resident text+data+stack pages.
.mI M
Maximum kilobytes of resident text+data+stack pages.
.mI I
The number of filesystem input events
(reads that came from the disk).
.mI O
The number of filesystem output events
(writes that went to the disk).
.mI F
The number of page faults which resulted in disk activity.
.mI R
The number of page faults resulting from the simulation of reference bits.
.mI W
The number of swaps which occurred.
.in -6
.ne 7
.PP
The default format is
.ti +2
.nf
"%Uu %Ss %E %P %X+%Dk %I+%Oio %Fpf+%Ww".
.fi
You might want to try
.ti +2
.nf
"%Uu %s %E %P (%Xt+%Dds+%Kavg+%Mmax)k %Ii+%Oo (%Fmaj+%Rmin)pf %Wswaps"
.fi
if you want more information and more mnemonic identifiers.
.PP
Note that if the format string has any special characters
(including spaces) then they must be protected by quoting.
.SH BUGS
Elapsed time is accurate to the second,
while the CPU times are measured
to the 60th second.
Thus the sum of the CPU times can be up to a second larger
than the elapsed time.
.PP
.I Time
is a built-in command to
.IR csh (1),
with a much different syntax.  This command is available as
``/bin/time'' to
.I csh
users.
.SH EXAMPLE
.nf
set x="%Uu %s %E %P (%Xt+%Dds+%Kavg+%Mmax)k %Ii+%Oo (%Fmaj+%Rmin)pf %Wswaps"
set time=(60 "$x")
.fi
.SH SEE\ ALSO
.IR vtimes (2V)


-- 
	David Brown	 (415) 945-2199
	Varian Instruments 2700 Mitchell Dr.  Walnut Creek, Ca. 94598
	{zehntel,amd,fortune,resonex}!varian!david