RSS feed: whole site
Man Page Lookup - multitime
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]

 <span class="bold">multitime</span> <span class="bold">-b</span> <span class="underline">batchfile</span> [<span class="bold">-f</span> <span class="underline">liketime</span> | <span class="underline">rusage</span>] [<span class="bold">-n</span> <span class="underline">numruns</span>] [<span class="bold">-s</span> <span class="underline">sleep</span>]
           [<span class="bold">-v</span>]

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.

 <span class="bold">multitime</span> is, in essence, a simple extension to time(1) which executes
 <span class="underline">command</span> 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.  <span class="bold">multitime</span> also has a number
 of options to help advanced uses.  For basic uses, <span class="bold">multitime</span> can replace
 time(1) by using the <span class="bold">-n</span> option to specifying how many times <span class="underline">command</span>
 should be executed.  e.g. if we want to time awk(1):

       $ multitime -n 5 awk 'function fib(n) \
       { return n &lt;= 1? 1: fib(n - 1) + fib(n - 2) } BEGIN { fib(30) }'

 The full set of options is as follows:

 <span class="bold">-b</span> <span class="underline">batchfile</span>
         Execute multiple commands from <span class="underline">batchfile</span>.  See the <span class="underline">BATCHFILES</span>
         section for more details.

 <span class="bold">-f</span> <span class="underline">liketime</span> | <span class="underline">rusage</span>
         If called as <span class="bold">time</span>, the default output style of <span class="bold">multitime</span> is
         POSIX.2 compatible, showing means for real, user, and sys
         readings.  <span class="bold">-f</span> <span class="underline">liketime</span> 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.  <span class="bold">-f</span> <span class="underline">rusage</span> additionally shows the
         entire output of the rusage structure.

 <span class="bold">-I</span> <span class="underline">replstr</span>
         Instances of <span class="underline">replstr</span> found in <span class="underline">inputcmd</span>, <span class="underline">outputcmd</span>, and <span class="underline">precmd</span> are
         replaced with an integer denoting the current execution run
         number, from 1 to <span class="underline">numruns</span> (both inclusive).

 <span class="bold">-i</span> <span class="underline">stdincmd</span>
         Before the timing of each execution of <span class="underline">command</span>, <span class="underline">stdincmd</span> is
         executed and its output piped to a temporary file.  That
         temporary file is then used as stdin for <span class="underline">command</span>, allowing the
         user to ensure that each execution of <span class="underline">command</span> sees exactly the
         input on stdin expected.  <span class="underline">stdincmd</span> is a full shell command which
         is passed to popen(3).

 <span class="bold">-l</span>      Same as <span class="bold">-f</span> <span class="underline">rusage</span>, for compatibility with time(1).

 <span class="bold">-n</span> <span class="underline">numruns</span>
         Specify how many times <span class="underline">command</span> should be executed.  Defaults to
         1.

 <span class="bold">-o</span> <span class="underline">stdoutcmd</span>
         When executing <span class="underline">command</span>, its output is piped to a temporary file.
         After execution has finished, <span class="underline">stdoutcmd</span> is then executed, with
         the temporary file being its stdin.  If <span class="underline">stdoutcmd</span> returns an exit
         code (i.e. non-zero), <span class="bold">multitime</span> stops executing.  This can be
         used as a sanity check that <span class="underline">command</span> is executing as per
         expectations.  <span class="underline">stdoutcmd</span> is a full shell command which is passed
         to popen(3).  This option is mutually exclusive with <span class="bold">-q</span>.

 <span class="bold">-p</span>      Same as <span class="bold">-f</span> <span class="underline">liketime</span>, for compatibility with time(1).

 <span class="bold">-r</span> <span class="underline">precmd</span>
         Before each execution of <span class="underline">command</span> -- and, if it is specified,
         before <span class="underline">stdincmd</span> -- <span class="underline">precmd</span> is executed by calling system(3).  This
         can be used to set the system to a known good state.  If <span class="underline">precmd</span>
         returns an exit code (i.e. non-zero), <span class="bold">multitime</span> stops executing.

 <span class="bold">-q</span>      Suppresses stdout output from <span class="underline">command</span>.  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 <span class="underline">command</span> itself.  This option is mutually
         exclusive with <span class="bold">-o</span>.

 <span class="bold">-s</span> <span class="underline">sleep</span>
         <span class="bold">multitime</span> pauses a random length of time between 0 and <span class="underline">sleep</span>
         seconds between each command execution.  Particularly for short-
         running commands, this can smooth out temporary peaks and
         troughs.  If not specified, <span class="underline">sleep</span> defaults to 3 seconds; if set
         to 0, <span class="bold">multitime</span> does not sleep at all between executions.

 <span class="bold">-v</span>      Causes verbose output (e.g. which commands are being executed).

 <span class="bold">multitime</span> exits immediately if any execution of <span class="underline">command</span> 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 <span class="bold">multitime</span> arguments without having to specify
 <span class="bold">multitime</span> itself.  Each line specifies a command to be executed. Each
 line has the format:

 [<span class="bold">-I</span> <span class="underline">replstr</span>] [<span class="bold">-i</span> <span class="underline">stdincmd</span>] [<span class="bold">-o</span> <span class="underline">stdoutcmd</span>] [<span class="bold">-q</span>] [<span class="bold">-r</span> <span class="underline">precmd</span>] <span class="underline">command</span> [arg1,
 ..., argn]

 The <span class="bold">-f</span>, <span class="bold">-n</span>, <span class="bold">-s</span>, and <span class="bold">-v</span> 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 &lt;= 1? 1: fib(n - 1) + fib(n - 2) } BEGIN { fib(30) }'

 <span class="underline">command</span> will produce its output as normal; <span class="bold">multitime</span> will then produce
 output such as the following on stderr:

       1: awk 'function fib(n)
       { return n &lt;= 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 <span class="bold">multitime</span>, one could time the
 overall performance of sort(1) on different sequences of random data
 using <span class="bold">-i</span>:
       $ 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 &gt; 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 <span class="underline">command</span> use <span class="bold">-o</span>:
       $ multitime -I{} -n 3 -o 'cat &gt; file{}' md5 -t

 An example batch file <span class="bold">bf</span> 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 <span class="underline">numruns</span> (and, depending on your
 circumstances, <span class="underline">sleep</span>) 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 <span class="bold">multitime</span> 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, <span class="bold">multitime</span>
 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