Command Syntax Primer

Last updated: 08 May, 2006
© 2003-2006 diglloyd, Inc.  All Rights Reserved.

Start

This document uses DiskTester commands as examples. Any other diglloyd.com command line tool uses the same syntax.

To explain the syntax of a command, special characters are used to denote usage:

  • Items in italic within angle brackets <> indicate required values;
  • Items in square brackets [] indicate optional values;
  • The vertical line (“pipe”) character '|'  means to enter exactly one of several possible values;
  • straight quotes "" for items with spaces in them (see below).

Examples—required value

<volume-name>
<iterations>
<size>

Three examples are shown above. The angle brackets (<>) indicate that the item is required.  The use of italic text indicates that you must enter an appropriate value, in this case the name of a volume (disk), the number of iterations, and the size, respectively.

Examples—one of several possible values

<start|middle|end|dd%>

The angle brackets (<>) indicate that the item is required.   There are 4 possible values to enter: the word “start”, the word “middle”, and the word “end”.  The final choice “dd%” (with the “dd” in italic text), means that a percentage is to be entered eg “30%, “50%”, “100%”.

Example—optional value

[volume-name]

The square brackets ([]) indicate that the value is optional. The use of italic text means that an appropriate value is to be entered, in this case the name of a volume (disk).  In some cases, values may be repeated.  This is denoted with the “*” character:

[volume-name [volume-name]*]

The line above indicate that all items are optional, but that more than one volume may be specified, separate by white space. For example:

disktester show-info "Macintosh HD" Backup "RAID"

Note the use of quotation marks around “Macintosh HD” above (straight quotes, not curly quotes). This is important: if the quotes are not used, then DiskTester will see the four (4) volumes named “Macintosh”, “HD”, “Backup”, and “RAID” instead of the desired “Macintosh HD”, “Backup”, and “RAID”.

Example—dissecting command syntax

Shown below is the command syntax as displayed by “disktester help run-area-cmd”.  (Note than when in terminal, there is no italic or bold or color to the text).  Note also that long option names must be specified starting with two dashes “--” and short option names must be specified using a single dash “-” eg “--chunk-size” vs “-c”.

run-area-test
        [--output-level|-l <terse|normal|verbose[+log]>]
        [--chunk-size|-c <size[K|M|G|T]>]
        [--test-size|-t <size[K|M|G|T]|max>]
        [--iterations|-i <count>]
        [--delta-percent|-p <percent>]
        <volume-name>

Here is what the above syntax means:

  • the command name is run-area-test;
  • none of the options are required;
  • exactly one volume name must be specified;
  • the amount of output printed by DiskTester is controlled by the “output-level” option, which may be specified as either “--output-level” or “-l”.  One of the values “terse”, “normal”, etc is required and “+log” may be optionally appended to that value;
  • the chunk size is specified via “--chunk-size” or “-c”, and requires a size value that may optionally include units of “K”, “M”, etc.
  • the test size is specified via “--test-size” or “-t”, and requires a size value that may optionally include units of “K”, “M”, ..., or “max”.
  • the number of iterations (repeats) of the test is specified by “--iterations” or “-i”.  A count must be supplied eg “5”.
  • the stepping percent (eg 10% means 0, 10, 20, ..., 100) is specified by “--delta-percent” or “-p”, and requires a percentage (from 1 to 100).

Here are example uses of the run-area-test command, where “Speedy” is the volume name:

disktester run-area-test Speedy

disktester run-area-test --output-level verbose Speedy

disktester run-area-test --chunk-size 32M --test-size max Speedy

disktester run-area-test --output-level verbose --chunk-size 32M --test-size max --iterations 10 --delta-percent 5 Speedy

disktester run-area-test -l verbose -c 32M -t max -i 10 -p 5 Speedy

The latter two examples are equivalent; the first one uses the full option names, and the second one uses the single-character equivalents.

Shortcuts

Within Terminal, there are various shortcuts you can use to reduce the amount of typing you need to do. Here are a few simple ones that work in the “bash” shell (the default for MacOS X):

  • the arrow keys can be used to go backwards in the "history" of commands you have invoked. Use the up-arrow key to go backward and the up-arrow key to go forward;
  • the “!!” command means repeat the previous command eg:
    llcG5:/Applications/Utilities lloyd$ !!
  • the 'history' command;
  • the 'alias' command;
  • a login profile file;
  • shell variables;
  • a shell script.

The 'alias' command

Suppose you always want to use run-area-test with specific arguments. Here is how to define a shortcut:

llcG5:/Applications/Utilities lloyd$ alias run-area-test="/disktester run-area-test --chunk-size 32M --test-size 1G --delta-percent 20"

Now you can simply enter 'run-area-test':

llcG5:/Applications/Utilities lloyd$ run-area-test X8

The 'alias' command is fairly limited, but very useful nonetheless.

The 'history' command

To see commands that you’ve previously entered, type 'history'. You can also specify the number of previous commands. For example, to see the last 30 commands you’ve entered:

llcG5:/Applications/Utilities lloyd$ history 3
  560  /disktester create-files -n 10 Small
  561  /disktester create-files -n 10 -l verbose Small
  562  /disktester create-files -n 100 -l verbose Small

You can then reference a command by number. For example, to repeat command 560, you would enter:

llcG5:/Applications/Utilities lloyd$ !560

Creating a login profile file

When you start Terminal, a “shell” is the program that runs within the window and accepts and executes the commands yo enter. On MacOS 10.4, the 'bash' is the default. If you are running MacOS X 10.3, you can set the default shell to bash using Terminal preferences, setting the shell to “/bin/bash”.

You can define shortcuts such as 'alias' in a login file that gets read whenever you open Terminal. Create a plain-text file named “ .bash_profile” in your home directory containing all your shortcuts. The quickest way to create and edit the file is as follows:

llcG5:~ lloyd$ cat > .bash_profile
^D
llcG5:~ lloyd$ open .bash_profile

The “^D” means to type control-D, which signals the end of input to the 'cat' command . The control key is labeled “control” on your keyboard. Following that, the 'open' command opens the (empty) file in the default text editor, typically TextEdit.

Before putting commands into '.bash_profile', you might want to verify you have typed them correctly by trying them first, then copying what you typed.

Shell variables [advanced topic]

Shell variables allow you to place values into variables, and then use those variables wherever desired. This can be useful if you want to run a series of commands, and want to ensure that the same parameters are used for every command.

In the example below, two variables are defined, 'CHUNK_SIZE' and 'TEST_SIZE', which are then used in the 'run-area-test' command. The '$' character means “substitute the value of the variable”. For example:

llcG5:~ lloyd$ export CHUNK_SIZE="--chunk-size 32M"
llcG5:~ lloyd$ export TEST_SIZE="--test-size 1G"
llcG5:~ lloyd$ /disktester run-area-test $CHUNK_SIZE $TEST_SIZE X8
DiskTester 2.0fc2 (C) 2003-2006 diglloyd, Inc. All Rights Reserved

=> Allocating maximum size contiguous file on "X8" (1.01TB)...
990.2GB (95.7% of volume size)

=> Using test size of 1GB, 32MB at a time, across a 990.2GB test file.
=> Testing at: 0%, 10%, 20%, 30%, 40%, 50%, 60%, 70%, 80%, 90%, 100%

Area 0% (offset 0B): writing...496MB/sec, reading...434MB/sec
… addititional output not shown …

Shell scripts

How to write shell scripts is beyond the scope of this document, and indeed the author is not particularly skilled at it. However, for those more adventurous souls, an example is shown below.

For your convenience, the script is in the “Extras” folder on the installation disk image.

Assuming you have saved the script as “test-all.sh” in your home directory, and that DiskTester is installed in /Applications/Utilities, the following commands will execute the script (substitute the desired volume name for volume-name):

llcG5:~ lloyd$ cd
llcG5:~ lloyd$ export DT=/Applications/Utilities/disktester
llcG5:~ lloyd$ export TEST_VOL=volume-name
llcG5:~ lloyd$ sh test-all.sh

The example script: 

#/bin/sh
export LOGGING="--output-level normal+log"
export DT=disktester

export LOG_FILE="$HOME/Library/Logs/disktester.log"

echo "Verifying volume $TEST_VOL" | tee -a $LOG_FILE
diskUtil verifyVolume /Volumes/$TEST_VOL | tee -a $LOG_FILE

$DT;$LINE
$DT help ;$LINE
$DT help run-area-test;$LINE
$DT help run-sequential;$LINE
$DT help run-sequential-suite;$LINE
$DT help run-random;$LINE
$DT help test-reliability;$LINE
$DT help show-info;$LINE
$DT help create-files;$LINE
$DT help read-files;$LINE
$DT help create-hierarchy;$LINE
$DT help create-hierarchy-template;$LINE
$DT help help;$LINE

$DT show-info $LOGGING $TEST_VOL;$LINE
$DT show-info $LOGGING ;$LINE

$DT run-area-test  $LOGGING -c 6M -p 50 -t 128M -i 1 $TEST_VOL;$LINE
$DT run-area-test  $LOGGING -c 6M -p 50 -t 128M -i 3 $TEST_VOL;$LINE
$DT run-area-test  $LOGGING -c 6M -p 50 -t 128M -i 3 $TEST_VOL;$LINE

$DT test-reliability  $LOGGING --test-size 256M $TEST_VOL;$LINE
$DT test-reliability  $LOGGING --test-size 256M -x random  $TEST_VOL;$LINE
$DT test-reliability  $LOGGING --test-size 256M -i 3  -x 01 $TEST_VOL;$LINE

$DT run-sequential  $LOGGING -c 32M -t 128M -a start -i 1 $TEST_VOL;$LINE
$DT run-sequential  $LOGGING -c 32M -t 128M -a middle -i 1 $TEST_VOL;$LINE
$DT run-sequential  $LOGGING -c 32M -t 128M -a end -i 1 $TEST_VOL;$LINE
$DT run-sequential  $LOGGING -c 32M -t 128M -a 20% -i 1 $TEST_VOL;$LINE
$DT run-sequential  $LOGGING -c 32M -t 128M -a start -i 3 $TEST_VOL;$LINE
$DT run-sequential  $LOGGING -c 32M -t 128M -a start -i 3 $TEST_VOL;$LINE

$DT run-sequential-suite  $LOGGING -t 128M -s 1M -e 8M -i 1 $TEST_VOL;$LINE
$DT run-sequential-suite  $LOGGING -t 128M -s 1M -e 8M -i 3 $TEST_VOL;$LINE
$DT run-sequential-suite  $LOGGING -t 128M -s 1M -e 8M -i 3 $TEST_VOL;$LINE

$DT run-random  $LOGGING -t 4G -c 32K --num-random 200 -i 1 $TEST_VOL;$LINE
$DT run-random  $LOGGING -t 4G -c 32K --num-random 200 -i 3 $TEST_VOL;$LINE
$DT run-random  $LOGGING -t 4G -c 32K --num-random 200 -i 3 $TEST_VOL;$LINE

$DT run-async-test  $LOGGING --duration 10S $TEST_VOL;$LINE

echo "Verifying volume $TEST_VOL" | tee -a $LOG_FILE
diskUtil verifyVolume /Volumes/$TEST_VOL | tee -a $LOG_FILE

$DT create-hierarchy-template  $LOGGING $TEST_VOL;$LINE

$DT create-files  $LOGGING --file-size 10M --num-files 10 $TEST_VOL;$LINE
$DT create-files  $LOGGING --file-size 128K --num-files 2000 $TEST_VOL;$LINE

echo "Verifying volume $TEST_VOL" | tee -a $LOG_FILE
diskUtil verifyVolume /Volumes/$TEST_VOL | tee -a $LOG_FILE

$DT read-files	 $LOGGING $TEST_VOL;$LINE

echo "Verifying volume $TEST_VOL" | tee -a $LOG_FILE
diskUtil verifyVolume /Volumes/$TEST_VOL | tee -a $LOG_FILE

echo DONE

Back to DiskTester User Manual