Provided by: multitime_1.4-2_amd64 bug

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      If specified once, -q suppresses stdout output; if specified twice, -qq suppresses
             both stdout and stderr. 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/>.