Provided by: multitime_1.3-1_amd64 
NAME
multitime — time command execution over multiple executions
SYNOPSIS
multitime [-f liketime | rusage] [-I replstr] [-i stdincmd] [-n numruns] [-o stdoutcmd] [-q] [-r precmd]
[-s sleep] [-v] command [arg1, ..., argn]
multitime -b batchfile [-f liketime | rusage] [-n numruns] [-s sleep] [-v]
DESCRIPTION
Unix's time(1) utility is a simple and often effective way of measuring how long a command takes to
execute. Unfortunately, executing a command once can give misleading timings: the process may create a
cache on its first execution, running faster subsequently; other processes may cause the command to be
starved of CPU or IO time; etc. It is common to see people execute time(1) several times and take
whichever values they feel most comfortable with. Inevitably, this causes problems.
multitime is, in essence, a simple extension to time(1) which executes command multiple times and prints
the timing means, standard deviations, mins, medians, and maxes having done so. This can give a much
better understanding of the command's performance. multitime also has a number of options to help
advanced uses. For basic uses, multitime can replace time(1) by using the -n option to specifying how
many times command should be executed. e.g. if we want to time awk(1):
$ multitime -n 5 awk 'function fib(n) \\
{ return n <= 1? 1: fib(n - 1) + fib(n - 2) } BEGIN { fib(30) }'
The full set of options is as follows:
-b batchfile
Execute multiple commands from batchfile. See the “BATCHFILES” section for more details.
-f liketime | rusage
If called as time, the default output style of multitime is POSIX.2 compatible, showing means for
real, user, and sys readings. -f liketime can be used to force POSIX.2 compatibility in all
cases. Otherwise, its default output style is an incompatible extension that shows means,
standard deviations, mins, medians, and maxes. -f rusage additionally shows the entire output of
the rusage structure.
-I replstr
Instances of replstr found in inputcmd, outputcmd, and precmd are replaced with an integer
denoting the current execution run number, from 1 to numruns (both inclusive).
-i stdincmd
Before the timing of each execution of command, stdincmd is executed and its output piped to a
temporary file. That temporary file is then used as stdin for command, allowing the user to
ensure that each execution of command sees exactly the input on stdin expected. stdincmd is a
full shell command which is passed to popen(3).
-l Same as -f rusage, for compatibility with time(1).
-n numruns
Specify how many times command should be executed. Defaults to 1.
-o stdoutcmd
When executing command, its output is piped to a temporary file. After execution has finished,
stdoutcmd is then executed, with the temporary file being its stdin. If stdoutcmd returns an
exit code (i.e. non-zero), multitime stops executing. This can be used as a sanity check that
command is executing as per expectations. stdoutcmd is a full shell command which is passed to
popen(3). This option is mutually exclusive with -q.
-p Same as -f liketime, for compatibility with time(1).
-r precmd
Before each execution of command -- and, if it is specified, before stdincmd -- precmd is
executed by calling system(3). This can be used to set the system to a known good state. If
precmd returns an exit code (i.e. non-zero), multitime stops executing.
-q Suppresses stdout output from command. This can be useful for programs which produce voluminous
output, which can lead to one unintentionally measuring the output speed of the terminal being
used, rather than command itself. This option is mutually exclusive with -o.
-s sleep
multitime pauses a random length of time between 0 and sleep seconds between each command
execution. Particularly for short-running commands, this can smooth out temporary peaks and
troughs. If not specified, sleep defaults to 3 seconds; if set to 0, multitime does not sleep at
all between executions.
-v Causes verbose output (e.g. which commands are being executed).
Note that multitime exits immediately if any execution of command fails, returning the failed commands
error code.
BATCHFILES
Batchfiles are only needed for advanced uses of multitime. One important use is when multitime is being
used to compare the performance of multiple commands. The obvious way to do this is to execute multitime
for each command and record its output. However, it is possible that one command is unduly affected by
issues elsewhere in the machine (e.g. a cron(8) job running in the background), distorting the
comparison. Batchfiles allow multiple completely different commands to be executed, with each iteration
running a random command. Assuming that numruns is set sufficiently high, batchfiles tend to better
spread timing problems over the whole set of commands rather than a single command.
The format of batchfiles is relatively simple being, more or less, a cut-down version of the normal
multitime arguments without having to specify multitime itself. Each line specifies a command to be
executed. Each line has the format:
[-I replstr] [-i stdincmd] [-o stdoutcmd] [-q] [-r precmd] command [arg1, ..., argn]
The -f, -n, -s, and -v options are global and can not be specified in the batch file.
EXAMPLES
A basic invocation of multitime is as follows:
$ multitime -n 10 awk 'function fib(n) \\
{ return n <= 1? 1: fib(n - 1) + fib(n - 2) } BEGIN { fib(30) }'
command will produce its output as normal; multitime will then produce output such as the following on
stderr:
1: awk 'function fib(n) \\
{ return n <= 1? 1: fib(n - 1) + fib(n - 2) } BEGIN { fib(30) }'
Mean Std.Dev. Min Median Max
real 0.474 0.001 0.473 0.474 0.477
user 0.456 0.016 0.430 0.460 0.480
sys 0.000 0.000 0.000 0.000 0.010
As an example of more complex uses of multitime, one could time the overall performance of sort(1) on
different sequences of random data using -i:
$ multitime -i 'jot -r 1000000 1 100000' -n 10 -q sort
Note that each execution of sort(1) will receive different output from jot(1). If you want each
execution to receive the same data, use a two-stage sequence with cat(1):
$ jot -r 1000000 1 100000 > file
$ multitime -i 'cat file' -n 10 -q sort
If you are timing sort(1) against pre-defined batches of data (called data1, data2, ..., data10):
$ multitime -I{} -i 'cat data{}' -n 10 -q sort
If you want to cache the output of each execution of command use -o:
$ multitime -I{} -n 3 -o 'cat > file{}' md5 -t
An example batch file bf is as follows:
-i 'jot -r 100000 1 100000' -q sort
md5 -t
and may be invoked thus:
$ multitime -b bf -n 10
LIMITATIONS
Though multitime goes out of its way not to colour timings, ultimately the operating system and tasks
executing in the system can significantly affect timing measurements. For example, multitime timings
include the time to fork(2) a process and execvp(3) a command, which are entirely outside its hands.
Short-running tasks can be particularly affected by seemingly minor blips in system activity.
There are methods which can increase the likely accuracy of timing measurements. For example, raising
numruns (and, depending on your circumstances, sleep) reduces the likelihood of temporary blips
distorting timing measurements. If comparing the execution times of multiple commands, the use of
batchfiles can spread blips out rather than concentrating them on a single command. Increasing the
process priority of multitime can decrease the likelihood of other tasks interfering with timings.
Ultimately, however, there can never be absolute guarantees of accuracy. Instead, such methods should be
thought of as increasing the likelihood that the numbers returned are indicative of the 'true'
measurements. By presenting means and standard deviations, multitime encourages the use of confidence
intervals, a statistical technique which encourages this mode of thinking.
AUTHORS
multitime was written by Laurence Tratt <http://tratt.net/laurie/>.
Debian August 31, 2012 MULTITIME(1)