Provided by: sg3-utils_1.17-2_i386 bug

NAME

       sg_format  -  format  or  resize  a SCSI disk (perhaps change its block
       size)

SYNOPSIS

       sg_format  [--count=<n>]   [--early]   [--format]   [--help]   [--long]
       [--resize] [--size=<n>] [--verbose] [--version] [--wait] <scsi_device>

DESCRIPTION

       Not  all  SCSI direct access devices need to be formatted and some have
       vendor specific formatting procedures. SCSI disks with  rotating  media
       are  probably  the  largest  group  that do support a ’standard’ format
       operation.  They are typically factory formatted to a block size of 512
       bytes   with  the  largest  number  of  blocks  that  the  manufacturer
       recommends. That number of blocks  typically  leaves  aside  a  certain
       number  of  tracks  and  sectors  for  reassignment  of  logical  block
       addresses during the life of the disk.

       This utility can format modern SCSI disks and potentially change  their
       block  size  (if  permitted)  and  the  block  count  (i.e.  number  of
       accessible blocks on the media also known as  "resizing").  Resizing  a
       disk  to  less  than  the  manufacturer’s  recommended  block  count is
       sometimes called "short stroking" (see  NOTES  section).  Resizing  the
       block  count while not changing the block size may not require a format
       operation. Recent changes to the SBC-2 draft standard (see www.t10.org)
       have  obsoleted  the  "format  device" mode page. Many of the low level
       details found in that mode page are now left up to  the  discretion  of
       the manufacturer.

       When  this  utility  is used without options (apart from a device name)
       then it prints out the existing block size and block count derived from
       two  sources.  These two sources are a block descriptor in the response
       to a MODE SENSE command and the response to a  READ  CAPACITY  command.
       The  reason for this double check is to detect a "format corrupt" state
       (see NOTES section).

       A recent addition in the SBC-2 is  "protection  information".  See  the
       section  of  that name (section 4.16 in draft SBC-2 rev 16). It adds an
       extra 8 bytes of  protection  information  to  each  block  (a  2  byte
       "logical  block  guard"  (CRC),  a  2  byte  "logical block application
       guard", and a 4 byte "logical block  reference  tag").  A  device  that
       supports  protection  information  sets the "protect" bit in a standard
       INQUIRY response. The "FMTPINFO"  and  "RTO_REQ"  bits  in  the  FORMAT
       command  cdb  are associated with protection information and can be set
       by this utility.

       --count=<n> | -c <n>
              count of blocks to be formatted or media to be resized  to.  Can
              be  used  with  either "--format" or "--resize". With "--format"
              this option need not be given in which case it is assumed to  be
              zero.  With "--format" the interpretation of <n> is:
                (n > 0) : only format the first <n> blocks and READ
                          CAPACITY will report <n> blocks after format
                (n = 0) and block size unchanged : use existing block count
                (n = 0) and block size changed : recommended maximum block
                                                 count for new block size
                (n = -1) : use recommended maximum block count
                (n < -1) : illegal
              With  "--resize"  this  option  must  be  given and <n> has this
              interpretation:
                (n > 0) : after resize READ CAPACITY will report <n>
                          blocks
                (n = 0) : after resize READ CAPACITY will report 0 blocks
                (n = -1) : after resize READ CAPACITY will report its
                           maximum number of blocks
                (n < -1) : illegal
              In both cases if the given <n> exceeds  the  maximum  number  of
              blocks (for the block size) then the disk reports an error.  See
              NOTES section below.

       --early | -e
              this option is active when  "--format"  is  given.  The  default
              action  of  this utility is to poll the disk every 30 seconds to
              determine the progress of  the  format  operation  until  it  is
              finished.  When  this  option  is  given  this utility will exit
              "early" as soon as the format has commenced. Then the  user  can
              monitor  the progress of the ongoing format operation with other
              utilities  (e.g.  sg_turs  or  sg_requests).  This  option   and
              "--wait" cannot both be given.

       --format | -F
              issue  a  SCSI  FORMAT  command.  This will destroy all the data
              held on the media.  This option is required to change the  block
              size  of  a  disk.  See NOTES section for implementation details
              and EXAMPLES section for typical use.

       --help | -h
              print out the usage information then exit.

       --long | -l
              the default action of this utility is to assume 32  bit  logical
              block  addresses. With 512 byte block size this permits almost 2
              terabytes (almost 2 ** 41 bytes) on a single disk.  This  option
              selects  commands  and  parameters that allow for 64 bit logical
              block addresses.  Specifically this is the "longlba" flag in the
              MODE  SENSE (10) command and READ CAPACITY (16) rather than READ
              CAPACITY (10). When a  disk  supports  "protection  information"
              then this option may also be useful.

       --pinfo | -p
              instructs  a  ’--format’  to  add an extra 8 bytes of protection
              information.  Default action is not to  format  with  protection
              information. Has no action unless ’--format’ is given.

       --resize | -r
              rather  than  format  the  disk,  it  can be resized. This means
              changing the number of blocks on the device reported by the READ
              CAPACITY   command.    This  option  should  be  used  with  the
              ’--count=<new_blk_count>’ option.  The contents of  all  logical
              blocks  on  the media remain unchanged when this option is used.
              This means that any  resize  operation  can  be  reversed.  This
              option  cannot  be  used  together  with  either "--format" or a
              "--size" whose argument is different to the existing block size.

       --rto_req | -R
              instructs a format to enable application client ownership of the
              "logical block reference tag" field. The default  action  is  to
              disable  application  client  ownership  of  that  field. Has no
              action unless both ’--format’ and ’--pinfo’ are given.

       --size=<n> | -s <n>
              block size (i.e. number of bytes in each block)  to  format  the
              device  to.  The default value is whatever is currently reported
              by the block descriptor in a MODE SENSE command.  This option is
              only  active  when  the  "--format" option is also given. If the
              block size given by this option is different  from  the  current
              value  then  a MODE SELECT command is used to change it prior to
              the FORMAT command being started (as recommended  in  the  draft
              standard).  Recent  SCSI  disks usually have 512 byte sectors by
              default and allow up to 16 bytes extra in  a  sector  (i.e.  528
              byte  sectors).   If the given size in unacceptable to the disk,
              most likely an "Invalid field in parameter  list"  message  will
              appear  in  sense data (requires the use of ’-v’ to decode sense
              data).

       --verbose | -v
              increase the level of verbosity,  (i.e.  debug  output).  "-vvv"
              gives the maximum debug output.

       --version | -V
              print the version string and then exit.

       --wait | -w
              this  option  only  has  an  effect  when used together with the
              "--format" option. The default  format  action  is  to  set  the
              "IMMED"  bit  in  the  FORMAT  UNIT  command’s (short) parameter
              header. If this option (i.e. "--wait") is given then the "IMMED"
              bit  is  not  set.  Then the FORMAT UNIT command waits until the
              format operation completes before returning its  response.  This
              can  be  several  hours on large disks. This utility sets a four
              hour timeout on such a FORMAT UNIT command.

NOTES

       The format command is still  quite  complicated  and  a  large  set  of
       variables  in  the  format command itself and associated parameters are
       set to default values by this utility. These include: LONGLIST, CMPLIST
       and  the  defect  list format (in the command) and all flags within the
       parameter header  apart  from  IMMED  (as  explained  in  the  "--wait"
       option).

       The  SBC-2  draft  standard  (revision  16) says that the REQUEST SENSE
       command should be used for obtaining a  progress  indication  when  the
       format command returns prior to the completion of the format operation.
       However, tests on a selection of recent  disks  shows  that  TEST  UNIT
       READY  commands  yield  progress  indications  (but  not  REQUEST SENSE
       commands). A new option may be required to handle this when disks catch
       up to the current draft.

       When  the  "--format"  option is given then there is a 10 second window
       during which the user is invited to abort sg_format. This is just prior
       the  FORMAT  UNIT  SCSI command being issued. If the "--wait" option is
       not given then the FORMAT UNIT SCSI command is issued  with  the  IMMED
       bit  set  which  causes the SCSI command to return after it has started
       the format operation. The "--early" option will cause sg_format to exit
       at  that  point.  Otherwise the given device is polled every 30 seconds
       with TEST UNIT READY commands until it reports an "all clear" (i.e. the
       format  operation  has completed). Normally these polling commands will
       result in a progress indicator (expressed as a percentage) being output
       to the screen. If the user gets bored watching the progress report then
       sg_format can be terminated (e.g. with control-C) without effecting the
       format  operation  which continues. However a bus or device reset (or a
       power cycle) may well cause the device to become "format corrupt".

       When the "--format" and "--wait"  options  are  both  given  then  this
       utility  may  take  a  long time to return. In this case care should be
       taken not to send any other SCSI commands to the disk  as  it  may  not
       respond leaving those commands queued behind the active format command.
       This may cause a timeout in the OS driver (in a lot shorter period than
       4  hours  applicable  to the format command). This may result in the OS
       resetting the disk leaving the format operation  incomplete.  This  may
       leave  the disk in a "format corrupt" state requiring another format to
       remedy the situation.

       When the block size (i.e. the number of bytes in each block) is changed
       on  a  disk two SCSI commands must be sent: a MODE SELECT to change the
       block size followed by a FORMAT command. If  the  MODE  SELECT  command
       succeeds  and the FORMAT fails then the disk may be in a state that the
       draft  standard  calls  "format  corrupt".  A  block  descriptor  in  a
       subsequent  MODE SENSE will report the requested new block size while a
       READ CAPACITY command will report the existing (i.e.  different)  block
       size.  Alternatively  the READ CAPACITY command may fail, reporting the
       device is not ready, potentially requiring a format.  The  solution  to
       this  situation  is  to  do a format again (and this time the new block
       size does not have to be given) or change the block size  back  to  the
       original size.

       The draft SBC-2 standard states that the block count can be set back to
       the manufacturer’s maximum recommended value  in  a  format  or  resize
       operation. This can be done by placing an address of 0xffffffff (or the
       64 bit equivalent) in the appropriate block descriptor field to a  MODE
       SELECT  command.  In  signed  (two’s  complement) arithmetic that value
       corresponds to ’-1’. So a "--count" argument of ’-1’ causes  the  block
       count  to  be set back to the manufacturer’s maximum recommended value.
       To see exactly which SCSI commands are being  executed  and  parameters
       passed add "-vvv" to the sg_format command line.

       Short  stroking  is  a technique to trade off capacity for performance.
       Disk performance is usually highest on the  outer  tracks  (i.e.  lower
       logical  block  addresses)  so  by resizing or reformatting a disk to a
       smaller capacity, average performance will usually be increased.

       Other utilities may be useful in finding  information  associated  with
       formatting.  These include sg_inq to fetch standard INQUIRY information
       (e.g. the PROTECT bit) and to fetch the extended INQUIRY VPD page (e.g.
       RTO  and  GRD_CHK  bits). The sdparm (or sginfo) utility can be used to
       access and potentially change the now obsolete format mode page.

       scsiformat is another utility available for formatting SCSI disks  with
       linux.  It  dates  from 1997 (most recent update) and may be useful for
       disks whose firmware is of that vintage.

       The argument to "--count" is a number which may be followed by  one  of
       these  multiplicative  suffixes:  c  C  *1;  w  W *2; b B *512; k K KiB
       *1,024; KB *1,000; m M MiB *1,048,576; MB  *1,000,000  .  This  pattern
       continues  for  "G",  "T"  and  "P".  Also  a suffix of the form "x<n>"
       multiplies the leading number by <n>.  Alternatively  numerical  values
       can  be  given in hexadecimal preceded by either "0x" or "0X". When hex
       numbers are given, multipliers cannot be used.

EXAMPLES

       First, do not alter anything but print out the existing block count and
       size  derived  from  two  sources:  a block descriptor in a MODE SELECT
       command response and from the response of a READ CAPACITY commands:

          sg_format /dev/sdm

       Now a simple format, leaving the block count  and  size  as  they  were
       previously,  executing  the  format  command  in IMMED mode and polling
       every 30 seconds to print out a progress indication:

          sg_format --format /dev/sdm

       Now the same format, but waiting (passively) until the format operation
       is complete:

          sg_format --format --wait /dev/sdm

       Next  is  a  format in which the block size is changed to 520 bytes and
       the block count is set to the manufacturer’s maximum  value  (for  that
       block size). Note, not all disks support changing the block size:

          sg_format --format --size=520 /dev/sdm

       Now a resize operation so that only the first 0x10000 (65536) blocks on
       a disk are accessible. The remaining blocks remain unaltered.

          sg_format --resize --count=0x10000 /dev/sdm

       Now resize the disk back to its normal (maximum) block count:

          sg_format --resize --count=-1 /dev/sdm

AUTHORS

       Written by Grant Grundler, James Bottomley and Douglas Gilbert.

REPORTING BUGS

       Report bugs to <dgilbert at interlog dot com>.

COPYRIGHT

       Copyright © 2005 Grant Grundler, James Bottomley and Douglas Gilbert
       This software is distributed under the  GPL  version  2.  There  is  NO
       warranty;  not  even  for  MERCHANTABILITY  or FITNESS FOR A PARTICULAR
       PURPOSE.

SEE ALSO

       sg_turs, sg_requests, sg_inq,  sg_modes,  sginfo,  sg_wr_mode  (all  in
       sg3_utils), sdparm, scsiformat, setblocksize