39.3 The csh time variable

The C shell's variable named time controls the built-in csh time command (39.2). It lets you run time by default on commands that take more than a certain number of CPU seconds, and it lets you control the format of time's output.

We'll start with the simple stuff. On virtually any UNIX system, you can use the time shell variable (6.8) to run time automatically when commands take more than a set amount of CPU time. Decide what your threshhold is (i.e., the point at which you want time to run automatically), in CPU seconds. Then set the time shell variable to this number. For example, if you want to run time automatically on programs that require more than 10 CPU seconds, give the command:

nroff	% set time=10 % ls file1.ms file2.ms file3.ms % nroff -ms *.ms | lpr 4.3u 9.8s 0:23 60% 0+200k 106+103io 143pf+0w

The ls command didn't generate a time report because it ran in well under 10 seconds. The nroff command took about 14.1 CPU seconds, so it did generate a report.

Why would you want to do this? It lets you monitor the performance of long jobs automatically without being bothered by statistics for the small jobs.

On many C shells, you can also use the time variable to customize the timing report. Sometimes this is useful; the standard report gives you a lot of information, but it's pretty ugly. For some reason, this feature often goes undocumented.

To customize a timing report, give a command like this:

% set time=(threshold "format-string")

Note that you have to give a threshold, whether you want one or not. If you don't want execution times reported automatically, set threshold to some large number.

The format string can be any combination of text and tags. Each tag causes time to insert particular statistics. The valid tags seem to vary some from system-to-system (and are undocumented some places, so you may not be able to tell). We've used two sources: a version for 4.1BSD written by Mark Wittenberg and one supplied with Solaris 2.4. Where the two are different, Mark's is labeled A> and Sun's is B>.

%D

A> Average kilobytes of resident data+stack pages.

B> Average amount of unshared data space used, in kilobytes. This excludes any "shared data." Shared memory is a relatively new feature; many programs don't use it.

%E

The elapsed time required to execute the program. This is the amount of time you'd measure if you sat with a stopwatch and waited for the program to finish; it's often called "wall clock" time.

%F

The number of page faults; i.e., the number of times UNIX had to bring a page of virtual memory in from disk. A large number of page faults may mean that your program is taking an unnecessarily long time to run, and you can fix the problem by buying more memory.

%I

The number of block input operations. This is the number of times the program needed to read data from disk.

%K

A> Average kilobytes of resident text+data+stack pages.

B> Average amount of unshared stack space used, in kilobytes.

%M

The maximum amount of real memory (physical memory) used by the program during execution, in kilobytes. (On 17 October 1986, Daniel V. Klein reported on Usenet net.unix that the amount %M gives is really just half the maximum. The number does seem to be smaller than %K sometimes, so Daniel is probably right. Don't you love undocumented features?)

%O

The number of block output operations.

%P

The program's total CPU time, as a percentage of elapsed time. If you're the only user on the system and the program does little I/O, this should be close to 100%. It will decrease as the program's I/O requirements and the system's overall load increase.

%S

CPU system time; the number of seconds the CPU spent in the "system" state on behalf of your program - i.e., how much time the system spent executing system calls on behalf of your program.

%U

CPU user time; the number of seconds the CPU spent in the "user" state on behalf of your program - i.e., how much time the system spent executing your program itself.

%W

The number of "swaps"; the number of times the system needed to move your whole program to disk in order to free memory. If this is non-zero, your system needs more memory.

%X

A> Average kilobytes of resident text pages.

B> The average amount of shared memory that your program required, in kilobytes.

For example, let's say that we want time statistics for programs that require more than 10 seconds of CPU time, and that we want to report the system time, the user time, and the elapsed time.

Despite the huge number of statistics you can get, these are all that you really care about, unless you're a performance expert. To do so, we'll set the time variable like this (you can also set it in your .cshrc file (2.2)):

% set time=(10 "System time: %S  User time: %U  Elapsed time: %E")
% nroff -man * > /dev/null
System time: 0.3  User time: 41.2  Elapsed time: 0:43

This report is much clearer than the mess you get by default. It shows clearly that the nroff command required 0.3 seconds of system-state CPU time, 41.2 seconds of user-state CPU time, and a total elapsed time of 43 seconds.

NOTE: I have seen a note somewhere saying that many of time's more obscure statistics weren't reported correctly. By "obscure statistics," I mean page faults, average amount of unshared stack space, and the like. You can trust the user and system CPU time, the elapsed time, and other basic statistics, but if you really care about the fancy statistics, beware. I seriously doubt that any vendor has fixed these problems.