MULTITIME(1)               OpenBSD Reference Manual               MULTITIME(1)

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

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

OpenBSD 5.2                     August 31, 2012                    OpenBSD 5.2