1COMPARE AND WRITE(8) SG3_UTILS COMPARE AND WRITE(8)
2
6 sg_compare_and_write - send the SCSI COMPARE AND WRITE command
7
9 sg_compare_and_write [--dpo] [--fua] [--fua_nv] [--grpnum=GN] [--help]
10 --in=IF [--inw=WF] --lba=LBA [--num=NUM] [--quiet] [--timeout=TO]
11 [--verbose] [--version] [--wrprotect=WP] [--xferlen=LEN] DEVICE
12
14 Send the SCSI COMPARE AND WRITE command to DEVICE. This utility fetches
15 a compare buffer and a write buffer from either one or two files. If
16 the --inw=WF option is given then the compare buffer is fetched from
17 the file indicated by the --in=IF while the write buffer is fetched
18 from the file indicated by the --inw=WF. If the --inw=WF option is not
19 given then the concatenated compare and write buffers are fetched from
20 the file indicated by the --in=IF option.
21 Those buffers are expected to each contain NUM blocks of data. The com‐
23 pare starts at logical block address LBA on the DEVICE and if the com‐
24 parison fails (i.e. the provided compare buffer does not equal the data
25 at LBA on the DEVICE) then the COMPARE AND WRITE command finishes with
26 a sense key of MISCOMPARE. In this case this utility will complete and
27 set an exit status of 14 (which happens to be the sense key value of
28 MISCOMPARE).
29 If the comparison succeeds then the provided write buffer is stored
31 starting at LBA for NUM blocks on the DEVICE.
32 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 performed by this utility (e.g. to find the block size).
41 The T10 definition of the SCSI COMPARE AND WRITE command requires that
43 the DEVICE implement the compare and optional write as an uninterrupted
44 series of actions. Depending on some other DEVICE settings a verify op‐
45 eration may occur prior to the compare.
46 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 This command is defined in SBC-3 whose most recent revision is 36.
55 SBC-3 and other SCSI documents can be found at http://www.t10.org .
56
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 -d, --dpo
63 Set the DPO bit in the COMPARE AND WRITE CDB
64 -f, --fua
66 Set the FUA bit in the COMPARE AND WRITE CDB
67 -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 "re‐
71 served".
72 -g, --grpnum=GN
74 where GN is the value to be placed in the group number field in
75 the COMPARE AND WRITE CDB.
76 -h, --help
78 output the usage message then exit.
79 -i, --in=IF
81 read data (binary) from file named IF. This will either be the
82 combined compare and write buffers (when the --inw=WF option is
83 not given) or just the compare buffer (when the --inw=WF option
84 is given). If IF is '-' then stdin (e.g. a pipe) is read.
85 -C, --inc=IF
87 The same as the --in option.
88 -D, --inw=WF
90 read data (binary) from file named WF. This will the write buf‐
91 fer that will become the second half of the data-out buffer sent
92 to the DEVICE associated with the COMPARE AND WRITE command.
93 Note that when this option is given then the --in=IF is expected
94 to hold the associated compare buffer.
95 -l, --lba=LBA
97 where LBA is the logical block address to start the COMPARE AND
98 WRITE command. Assumed to be in decimal unless prefixed with
99 '0x' or has a trailing 'h'.
100 -n, --num=NUM
102 where NUM is the number of blocks, starting at LBA, to read and
103 compare with the verify instance. And given a match, the NUM of
104 blocks to write starting LBA. The default value for NUM is 1.
105 -q, --quiet
107 suppress the sense buffer messages associated with a MISCOMPARE
108 sense key that would otherwise be sent to stderr. Still set the
109 exit status to 14 which is the sense key value indicating a MIS‐
110 COMPARE.
111 -t, --timeout=TO
113 where TO is the command timeout value in seconds. The default
114 value is 60 seconds. If NUM is large (or zero) a WRITE SAME com‐
115 mand may require considerably more time than 60 seconds to com‐
116 plete.
117 -v, --verbose
119 increase the degree of verbosity (debug messages).
120 -V, --version
122 output version string then exit.
123 -w, --wrprotect=WP
125 set the WRPROTECT field in the cdb to WP. The default value is 0
126 which implies no protection information is sent (along with the
127 user data) by this utility.
128 -x, --xferlen=LEN
130 where LEN is the data out buffer length in byte. It defaults to
131 (2 * NUM * 512) bytes. If the DEVICE block size is other than
132 512 bytes or WP is non-zero (implying additional protection in‐
133 formation) then this default will be incorrect; the use must
134 supply the correct value for LEN
135
137 Various numeric arguments (e.g. LBA) may include multiplicative suf‐
138 fixes or be given in hexadecimal. See the "NUMERIC ARGUMENTS" section
139 in the sg3_utils(8) man page.
140
142 Before overwriting the first two blocks of whatever (SCSI) storage de‐
143 vice that is chosen, take a small backup. The logical block size is as‐
144 sumed to be 512 bytes. Take a copy (in backup01.bin) of the first two
145 blocks::
146 # sg_dd if=/dev/sg1 bs=512 of=backup01.bin count=2
148 2+0 records in
149 2+0 records out
150 WARNING: if /dev/sg1 corresponds to a disk on your system that contains
152 currently mounted file systems, do _not_ continue. If you can, unmount
153 all file systems on that disk. If that is not possible, use another
154 disk with no mounted file systems on it. In Linux the scsi_debug driver
155 is a good candidate for experimentation.
156 Now fill the first block with 0xff bytes:
158 # sg_dd iflag=ff bs=512 of=/dev/sg1 count=1
160 1+0 records in
161 1+0 records out
162 and the second block with 0x0 bytes:
164 # sg_dd iflag=00 bs=512 seek=1 of=/dev/sg1 count=1
166 1+0 records in
167 1+0 records out
168 Now copy those two blocks into a file:
170 # sg_dd if=/dev/sg1 bs=512 of=ff00.bin count=2
172 2+0 records in
173 2+0 records out
174 Now we can do a compare and write command. It is told to compare the
176 first block (i.e. LBA 0) with the first block in the given file (i.e.
177 ff00.bin). If they are equal (they should be both full of 0xff bytes).
178 Since the compare succeeds, it will write the second block in ff00.bin
179 over LBA 0:
180 # sg_compare_and_write --in=ff00.bin --lba=0 --num=1 /dev/sg1
182 No news is good news. Now if we do that command again:
185 # sg_compare_and_write --in=ff00.bin --lba=0 --num=1 /dev/sg1
187 Miscompare at byte offset: 0 [0x0]
188 sg_compare_and_write failed: Miscompare
189 This is expected. The first sg_compare_and_write ended up writing 0x0
191 bytes over LBA 0x0. The second sg_compare_and_write command compares
192 LBA 0x0 with 0xff bytes and fails immediately (i.e. at byte offset: 0).
193 Now we will overwrite the first 3 bytes of ff00.bin with 0x0:
194 # sg_dd bs=1 iflag=00 of=ff00.bin count=3
196 3+0 records in
197 3+0 records out
198 Notice the 'bs=1' operand. The dd utility (and thus sg_dd) is very use‐
200 ful for doing small binary edits on a file. Now if we do that sg_com‐
201 pare_and_write again, it still fails but with a small difference:
202 # sg_compare_and_write --in=ff00.bin --lba=0 --num=1 /dev/sg1
204 Miscompare at byte offset: 3 [0x3]
205 sg_compare_and_write failed: Miscompare
206 So the bytes at offset 0, 1, and 2 compared equal but not the byte at
208 offset 3. The SCSI COMPARE AND WRITE will stop on the first micompared
209 byte.
210
212 The exit status of sg_compare_and_write is 0 when it is successful. If
213 the compare step fails then the exit status is 14. For other exit sta‐
214 tus values see the EXIT STATUS section in the sg3_utils(8) man page.
215 Earlier versions of this utility set an exit status of 98 when there
217 was a MISCOMPARE.
218
220 Written by Shahar Salzman. Maintained by Douglas Gilbert. Additions by
221 Eric Seppanen.
222
224 Report bugs to shahar.salzman@kaminario.com or dgilbert@interlog.com
225
227 Copyright © 2012-2020 Kaminario Technologies LTD
228 Redistribution and use in source and binary forms, with or without mod‐
229 ification, are permitted provided that the following conditions are
230 met:
231 * Redistributions of source code must retain the above copyright no‐
232 tice, this list of conditions and the following disclaimer.
233 * Redistributions in binary form must reproduce the above copyright no‐
234 tice, this list of conditions and the following disclaimer in the docu‐
235 mentation and/or other materials provided with the distribution.
236 * Neither the name of the <organization> nor the names of its contribu‐
237 tors may be used to endorse or promote products derived from this soft‐
238 ware without specific prior written permission.
239 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
241 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
242 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTIC‐
243 ULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL Kaminario Technologies
244 LTD BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
245 OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
246 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSI‐
247 NESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
248 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
249 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
250 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
251
254 sg_xcopy, sg_receive_copy_results(sg3_utils)
255sg3_utils-1.46 November 2020 COMPARE AND WRITE(8)