220 lines
11 KiB
Groff
220 lines
11 KiB
Groff
.TH SG_VERIFY "8" "December 2019" "sg3_utils\-1.45" SG3_UTILS
|
|
.SH NAME
|
|
sg_verify \- invoke SCSI VERIFY command(s) on a block device
|
|
.SH SYNOPSIS
|
|
.B sg_verify
|
|
[\fI\-\-0\fR] [\fI\-\-16\fR] [\fI\-\-bpc=BPC\fR] [\fI\-\-count=COUNT\fR]
|
|
[\fI\-\-dpo\fR] [\fI\-\-ff\fR] [\fI\-\-ebytchk=BCH\fR] [\fI\-\-group=GN\fR]
|
|
[\fI\-\-help\fR] [\fI\-\-in=IF\fR] [\fI\-\-lba=LBA\fR] [\fI\-\-ndo=NDO\fR]
|
|
[\fI\-\-quiet\fR] [\fI\-\-readonly\fR] [\fI\-\-verbose\fR]
|
|
[\fI\-\-version\fR] [\fI\-\-vrprotect=VRP\fR] \fIDEVICE\fR
|
|
.SH DESCRIPTION
|
|
.\" Add any additional description here
|
|
.PP
|
|
Sends one or more SCSI VERIFY (10 or 16) commands to \fIDEVICE\fR. These SCSI
|
|
commands are defined in the SBC\-2 and SBC\-3 standards at https://www.t10.org
|
|
and SBC\-4 drafts.
|
|
.PP
|
|
When \fI\-\-ndo=NDO\fR is not given then the verify starts at the logical
|
|
block address given by the \fI\-\-lba=LBA\fR option and continues for
|
|
\fI\-\-count=COUNT\fR blocks. No more than \fI\-\-bpc=BPC\fR blocks are
|
|
verified by each VERIFY command so if necessary multiple VERIFY commands are
|
|
sent. Medium verification operations are performed by the \fIDEVICE\fR (e.g.
|
|
assuming each block has additional EEC data, check this against the logical
|
|
block contents). No news is good news (i.e. if there are no verify errors
|
|
detected then no messages are sent to stderr and the Unix exit status is 0).
|
|
.PP
|
|
When \fI\-\-ndo=NDO\fR is given then the \fI\-\-bpc=BPC\fR option is
|
|
ignored. A single VERIFY command is issued and a comparison starts at the
|
|
logical block address given by the \fI\-\-lba=LBA\fR option and continues for
|
|
\fI\-\-count=COUNT\fR blocks. The VERIFY command has an associated data\-out
|
|
buffer that is \fINDO\fR bytes long. The contents of the data\-out buffer are
|
|
obtained from the \fIFN\fR file (if \fI\-\-in=FN\fR is given) or from stdin.
|
|
A comparison takes place between data\-out buffer and the logical blocks
|
|
on the \fIDEVICE\fR. If the comparison is good then no messages are sent to
|
|
stderr and the Unix exit status is 0. If the comparison fails then a sense
|
|
buffer with a sense key of MISCOMPARE is returned; in this case the Unix exit
|
|
status will be 14. Messages will be sent to stderr associated with MISCOMPARE
|
|
sense buffer unless the \fI\-\-quiet\fR option is given.
|
|
.PP
|
|
In SBC\-3 revision 34 the BYTCHK field in all SCSI VERIFY commands was
|
|
expanded from one to two bits. That required some changes in the options
|
|
of this utility, see the section below on OPTION CHANGES.
|
|
.SH OPTIONS
|
|
Arguments to long options are mandatory for short options as well.
|
|
The options are arranged in alphabetical order based on the long
|
|
option name.
|
|
.TP
|
|
\fB\-0\fR, \fB\-\-0\fR
|
|
a buffer \fINDO\fR bytes long full of zeros is sent as the data\-out
|
|
part of a VERIFY command. So stdin is not read and if \fI\-\-in=IF\fR
|
|
is given, an error is generated. Useful when \fIBCH\fR is 3 to check
|
|
if some or all of \fIDEVICE\fR (e.g. a disk) is zero filled blocks.
|
|
.TP
|
|
\fB\-S\fR, \fB\-\-16\fR
|
|
uses a VERIFY(16) command (default VERIFY(10)). Even without this option,
|
|
using an \fI\-\-lba=LBA\fR which is too large, will cause the utility
|
|
to issue a VERIFY(16) command.
|
|
.TP
|
|
\fB\-b\fR, \fB\-\-bpc\fR=\fIBPC\fR
|
|
this option is ignored if \fI\-\-ndo=NDO\fR is given. Otherwise \fIBPC\fR
|
|
specifies the maximum number of blocks that will be verified by a single SCSI
|
|
VERIFY command. The default value is 128 blocks which equates to 64 KB for a
|
|
disk with 512 byte blocks. If \fIBPC\fR is less than \fICOUNT\fR then
|
|
multiple SCSI VERIFY commands are sent to the \fIDEVICE\fR. For the default
|
|
VERIFY(10) \fIBPC\fR cannot exceed 0xffff (65,535) while for VERIFY(16)
|
|
\fIBPC\fR cannot exceed 0x7fffffff (2,147,483,647). For recent block
|
|
devices (disks) this value may be constrained by the maximum transfer length
|
|
field in the block limits VPD page.
|
|
.TP
|
|
\fB\-c\fR, \fB\-\-count\fR=\fICOUNT\fR
|
|
where \fICOUNT\fR specifies the number of blocks to verify. The default value
|
|
is 1 . If \fICOUNT\fR is greater than \fIBPC\fR (or its default value of 128)
|
|
and \fINDO\fR is not given, 0 or less than multiple SCSI VERIFY commands are
|
|
sent to the device. Otherwise \fICOUNT\fR becomes the contents of the
|
|
verification length field of the SCSI VERIFY command issued. The
|
|
.B sg_readcap
|
|
utility can be used to find the maximum number of blocks that a block
|
|
device (e.g. a disk) has.
|
|
.TP
|
|
\fB\-d\fR, \fB\-\-dpo\fR
|
|
disable page out changes the cache retention priority of blocks read on
|
|
the device's cache to the lowest priority. This means that blocks read by
|
|
other commands are more likely to remain in the device's cache.
|
|
.TP
|
|
\fB\-E\fR, \fB\-\-ebytchk\fR=\fIBCH\fR
|
|
sets the BYTCHK field to \fIBCH\fR overriding the value (1) set by the
|
|
\fI\-\-ndo=NDO\fR option. Values of 1, 2 or 3 are accepted for \fIBCH\fR
|
|
however sbc3r34 reserves the value 2. If this option is given then
|
|
\fI\-\-ndo=NDO\fR must also be given. If \fIBCH\fR is 3 then \fINDO\fR
|
|
should be the size of one logical block (plus the size of some or all
|
|
of the protection information if \fIVRP\fR is greater
|
|
than 0).
|
|
.TP
|
|
\fB\-f\fR, \fB\-\-ff\fR
|
|
a buffer \fINDO\fR bytes long full of 0xff bytes is sent as the data\-out
|
|
part of a VERIFY command. So stdin is not read and if \fI\-\-in=IF\fR
|
|
is given, an error is generated. Useful when \fIBCH\fR is 3 to check
|
|
if some or all of \fIDEVICE\fR (e.g. a disk) is 0xff byte filled blocks.
|
|
.TP
|
|
\fB\-g\fR, \fB\-\-group\fR=\fIGN\fR
|
|
where \fIGN\fR becomes the contents of the group number field in the SCSI
|
|
VERIFY(16) command. It can be from 0 to 63 inclusive. The default value for
|
|
\fIGN\fR is 0. Note that this option is ignored for the SCSI VERIFY(10)
|
|
command.
|
|
.TP
|
|
\fB\-h\fR, \fB\-\-help\fR
|
|
output the usage message then exit.
|
|
.TP
|
|
\fB\-i\fR, \fB\-\-in\fR=\fIIF\fR
|
|
where \fIIF\fR is the name of a file from which \fINDO\fR bytes will be read
|
|
and placed in the data\-out buffer. This is only done when the
|
|
\fI\-\-ndo=NDO\fR option is given. If this option is not given then stdin
|
|
is read. If \fIIF\fR is "\-" then stdin is also used.
|
|
.TP
|
|
\fB\-l\fR, \fB\-\-lba\fR=\fILBA\fR
|
|
where \fILBA\fR specifies the logical block address of the first block to
|
|
start the verify operation. \fILBA\fR is assumed to be decimal unless prefixed
|
|
by '0x' or a trailing 'h' (see below). The default value is 0 (i.e. the start
|
|
of the device).
|
|
.TP
|
|
\fB\-n\fR, \fB\-\-ndo\fR=\fINDO\fR
|
|
\fINDO\fR is the number of bytes to obtain from the \fIFN\fR file (if
|
|
\fI\-\-in=FN\fR is given) or from stdin. Those bytes are placed in the
|
|
data\-out buffer associated with the SCSI VERIFY command and \fINDO\fR
|
|
is placed in the verification length field in the cdb. The default value
|
|
for \fINDO\fR is 0 and the maximum value is dependent on the OS. If the
|
|
\fI\-\-ebytchk=BCH\fR option is not given then the BYTCHK field in the cdb
|
|
is set to 1.
|
|
.TP
|
|
\fB\-q\fR, \fB\-\-quiet\fR
|
|
suppress the sense buffer messages associated with a MISCOMPARE sense key
|
|
that would otherwise be sent to stderr. Still set the exit status to 14
|
|
which is the sense key value indicating a MISCOMPARE .
|
|
.TP
|
|
\fB\-r\fR, \fB\-\-readonly\fR
|
|
opens the DEVICE read\-only rather than read\-write which is the
|
|
default. The Linux sg driver needs read\-write access for the SCSI
|
|
VERIFY command but other access methods may require read\-only access.
|
|
.TP
|
|
\fB\-v\fR, \fB\-\-verbose\fR
|
|
increase the level of verbosity, (i.e. debug output).
|
|
.TP
|
|
\fB\-V\fR, \fB\-\-version\fR
|
|
print the version string and then exit.
|
|
.TP
|
|
\fB\-P\fR, \fB\-\-vrprotect\fR=\fIVRP\fR
|
|
where \fIVRP\fR is the value in the vrprotect field in the VERIFY command
|
|
cdb. It must be a value between 0 and 7 inclusive. The default value is
|
|
zero.
|
|
.SH BYTCHK
|
|
BYTCHK is the name of a field (two bits wide) in the VERIFY(10) and
|
|
VERIFY(16) commands. When set to 1 or 3 (sbc3r34 reserves the value 2) it
|
|
indicates that associated with the SCSI VERIFY command, a data\-out buffer
|
|
will be sent for the device (disk) to check. Using the \fI\-\-ndo=NDO\fR
|
|
option sets the BYTCHK field to 1 and \fINDO\fR is the number of bytes
|
|
placed in the data\-out buffer. Those bytes are obtained from stdin or
|
|
\fIIF\fR (from the \fI\-\-in=FN\fR option). The \fI\-\-ebytchk=BCH\fR
|
|
option may be used to override the BYTCHK field value of 1 with \fIBCH\fR.
|
|
.PP
|
|
The calculation of \fINDO\fR is left up to the user. Its value depends
|
|
on the logical block size (which can be found with the sg_readcap utility),
|
|
the \fICOUNT\fR and the \fIVRP\fR values. If the \fIVRP\fR is greater than
|
|
0 then each logical block will contain an extra 8 bytes (at least) of
|
|
protection information.
|
|
.PP
|
|
When the BYTCHK field is 0 then the verification process done by the
|
|
device (disk) is vendor specific. It typically involves checking each
|
|
block on the disk against its error correction codes (ECC) which is
|
|
additional data also held on the disk.
|
|
.PP
|
|
Many Operating Systems put limits on the maximum size of the
|
|
data\-out (and data\-in) buffer. For Linux at one time the limit was
|
|
less than 1 MB but has been increased somewhat.
|
|
.SH OPTION CHANGES
|
|
Earlier versions of this utility had a \fI\-\-bytchk=NDO\fR option which
|
|
set the BYTCHK bit and set the cdb verification length field to \fINDO\fR.
|
|
The shorter form of that option was \fI\-B NDO\fR. For backward
|
|
compatibility that option is still present but not documented. In its place
|
|
is the \fI\-\-ndo=NDO\fR whose shorter form of \fI\-n NDO\fR.
|
|
\fI\-\-ndo=NDO\fR sets the BYTCHK field to 1 unless that is overridden by
|
|
the \fI\-\-ebytchk=BCH\fR.
|
|
.SH NOTES
|
|
Various numeric arguments (e.g. \fILBA\fR) may include multiplicative
|
|
suffixes or be given in hexadecimal. See the "NUMERIC ARGUMENTS" section
|
|
in the sg3_utils(8) man page.
|
|
.PP
|
|
The amount of error correction and the number of retries attempted before a
|
|
block is considered defective are controlled in part by the Verify Error
|
|
Recovery mode page. A note in the SBC\-3 draft (rev 29 section 6.4.9 on the
|
|
Verify Error Recovery mode page) advises that to minimize the number of
|
|
checks (and hence have the most "sensitive" verify check) do the following
|
|
in that mode page: set the EER bit to 0, the PER bit to 1, the DTE bit to 1,
|
|
the DCR bit to 1, the verify retry count to 0 and the verify recovery time
|
|
limit to 0. Mode pages can be modified with the
|
|
.B sdparm
|
|
utility.
|
|
.PP
|
|
The SCSI VERIFY(6) command defined in the SSC\-2 standard and later (i.e.
|
|
for tape drive systems) is not supported by this utility.
|
|
.SH EXIT STATUS
|
|
The exit status of sg_verify is 0 when it is successful. When \fIBCH\fR is
|
|
other than 0 then a comparison takes place and if it fails then the exit
|
|
status is 14 which happens to be the sense key value of MISCOMPARE.
|
|
Otherwise see the EXIT STATUS section in the sg3_utils(8) man page.
|
|
.PP
|
|
Earlier versions of this utility set an exit status of 98 when there was a
|
|
MISCOMPARE.
|
|
.SH AUTHORS
|
|
Written by Douglas Gilbert.
|
|
.SH "REPORTING BUGS"
|
|
Report bugs to <dgilbert at interlog dot com>.
|
|
.SH COPYRIGHT
|
|
Copyright \(co 2004\-2019 Douglas Gilbert
|
|
.br
|
|
This software is distributed under a BSD\-2\-Clause license. There is NO
|
|
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
|
.SH "SEE ALSO"
|
|
.B sdparm(sdparm), sg_modes(sg3_utils), sg_readcap(sg3_utils),
|
|
.B sg_inq(sg3_utils)
|