1WRITE AND VERIFY(8) SG3_UTILS WRITE AND VERIFY(8)
2
3
4
6 sg_write_and_verify - send the SCSI WRITE AND VERIFY command
7
9 sg_write_verify [--16] [--bytchk=BC] [--dpo] [--group=GN] [--help]
10 [--ilen=ILEN] [--in=IF] --lba=LBA [--num=NUM] [--repeat] [--timeout=TO]
11 [--verbose] [--version] [--wrprotect=WP] DEVICE
12
14 Send a SCSI WRITE AND VERIFY (10) or (16) command to DEVICE. The data
15 to be written is read from the IF file or, in its absence, a buffer
16 full of 0xff bytes is used. The length of the data-out buffer sent with
17 the command is ILEN bytes or, if that is not given, then it is the
18 length of the IF file.
19
20 The write operation is to the DEVICE's medium (optionally to its cache)
21 starting at logical block address LBA for NUM logical blocks. After
22 the write to medium is performed a verify operation takes place which
23 may viewed as a medium read (with appropriate checks) but without the
24 data being returned. Additionally, if BS is set to one, the data read
25 back from the medium in the verify operation is compared to the origi‐
26 nal data-out buffer.
27
28 The relationship between the number of logical blocks to be written
29 (i.e. NUM) and the length (in bytes) of the data-out buffer (i.e.
30 ILEN) may be simply found by multiplying the former by the logical
31 block size. However if the DEVICE has protection information (PI) then
32 it becomes a bit more complicated. Hence the calculation is left to the
33 user with the default ILEN, in the absence of the IF file, being set to
34 NUM * 512.
35
36 For sending large amounts of data to contiguous logical blocks, a sin‐
37 gle WRITE AND VERIFY command may not be appropriate (e.g. due to oper‐
38 ating system limitations). In such cases see the REPEAT section below.
39
41 Arguments to long options are mandatory for short options as well. The
42 options are arranged in alphabetical order based on the long option
43 name.
44
45 -S, --16
46 Send a WRITE AND VERIFY(16) command. The default is to send a
47 WRITE AND VERIFY(10) command unless LBA or NUM are too large for
48 the 10 byte variant.
49
50 -b, --bytchk=BC
51 where BC is the value to place in the command's BYTCHK field.
52 Values between 0 and 3 (inclusive) are accepted. The default is
53 value is 0 which implies only a write to the medium then a ver‐
54 ify operation are performed. The only other value T10 defines
55 currently is 1 which does performs an additional comparison
56 between the data-out buffer that was used by the write operation
57 and the contents of the logical blocks read back from the
58 medium.
59
60 -d, --dpo
61 Set the DPO (disable page out) bit in the command. The default
62 is to leave it clear.
63
64 -g, --group=GN
65 where GN is the value to place in the command's GROUP NUMBER
66 field. Values between 0 and 31 (inclusive) are accepted. The
67 default is value is 0.
68
69 -h, --help
70 output the usage message then exit.
71
72 -I, --ilen=ILEN
73 where ILEN is the number of bytes that will be placed in the
74 data-out buffer. If the IF file is given then no more than ILEN
75 bytes are read from that file. If the IF file does not contain
76 ILEN bytes then an error is reported. If the IF file is not
77 given then a data-out buffer with ILEN bytes of 0xff is sent.
78
79 -i, --in=IF
80 read data (binary) from file named IF. If IF is "-" then stdin
81 is used. This data will become the data-out buffer and will be
82 written to the DEVICE's medium. If BC is 1 then that data-out
83 buffer will be held until after the verify operation and com‐
84 pared to the data read back from the medium.
85
86 -l, --lba=LBA
87 where LBA is the logical block address to start the write to
88 medium. Assumed to be in decimal unless prefixed with '0x' or
89 has a trailing 'h'. Must be provided.
90
91 -n, --num=NUM
92 where NUM is the number of blocks, starting at LBA, to write to
93 the medium. The default value for NUM is 1.
94
95 -R, --repeat
96 this option will continue to do WRITE AND VERIFY commands until
97 the IF file is exhausted. This option requires both the
98 --ilen=ILEN and --in=IF options to be given. Each command starts
99 at the next logical block address and is for no more than NUM
100 blocks. The last command may be shorter with the number of
101 blocks scaled as required. If there are residue bytes a warning
102 is sent to stderr. See the REPEAT section.
103
104 -t, --timeout=TO
105 where TO is the command timeout value in seconds. The default
106 value is 60 seconds. If NUM is large then command may require
107 considerably more time than 60 seconds to complete.
108
109 -v, --verbose
110 increase the degree of verbosity (debug messages).
111
112 -V, --version
113 output version string then exit.
114
115 -w, --wrprotect=WP
116 set the WRPROTECT field in the cdb to WP. The default value is 0
117 which implies no protection information is sent (along with the
118 user data) in the data-out buffer.
119
121 For data sizes around a megabyte and larger, it may be appropriate to
122 send multiple SCSI WRITE AND VERIFY commands due to operating system
123 limitations (e.g. pass-through SCSI interfaces often limit the amount
124 of data that can be passed with a SCSI command). With this utility the
125 mechanism for doing that is the --repeat option.
126
127 In this mode the --ilen=ILEN and --in=IF options must be given. The
128 ILEN and NUM values are treated as a per SCSI command parameters. Up to
129 ILEN bytes will be read from the IF file continually until it is
130 exhausted. If the IF file is stdin, reading continues until an EOF is
131 detected. The data read from each iteration becomes the data-out buffer
132 for a new WRITE AND VERIFY command.
133
134 The last read from the file (or stdin) may read less than ILEN bytes in
135 which case the number of logical blocks sent to the last WRITE AND VER‐
136 IFY is scaled back accordingly. If there is a residual number of bytes
137 left after that scaling then that is reported to stderr.
138
139 If an error occurs then that is reported to stderr and via the exit
140 status and the utility stops at that point.
141
143 Other SCSI WRITE commands have a Force Unit Access (FUA) bit but that
144 is set (implicitly) by WRITE AND VERIFY commands hence there is no
145 option to set it. The data-out buffer may still additionally be placed
146 in the DEVICE's cache and setting the DPO bit is a hint not to do that.
147
148 Normal SCSI WRITEs can be done with the ddpt and the sg_dd utilities.
149 The SCSI WRITE SAME command can be done with the sg_write_same utility
150 while the SCSI COMPARE AND WRITE command (sg_compare_and_write utility)
151 offers a "test and set" facility.
152
153 Various numeric arguments (e.g. LBA) may include multiplicative suf‐
154 fixes or be given in hexadecimal. See the "NUMERIC ARGUMENTS" section
155 in the sg3_utils(8) man page.
156
158 The exit status of sg_write_verify is 0 when it is successful. If the
159 verify operation fails that is typically indicated with a medium error
160 which leads to an exit status of 3.
161
162 If BC is set to 1 and the comparison it causes fails this utility will
163 indicate the miscompare with an exit status of 14. For other exit sta‐
164 tus values see the EXIT STATUS section in the sg3_utils(8) man page.
165
167 To start with, a simple example: write 1 block of data held in file
168 t.bin that is 512 bytes long then write that block to LBA 0x1234 on
169 /dev/sg4 .
170
171 # sg_write_verify --lba=0x1234 --in=t.bin /dev/sg4
172
173 Since '--num=' is not given then it defaults to 1. Further the ILEN
174 value is obtained from the file size of t.bin . To additionally do a
175 data-out comparison to the read back data:
176
177 # sg_write_verify -l 0x1234 -i t.bin --bytchk=1 /dev/sg4
178
179 The ddpt command can do copies between SCSI devices using READ and
180 WRITE commands. However, currently it has no facility to promote those
181 WRITES to WRITE AND VERIFY commands. Using a pipe, that could be done
182 like this:
183
184 # ddpt if=/dev/sg2 bs=512 bpt=8 count=11 of=- |
185 sg_write_verify --in=- -l 0x567 -n 8 --ilen=4096 --repeat /dev/sg4
186
187 Both ddpt and sg_write_verify are configured for segments of 8 512 byte
188 logical blocks. Since 11 logical blocks are read then first 8 logical
189 blocks are copied followed by a copy of the remaining 3 blocks. Since
190 it is assumed that there is no protection information then the data-in
191 and data-out buffers will be 4096 bytes each. For sg_write_verify this
192 needs to be stated explicitly with the --ilen=4096 option.
193
195 Bruno Goncalves and Douglas Gilbert.
196
198 Report bugs to <dgilbert at interlog dot com>.
199
201 Copyright © 2014-2018 Douglas Gilbert
202 This software is distributed under a FreeBSD license. There is NO war‐
203 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
204 POSE.
205
207 ddpt(in a package of that name), sg_compare_and_write(8), sg_dd(8),
208 sg_write_same(8)
209
210
211
212sg3_utils-1.43 June 2018 WRITE AND VERIFY(8)