Provided by: sg3-utils_1.27-0.1_i386 bug

NAME

       sg_write_same - send the SCSI WRITE SAME command

SYNOPSIS

       sg_write_same    [--16]   [--32]   [--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.

       By default WRITE SAME(10) is sent unless  LBA  (plus  NUM)  exceeds  32
       bits,  NUM  exceeds  65535  or  --unmap is given.  In these cases WRITE
       SAME(16) is sent.

       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 will most likely 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.

       This  utility   is   based   SBC-3   draft   revision   18   found   at
       http://www.t10.org .

OPTIONS

       Arguments to long options are mandatory for short options as well.

       -S, --16
              send  a  SCSI  WRITE  SAME  (16)  command to DEVICE. The default
              action (in the absence of this option and the --32 option) is to
              send a SCSI WRITE SAME (10) command.

       -T, --32
              send  a  SCSI  WRITE  SAME  (32)  command to DEVICE. The default
              action (in the absence of this option and the --16 option) is to
              send a SCSI WRITE SAME (10) command.

       -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). 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(16 and 32) cdb. When this
              option is given the default command becomes WRITE SAME(16) since
              the  WRITE  SAME(10)  command  does not offer this bit (in SBC-3
              draft revision 18). 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)  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

       Thin provisioning is the sophisticated term used in SBC-3  revision  18
       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 thin provisioning is indicated by the TPE bit being set  in
       the  READ  CAPACITY(16)  command response. That implies at least one of
       the UNMAP, WRITE SAME(16) or WRITE SAME(32) 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 TPRZ 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 the cases of WRITE SAME(16) and WRITE SAME(32) 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 TPRZ 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.

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 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_readcap