1COMPARE AND WRITE(8)               SG3_UTILS              COMPARE AND WRITE(8)
2
3
4

NAME

6       sg_compare_and_write - send the SCSI COMPARE AND WRITE command
7

SYNOPSIS

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

DESCRIPTION

14       Send the SCSI COMPARE AND WRITE command to DEVICE. This utility reads a
15       compare buffer and a write buffer from either one or two files. If  the
16       --inw=WF  option  is  not given then the concatenated compare and write
17       buffers are read from the file indicated by the --in=IF option. If  the
18       --inw=WF  option is given then the compare buffer is read from the file
19       indicated by the --in=IF while the write buffer is read from  the  file
20       indicated by the --inw=WF.
21
22       Those buffers are expected to each contain NUM blocks of data. The com‐
23       pare starts at at logical block address LBA on the DEVICE  and  if  the
24       comparison  fails  (i.e.  the provided compare buffer does not equal at
25       LBA on the DEVICE) then the COMPARE AND WRITE command finishes  with  a
26       sense  key  of MISCOMPARE. In this case this utility will completes and
27       set an exit status of 14 (which happens to be the sense  key  value  of
28       MISCOMPARE).
29
30       If the comparison succeeds then the provided write buffer is written to
31       starting at LBA for NUM blocks on the DEVICE.
32
33       The actual number of bytes transferred in the data-out  buffer  of  the
34       COMPARE  AND  WRITE  command  may need to be given by the user with the
35       --xferlen=LEN option. LEN defaults to (2* NUM * 512) which is 1024  for
36       the default NUM of 1. If the block size is other than 512 then the user
37       will need to use --xferlen=LEN option.  If  protection  information  is
38       given  (indicated by a value of WP other than 0 (the default)) then for
39       a NUM of 1 LEN should be 1040 . Note that the SCSI READ  CAPACITY  com‐
40       mand is not checked by this utility (e.g. to find the block size).
41
42       The  definition of the SCSI COMPARE AND WRITE command requires that the
43       DEVICE implement the compare and optional  write  as  an  uninterrupted
44       series  of  actions.  Depending  on some other DEVICE settings a verify
45       operation may occur prior to the compare.
46
47       When a mismatch occurs between the compare buffer and the blocks start‐
48       ing at LBA read from the DEVICE the sense buffer containing the MISCOM‐
49       PARE sense key causes several messages to be sent to stderr  (including
50       the  offset of the first byte mismatch). To suppress these messages use
51       the --quiet option. With or without the --quiet option the exit  status
52       will be set to 14.
53
54       This  command  is  defined  in SBC-3 whose most recent revision is 35f.
55       SBC-3 and other SCSI documents can be found at http://www.t10.org .
56

OPTIONS

58       Arguments to long options are mandatory for short options as well.  The
59       options  are  arranged  in  alphabetical order based on the long option
60       name.
61
62       -d, --dpo
63              Set the DPO bit in the COMPARE AND WRITE CDB
64
65       -f, --fua
66              Set the FUA bit in the COMPARE AND WRITE CDB
67
68       -F, --fua_nv
69              Set the FUA_NV bit in the COMPARE AND WRITE CDB.  This  bit  was
70              removed  in  SBC-3  revision  35d  and  its  position  marked as
71              "reserved".
72
73       -h, --help
74              output the usage message then exit.
75
76       -i, --in=IF
77              read data (binary) from file named IF. This will either  be  the
78              combined  compare and write buffers (when the --inw=WF option is
79              not given) or just the compare buffer (when the --inw=WF  option
80              is given). If IF is '-' then stdin (e.g. a pipe) is read.
81
82       -C, --inc=IF
83              The same as the --in option.
84
85       -D, --inw=WF
86              read  data (binary) from file named WF. This will the write buf‐
87              fer that will become the second half of the data-out buffer sent
88              to  the  DEVICE  associated  with the COMPARE AND WRITE command.
89              Note that when this option is given then the --in=IF is expected
90              to hold the associated compare buffer.
91
92       -l, --lba=LBA
93              where  LBA is the logical block address to start the COMPARE AND
94              WRITE command. Assumed to be in  decimal  unless  prefixed  with
95              '0x' or has a trailing 'h'.
96
97       -n, --num=NUM
98              where  NUM is the number of blocks, starting at LBA, to read and
99              compare with the verify instance. And given a match, the NUM  of
100              blocks to write starting LBA. The default value for NUM is 1.
101
102       -q, --quiet
103              suppress  the sense buffer messages associated with a MISCOMPARE
104              sense key that would otherwise be sent to stderr. Still set  the
105              exit status to 14 which is the sense key value indicating a MIS‐
106              COMPARE.
107
108       -t, --timeout=TO
109              where TO is the command timeout value in  seconds.  The  default
110              value is 60 seconds. If NUM is large (or zero) a WRITE SAME com‐
111              mand may require considerably more time than 60 seconds to  com‐
112              plete.
113
114       -v, --verbose
115              increase the degree of verbosity (debug messages).
116
117       -V, --version
118              output version string then exit.
119
120       -w, --wrprotect=WP
121              set the WRPROTECT field in the cdb to WP. The default value is 0
122              which implies no protection information is sent (along with  the
123              user data) by this utility.
124
125       -x, --xferlen=LEN
126              where  LEN is the data out buffer length in byte. It defaults to
127              (2 * NUM * 512) bytes. If the DEVICE block size  is  other  than
128              512  bytes  or  WP  is  non-zero (implying additional protection
129              information) then this default will be incorrect; the  use  must
130              supply the correct value for LEN
131

NOTES

133       Various  numeric  arguments  (e.g. LBA) may include multiplicative suf‐
134       fixes or be given in hexadecimal. See the "NUMERIC  ARGUMENTS"  section
135       in the sg3_utils(8) man page.
136

EXIT STATUS

138       The  exit status of sg_compare_and_write is 0 when it is successful. If
139       the compare step fails then the exit status is 14. For other exit  sta‐
140       tus values see the EXIT STATUS section in the sg3_utils(8) man page.
141
142       Earlier  versions  of  this utility set an exit status of 98 when there
143       was a MISCOMPARE.
144

AUTHORS

146       Written by Shahar Salzman. Maintained by Douglas Gilbert. Additions  by
147       Eric Seppanen.
148

REPORTING BUGS

150       Report bugs to shahar.salzman@kaminario.com or dgilbert@interlog.com
151
153       Copyright © 2012-2013 Kaminario Technologies LTD
154
155       Redistribution and use in source and binary forms, with or without mod‐
156       ification, are permitted provided that  the  following  conditions  are
157       met:
158       *  Redistributions  of  source  code  must  retain  the above copyright
159       notice, this list of conditions and the following disclaimer.
160       * Redistributions in binary form must  reproduce  the  above  copyright
161       notice,  this  list  of  conditions and the following disclaimer in the
162       documentation and/or other materials provided with the distribution.
163       * Neither the name of the <organization> nor the names of its contribu‐
164       tors may be used to endorse or promote products derived from this soft‐
165       ware without specific prior written permission.
166
167       THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
168       IS"  AND  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
169       TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTIC‐
170       ULAR  PURPOSE  ARE DISCLAIMED. IN NO EVENT SHALL Kaminario Technologies
171       LTD BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
172       OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
173       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;  OR  BUSI‐
174       NESS  INTERRUPTION)  HOWEVER  CAUSED  AND  ON  ANY THEORY OF LIABILITY,
175       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
176       OTHERWISE)  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
177       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
178
179

SEE ALSO

181       sg_xcopy, sg_receive_copy_results(sg3_utils)
182
183
184
185sg3_utils-1.37                    August 2013             COMPARE AND WRITE(8)
Impressum