focal (8) sg_compare_and_write.8.gz

Provided by: sg3-utils_1.44-1ubuntu2_amd64 bug

NAME

       sg_compare_and_write - send the SCSI COMPARE AND WRITE command

SYNOPSIS

       sg_compare_and_write  [--dpo]  [--fua]  [--fua_nv]  [--grpnum=GN]  [--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  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".

       -g, --grpnum=GN
              where GN is the value to be placed in the group number field in the COMPARE AND WRITE CDB.

       -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.

       -C, --inc=IF
              The same as the --in option.

       -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 © 2012-2018 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.

SEE ALSO

       sg_xcopy, sg_receive_copy_results(sg3_utils)