sg_write_verify: add --repeat option logic

git-svn-id: https://svn.bingwo.ca/repos/sg3_utils/trunk@595 6180dd3e-e324-4e3e-922d-17de1ae2f315

1 files changed, 43 insertions, 9 deletions

diff --git a/doc/sg_write_verify.8 b/doc/sg_write_verify.8
index 1df6e9a2..33571b54 100644
--- a/doc/sg_write_verify.8
+++ b/doc/sg_write_verify.8
@@ -4,9 +4,9 @@ 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\-\-in=IF\fR] [\fI\-\-ilen=ILEN\fR] \fI\-\-lba=LBA\fR
-[\fI\-\-num=NUM\fR] [\fI\-\-timeout=TO\fR] [\fI\-\-verbose\fR]
-[\fI\-\-version\fR] [\fI\-\-wrprotect=WP\fR] \fIDEVICE\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
@@ -30,6 +30,10 @@ 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.
@@ -58,12 +62,6 @@ Values between 0 and 31 (inclusive) are accepted. The default is value is 0.
 \fB\-h\fR, \fB\-\-help\fR
 output the usage message then exit.
 .TP
-\fB\-i\fR, \fB\-\-in\fR=\fIIF\fR
-read data (binary) from file named \fIIF\fR. 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\-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
@@ -71,6 +69,13 @@ 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'.
@@ -80,6 +85,14 @@ Must be provided.
 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
@@ -95,6 +108,27 @@ output version string then exit.
 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 appropraite 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