Command Line Tips

This overview is oriented to usage of diglloydTools .

A “command line” facility exists in Mac OS X. A command line is the traditional unix and Windows approach to getting things done. A command line is very powerful, but it’s not a GUI. To run a command, use the Terminal program, found in the /Applications/Utilities folder.

The DiskTester and MemoryTester and IntegrityChecker command line tools all use the same syntax.

Using command sub-command options arguments

Type the command name (eg 'disktester' or 'mt' or 'ic'), then the sub-command, then options (if any) and operand(s). For example:

disktester run-area-test --iterations 3 Scratch4
disktester fill-volume "Macintosh HD"
ic update Master
mt stress

As seen above, this is what the command looks like in Terminal (at top), with program output following it.

In the example at right, the program to run is disktester, the command is run-area-test, the iterations option has been specified with a value of "3", and the drive to test is Scratch4.

You can Select All in the Terminal window to save the output as text, or select just the output you want.

Using DiskTester in Terminal

Common mistakes

Spaces in a volume name PERMALINK

Folders and/or paths that contain spaces must be quoted. This is because the command “shell” uses spaces as a delimiter to separate different arguments. For example, this command tells IntegrityChecker to verify the two items "Macintosh" and "HD", probably not at all what you meant!

llcG5:/ lloyd$ ic verify Macintosh HD <=== needs quotes!

To avoid the spaces issues, use straight quotes to indicate that it’s one name eg “Macintosh HD” :

llcG5:/ lloyd$ ic verify "Macintosh HD"

If a path contains one or more folders with a space, use quotes around the whole path eg:

llcG5:/ lloyd$ ic verify "/Volumes/Macintosh HD"

Typos

The most common user error is typing a command incorrectly. For example, you might type “stres” instead of the correct “stress”. You will get an error something like this:

llcMP:MPG lloyd$ mt stres
MemoryTester 1.3.0 beta 3, 64-bit
Copyright 2006-2009 diglloyd, Inc. All Rights Reserved
Use of this software requires a license. See https://macperformanceguide.com/../index.html

Mac OS X 10.6.1, 16 virtual cores, 24576MB
Tuesday, November 3, 2009 7:13:08 PM PT

mt stres
Processor clock: 2925 MHz
Bus clock: 1073 MHz

ERROR: unknown cmd [-40003], msg ="Unknown command: "stres"

Command path

If you get “command not found”, it’s because your “path” is not set.

llcMP:MPG lloyd$ disktester
-bash: disktester: command not found

The diglloydSoftware installer sets the path for you. You can also add it manually by editing “.bash_profile” in your home directory.

However, any shell (Terminal) command can be run explicitly by specifying its full path, or changing to the directory (folder) containing it. If you wish to manually install, then be aware of this. You can keep any of the diglloyd software tools anywhere on any hard disk.

For example, suppose IntegrityChecker is in /Applications/Utilities/diglloyd folder and you want to run the IntegrityChecker verify command on the volume “Master”. You would enter the following commands; the “./” part means “look in the current directory”.

llcMP:~ lloyd$ cd /Applications/Utilities/diglloyd
llcMP:~ lloyd$ ./ic verify Master

Syntax overview

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).

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 PERMALINK

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/10.5, 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) PERMALINK

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
… additional output not shown …