1 files changed, 219 insertions, 0 deletions
diff --git a/doc/sg_verify.8 b/doc/sg_verify.8
new file mode 100644
index 00000000..dae36042
--- /dev/null
+++ b/doc/sg_verify.8
@@ -0,0 +1,219 @@
+.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)