VDT(1)

NAME
vdt - visual disk test

SYNOPSIS
vdt [-options]

DESCRIPTION
vdt performs i/o tests on files, logical volumes, partitions or whole disks.

vdt offers various disk addressing patterns and test area selections.

OPTIONS
 basic parameters:

 -b size       alternate i/o buffer size
 -c filename   target file for comparison tests
 -D deadline   run until [[[CC]YY]MMDD]hhmm.ss
 -e seed       random number generator seed
 -f filename   use this file for read/write (compound) tests
 -I 'comment'  (short) information to appear on screen and logs
 -m number     maximum number of operations per test
 -M number     maximum number of passes per test
 -p percent    test area = given % of testsize
 -P pattern    filler for output buffer (0oct|Xhex|Bbin|dec|Rand|Zero)
 -r filename   input(source) file for read-only(comparison) tests
 -s stripes    split test area in given # of stripes
 -t lifespan   [[hh:]mm:]ss = maximum elapsed time per test
 -w filename   use this output file for write-only tests
 -z testsize   test area = just this much
 -Z bulksize   terminate after transfer this much

 basic tests:

 --make        create & fill test (Bunch_of_Sectors at a time)
 --poke        poke test (same as '--writ --sect')
 --read        read test (B.o.S. at a time)
 --seek        seek test (same as '--read --sect')
 --writ        write test (B.o.S. at a time)

 compound tests:

 --aver        ratification test (write, read back, compare)
 --blot        update test (read, stain, write back)
 --comp        comparison test (B.o.S. at a time)
 --cool        freshen test (read, write back)
 --copy        copy test (B.o.S. at a time)
 --stir        shuffle test (read, write somewhere else)

 stress tests:

 --boil        read-only  test (2 files, all addressing modes)
 --brew        read+write test (2 files, all addressing modes)
 --burn        write-only test (1 file,  all addressing modes)
 --cook        read-only  test (1 file,  all addressing modes)
 --mess        read+write test (1 file,  all addressing modes)

 addressing patterns:

 --incr        incrementing addresses (start to end)
 --decr        decrementing addresses (end to start)
 --conv        converging addresses (edges to middle)
 --scat        scattering addresses (middle to edges)
 --gold        'diamond'-pattern (middle to edges and back)
 --spot        'X'-pattern (edges to middle and back)
 --rand        random addresses

 region selection:

 --edge        --head and --tail combined
 --head        select initial portion of test area (default)
 --core        select central portion of test area
 --tail        select  final  portion of test area
 --slab        --edge and --core combined
 --even        divide test area proportionally
 --flip        invert selection of test area

 entropy control:

 --same        yields same random numbers across tests
 --firm        yields same random numbers across platforms
 --fate        same as '--same --firm'
 --whim        extra entropy for unpredictable randomness

 cache illustration:

 --cloy        stops after (default 90) hit limit
 --glib        smooth transition to next round
 --snag        cloggy transition to next round

 operation flags:

 -A            append to log file
 -E            separate error messages into 'vdt.err'
 -F            force overwrite existing files
 -T            timestamped names for log and error files
 -V            show version info and exit
 -v            verbose and additional details

 --si          use powers of 1000 not 1024

 --bias        skip (possibly) cached B.o.S.
 --bang        same as -F above
 --boon        allow last test to end cleanly past deadline
 --daze        full buffer random pattern fill (implies --stew)
 --fast        apply faster algorithms
 --full        random seek within B.o.S.
 --help        show this usage help
 --once        same as --uniq
 --part        compute performance using alt. buffer size
 --raze        flatten (truncate) output file
 --sect        i/o just a single (512-Byte) sector at a time
 --stew        applies '-P Rand' for each B.o.S.
 --sync        synchronous (blocking) output
 --uniq        test each and every random address just once
 --wait        request user interaction to finish
 --wrap        wrap around EOF until timeout

 extra parameters:

 -L lines      override screen's # of lines
 -C columns    ditto for columns

USAGE
Without any options, vdt shows a minimal help message, and bails out.

Upon completion, a log file (`vdt.log' by default) can be found in the calling directory.

The location and name of this log file can be modified by means of the flags shown above.

Any test can be time-limited by using the '-t seconds' (or the more complete '-t HH:MM:SS' form) option.

The '-v' flag enhances log details, changes log output format from 'line-wise' (all-in-one-line) to 'column-wise' (one info per line), and improves visual feedback.

The -P 'fill-pattern' accepts, besides simple decimal numbers, the forms '0<octal-number>' (eg.: 0572), 'x<hexadecimal-number>' (eg.: Xa5b3c), 'b<binary-number>' (eg.: b01011010), the words 'zero' (for 'all-zero'), and 'random' (for a random bit pattern) -- all case-insensitive and ranging in size from one single bit to 64 bits.

Ordinarily, Vdt does not interact with the observer, but the '--wait' flag can give you an option to pause at test completion just before cleaning up the screen (specially useful if tests are short-lived).

Vdt can be interrupted at any time with '^C' (Control+C).

Command-line parameters are trimmed to no less than 512 characters per string (larger values are 'operating system'-dependent), to avoid buffer-overflow exploits; exceeding characters are ignored.

FILES
 vdt.log                vdt's log file
 vdt.err                separate error messages
 vdt.opt                vdt's options file

DIRECTORIES
 $HOME/.vdt             vdt's workplace (if found)
 /usr/local/bin         vdt's default executable path

EXAMPLES
Example 1: create and fill a 64MiB new file

 $ vdt -w test.dat --make -z 64M

Example 2: basic read test from start to end

 $ vdt -r test.dat --read --incr

Example 3: basic write-test an existing file from start to end

 $ vdt -w test.dat --writ --incr

Example 4: stress write-test an existing file

 $ vdt -w test.dat --burn

Example 5: copy-test an existing file to a new one, pausing at completion.

 $ vdt -r test.dat -w clone.dat --copy --wait

Example 6: compare-test two existing files, pausing at completion.

 $ vdt -r test.dat -c clone.dat --comp --wait

Example 7: time-limited (to 3 seconds) random write-test with pause

 $ vdt -w test.dat --writ --rand --wait -t 3

Example 8: same as above with synchronous/blocking output

 $ vdt -w test.dat --writ --rand --wait -t 3 --sync

ENVIRONMENT
 TERM           The value of the TERM environment variable may affect
                the output of `vdt'.

 VDT            Optionally used to automate initialization of flags
                and/or parameters.

EXIT STATUS
The following exit values are returned:

 0                      No errors of any kind.

 >0                     An error occurred.

DIAGNOSTICS
 EACCES         Permission denied (POSIX.1)

                Search permission is denied for
                a component of the path prefix
                of a given <pathname>.

 ENOTTY         Inappropriate I/O control operation (POSIX.1)

                The type of the file or device being tested
                is not suitable (eg. chosing a block device
                instead of a raw device).

SEE ALSO
opm(1), xdf(1), iostat(1).

NOTES
Ordinarily, `vdt' does not require `root' privileges or SUID file permissions in order to operate on regular files.

The INT, and TERM signals are caught by `vdt', allowing for an orderly quit.

The QUIT signal causes `vdt' to restart the current test, as would happen in the case of a window resize.

CAVEATS
On some operating systems, the logical sector size may be greater than 512 bytes.

When the test subject is big enough while available memory not so, enlarging the screen window may avoid buffer allocation failures.

In the event of a failure to detect the actual disk/partition size, providing an explicit test area size (by means of '-z') may circumvent the problem.

BUGS
A screen with less than 24 lines results in garbled output.

On some systems, using the default 24x80 screen leads to a miscalculation of available columns and a shorter block-window; the 'easier' workaround is (if possible) to manually enlarge the screen window horizontally by at least one column, or simply to use the '-C 64' option in order to force the use of all available columns.

Not all possibly harmfull/misleading/nonsensical combinations of the options are prevented nor handled in the appropriate manner (like, for example, --make and --wrap), and such use possibly may (and most certainly will) cause unpredictable results (and/or consequential damage if the test type is not read-only).

AUTHOR
The original and current versions of `vdt' consist of code and documentation written by:

        Alexandre Botao           http://botao.org
        botao@unix.sh
        botao@linux.sh            alexandre@botao.org

COPYRIGHT
        Copyright (C) 2010 Alexandre Botao

LICENSE
`vdt' is `Free and Open Source Software' (FOSS), and is licensed under the GNU GENERAL PUBLIC LICENSE Version 3 (the "License");

You may not use `vdt' except in compliance with the License. You may obtain a copy of the License at

        http://www.gnu.org/licenses/

Additionally, a copy of the License is distributed along with `vdt' in a file called 'LICENSE';

SUPPORT
 Commercial support is NOT available for `vdt'.
 Suggestions and/or bug reports are very welcome.

DISCLAIMER
`vdt' is distributed on an ``AS IS'' basis, WITHOUT ANY WARRANTY OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.