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] [--grpnum=GN] [--help]
10 [--in=IF] [--lba=LBA] [--lbdata] [--pbdata] [--num=NUM] [--ndob]
11 [--timeout=TO] [--unmap] [--verbose] [--version] [--wrprotect=WPR]
12 [--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 SBC-3 revision 35d introduced a "no data-out buffer" (NDOB) bit which,
20 if set, bypasses the requirement to send a single block of data to the
21 DEVICE together with the command. Only WRITE SAME (16 and 32 byte) sup‐
22 port the NDOB bit.
23 The length of the block to be written multiple times is obtained from
25 either the LEN argument, or the length of the given input file IF, or
26 by calling READ CAPACITY(16) on DEVICE. The contents of the block to be
27 written are obtained from the input file IF or zeros are used. If READ
28 CAPACITY(16) is called (which implies IF was not given) and the PROT_EN
29 bit is set then an extra 8 bytes (i.e. more than the logical block
30 size) of 0xff are sent. If READ CAPACITY(16) fails then READ CAPAC‐
31 ITY(10) is used to determine the block size.
32 If neither --10, --16 nor --32 is given then WRITE SAME(10) is sent
34 unless one of the following conditions is met. If LBA (plus NUM)
35 exceeds 32 bits, NUM exceeds 65535, or the --unmap option is given then
36 WRITE SAME(16) is sent. The --10, --16 and --32 options are mutually
37 exclusive.
38 In SBC-3 revision 26 the UNMAP and ANCHOR bits were added to the WRITE
40 SAME (10) command. Since the UNMAP bit has been in WRITE SAME (16) and
41 WRITE SAME (32) since SBC-3 revision 18, the lower of the two (i.e.
42 WRITE SAME (16)) is the default when the --unmap option is given. To
43 send WRITE SAME (10) use the --10 option.
44 Take care: The WRITE SAME(10, 16 and 32) commands interpret a NUM of
46 zero as write to the end of DEVICE. This utility defaults NUM to 1 .
47 The WRITE SAME commands have no IMMED bit so if NUM is large (or zero)
48 then an invocation of this utility could take a long time, potentially
49 as long as a FORMAT UNIT command. In such situations the command time‐
50 out value TO may need to be increased from its default value of 60 sec‐
51 onds. In SBC-3 revision 26 the WSNZ (write same no zero) bit was added
52 to the Block Limits VPD page [0xB0]. If set the WRITE SAME commands
53 will not accept a NUM of zero. The same SBC-3 revision added the "Maxi‐
54 mum Write Same Length" field to the Block Limits VPD page.
55 The Logical Block Provisioning VPD page [0xB2] contains the LBWS and
57 LBW10 bits. If LBWS is set then WRITE SAME (16) supports the UNMAP bit.
58 If LBWS10 is set then WRITE SAME (10) supports the UNMAP bit. If either
59 LBWS or LBWS10 is set and the WRITE SAME (32) is supported then WRITE
60 SAME (32) supports the UNMAP bit. This is as of SBC-3 revision 26.
61 As a precaution against an accidental 'sg_write_same /dev/sda' (for
63 example) overwriting LBA 0 on /dev/sda with zeros, at least one of the
64 --in=IF, --lba=LBA or --num=NUM options must be given. Obviously this
65 utility can destroy a lot of user data so check the options carefully.
66
68 Arguments to long options are mandatory for short options as well.
69 -R, --10
71 send a SCSI WRITE SAME (10) command to DEVICE. The ability to
72 set the --unmap (and --anchor) options to this command was added
73 in SBC-3 revision 26.
74 -S, --16
76 send a SCSI WRITE SAME (16) command to DEVICE.
77 -T, --32
79 send a SCSI WRITE SAME (32) command to DEVICE.
80 -a, --anchor
82 sets the ANCHOR bit in the cdb. Introduced in SBC-3 revision 22.
83 That draft requires the --unmap option to also be specified.
84 -g, --grpnum=GN
86 sets the 'Group number' field to GN. Defaults to a value of
87 zero. GN should be a value between 0 and 31.
88 -h, --help
90 output the usage message then exit.
91 -i, --in=IF
93 read data (binary) from file named IF and use it as the data out
94 buffer for the SCSI WRITE SAME command. The length of the data
95 out buffer is --xferlen=LEN or, if that is not given, the length
96 of the IF file. If IF is "-" then stdin is read. If this option
97 is not given then 0x00 bytes are used as fill with the length of
98 the data out buffer obtained from --xferlen=LEN or by calling
99 READ CAPACITY(16 or 10). If the response to READ CAPACITY(16)
100 has the PROT_EN bit set then data out buffer size is modified
101 accordingly with the last 8 bytes set to 0xff.
102 -l, --lba=LBA
104 where LBA is the logical block address to start the WRITE SAME
105 command. Defaults to lba 0 which is a dangerous block to over‐
106 write on a disk that is in use. Assumed to be in decimal unless
107 prefixed with '0x' or has a trailing 'h'.
108 -L, --lbdata
110 sets the LBDATA bit in the WRITE SAME cdb.
111 -N, --ndob
113 sets the NDOB bit in the WRITE SAME (16 and 32 byte) commands.
114 Default is to clear this bit. When this option is given then
115 --in=IF is not allowed and --xferlen=LEN can only be given if
116 LEN is 0 .
117 -n, --num=NUM
119 where NUM is the number of blocks, starting at LBA, to write the
120 data out buffer to. The default value for NUM is 1. The value
121 corresponds to the 'Number of logical blocks' field in the WRITE
122 SAME cdb. Note that a value of 0 in NUM is interpreted as write
123 the data out buffer on every block starting at LBA to the end of
124 the DEVICE.
125 -P, --pbdata
127 sets the PBDATA bit in the WRITE SAME cdb.
128 -t, --timeout=TO
130 where TO is the command timeout value in seconds. The default
131 value is 60 seconds. If NUM is large (or zero) a WRITE SAME com‐
132 mand may require considerably more time than 60 seconds to com‐
133 plete.
134 -U, --unmap
136 sets the UNMAP bit in the WRITE SAME(10, 16 and 32) cdb. See
137 UNMAP section below.
138 -v, --verbose
140 increase the degree of verbosity (debug messages).
141 -V, --version
143 output version string then exit.
144 -w, --wrprotect=WPR
146 sets the "Write protect" field in the WRITE SAME cdb to WPR. The
147 default value is zero. WPR should be a value between 0 and 7.
148 When WPR is 1 or greater, and the disk's protection type is 1 or
149 greater, then 8 extra bytes of protection information are
150 expected or generated (to place in the command's data out buf‐
151 fer).
152 -x, --xferlen=LEN
154 where LEN is the data out buffer length. Defaults to the length
155 of the IF file or, if that is not given, then the READ CAPAC‐
156 ITY(16 or 10) command is used to find the 'Logical block length
157 in bytes'. That figure may be increased by 8 bytes if the
158 DEVICE's protection type is 1 or greater and the WRPROTECT field
159 (see --wrprotect=WPR) is 1 or greater. If both this option and
160 the IF option are given and LEN exceeds the length of the IF
161 file then LEN is the data out buffer length with zeros used as
162 pad bytes.
163
165 Logical block provisioning is a new term introduced in SBC-3 revision
166 25 for the ability to mark blocks as unused. It is closely related to
167 the ATA DATA SET MANAGEMENT command with the "Trim" bit set. For large
168 storage arrays, it is a way to provision less physical storage than the
169 READ CAPACITY command reports is available, potentially allocating more
170 physical storage when WRITE commands require it. For flash memory it is
171 a way of potentially saving power (and perhaps access time) when it is
172 known large sections (or almost all) of the flash memory is not in use.
173 Support for logical block provisioning is indicated by the LBPME bit
175 being set in the READ CAPACITY(16) command response (see the sg_readcap
176 utility). That implies at least one of the UNMAP or WRITE SAME(16)
177 commands is implemented. If the UNMAP command is implemented then the
178 "Maximum unmap LBA count" and "Maximum unmap block descriptor count"
179 fields in the Block Limits VPD page should both be greater than zero.
180 The READ CAPACITY(16) command response also contains a LBPRZ bit which
181 if set means that if unmapped blocks are read then zeros will be
182 returned for the data (and if protection information is active, 0xff
183 bytes are returned for that). In SBC-3 revision 27 the same LBPRZ bit
184 was added to the Logical Block Provisioning VPD page.
185 In SBC-3 revision 25 the LBPU and ANC_SUP bits where added to the Logi‐
187 cal Block Provisioning VPD page. When LBPU is set it indicates that the
188 device supports the UNMAP command (see the sg_unmap utility). When the
189 ANC_SUP bit is set it indicates the device supports anchored LBAs.
190 When the UNMAP bit is set in the cdb then the data out buffer is also
192 sent. Additionally the data section of that data out buffer should be
193 full of 0x0 bytes while the data protection block, 8 bytes at the end
194 if present, should be set to 0xff bytes. If these conditions are not
195 met and the LBPRZ bit is set then the UNMAP bit is ignored and the data
196 out buffer is written to the DEVICE as if the UNMAP bit was zero. In
197 the absence of the --in=IF option, this utility will attempt build a
198 data out buffer that meets the requirements for the UNMAP bit in the
199 cdb to be acted on by the DEVICE.
200 Logical blocks may also be unmapped by the SCSI UNMAP and FORMAT UNIT
202 commands (see the sg_unmap and sg_format utilities).
203
205 Various numeric arguments (e.g. LBA) may include multiplicative suf‐
206 fixes or be given in hexadecimal. See the "NUMERIC ARGUMENTS" section
207 in the sg3_utils(8) man page.
208 In Linux at this time the sg driver does not support cdb sizes greater
210 than 16 bytes. Hence a device node like /dev/sg1 which is associated
211 with the sg driver will fail with this utility if the --32 option is
212 given (or implied by other options). The bsg driver with device nodes
213 like /dev/bsg/6:0:0:1 does support cdb sizes greater than 16 bytes.
214
216 The exit status of sg_write_same is 0 when it is successful. Otherwise
217 see the sg3_utils(8) man page.
218
220 One simple usage is to write blocks of zero from (and including) a
221 given LBA:
222 sg_write_same --lba=0x1234 --num=63 /dev/sdc
224 Since --xferlen=LEN has not been given, then this utility will call the
226 READ CAPACITY command on /dev/sdc to determine the number of bytes in a
227 logical block. Let us assume that is 512 bytes. Since --in=IF is not
228 given a block of zeros is assumed. So 63 blocks of zeros (each block
229 containing 512 bytes) will be written from (and including) LBA 0x1234 .
230 Note that only one block of zeros is passed to the SCSI WRITE SAME com‐
231 mand in the data out buffer (as required by SBC-3).
232 A similar example follows but in this case the blocks are "unmapped"
234 ("trimmed" in ATA speak) rather than zeroed:
235 sg_write_same --unmap -L 0x1234 -n 63 /dev/sdc
237 Note that if the LBPRZ bit in the READ CAPACITY(16) response is set
239 (i.e. LPPRZ is an acronym for logical block provisioning read zeros)
240 then these two examples do the same thing, at least seen from the point
241 of view of subsequent reads.
242 This utility can also be used to write protection information (PI) on
244 disks formatted with a protection type greater than zero. PI is 8 bytes
245 of extra data appended to the user data of a logical block: the first
246 two bytes are a CRC (the "guard"), the next two bytes are the "applica‐
247 tion tag" and the last four bytes are the "reference tag". With protec‐
248 tion types 1 and 2 if the application tag is 0xffff then the guard
249 should not be checked (against the user data).
250 In this example we assume the logical block size (of the user data) is
252 512 bytes and the disk has been formatted with protection type 1. Since
253 we are going to modify LBA 2468 then we take a copy of it first:
254 dd if=/dev/sdb skip=2468 bs=512 of=2468.bin count=1
256 The following command line sets the user data to zeros and the PI to 8
258 0xFF bytes on LBA 2468:
259 sg_write_same --lba=2468 /dev/sdb
261 Reading back that block should be successful because the application
263 tag is 0xffff which suppresses the guard (CRC) check (which would oth‐
264 erwise be wrong):
265 dd if=/dev/sdb skip=2468 bs=512 of=/dev/null count=1
267 Now an attempt is made to create a binary file with zeros in the user
269 data, 0x0000 in the application tag and 0xff bytes in the other two PI
270 fields. It is awkward to create 0xff bytes in a file (in Unix) as the
271 "tr" command below shows:
272 dd if=/dev/zero bs=1 count=512 of=ud.bin
274 tr "\000" "\377" < /dev/zero | dd bs=1 of=ff_s.bin count=8
275 cat ud.bin ff_s.bin > lb.bin
276 dd if=/dev/zero bs=1 count=2 seek=514 conv=notrunc of=lb.bin
277 The resulting file can be viewed with 'hexdump -C lb.bin' and should
279 contain 520 bytes. Now that file can be written to LBA 2468 as follows:
280 sg_write_same --lba=2468 wrprotect=3 --in=lb.bin /dev/sdb
282 Note the --wrprotect=3 rather than being set to 1, since we want the
284 WRITE SAME command to succeed even though the PI data now indicates the
285 user data is corrupted. When an attempt is made to read the LBA, an
286 error should occur:
287 dd if=/dev/sdb skip=2468 bs=512 of=/dev/null count=1
289 dd errors are not very expressive, if dmesg is checked there should be
291 a line something like this: "[sdb] Add. Sense: Logical block guard
292 check failed". The block can be corrected by doing a "sg_write_same
293 --lba=1234 /dev/sdb" again or restoring the original contents of that
294 LBA:
295 dd if=2468.bin bs=512 seek=2468 of=/dev/sdb conv=notrunc count=1
297 Hopefully the dd command would never try to truncate the output file
299 when it is a block device.
300
302 Written by Douglas Gilbert.
303
305 Report bugs to <dgilbert at interlog dot com>.
306
308 Copyright © 2009-2013 Douglas Gilbert
309 This software is distributed under a FreeBSD license. There is NO war‐
310 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
311 POSE.
312
314 sg_format,sg_get_lba_status,sg_readcap,sg_vpd,sg_unmap(sg3_utils)
315sg3_utils-1.36 May 2013 SG_WRITE_SAME(8)