1SG_WRITE_SAME(8) SG3_UTILS SG_WRITE_SAME(8)
2
6 sg_write_same - send SCSI WRITE SAME command
7
9 sg_write_same [--10] [--16] [--32] [--anchor] [--ff] [--grpnum=GN]
10 [--help] [--in=IF] [--lba=LBA] [--lbdata] [--num=NUM] [--ndob] [--pb‐
11 data] [--timeout=TO] [--unmap] [--verbose] [--version] [--wrpro‐
12 tect=WPR] [--xferlen=LEN] DEVICE
13
15 Send the SCSI WRITE SAME (10, 16 or 32 byte) command to DEVICE. This
16 command writes the given block NUM times to consecutive blocks on the
17 DEVICE starting at logical block address LBA.
18 The length of the block to be written multiple times is obtained from
20 either the LEN argument, or the length of the given input file IF, or
21 by calling READ CAPACITY(16) on DEVICE. The contents of the block to be
22 written are obtained from the input file IF or zeros are used. If READ
23 CAPACITY(16) is called (which implies IF was not given) and the PROT_EN
24 bit is set then an extra 8 bytes (i.e. more than the logical block
25 size) of 0xff are sent. If READ CAPACITY(16) fails then READ CAPAC‐
26 ITY(10) is used to determine the block size.
27 If neither --10, --16 nor --32 is given then WRITE SAME(10) is sent un‐
29 less one of the following conditions is met. If LBA (plus NUM) exceeds
30 32 bits, NUM exceeds 65535, or the --unmap option is given then WRITE
31 SAME(16) is sent. The --10, --16 and --32 options are mutually exclu‐
32 sive.
33 SBC-3 revision 35d introduced a "No Data-Out Buffer" (NDOB) bit which,
35 if set, bypasses the requirement to send a single block of data to the
36 DEVICE together with the command. Only WRITE SAME (16 and 32 byte) sup‐
37 port the NDOB bit. If given, a user block of zeros is assumed; if re‐
38 quired, protection information of 0xffs is assumed.
39 In SBC-3 revision 26 the UNMAP and ANCHOR bits were added to the WRITE
41 SAME (10) command. Since the UNMAP bit has been in WRITE SAME (16) and
42 WRITE SAME (32) since SBC-3 revision 18, the lower of the two (i.e.
43 WRITE SAME (16)) is the default when the --unmap option is given. To
44 send WRITE SAME (10) use the --10 option.
45 Take care: The WRITE SAME(10, 16 and 32) commands may interpret a NUM
47 of zero as write to the end of DEVICE. This utility defaults NUM to 1 .
48 The WRITE SAME commands have no IMMED bit so if NUM is large (or zero)
49 then an invocation of this utility could take a long time, potentially
50 as long as a FORMAT UNIT command. In such situations the command time‐
51 out value TO may need to be increased from its default value of 60 sec‐
52 onds. In SBC-3 revision 26 the WSNZ (write same no zero) bit was added
53 to the Block Limits VPD page [0xB0]. If set the WRITE SAME commands
54 will not accept a NUM of zero. The same SBC-3 revision added the "Maxi‐
55 mum Write Same Length" field to the Block Limits VPD page.
56 The Logical Block Provisioning VPD page [0xB2] contains the LBPWS and
58 LBPWS10 bits. If LBPWS is set then WRITE SAME (16) supports the UNMAP
59 bit. If LBPWS10 is set then WRITE SAME (10) supports the UNMAP bit. If
60 either LBPWS or LBPWS10 is set and the WRITE SAME (32) is supported
61 then WRITE SAME (32) supports the UNMAP bit.
62 As a precaution against an accidental 'sg_write_same /dev/sda' (for ex‐
64 ample) overwriting LBA 0 on /dev/sda with zeros, at least one of the
65 --in=IF, --lba=LBA or --num=NUM options must be given. Obviously this
66 utility can destroy a lot of user data so check the options carefully.
67
69 Arguments to long options are mandatory for short options as well. The
70 options are arranged in alphabetical order based on the long option
71 name.
72 -R, --10
74 send a SCSI WRITE SAME (10) command to DEVICE. The ability to
75 set the --unmap (and --anchor) options to this command was added
76 in SBC-3 revision 26.
77 -S, --16
79 send a SCSI WRITE SAME (16) command to DEVICE.
80 -T, --32
82 send a SCSI WRITE SAME (32) command to DEVICE.
83 -a, --anchor
85 sets the ANCHOR bit in the cdb. Introduced in SBC-3 revision 22.
86 That draft requires the --unmap option to also be specified.
87 -f, --ff
89 the data-out buffer sent with this command is initialized with
90 0xff bytes when this option is given.
91 -g, --grpnum=GN
93 sets the 'Group number' field to GN. Defaults to a value of
94 zero. GN should be a value between 0 and 63.
95 -h, --help
97 output the usage message then exit.
98 -i, --in=IF
100 read data (binary) from file named IF and use it as the data-out
101 buffer for the SCSI WRITE SAME command. The length of the
102 data-out buffer is --xferlen=LEN or, if that is not given, the
103 length of the IF file. If IF is "-" then stdin is read. If this
104 option and the --ff are not given then 0x00 bytes are used as
105 fill with the length of the data-out buffer obtained from
106 --xferlen=LEN or by calling READ CAPACITY(16 or 10). If the re‐
107 sponse to READ CAPACITY(16) has the PROT_EN bit set then data-
108 out buffer size is modified accordingly with the last 8 bytes
109 set to 0xff.
110 -l, --lba=LBA
112 where LBA is the logical block address to start the WRITE SAME
113 command. Defaults to lba 0 which is a dangerous block to over‐
114 write on a disk that is in use. Assumed to be in decimal unless
115 prefixed with '0x' or has a trailing 'h'.
116 -L, --lbdata
118 sets the LBDATA bit in the WRITE SAME cdb. This bit was made ob‐
119 solete in sbc3r32 in September 2012.
120 -N, --ndob
122 sets the NDOB bit in the WRITE SAME (16 and 32 byte) commands.
123 NDOB stands for No Data-Out Buffer. Default is to clear this
124 bit. When this option is given then --in=IF is not allowed and
125 --xferlen=LEN can only be given if LEN is 0 .
126 By default zeros are written in each block, but it is possible
127 that the "provisioning initialization pattern" is written de‐
128 pending on other settings.
129 -n, --num=NUM
131 where NUM is the number of blocks, starting at LBA, to write the
132 data-out buffer to. The default value for NUM is 1. The value
133 corresponds to the 'Number of logical blocks' field in the WRITE
134 SAME cdb.
135 Note that a value of 0 in NUM may be interpreted as write the
136 data-out buffer on every block starting at LBA to the end of the
137 DEVICE. If the WSNZ bit (introduced in sbc3r26, January 2011)
138 in the Block Limits VPD page is set then the value of 0 is dis‐
139 allowed, yielding an Invalid request sense key.
140 -P, --pbdata
142 sets the PBDATA bit in the WRITE SAME cdb. This bit was made ob‐
143 solete in sbc3r32 in September 2012.
144 -t, --timeout=TO
146 where TO is the command timeout value in seconds. The default
147 value is 60 seconds. If NUM is large (or zero) a WRITE SAME com‐
148 mand may require considerably more time than 60 seconds to com‐
149 plete.
150 -U, --unmap
152 sets the UNMAP bit in the WRITE SAME(10, 16 and 32) cdb. See UN‐
153 MAP section below.
154 -v, --verbose
156 increase the degree of verbosity (debug messages).
157 -V, --version
159 output version string then exit.
160 -w, --wrprotect=WPR
162 sets the "Write protect" field in the WRITE SAME cdb to WPR. The
163 default value is zero. WPR should be a value between 0 and 7.
164 When WPR is 1 or greater, and the disk's protection type is 1 or
165 greater, then 8 extra bytes of protection information are ex‐
166 pected or generated (to place in the command's data-out buffer).
167 -x, --xferlen=LEN
169 where LEN is the data-out buffer length. Defaults to the length
170 of the IF file or, if that is not given, then the READ CAPAC‐
171 ITY(16 or 10) command is used to find the 'Logical block length
172 in bytes'. That figure may be increased by 8 bytes if the DE‐
173 VICE's protection type is 1 or greater and the WRPROTECT field
174 (see --wrprotect=WPR) is 1 or greater. If both this option and
175 the IF option are given and LEN exceeds the length of the IF
176 file then LEN is the data-out buffer length with zeros used as
177 pad bytes.
178
180 Logical block provisioning is a new term introduced in SBC-3 revision
181 25 for the ability to mark blocks as unused. For large storage arrays,
182 it is a way to provision less physical storage than the READ CAPACITY
183 command reports is available, potentially allocating more physical
184 storage when WRITE commands require it. For flash memory (e.g. SSD
185 drives) it is a way of potentially saving power (and perhaps access
186 time) when it is known large sections (or almost all) of the flash mem‐
187 ory is not in use. SSDs need wear levelling algorithms to have accept‐
188 able endurance and typically over provision to simplify those algo‐
189 rithms; hence they typically contain more physical flash storage than
190 their logical size would dictate.
191 Support for logical block provisioning is indicated by the LBPME bit
193 being set in the READ CAPACITY(16) command response (see the sg_readcap
194 utility). That implies at least one of the UNMAP or WRITE SAME(16)
195 commands is implemented. If the UNMAP command is implemented then the
196 "Maximum unmap LBA count" and "Maximum unmap block descriptor count"
197 fields in the Block Limits VPD page should both be greater than zero.
198 The READ CAPACITY(16) command response also contains a LBPRZ bit which
199 if set means that if unmapped blocks are read then zeros will be re‐
200 turned for the data (and if protection information is active, 0xff
201 bytes are returned for that). In SBC-3 revision 27 the same LBPRZ bit
202 was added to the Logical Block Provisioning VPD page.
203 In SBC-3 revision 25 the LBPU and ANC_SUP bits where added to the Logi‐
205 cal Block Provisioning VPD page. When LBPU is set it indicates that the
206 device supports the UNMAP command (see the sg_unmap utility). When the
207 ANC_SUP bit is set it indicates the device supports anchored LBAs.
208 When the UNMAP bit is set in the cdb then the data-out buffer is also
210 sent. Additionally the data section of that data-out buffer should be
211 full of 0x0 bytes while the data protection block, 8 bytes at the end
212 if present, should be set to 0xff bytes. If these conditions are not
213 met and the LBPRZ bit is set then the UNMAP bit is ignored and the
214 data-out buffer is written to the DEVICE as if the UNMAP bit was zero.
215 In the absence of the --in=IF option, this utility will attempt build a
216 data-out buffer that meets the requirements for the UNMAP bit in the
217 cdb to be acted on by the DEVICE.
218 Logical blocks may also be unmapped by the SCSI UNMAP and FORMAT UNIT
220 commands (see the sg_unmap and sg_format utilities).
221 The unmap capability in SCSI is closely related to the ATA DATA SET
223 MANAGEMENT command with the "Trim" bit set. That ATA trim capability
224 does not interact well with SATA command queueing known as NCQ. T13
225 have introduced a new command called the SFQ DATA SET MANAGEMENT com‐
226 mand also with a the "Trim" bit to address that problem. The SCSI WRITE
227 SAME with the UNMAP bit set and the UNMAP commands do not have any
228 problems with SCSI queueing.
229
231 Various numeric arguments (e.g. LBA) may include multiplicative suf‐
232 fixes or be given in hexadecimal. See the "NUMERIC ARGUMENTS" section
233 in the sg3_utils(8) man page.
234 In Linux, prior to lk 3.17, the sg driver did not support cdb sizes
236 greater than 16 bytes. Hence a device node like /dev/sg1 which is asso‐
237 ciated with the sg driver would fail with this utility if the --32 op‐
238 tion was given (or implied by other options). The bsg driver with de‐
239 vice nodes like /dev/bsg/6:0:0:1 does support cdb sizes greater than 16
240 bytes since its introduction in lk 2.6.28 .
241
243 The exit status of sg_write_same is 0 when it is successful. Otherwise
244 see the sg3_utils(8) man page.
245
247 BEWARE: all these examples will overwrite the data on one or more
248 blocks, potentially CLEARING the WHOLE DISK.
249 One simple usage is to write blocks of zero from (and including) a
251 given LBA for 63 blocks:
252 sg_write_same --lba=0x1234 --num=63 /dev/sdc
254 Since --xferlen=LEN has not been given, then this utility will call the
256 READ CAPACITY command on /dev/sdc to determine the number of bytes in a
257 logical block. Let us assume that is 512 bytes. Since --in=IF is not
258 given a block of zeros is assumed. So 63 blocks of zeros (each block
259 containing 512 bytes) will be written from (and including) LBA 0x1234 .
260 Note that only one block of zeros is passed to the SCSI WRITE SAME com‐
261 mand in the data-out buffer (as required by SBC-3). Using the WRITE
262 SAME SCSI command to write one or more blocks blocks of zeros is equiv‐
263 alent to the NVMe command: Write Zeroes.
264 Now we will write zero blocks to the WHOLE disk. [Note sanitize type
265 commands will also clear blocks and metadata that are not directly vis‐
266 ible]:
267 sg_write_same --lba=0x0 --num=0 /dev/sdc
269 Yes, in this context --num=0 means the rest of the disk. The above in‐
271 vocation may give an error due to the WSNZ bit in the Block Limits VPD
272 page being set. To get around that try:
273 sg_write_same --lba=0x0 --ndob /dev/sdc
275 this invocation, if supported, has the added benefit of not sending a
277 data out buffer of zeros. Notes that it is possible that the "provi‐
278 sioning initialization pattern" is written to each block instead of ze‐
279 ros.
280 A similar example follows but in this case the blocks are "unmapped"
282 ("trimmed" in ATA speak) rather than zeroed:
283 sg_write_same --unmap -L 0x1234 -n 63 /dev/sdc
285 Note that if the LBPRZ bit in the READ CAPACITY(16) response is set
287 (i.e. LPPRZ is an acronym for logical block provisioning read zeros)
288 then these two examples do the same thing, at least seen from the point
289 of view of subsequent reads.
290 This utility can also be used to write protection information (PI) on
292 disks formatted with a protection type greater than zero. PI is 8 bytes
293 of extra data appended to the user data of a logical block: the first
294 two bytes are a CRC (the "guard"), the next two bytes are the "applica‐
295 tion tag" and the last four bytes are the "reference tag". With protec‐
296 tion types 1 and 2 if the application tag is 0xffff then the guard
297 should not be checked (against the user data).
298 In this example we assume the logical block size (of the user data) is
300 512 bytes and the disk has been formatted with protection type 1. Since
301 we are going to modify LBA 2468 then we take a copy of it first:
302 dd if=/dev/sdb skip=2468 bs=512 of=2468.bin count=1
304 The following command line sets the user data to zeros and the PI to 8
306 0xFF bytes on LBA 2468:
307 sg_write_same --lba=2468 /dev/sdb
309 Reading back that block should be successful because the application
311 tag is 0xffff which suppresses the guard (CRC) check (which would oth‐
312 erwise be wrong):
313 dd if=/dev/sdb skip=2468 bs=512 of=/dev/null count=1
315 Now an attempt is made to create a binary file with zeros in the user
317 data, 0x0000 in the application tag and 0xff bytes in the other two PI
318 fields. It is awkward to create 0xff bytes in a file (in Unix) as the
319 "tr" command below shows:
320 dd if=/dev/zero bs=1 count=512 of=ud.bin
322 tr "\000" "\377" < /dev/zero | dd bs=1 of=ff_s.bin count=8
323 cat ud.bin ff_s.bin > lb.bin
324 dd if=/dev/zero bs=1 count=2 seek=514 conv=notrunc of=lb.bin
325 The resulting file can be viewed with 'hexdump -C lb.bin' and should
327 contain 520 bytes. Now that file can be written to LBA 2468 as follows:
328 sg_write_same --lba=2468 wrprotect=3 --in=lb.bin /dev/sdb
330 Note the --wrprotect=3 rather than being set to 1, since we want the
332 WRITE SAME command to succeed even though the PI data now indicates the
333 user data is corrupted. When an attempt is made to read the LBA, an er‐
334 ror should occur:
335 dd if=/dev/sdb skip=2468 bs=512 of=/dev/null count=1
337 dd errors are not very expressive, if dmesg is checked there should be
339 a line something like this: "[sdb] Add. Sense: Logical block guard
340 check failed". The block can be corrected by doing a "sg_write_same
341 --lba=1234 /dev/sdb" again or restoring the original contents of that
342 LBA:
343 dd if=2468.bin bs=512 seek=2468 of=/dev/sdb conv=notrunc count=1
345 Hopefully the dd command would never try to truncate the output file
347 when it is a block device.
348
350 Written by Douglas Gilbert.
351
353 Report bugs to <dgilbert at interlog dot com>.
354
356 Copyright © 2009-2020 Douglas Gilbert
357 This software is distributed under a FreeBSD license. There is NO war‐
358 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
359 POSE.
360
362 sg_format,sg_get_lba_status,sg_readcap,sg_vpd,sg_unmap,
363 sg_write_x(sg3_utils)
364sg3_utils-1.45 June 2020 SG_WRITE_SAME(8)