diff options
Diffstat (limited to 'doc/sg_write_verify.8')
| -rw-r--r-- | doc/sg_write_verify.8 | 191 |
1 files changed, 191 insertions, 0 deletions
diff --git a/doc/sg_write_verify.8 b/doc/sg_write_verify.8 new file mode 100644 index 00000000..6a784e0a --- /dev/null +++ b/doc/sg_write_verify.8 @@ -0,0 +1,191 @@ +.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) |