Poster of Linux kernelThe best gift for a Linux geek
SG_WRITE_SAME

SG_WRITE_SAME

Section: SG3_UTILS (8) Updated: November 2010
Local index Up
 

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 the LEN argument, 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 the last 8 bytes are set to 0xff. If READ CAPACITY(16) fails then READ CAPACITY(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.

As of SBC-3 revision 24 the UNMAP and ANCHOR bits are not supported by WRITE SAME (10). However there is a proposal to allow that case and this utility now allows those bits to be set for WRITE SAME (10) when the --10 is given.

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 timeout value TO may need to be increased from its default value of 60 seconds.

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. This option has been added to allow the --unmap (and --anchor) options to be set on the SCSI WRITE SAME (10) command. As of the SBC-3 revision 25 draft this has been proposed but hasn't be accepted.
-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 overwrite 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 command may require considerably more time than 60 seconds to complete.
-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.
-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 CAPACITY(16 or 10) command is called on the DEVICE and the 'Logical block length in bytes' and the PROT_EN bit in the response are used to determine the data out buffer length. 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 the complicated term used 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).

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).  

NOTES

Various numeric arguments (e.g. LBA) may include multiplicative suffixes 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.  

AUTHORS

Written by Douglas Gilbert.  

REPORTING BUGS

Report bugs to <dgilbert at interlog dot com>.  

COPYRIGHT

Copyright © 2009-2010 Douglas Gilbert
This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  

SEE ALSO

sg_format,sg_get_lba_status,sg_readcap,sg_unmap(sg3_utils)


 

Index

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
UNMAP
NOTES
EXIT STATUS
AUTHORS
REPORTING BUGS
COPYRIGHT
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 22:02:22 GMT, April 16, 2011