MULTITIME(1)

💖 MULTITIME(1) 💖

okay bestie, welcome to multitime from the General Commands Manual section — it's the little tool that times your commands over multiple runs and then gives you actual stats instead of vibes. 🎀

---

✨ NAME ✨

multitime — time command execution over multiple executions. no cap, that's the whole job. 💅

---

🦋 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 🌸

so like, Unix's time(1) utility is a cute lil way of measuring how long a command takes to run. but — and this is the tea — running a command once can hand you straight-up misleading timings. 😭 the process might build a cache on its first execution and then run faster afterwards, other processes might starve your command of CPU or IO time, etc. etc. and it's so common to see people run time(1) a bunch of times and then just pick whichever numbers they feel most comfortable with. which, bestie, inevitably causes problems. 💀

multitime is, at its heart, a simple lil extension to time(1) that runs command multiple times and then prints the timing means, standard deviations, mins, medians, and maxes after doing so. that gives you a much better understanding of how your command actually performs. 🫶 it also has a bunch of options for advanced uses. for basic uses, you can straight up replace time(1) by using the -n option to say how many times command should be executed. e.g. if we wanna 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. the BATCHFILES section below has the details, iykyk. 📄
• -f liketime | rusage — if it's called as time, the default output style of multitime is POSIX.2 compatible, showing means for real, user, and sys readings. -f liketime forces POSIX.2 compatibility in all cases. otherwise, the 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 get 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 is piped to a temporary file. that temporary file is then used as stdin for command, so you can make sure every single execution of command sees exactly the input on stdin you 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 you 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). 🗣️

heads up bestie: multitime exits immediately if any execution of command fails, returning the failed command's 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 that is to execute multitime for each command and record its output. however — it's possible that one command is unduly affected by issues elsewhere in the machine (e.g. a cron(8) job running in the background), which distorts the comparison. 💀 batchfiles let multiple completely different commands be executed, with each iteration running a random command. assuming 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 😭

even 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 you're 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/>. 💖

---

and that's the whole page bestie!! 🎀 this lil icon shipped from Debian, dated August 31, 2012 — so go forth and time your commands over multiple executions, slay, and remember: means and standard deviations are your besties now. periodt. 💅✨🦋