1SG_WRITE_SAME(8)                   SG3_UTILS                  SG_WRITE_SAME(8)
2
3
4

NAME

6       sg_write_same - send SCSI WRITE SAME command
7

SYNOPSIS

9       sg_write_same  [--10]  [--16]  [--32]  [--anchor]  [--ff] [--grpnum=GN]
10       [--help]  [--in=IF]   [--lba=LBA]   [--lbdata]   [--num=NUM]   [--ndob]
11       [--pbdata]  [--timeout=TO]  [--unmap] [--verbose] [--version] [--wrpro‐
12       tect=WPR] [--xferlen=LEN] DEVICE
13

DESCRIPTION

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
19       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
28       If  neither  --10,  --16  nor --32 is given then WRITE SAME(10) is sent
29       unless one of the following conditions  is  met.   If  LBA  (plus  NUM)
30       exceeds 32 bits, NUM exceeds 65535, or the --unmap option is given then
31       WRITE SAME(16) is sent.  The --10, --16 and --32 options  are  mutually
32       exclusive.
33
34       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
38       required, protection information of 0xffs is assumed.
39
40       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
46       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
57       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
63       As a precaution against an  accidental  'sg_write_same  /dev/sda'  (for
64       example)  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

OPTIONS

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
73       -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
78       -S, --16
79              send a SCSI WRITE SAME (16) command to DEVICE.
80
81       -T, --32
82              send a SCSI WRITE SAME (32) command to DEVICE.
83
84       -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
88       -f, --ff
89              the data-out buffer sent with this command is  initialized  with
90              0xff bytes when this option is given.
91
92       -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
96       -h, --help
97              output the usage message then exit.
98
99       -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
107              response 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
111       -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
117       -L, --lbdata
118              sets the LBDATA bit in the WRITE SAME cdb.  This  bit  was  made
119              obsolete in sbc3r32 in September 2012.
120
121       -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
127       -n, --num=NUM
128              where NUM is the number of blocks, starting at LBA, to write the
129              data-out  buffer  to.  The default value for NUM is 1. The value
130              corresponds to the 'Number of logical blocks' field in the WRITE
131              SAME cdb.
132              Note  that  a  value of 0 in NUM may be interpreted as write the
133              data-out buffer on every block starting at LBA to the end of the
134              DEVICE.   If  the WSNZ bit (introduced in sbc3r26, January 2011)
135              in the Block Limits VPD page is set then the value of 0 is  dis‐
136              allowed, yielding an Invalid request sense key.
137
138       -P, --pbdata
139              sets  the  PBDATA  bit  in the WRITE SAME cdb. This bit was made
140              obsolete in sbc3r32 in September 2012.
141
142       -t, --timeout=TO
143              where TO is the command timeout value in  seconds.  The  default
144              value is 60 seconds. If NUM is large (or zero) a WRITE SAME com‐
145              mand may require considerably more time than 60 seconds to  com‐
146              plete.
147
148       -U, --unmap
149              sets  the  UNMAP  bit  in the WRITE SAME(10, 16 and 32) cdb. See
150              UNMAP section below.
151
152       -v, --verbose
153              increase the degree of verbosity (debug messages).
154
155       -V, --version
156              output version string then exit.
157
158       -w, --wrprotect=WPR
159              sets the "Write protect" field in the WRITE SAME cdb to WPR. The
160              default  value  is  zero. WPR should be a value between 0 and 7.
161              When WPR is 1 or greater, and the disk's protection type is 1 or
162              greater,  then  8  extra  bytes  of  protection  information are
163              expected or generated (to place in the command's  data-out  buf‐
164              fer).
165
166       -x, --xferlen=LEN
167              where  LEN is the data-out buffer length. Defaults to the length
168              of the IF file or, if that is not given, then  the  READ  CAPAC‐
169              ITY(16  or 10) command is used to find the 'Logical block length
170              in bytes'. That figure may  be  increased  by  8  bytes  if  the
171              DEVICE's protection type is 1 or greater and the WRPROTECT field
172              (see --wrprotect=WPR) is 1 or greater. If both this  option  and
173              the  IF  option  are  given and LEN exceeds the length of the IF
174              file then LEN is the data-out buffer length with zeros  used  as
175              pad bytes.
176

UNMAP

178       Logical  block  provisioning is a new term introduced in SBC-3 revision
179       25 for the ability to mark blocks as unused. For large storage  arrays,
180       it  is  a way to provision less physical storage than the READ CAPACITY
181       command reports is  available,  potentially  allocating  more  physical
182       storage  when  WRITE  commands  require  it. For flash memory (e.g. SSD
183       drives) it is a way of potentially saving  power  (and  perhaps  access
184       time) when it is known large sections (or almost all) of the flash mem‐
185       ory is not in use. SSDs need wear levelling algorithms to have  accept‐
186       able  endurance  and  typically  over provision to simplify those algo‐
187       rithms; hence they typically contain more physical flash  storage  than
188       their logical size would dictate.
189
190       Support  for  logical  block provisioning is indicated by the LBPME bit
191       being set in the READ CAPACITY(16) command response (see the sg_readcap
192       utility).   That  implies  at  least one of the UNMAP or WRITE SAME(16)
193       commands is implemented. If the UNMAP command is implemented  then  the
194       "Maximum  unmap  LBA  count" and "Maximum unmap block descriptor count"
195       fields in the Block Limits VPD page should both be greater  than  zero.
196       The  READ CAPACITY(16) command response also contains a LBPRZ bit which
197       if set means that if unmapped  blocks  are  read  then  zeros  will  be
198       returned  for  the  data (and if protection information is active, 0xff
199       bytes are returned for that). In SBC-3 revision 27 the same  LBPRZ  bit
200       was added to the Logical Block Provisioning VPD page.
201
202       In SBC-3 revision 25 the LBPU and ANC_SUP bits where added to the Logi‐
203       cal Block Provisioning VPD page. When LBPU is set it indicates that the
204       device  supports the UNMAP command (see the sg_unmap utility). When the
205       ANC_SUP bit is set it indicates the device supports anchored LBAs.
206
207       When the UNMAP bit is set in the cdb then the data-out buffer  is  also
208       sent.   Additionally the data section of that data-out buffer should be
209       full of 0x0 bytes while the data protection block, 8 bytes at  the  end
210       if  present,  should  be set to 0xff bytes. If these conditions are not
211       met and the LBPRZ bit is set then the UNMAP  bit  is  ignored  and  the
212       data-out  buffer is written to the DEVICE as if the UNMAP bit was zero.
213       In the absence of the --in=IF option, this utility will attempt build a
214       data-out  buffer  that  meets the requirements for the UNMAP bit in the
215       cdb to be acted on by the DEVICE.
216
217       Logical blocks may also be unmapped by the SCSI UNMAP and  FORMAT  UNIT
218       commands (see the sg_unmap and sg_format utilities).
219
220       The  unmap  capability  in  SCSI is closely related to the ATA DATA SET
221       MANAGEMENT command with the "Trim" bit set. That  ATA  trim  capability
222       does  not  interact  well  with SATA command queueing known as NCQ. T13
223       have introduced a new command called the SFQ DATA SET  MANAGEMENT  com‐
224       mand also with a the "Trim" bit to address that problem. The SCSI WRITE
225       SAME with the UNMAP bit set and the UNMAP  commands  do  not  have  any
226       problems with SCSI queueing.
227

NOTES

229       Various  numeric  arguments  (e.g. LBA) may include multiplicative suf‐
230       fixes or be given in hexadecimal. See the "NUMERIC  ARGUMENTS"  section
231       in the sg3_utils(8) man page.
232
233       In  Linux,  prior  to  lk 3.17, the sg driver did not support cdb sizes
234       greater than 16 bytes. Hence a device node like /dev/sg1 which is asso‐
235       ciated  with  the  sg  driver  would fail with this utility if the --32
236       option was given (or implied by other options).  The  bsg  driver  with
237       device  nodes like /dev/bsg/6:0:0:1 does support cdb sizes greater than
238       16 bytes since its introduction in lk 2.6.28 .
239

EXIT STATUS

241       The exit status of sg_write_same is 0 when it is successful.  Otherwise
242       see the sg3_utils(8) man page.
243

EXAMPLES

245       One  simple  usage  is  to  write blocks of zero from (and including) a
246       given LBA:
247
248         sg_write_same --lba=0x1234 --num=63 /dev/sdc
249
250       Since --xferlen=LEN has not been given, then this utility will call the
251       READ CAPACITY command on /dev/sdc to determine the number of bytes in a
252       logical block.  Let us assume that is 512 bytes. Since --in=IF  is  not
253       given  a  block  of zeros is assumed. So 63 blocks of zeros (each block
254       containing 512 bytes) will be written from (and including) LBA 0x1234 .
255       Note that only one block of zeros is passed to the SCSI WRITE SAME com‐
256       mand in the data-out buffer (as required by SBC-3).
257
258       A similar example follows but in this case the  blocks  are  "unmapped"
259       ("trimmed" in ATA speak) rather than zeroed:
260
261         sg_write_same --unmap -L 0x1234 -n 63 /dev/sdc
262
263       Note  that  if  the  LBPRZ bit in the READ CAPACITY(16) response is set
264       (i.e.  LPPRZ is an acronym for logical block provisioning  read  zeros)
265       then these two examples do the same thing, at least seen from the point
266       of view of subsequent reads.
267
268       This utility can also be used to write protection information  (PI)  on
269       disks formatted with a protection type greater than zero. PI is 8 bytes
270       of extra data appended to the user data of a logical block:  the  first
271       two bytes are a CRC (the "guard"), the next two bytes are the "applica‐
272       tion tag" and the last four bytes are the "reference tag". With protec‐
273       tion  types  1  and  2  if the application tag is 0xffff then the guard
274       should not be checked (against the user data).
275
276       In this example we assume the logical block size (of the user data)  is
277       512 bytes and the disk has been formatted with protection type 1. Since
278       we are going to modify LBA 2468 then we take a copy of it first:
279
280         dd if=/dev/sdb skip=2468 bs=512 of=2468.bin count=1
281
282       The following command line sets the user data to zeros and the PI to  8
283       0xFF bytes on LBA 2468:
284
285         sg_write_same --lba=2468 /dev/sdb
286
287       Reading  back  that  block should be successful because the application
288       tag is 0xffff which suppresses the guard (CRC) check (which would  oth‐
289       erwise be wrong):
290
291         dd if=/dev/sdb skip=2468 bs=512 of=/dev/null count=1
292
293       Now  an  attempt is made to create a binary file with zeros in the user
294       data, 0x0000 in the application tag and 0xff bytes in the other two  PI
295       fields.  It  is awkward to create 0xff bytes in a file (in Unix) as the
296       "tr" command below shows:
297
298         dd if=/dev/zero bs=1 count=512 of=ud.bin
299         tr "\000" "\377" < /dev/zero | dd bs=1 of=ff_s.bin count=8
300         cat ud.bin ff_s.bin > lb.bin
301         dd if=/dev/zero bs=1 count=2 seek=514 conv=notrunc of=lb.bin
302
303       The resulting file can be viewed with 'hexdump -C  lb.bin'  and  should
304       contain 520 bytes. Now that file can be written to LBA 2468 as follows:
305
306         sg_write_same --lba=2468 wrprotect=3 --in=lb.bin /dev/sdb
307
308       Note  the  --wrprotect=3  rather than being set to 1, since we want the
309       WRITE SAME command to succeed even though the PI data now indicates the
310       user  data  is  corrupted.  When an attempt is made to read the LBA, an
311       error should occur:
312
313         dd if=/dev/sdb skip=2468 bs=512 of=/dev/null count=1
314
315       dd errors are not very expressive, if dmesg is checked there should  be
316       a  line  something  like  this: "[sdb]  Add. Sense: Logical block guard
317       check failed". The block can be corrected  by  doing  a  "sg_write_same
318       --lba=1234  /dev/sdb"  again or restoring the original contents of that
319       LBA:
320
321         dd if=2468.bin bs=512 seek=2468 of=/dev/sdb conv=notrunc count=1
322
323       Hopefully the dd command would never try to truncate  the  output  file
324       when it is a block device.
325

AUTHORS

327       Written by Douglas Gilbert.
328

REPORTING BUGS

330       Report bugs to <dgilbert at interlog dot com>.
331
333       Copyright © 2009-2019 Douglas Gilbert
334       This  software is distributed under a FreeBSD license. There is NO war‐
335       ranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR  PUR‐
336       POSE.
337

SEE ALSO

339       sg_format,sg_get_lba_status,sg_readcap,sg_vpd,sg_unmap(sg3_utils)
340
341
342
343sg3_utils-1.45                   December 2019                SG_WRITE_SAME(8)
Impressum