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] [--help] --in=IF
10 [--inw=WF] --lba=LBA [--num=NUM] [--quiet] [--timeout=TO] [--verbose]
11 [--version] [--wrprotect=WP] [--xferlen=LEN] DEVICE
12
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 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 If the comparison succeeds then the provided write buffer is written to
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 checked by this utility (e.g. to find the block size).
41 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 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
71 "reserved".
72 -h, --help
74 output the usage message then exit.
75 -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 -D, --inw=WF
83 read data (binary) from file named WF. This will the write buf‐
84 fer that will become the second half of the data-out buffer sent
85 to the DEVICE associated with the COMPARE AND WRITE command.
86 Note that when this option is given then the --in=IF is expected
87 to hold the associated compare buffer.
88 -l, --lba=LBA
90 where LBA is the logical block address to start the COMPARE AND
91 WRITE command. Assumed to be in decimal unless prefixed with
92 '0x' or has a trailing 'h'.
93 -n, --num=NUM
95 where NUM is the number of blocks, starting at LBA, to read and
96 compare with the verify instance. And given a match, the NUM of
97 blocks to write starting LBA. The default value for NUM is 1.
98 -q, --quiet
100 suppress the sense buffer messages associated with a MISCOMPARE
101 sense key that would otherwise be sent to stderr. Still set the
102 exit status to 14 which is the sense key value indicating a MIS‐
103 COMPARE.
104 -t, --timeout=TO
106 where TO is the command timeout value in seconds. The default
107 value is 60 seconds. If NUM is large (or zero) a WRITE SAME com‐
108 mand may require considerably more time than 60 seconds to com‐
109 plete.
110 -v, --verbose
112 increase the degree of verbosity (debug messages).
113 -V, --version
115 output version string then exit.
116 -w, --wrprotect=WP
118 set the WRPROTECT field in the cdb to WP. The default value is 0
119 which implies no protection information is sent (along with the
120 user data) by this utility.
121 -x, --xferlen=LEN
123 where LEN is the data out buffer length in byte. It defaults to
124 (2 * NUM * 512) bytes. If the DEVICE block size is other than
125 512 bytes or WP is non-zero (implying additional protection
126 information) then this default will be incorrect; the use must
127 supply the correct value for LEN
128
130 Various numeric arguments (e.g. LBA) may include multiplicative suf‐
131 fixes or be given in hexadecimal. See the "NUMERIC ARGUMENTS" section
132 in the sg3_utils(8) man page.
133
135 The exit status of sg_compare_and_write is 0 when it is successful. If
136 the compare step fails then the exit status is 14. For other exit sta‐
137 tus values see the EXIT STATUS section in the sg3_utils(8) man page.
138 Earlier versions of this utility set an exit status of 98 when there
140 was a MISCOMPARE.
141
143 Written by Shahar Salzman. Maintained by Douglas Gilbert. Additions by
144 Eric Seppanen.
145
147 Report bugs to shahar.salzman@kaminario.com or dgilbert@interlog.com
148
150 Copyright © 2012-2014 Kaminario Technologies LTD
151 Redistribution and use in source and binary forms, with or without mod‐
153 ification, are permitted provided that the following conditions are
154 met:
155 * Redistributions of source code must retain the above copyright
156 notice, this list of conditions and the following disclaimer.
157 * Redistributions in binary form must reproduce the above copyright
158 notice, this list of conditions and the following disclaimer in the
159 documentation and/or other materials provided with the distribution.
160 * Neither the name of the <organization> nor the names of its contribu‐
161 tors may be used to endorse or promote products derived from this soft‐
162 ware without specific prior written permission.
163 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
165 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
166 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTIC‐
167 ULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL Kaminario Technologies
168 LTD BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
169 OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
170 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSI‐
171 NESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
172 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
173 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
174 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
175
178 sg_xcopy, sg_receive_copy_results(sg3_utils)
179sg3_utils-1.38 March 2014 COMPARE AND WRITE(8)