--- name: "multitime" section: "1" platform: "linux" package: "multitime" version: "1.4-2" release: "Debian 12 (Bookworm)" platforms: ["linux"] url: "https://new.carta.tech/multitime" --- # multitime(1) time command execution over multiple executions ## 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)](/time/1.md) 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)](/time/1.md) 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)](/time/1.md) 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)](/time/1.md) by using the **-n** option to specifying how many times *command* should be executed. e.g. if we want to time [awk(1)](/awk/1.md): ``` $ 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)](/popen/3.md). - **-l** Same as **-f** *rusage*, for compatibility with [time(1)](/time/1.md). - **-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)](/popen/3.md). This option is mutually exclusive with **-q**. - **-p** Same as **-f** *liketime*, for compatibility with [time(1)](/time/1.md). - **-r** *precmd* Before each execution of *command* -- and, if it is specified, before *stdincmd* -- *precmd* is executed by calling [system(3)](/system/3.md). 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)](/cron/8.md) 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)](/sort/1.md) 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)](/sort/1.md) will receive different output from [jot(1)](/jot/1.md). If you want each execution to receive the same data, use a two-stage sequence with [cat(1)](/cat/1.md): ``` $ jot -r 1000000 1 100000 > file ``` ``` $ multitime -i 'cat file' -n 10 -q sort ``` If you are timing [sort(1)](/sort/1.md) 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)](/fork/2.md) a process and [execvp(3)](/execvp/3.md) 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/⟩.