192 lines
9.2 KiB
Groff
192 lines
9.2 KiB
Groff
.TH "WRITE AND VERIFY" "8" "January 2022" "sg3_utils\-1.48" SG3_UTILS
|
|
.SH NAME
|
|
sg_write_and_verify \- send the SCSI WRITE AND VERIFY command
|
|
.SH SYNOPSIS
|
|
.B sg_write_verify
|
|
[\fI\-\-16\fR] [\fI\-\-bytchk=BC\fR] [\fI\-\-dpo\fR] [\fI\-\-group=GN\fR]
|
|
[\fI\-\-help\fR] [\fI\-\-ilen=ILEN\fR] [\fI\-\-in=IF\fR] \fI\-\-lba=LBA\fR
|
|
[\fI\-\-num=NUM\fR] [\fI\-\-repeat\fR] [\fI\-\-timeout=TO\fR]
|
|
[\fI\-\-verbose\fR] [\fI\-\-version\fR] [\fI\-\-wrprotect=WP\fR] \fIDEVICE\fR
|
|
.SH DESCRIPTION
|
|
.\" Add any additional description here
|
|
Send a SCSI WRITE AND VERIFY (10) or (16) command to \fIDEVICE\fR. The
|
|
data to be written is read from the \fIIF\fR file or, in its absence, a
|
|
buffer full of 0xff bytes is used. The length of the data\-out buffer sent
|
|
with the command is \fIILEN\fR bytes or, if that is not given, then it is
|
|
the length of the \fIIF\fR file.
|
|
.PP
|
|
The write operation is to the \fIDEVICE\fR's medium (optionally to its cache)
|
|
starting at logical block address \fILBA\fR for \fINUM\fR logical blocks.
|
|
After the write to medium is performed a verify operation takes place which
|
|
may viewed as a medium read (with appropriate checks) but without the data
|
|
being returned. Additionally, if \fIBS\fR is set to one, the data read back
|
|
from the medium in the verify operation is compared to the original data\-out
|
|
buffer.
|
|
.PP
|
|
The relationship between the number of logical blocks to be written (i.e.
|
|
\fINUM\fR) and the length (in bytes) of the data\-out buffer (i.e.
|
|
\fIILEN\fR) may be simply found by multiplying the former by the logical
|
|
block size. However if the \fIDEVICE\fR has protection information (PI)
|
|
then it becomes a bit more complicated. Hence the calculation is left to
|
|
the user with the default \fIILEN\fR, in the absence of the \fIIF\fR file,
|
|
being set to \fINUM\fR * 512.
|
|
.PP
|
|
For sending large amounts of data to contiguous logical blocks, a single
|
|
WRITE AND VERIFY command may not be appropriate (e.g. due to operating
|
|
system limitations). In such cases see the REPEAT section below.
|
|
.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\-S\fR, \fB\-\-16\fR
|
|
Send a WRITE AND VERIFY(16) command. The default is to send a WRITE AND
|
|
VERIFY(10) command unless \fILBA\fR or \fINUM\fR are too large for the
|
|
10 byte variant.
|
|
.TP
|
|
\fB\-b\fR, \fB\-\-bytchk\fR=\fIBC\fR
|
|
where \fIBC\fR is the value to place in the command's BYTCHK field. Values
|
|
between 0 and 3 (inclusive) are accepted. The default is value is 0 which
|
|
implies only a write to the medium then a verify operation are performed. The
|
|
only other value T10 defines currently is 1 which does performs an additional
|
|
comparison between the data\-out buffer that was used by the write operation
|
|
and the contents of the logical blocks read back from the medium.
|
|
.TP
|
|
\fB\-d\fR, \fB\-\-dpo\fR
|
|
Set the DPO (disable page out) bit in the command. The default is to leave
|
|
it clear.
|
|
.TP
|
|
\fB\-g\fR, \fB\-\-group\fR=\fIGN\fR
|
|
where \fIGN\fR is the value to place in the command's GROUP NUMBER field.
|
|
Values between 0 and 63 (inclusive) are accepted. The default is value is 0.
|
|
.TP
|
|
\fB\-h\fR, \fB\-\-help\fR
|
|
output the usage message then exit.
|
|
.TP
|
|
\fB\-I\fR, \fB\-\-ilen\fR=\fIILEN\fR
|
|
where \fIILEN\fR is the number of bytes that will be placed in the data\-out
|
|
buffer. If the \fIIF\fR file is given then no more than \fIILEN\fR bytes
|
|
are read from that file. If the \fIIF\fR file does not contain \fIILEN\fR
|
|
bytes then an error is reported. If the \fIIF\fR file is not given then
|
|
a data\-out buffer with \fIILEN\fR bytes of 0xff is sent.
|
|
.TP
|
|
\fB\-i\fR, \fB\-\-in\fR=\fIIF\fR
|
|
read data (binary) from file named \fIIF\fR. If \fIIF\fR is "\-" then
|
|
stdin is used. This data will become the data\-out buffer and will be written
|
|
to the \fIDEVICE\fR's medium. If \fIBC\fR is 1 then that data\-out buffer
|
|
will be held until after the verify operation and compared to the data read
|
|
back from the medium.
|
|
.TP
|
|
\fB\-l\fR, \fB\-\-lba\fR=\fILBA\fR
|
|
where \fILBA\fR is the logical block address to start the write to medium.
|
|
Assumed to be in decimal unless prefixed with '0x' or has a trailing 'h'.
|
|
Must be provided.
|
|
.TP
|
|
\fB\-n\fR, \fB\-\-num\fR=\fINUM\fR
|
|
where \fINUM\fR is the number of blocks, starting at \fILBA\fR, to write
|
|
to the medium. The default value for \fINUM\fR is 1.
|
|
.TP
|
|
\fB\-R\fR, \fB\-\-repeat\fR
|
|
this option will continue to do WRITE AND VERIFY commands until the \fIIF\fR
|
|
file is exhausted. This option requires both the \fI\-\-ilen=ILEN\fR and
|
|
\fI\-\-in=IF\fR options to be given. Each command starts at the next logical
|
|
block address and is for no more than \fINUM\fR blocks. The last command may
|
|
be shorter with the number of blocks scaled as required. If there are
|
|
residue bytes a warning is sent to stderr. See the REPEAT section.
|
|
.TP
|
|
\fB\-t\fR, \fB\-\-timeout\fR=\fITO\fR
|
|
where \fITO\fR is the command timeout value in seconds. The default value is
|
|
60 seconds. If \fINUM\fR is large then command may require considerably more
|
|
time than 60 seconds to complete.
|
|
.TP
|
|
\fB\-v\fR, \fB\-\-verbose\fR
|
|
increase the degree of verbosity (debug messages).
|
|
.TP
|
|
\fB\-V\fR, \fB\-\-version\fR
|
|
output version string then exit.
|
|
.TP
|
|
\fB\-w\fR, \fB\-\-wrprotect\fR=\fIWP\fR
|
|
set the WRPROTECT field in the cdb to \fIWP\fR. The default value is 0 which
|
|
implies no protection information is sent (along with the user data) in the
|
|
data\-out buffer.
|
|
.SH REPEAT
|
|
For data sizes around a megabyte and larger, it may be appropriate to send
|
|
multiple SCSI WRITE AND VERIFY commands due to operating system
|
|
limitations (e.g. pass\-through SCSI interfaces often limit the amount
|
|
of data that can be passed with a SCSI command). With this utility the
|
|
mechanism for doing that is the \fI\-\-repeat\fR option.
|
|
.PP
|
|
In this mode the \fI\-\-ilen=ILEN\fR and \fI\-\-in=IF\fR options must be
|
|
given. The \fIILEN\fR and \fINUM\fR values are treated as a per SCSI command
|
|
parameters. Up to \fIILEN\fR bytes will be read from the \fIIF\fR file
|
|
continually until it is exhausted. If the \fIIF\fR file is stdin, reading
|
|
continues until an EOF is detected. The data read from each iteration becomes
|
|
the data\-out buffer for a new WRITE AND VERIFY command.
|
|
.PP
|
|
The last read from the file (or stdin) may read less than \fIILEN\fR bytes
|
|
in which case the number of logical blocks sent to the last WRITE AND VERIFY
|
|
is scaled back accordingly. If there is a residual number of bytes left
|
|
after that scaling then that is reported to stderr.
|
|
.PP
|
|
If an error occurs then that is reported to stderr and via the exit status
|
|
and the utility stops at that point.
|
|
.SH NOTES
|
|
Other SCSI WRITE commands have a Force Unit Access (FUA) bit but that is
|
|
set (implicitly) by WRITE AND VERIFY commands hence there is no option to set
|
|
it. The data\-out buffer may still additionally be placed in the
|
|
\fIDEVICE\fR's cache and setting the DPO bit is a hint not to do that.
|
|
.PP
|
|
Normal SCSI WRITEs can be done with the ddpt and the sg_dd utilities. The
|
|
SCSI WRITE SAME command can be done with the sg_write_same utility while
|
|
the SCSI COMPARE AND WRITE command (sg_compare_and_write utility) offers
|
|
a "test and set" facility.
|
|
.PP
|
|
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.
|
|
.SH EXIT STATUS
|
|
The exit status of sg_write_verify is 0 when it is successful. If the verify
|
|
operation fails that is typically indicated with a medium error which leads
|
|
to an exit status of 3.
|
|
.PP
|
|
If \fIBC\fR is set to 1 and the comparison it causes fails this utility will
|
|
indicate the miscompare with an exit status of 14. For other exit status
|
|
values see the EXIT STATUS section in the sg3_utils(8) man page.
|
|
.SH EXAMPLES
|
|
To start with, a simple example: write 1 block of data held in file t.bin
|
|
that is 512 bytes long then write that block to LBA 0x1234 on /dev/sg4 .
|
|
.PP
|
|
# sg_write_verify \-\-lba=0x1234 \-\-in=t.bin /dev/sg4
|
|
.PP
|
|
Since '\-\-num=' is not given then it defaults to 1. Further the \fIILEN\fR
|
|
value is obtained from the file size of t.bin . To additionally do a
|
|
data\-out comparison to the read back data:
|
|
.PP
|
|
# sg_write_verify \-l 0x1234 \-i t.bin --bytchk=1 /dev/sg4
|
|
.PP
|
|
The ddpt command can do copies between SCSI devices using READ and WRITE
|
|
commands. However, currently it has no facility to promote those WRITES
|
|
to WRITE AND VERIFY commands. Using a pipe, that could be done like this:
|
|
.PP
|
|
# ddpt if=/dev/sg2 bs=512 bpt=8 count=11 of=\- |
|
|
.br
|
|
sg_write_verify \-\-in=\- \-l 0x567 \-n 8 \-\-ilen=4096 \-\-repeat /dev/sg4
|
|
.PP
|
|
Both ddpt and sg_write_verify are configured for segments of 8 512 byte
|
|
logical blocks. Since 11 logical blocks are read then first 8 logical blocks
|
|
are copied followed by a copy of the remaining 3 blocks. Since it is assumed
|
|
that there is no protection information then the data\-in and data\-out
|
|
buffers will be 4096 bytes each. For sg_write_verify this needs to be stated
|
|
explicitly with the \-\-ilen=4096 option.
|
|
.SH AUTHORS
|
|
Bruno Goncalves and Douglas Gilbert.
|
|
.SH "REPORTING BUGS"
|
|
Report bugs to <dgilbert at interlog dot com>.
|
|
.SH COPYRIGHT
|
|
Copyright \(co 2014\-2018 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 ddpt(in a package of that name), sg_compare_and_write(8), sg_dd(8),
|
|
.B sg_write_same(8)
|