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 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       -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       -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
89       -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
94       -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
99       -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
105       -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
111       -v, --verbose
112              increase the degree of verbosity (debug messages).
113
114       -V, --version
115              output version string then exit.
116
117       -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
122       -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

NOTES

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

EXIT STATUS

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
139       Earlier  versions  of  this utility set an exit status of 98 when there
140       was a MISCOMPARE.
141

AUTHORS

143       Written by Shahar Salzman. Maintained by Douglas Gilbert. Additions  by
144       Eric Seppanen.
145

REPORTING BUGS

147       Report bugs to shahar.salzman@kaminario.com or dgilbert@interlog.com
148
150       Copyright © 2012-2014 Kaminario Technologies LTD
151
152       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
164       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
176

SEE ALSO

178       sg_xcopy, sg_receive_copy_results(sg3_utils)
179
180
181
182sg3_utils-1.38                    March 2014              COMPARE AND WRITE(8)
Impressum