." Text automatically generated by txt2man-1.4.7
.TH dits 1 "October 18, 2005" "src" "FreeBSD Reference Manual"
.SH NAME
\fBdits \fP- Data Integrity Test Suite
\fB
.SH SYNOPSIS
.nf
.fam C
\fBdits\fP \fB-i\fP [\fB-rv\fP] [\fB-o\fP \fIskip\fP] [\fB-S\fP \fImax\fP] \fIpartition\fP \fInsectors\fP
\fBdits\fP \fB-t\fP [\fB-nrv\fP] [\fB-a\fP \fInaioreqs\fP] [\fB-b\fP \fIbps\fP] [\fB-C\fP \fInprocs\fP] [\fB-I\fP \fIiter\fP] [\fB-o\fP \fIskip\fP] [\fB-S\fP \fImax\fP] [\fB-s\fP \fImin\fP] \fIpartition\fP
\fBdits\fP \fB-c\fP [\fB-Rrv\fP] [\fB-a\fP \fInreqs\fP] [\fB-o\fP \fIskip\fP] [\fB-S\fP \fImax\fP] \fIpartition\fP
\fBdits\fP \fB-D\fP [\fB-v\fP] \fIsrc\fP \fIdst\fP
\fBdits\fP \fB-d\fP [\fB-rv\fP] [\fB-o\fP \fIskip\fP] [\fB-S\fP \fImax\fP] \fIpartition\fP [\fIstart\fP [\fIstop\fP]]
\fBdits\fP \fB-h\fP
\fBdits\fP \fB-V\fP
.fam T
.fi
.SH DESCRIPTION
\fBdits\fP is a tool for validating disk drivers, file systems, and
lock managers. More than a simple exerciser, \fBdits\fP is able to
verify that no detectable data integrity errors have occurred.
.PP
The tool does its work in three mutually exclusive phases:
.PP
(1) Init - Write a unique ID to each sector in the test bed.
.PP
(2) Test - Continuously select arbitrary non-overlapping ranges of
sectors and swap them. File range locking is used to ensure mutual
exclusion amongst concurrently executing processes working in the
same test bed.
.PP
(3) Check - Verify that each and every unique ID written in
phase (1) is intact and neither missing nor duplicated.
.SH OPTIONS
.TP
.B
\fB-a\fP \fInreqs\fP
use AIO, limit to \fInreqs\fP outstanding requests
.TP
.B
\fB-b\fP \fIbps\fP
limit per-process throughput to \fIbps\fP blocks/sec
.TP
.B
\fB-C\fP \fInprocs\fP
set concurrency (default: 4)
.TP
.B
\fB-c\fP
check
.TP
.B
\fB-D\fP \fIsrc\fP \fIdst\fP
duplicate session '\fIsrc\fP' to '\fIdst\fP'
.TP
.B
\fB-d\fP
dump the given range of sectors
.TP
.B
\fB-h\fP
show this help list
.TP
.B
\fB-I\fP \fIiter\fP
\fImax\fP iterations
.TP
.B
\fB-i\fP
initialize test bed
.TP
.B
\fB-N\fP session
specify a session name
.TP
.B
\fB-n\fP
don't perform write operations
.TP
.B
\fB-o\fP \fIskip\fP
\fIskip\fP first \fInsectors\fP in \fIpartition\fP
.TP
.B
\fB-R\fP
try to repair a corrupted test bed
.TP
.B
\fB-r\fP
disable run time sanity checking
.TP
.B
\fB-S\fP \fImax\fP
maximum sectors to read/write (default: 2048)
.TP
.B
\fB-s\fP \fImin\fP
minimum sectors to read/write (default: 1)
.TP
.B
\fB-t\fP
test
.TP
.B
\fB-V\fP
print version
.TP
.B
\fB-v\fP
increase verbosity
.TP
.B
\fIpartition\fP
a disk \fIpartition\fP, volume, file, etc, \.\.\.
.TP
.B
\fInsectors\fP
number of sectors in test bed
.TP
.B
session
a session name
.TP
.B
\fIstart\fP
starting block number
.TP
.B
\fIstop\fP
ending block number
.SH EXAMPLES
Typically, one runs \fBdits\fP over a raw device, but it
will run over a file in a file system. Given
a raw device, one must first initialize the test
bed in which \fBdits\fP will work. The larger the bed
the longer it takes to initialize and check.
.PP
To initialize the test bed, choose some number
of sectors. For example, a test bed that is
128MB in size requires 262144 512-byte sectors.
.PP
Given a logical volume named lvtest on AIX:
.PP
$ \fBdits\fP \fB-vi\fP 262144 /dev/rlvtest
.RE
.PP

.RS
Next, run the test process. By default this
process will fork and generate four test
process that will access the test bed concurrently.
.PP
$ \fBdits\fP \fB-tv\fP /dev/rlvtest
.RE
.PP

.RS
This process will run until interrupted with <CTRL>\fB-C\fP,
generating as much I/O as possible within the
constraints of the block swapping algorithm.
.PP
Finally, kill the test process (with <CTRL-C> and verify
the integrity of the test bed:
.PP
$ \fBdits\fP \fB-cv\fP \fB-a2\fP /dev/rlvtest
.RE
.PP

.RS
If successful, the check process will report
statistics on the state of the test bed and
exit with a zero result code. If any data integrity
errors are detected, the check process will produce
error messages to that effect and return a non-zero
result.
.RE
.PP

.RS
To use POSIX AIO, give \fBdits\fP the \fB-a\fP flag during the
test process. The parameter to the \fB-a\fP flags is the
maximum number of concurrent requests that you wish for
the test process to have outstanding at any one time.
Note: AIO mode currently only works with one test process
because of a locking problem.
.PP
$ \fBdits\fP \fB-v\fP \fB-a32\fP /dev/rlvtest
.RE
.PP

.RS
To use \fBdits\fP on a file system, first create a file
that will be used as the test bed:
.PP
$ dd if=/dev/zero of=/tmp/testbed bs=1024k count=128
.RE
.PP

.RS
Then simply run \fBdits\fP as before, but give it the name
of the file (/tmp/testbed) instead of /dev/rlvtest.
.SH DIAGNOSTICS
The \fBdits\fP utility exits 0 on success, and non-zero
if an error occurs.
.SH CAVEATS
Be warned that because of file system caching and
such, the behavior of running \fBdits\fP on a file in a
file system or on a block device will produce
significantly different result than running
on a raw device. In particular, if the machine
crashes while \fBdits\fP is running in test mode, the
test bed will most likely be corrupted beyond
repair.
.SH AUTHORS
Greg Becker greg@codeconcepts.com
.PP
Thanks to Jeff d'Arcy for explaining the functional
concept and inspiring the first of a number of
predecessors to this particular incarnation.