sg_write_same - send the SCSI WRITE SAME command
sg_write_same [--10] [--16] [--32] [--anchor] [--grpnum=GN] [--help] [--in=IF] [--lba=LBA] [--lbdata] [--num=NUM] [--pbdata] [--timeout=TO] [--unmap] [--verbose] [--version] [--wrprotect=WPR] [--xferlen=LEN] DEVICE
SG_WRITE_SAME(8) SG3_UTILS SG_WRITE_SAME(8)
NAME
sg_write_same - send the SCSI WRITE SAME command
SYNOPSIS
sg_write_same [--10] [--16] [--32] [--anchor] [--grpnum=GN] [--help]
[--in=IF] [--lba=LBA] [--lbdata] [--num=NUM] [--pbdata] [--timeout=TO]
[--unmap] [--verbose] [--version] [--wrprotect=WPR] [--xferlen=LEN]
DEVICE
DESCRIPTION
Send the SCSI WRITE SAME (10, 16 or 32 byte) command to DEVICE. This
command writes the given block NUM times to consecutive blocks on the
DEVICE starting at logical block address LBA.
The length of the block to be written multiple times is obtained from
either the LEN argument, or the length of the given input file IF, or
by calling READ CAPACITY(16) on DEVICE. The contents of the block to be
written are obtained from the input file IF or zeroes are used. If READ
CAPACITY(16) is called (which implies IF was not given) and the PROT_EN
bit is set then an extra 8 bytes (i.e. more than the logical block
size) of 0xff are sent. If READ CAPACITY(16) fails then READ CAPAC-
ITY(10) is used to determine the block size.
If neither --10, --16 nor --32 is given then WRITE SAME(10) is sent
unless one of the following conditions is met. If LBA (plus NUM)
exceeds 32 bits, NUM exceeds 65535, or the --unmap option is given then
WRITE SAME(16) is sent. The --10, --16 and --32 options are mutually
exclusive.
In SBC-3 revision 26 the UNMAP and ANCHOR bits were added to the WRITE
SAME (10) command. Since the UNMAP bit has been in WRITE SAME (16) and
WRITE SAME (32) since SBC-3 revision 18, the lower of the two (i.e.
WRITE SAME (16)) is the default when the --unmap option is given. To
send WRITE SAME (10) use the --10 option.
Take care: The WRITE SAME(10, 16 and 32) commands interpret a NUM of
zero as write to the end of DEVICE. This utility defaults NUM to 1 .
The WRITE SAME commands have no IMMED bit so if NUM is large (or zero)
then an invocation of this utility could take a long time, potentially
as long as a FORMAT UNIT command. In such situations the command time-
out value TO may need to be increased from its default value of 60 sec-
onds. In SBC-3 revision 26 the WSNZ (write same no zero) bit was added
to the Block Limits VPD page [0xB0]. If set the WRITE SAME commands
will not accept a NUM of zero. The same SBC-3 revision added the "Maxi-
mum Write Same Length" field to the Block Limits VPD page.
The Logical Block Provisioning VPD page [0xB2] contains the LBWS and
LBW10 bits. If LBWS is set then WRITE SAME (16) supports the UNMAP bit.
If LBWS10 is set then WRITE SAME (10) supports the UNMAP bit. If either
LBWS or LBWS10 is set and the WRITE SAME (32) is supported then WRITE
SAME (32) supports the UNMAP bit. This is as of SBC-3 revision 26.
As a precaution against an accidental 'sg_write_same /dev/sda' (for
example) overwriting LBA 0 on /dev/sda with zeroes, at least one of the
--in=IF, --lba=LBA or --num=NUM options must be given. Obviously this
utility can destroy a lot of user data so check the options carefully.
OPTIONS
Arguments to long options are mandatory for short options as well.
-R, --10
send a SCSI WRITE SAME (10) command to DEVICE. The ability to
set the --unmap (and --anchor) options to this command was added
in SBC-3 revision 26.
-S, --16
send a SCSI WRITE SAME (16) command to DEVICE.
-T, --32
send a SCSI WRITE SAME (32) command to DEVICE.
-a, --anchor
sets the ANCHOR bit in the cdb. Introduced in SBC-3 revision 22.
That draft requires the --unmap option to also be specified.
-g, --grpnum=GN
sets the 'Group number' field to GN. Defaults to a value of
zero. GN should be a value between 0 and 31.
-h, --help
output the usage message then exit.
-i, --in=IF
read data (binary) from file named IF and use it as the data out
buffer for the SCSI WRITE SAME command. The length of the data
out buffer is --xferlen=LEN or, if that is not given, the length
of the IF file. If IF is "-" then stdin is read. If this option
is not given then 0x00 bytes are used as fill with the length of
the data out buffer obtained from --xferlen=LEN or by calling
READ CAPACITY(16 or 10). If the response to READ CAPACITY(16)
has the PROT_EN bit set then data out buffer size is modified
accordingly with the last 8 bytes set to 0xff.
-l, --lba=LBA
where LBA is the logical block address to start the WRITE SAME
command. Defaults to lba 0 which is a dangerous block to over-
write on a disk that is in use. Assumed to be in decimal unless
prefixed with '0x' or has a trailing 'h'.
-L, --lbdata
sets the LBDATA bit in the WRITE SAME cdb.
-n, --num=NUM
where NUM is the number of blocks, starting at LBA, to write the
data out buffer to. The default value for NUM is 1. The value
corresponds to the 'Number of logical blocks' field in the WRITE
SAME cdb. Note that a value of 0 in NUM is interpreted as write
the data out buffer on every block starting at LBA to the end of
the DEVICE.
-P, --pbdata
sets the PBDATA bit in the WRITE SAME cdb.
-t, --timeout=TO
where TO is the command timeout value in seconds. The default
value is 60 seconds. If NUM is large (or zero) a WRITE SAME com-
mand may require considerably more time than 60 seconds to com-
plete.
-U, --unmap
sets the UNMAP bit in the WRITE SAME(10, 16 and 32) cdb. See
UNMAP section below.
-v, --verbose
increase the degree of verbosity (debug messages).
-V, --version
output version string then exit.
-w, --wrprotect=WPR
sets the "Write protect" field in the WRITE SAME cdb to WPR. The
default value is zero. WPR should be a value between 0 and 7.
When WPR is 1 or greater, and the disk's protection type is 1 or
greater, then 8 extra bytes of protection information are
expected or generated (to place in the commmand's data out buf-
fer).
-x, --xferlen=LEN
where LEN is the data out buffer length. Defaults to the length
of the IF file or, if that is not given, then the READ CAPAC-
ITY(16 or 10) command is used to find the 'Logical block length
in bytes'. That figure may be increased by 8 bytes if the
DEVICE's protection type is 1 or greater and the WRPROTECT field
(see --wrprotect=WPR) is 1 or greater. If both this option and
the IF option are given and LEN exceeds the length of the IF
file then LEN is the data out buffer length with zeroes used as
pad bytes.
UNMAP
Logical block provisioning is a new term introduced in SBC-3 revision
25 for the ability to mark blocks as unused. It is closely related to
the ATA DATA SET MANAGEMENT command with the "Trim" bit set. For large
storage arrays, it is a way to provision less physical storage than the
READ CAPACITY command reports is available, potentially allocating more
physical storage when WRITE commands require it. For flash memory it is
a way of potentially saving power (and perhaps access time) when it is
known large sections (or almost all) of the flash memory is not in use.
Support for logical block provisioning is indicated by the LBPME bit
being set in the READ CAPACITY(16) command response (see the sg_readcap
utility). That implies at least one of the UNMAP or WRITE SAME(16)
commands is implemented. If the UNMAP command is implemented then the
"Maximum unmap LBA count" and "Maximum unmap block descriptor count"
fields in the Block Limits VPD page should both be greater than zero.
The READ CAPACITY(16) command response also contains a LBPRZ bit which
if set means that if unmapped blocks are read then zeroes will be
returned for the data (and if protection information is active, 0xff
bytes are returned for that). In SBC-3 revision 27 the same LBPRZ bit
was added to the Logical Block Provisioning VPD page.
In SBC-3 revision 25 the LBPU and ANC_SUP bits where added to the Logi-
cal Block Provisioning VPD page. When LBPU is set it indicates that the
device supports the UNMAP command (see the sg_unmap utility). When the
ANC_SUP bit is set it indicates the device supports anchored LBAs.
When the UNMAP bit is set in the cdb then the data out buffer is also
sent. Additionally the data section of that data out buffer should be
full of 0x0 bytes while the data protection block, 8 bytes at the end
if present, should be set to 0xff bytes. If these conditions are not
met and the LBPRZ bit is set then the UNMAP bit is ignored and the data
out buffer is written to the DEVICE as if the UNMAP bit was zero. In
the absence of the --in=IF option, this utility will attempt build a
data out buffer that meets the requirements for the UNMAP bit in the
cdb to be acted on by the DEVICE.
Logical blocks may also be unmapped by the SCSI UNMAP and FORMAT UNIT
commands (see the sg_unmap and sg_format utilities).
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
+---------------+--------------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+--------------------------+
|Availability | system/storage/sg3_utils |
+---------------+--------------------------+
|Stability | Uncommitted |
+---------------+--------------------------+
NOTES
Various numeric arguments (e.g. LBA) may include multiplicative suf-
fixes or be given in hexadecimal. See the "NUMERIC ARGUMENTS" section
in the sg3_utils(8) man page.
EXIT STATUS
The exit status of sg_write_same is 0 when it is successful. Otherwise
see the sg3_utils(8) man page.
EXAMPLES
One simple usage is to write blocks of zero from (and including) a
given LBA:
sg_write_same --lba=0x1234 --num=63 /dev/sdc
Since --xferlen=LEN has not been given, then this utility will call the
READ CAPACITY command on /dev/sdc to determine the number of bytes in a
logical block. Let us assume that is 512 bytes. Since --in=IF is not
given a block of zeroes is assumed. So 63 blocks of zeroes (each block
containing 512 bytes) will be written from (and including) LBA 0x1234 .
Note that only one block of zeroes is passed to the SCSI WRITE SAME
command in the data out buffer (as required by SBC-3).
A similar example follows but in this case the blocks are "unmapped"
("trimmed" in ATA speak) rather than zeroed:
sg_write_same --unmap -L 0x1234 -n 63 /dev/sdc
Note that if the LBPRZ bit in the READ CAPACITY(16) response is set
(i.e. LPPRZ is an acronym for logical block provisioning read zeroes)
then these two examples do the same thing, at least seen from the point
of view of subsequent reads.
This utility can also be used to write protection information (PI) on
disks formatted with a protection type greater than zero. PI is 8 bytes
of extra data appended to the user data of a logical block: the first
two bytes are a CRC (the "guard"), the next two bytes are the "applica-
tion tag" and the last four bytes are the "reference tag". With protec-
tion types 1 and 2 if the application tag is 0xffff then the guard
should not be checked (against the user data).
In this example we assume the logical block size (of the user data) is
512 bytes and the disk has been formatted with protection type 1. Since
we are going to modify LBA 2468 then we take a copy of it first:
dd if=/dev/sdb skip=2468 bs=512 of=2468.bin count=1
The following command line sets the user data to zeroes and the PI to 8
0xFF bytes on LBA 2468:
sg_write_same --lba=2468 /dev/sdb
Reading back that block should be successful because the application
tag is 0xffff which suppresses the guard (CRC) check (which would oth-
erwise be wrong):
dd if=/dev/sdb skip=2468 bs=512 of=/dev/null count=1
Now an attempt is made to create a binary file with zeroes in the user
data, 0x0000 in the application tag and 0xff bytes in the other two PI
fields. It is awkward to create 0xff bytes in a file (in Unix) as the
"tr" command below shows:
dd if=/dev/zero bs=1 count=512 of=ud.bin
tr "\000" "\377" < /dev/zero | dd bs=1 of=ff_s.bin count=8
cat ud.bin ff_s.bin > lb.bin
dd if=/dev/zero bs=1 count=2 seek=514 conv=notrunc of=lb.bin
The resulting file can be viewed with 'hexdump -C lb.bin' and should
contain 520 bytes. Now that file can be written to LBA 2468 as follows:
sg_write_same --lba=2468 wrprotect=3 --in=lb.bin /dev/sdb
Note the --wrprotect=3 rather than being set to 1, since we want the
WRITE SAME command to succeed even though the PI data now indicates the
user data is corrupted. When an attempt is made to read the LBA, an
error should occur:
dd if=/dev/sdb skip=2468 bs=512 of=/dev/null count=1
dd errors are not very expressive, if dmesg is checked there should be
a line something like this: "[sdb] Add. Sense: Logical block guard
check failed". The block can be corrected by doing a "sg_write_same
--lba=1234 /dev/sdb" again or restoring the original contents of that
LBA:
dd if=2468.bin bs=512 seek=2468 of=/dev/sdb conv=notrunc count=1
Hopefully the dd command would never try to truncate the output file
when it is a block device.
AUTHORS
Written by Douglas Gilbert.
REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.
COPYRIGHT
Copyright (C) 2009-2011 Douglas Gilbert
This software is distributed under a FreeBSD license. There is NO war-
ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR-
POSE.
SEE ALSO
sg_format,sg_get_lba_status,sg_readcap,sg_vpd,sg_unmap(sg3_utils)
This software was built from source available at
https://java.net/projects/solaris-userland. The original community
source was downloaded from http://sg.danny.cz/sg/p/sg3_utils-1.33.tgz
Further information about this software can be found on the open source
community website at http://sg.danny.cz/sg/sg3_utils.html.
sg3_utils-1.33 November 2011 SG_WRITE_SAME(8)