Ubuntu Manpage: sg_compare_and_write - send the SCSI COMPARE AND WRITE command

Provided by: sg3-utils_1.40-0ubuntu1_amd64

NAME

       sg_compare_and_write - send the SCSI COMPARE AND WRITE command

SYNOPSIS

       sg_compare_and_write  [--dpo]  [--fua]  [--fua_nv]  [--help]  --in=IF [--inw=WF] --lba=LBA
       [--num=NUM]   [--quiet]   [--timeout=TO]    [--verbose]    [--version]    [--wrprotect=WP]
       [--xferlen=LEN] DEVICE

DESCRIPTION

Send the SCSI COMPARE AND WRITE command to DEVICE. This utility reads a compare buffer and
a write buffer from either one or two files. If the --inw=WF option is not given then the
concatenated compare and write buffers are read from the file indicated by the --in=IF
option. If the --inw=WF option is given then the compare buffer is read from the file
indicated by the --in=IF while the write buffer is read from the file indicated by the
--inw=WF.

Those buffers are expected to each contain NUM blocks of data. The compare starts at at
logical block address LBA on the DEVICE and if the comparison fails (i.e. the provided
compare buffer does not equal at LBA on the DEVICE) then the COMPARE AND WRITE command
finishes with a sense key of MISCOMPARE. In this case this utility will completes and set
an exit status of 14 (which happens to be the sense key value of MISCOMPARE).

If the comparison succeeds then the provided write buffer is written to starting at LBA
for NUM blocks on the DEVICE.

The actual number of bytes transferred in the data-out buffer of the COMPARE AND WRITE
command may need to be given by the user with the --xferlen=LEN option. LEN defaults to (2
* NUM * 512) which is 1024 for the default NUM of 1. If the block size is other than 512
then the user will need to use --xferlen=LEN option. If protection information is given
(indicated by a value of WP other than 0 (the default)) then for a NUM of 1 LEN should be
1040 . Note that the SCSI READ CAPACITY command is not checked by this utility (e.g. to
find the block size).

The definition of the SCSI COMPARE AND WRITE command requires that the DEVICE implement
the compare and optional write as an uninterrupted series of actions. Depending on some
other DEVICE settings a verify operation may occur prior to the compare.

When a mismatch occurs between the compare buffer and the blocks starting at LBA read from
the DEVICE the sense buffer containing the MISCOMPARE sense key causes several messages to
be sent to stderr (including the offset of the first byte mismatch). To suppress these
messages use the --quiet option. With or without the --quiet option the exit status will
be set to 14.

This command is defined in SBC-3 whose most recent revision is 36. SBC-3 and other SCSI
documents can be found at http://www.t10.org .

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.

-d, --dpo
Set the DPO bit in the COMPARE AND WRITE CDB

-f, --fua
Set the FUA bit in the COMPARE AND WRITE CDB

-F, --fua_nv
Set the FUA_NV bit in the COMPARE AND WRITE CDB. This bit was removed in SBC-3
revision 35d and its position marked as "reserved".

-h, --help
output the usage message then exit.

-i, --in=IF
read data (binary) from file named IF. This will either be the combined compare and
write buffers (when the --inw=WF option is not given) or just the compare buffer
(when the --inw=WF option is given). If IF is '-' then stdin (e.g. a pipe) is read.

-D, --inw=WF
read data (binary) from file named WF. This will the write buffer that will become
the second half of the data-out buffer sent to the DEVICE associated with the
COMPARE AND WRITE command. Note that when this option is given then the --in=IF is
expected to hold the associated compare buffer.

-l, --lba=LBA
where LBA is the logical block address to start the COMPARE AND WRITE command.
Assumed to be in decimal unless prefixed with '0x' or has a trailing 'h'.

-n, --num=NUM
where NUM is the number of blocks, starting at LBA, to read and compare with the
verify instance. And given a match, the NUM of blocks to write starting LBA. The
default value for NUM is 1.

-q, --quiet
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.

-t, --timeout=TO
where TO is the command timeout value in seconds. The default value is 60 seconds.
If NUM is large (or zero) a WRITE SAME command may require considerably more time
than 60 seconds to complete.

-v, --verbose
increase the degree of verbosity (debug messages).

-V, --version
output version string then exit.

-w, --wrprotect=WP
set the WRPROTECT field in the cdb to WP. The default value is 0 which implies no
protection information is sent (along with the user data) by this utility.

-x, --xferlen=LEN
where LEN is the data out buffer length in byte. It defaults to (2 * NUM * 512)
bytes. If the DEVICE block size is other than 512 bytes or WP is non-zero (implying
additional protection information) then this default will be incorrect; the use
must supply the correct value for LEN

NOTES

       Various numeric arguments (e.g. LBA) may include multiplicative suffixes or  be  given  in
       hexadecimal. See the "NUMERIC ARGUMENTS" section in the sg3_utils(8) man page.

EXIT STATUS

       The  exit  status  of sg_compare_and_write is 0 when it is successful. If the compare step
       fails then the exit status is 14. For other exit status values see the EXIT STATUS section
       in the sg3_utils(8) man page.

       Earlier versions of this utility set an exit status of 98 when there was a MISCOMPARE.

AUTHORS

       Written by Shahar Salzman. Maintained by Douglas Gilbert. Additions by Eric Seppanen.

REPORTING BUGS

       Report bugs to shahar.salzman@kaminario.com or dgilbert@interlog.com

COPYRIGHT

       Copyright © 2012-2014 Kaminario Technologies LTD

       Redistribution  and  use  in  source  and  binary forms, with or without modification, are
       permitted provided that the following conditions are met:
       * Redistributions of source code must retain the above  copyright  notice,  this  list  of
       conditions and the following disclaimer.
       *  Redistributions  in binary form must reproduce the above copyright notice, this list of
       conditions and the following  disclaimer  in  the  documentation  and/or  other  materials
       provided with the distribution.
       *  Neither the name of the <organization> nor the names of its contributors may be used to
       endorse or promote products derived from this  software  without  specific  prior  written
       permission.

       THIS  SOFTWARE  IS  PROVIDED  BY  THE  COPYRIGHT  HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE  IMPLIED  WARRANTIES  OF
       MERCHANTABILITY  AND  FITNESS  FOR  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
       Kaminario Technologies LTD BE  LIABLE  FOR  ANY  DIRECT,  INDIRECT,  INCIDENTAL,  SPECIAL,
       EXEMPLARY,  OR  CONSEQUENTIAL  DAMAGES  (INCLUDING,  BUT  NOT  LIMITED  TO, PROCUREMENT OF
       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR  PROFITS;  OR  BUSINESS  INTERRUPTION)
       HOWEVER  CAUSED  AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
       TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN  ANY  WAY  OUT  OF  THE  USE  OF  THIS
       SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.