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] [--grpnum=GN] [--help]
10       --in=IF  [--inw=WF]  --lba=LBA  [--num=NUM]  [--quiet]   [--timeout=TO]
11       [--verbose] [--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 logical block address LBA on the DEVICE and if the  com‐
24       parison  fails  (i.e. the provided compare buffer does not equal at LBA
25       on the DEVICE) then the COMPARE AND WRITE command finishes with a sense
26       key  of MISCOMPARE. In this case this utility will completes and set an
27       exit status of 14 (which happens to be the sense key value  of  MISCOM‐
28       PARE).
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 36.
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       -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
77       -h, --help
78              output the usage message then exit.
79
80       -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
86       -C, --inc=IF
87              The same as the --in option.
88
89       -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
96       -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
101       -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
106       -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
112       -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
118       -v, --verbose
119              increase the degree of verbosity (debug messages).
120
121       -V, --version
122              output version string then exit.
123
124       -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
129       -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
133              information)  then  this default will be incorrect; the use must
134              supply the correct value for LEN
135

NOTES

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

EXIT STATUS

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

AUTHORS

150       Written  by Shahar Salzman. Maintained by Douglas Gilbert. Additions by
151       Eric Seppanen.
152

REPORTING BUGS

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

SEE ALSO

184       sg_xcopy, sg_receive_copy_results(sg3_utils)
185
186
187
188sg3_utils-1.43                    August 2018             COMPARE AND WRITE(8)
Impressum