path: root/doc/sg_format.8

.TH SG_FORMAT "8" "March 2009" "sg3_utils\-1.27" SG3_UTILS
.SH NAME
sg_format \- format or resize a SCSI disk (perhaps change its block size)
.SH SYNOPSIS
.B sg_format
[\fI\-\-cmplst=\fR0|1] [\fI\-\-count=COUNT\fR] [\fI\-\-dcrt\fR]
[\fI\-\-early\fR] [\fI\-\-fmtpinfo=FPI\fR] [\fI\-\-format\fR] [\fI\-\-help\fR]
[\fI\-\-long\fR] [\fI\-\-pfu=PFU\fR] [\fI\-\-pie=PIE\fR] [\fI\-\-pinfo\fR]
[\fI\-\-resize\fR] [\fI\-\-rto_req\fR] [\fI\-\-security\fR] [\fI\-\-six\fR]
[\fI\-\-size=SIZE\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR] [\fI\-\-wait\fR]
\fIDEVICE\fR
.SH DESCRIPTION
.\" Add any additional description here
.PP
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. The manufacturer's
recommendation typically leaves aside a certain number of tracks, spread
across the media, for reassignment of logical block addresses during the life
of the disk.
.PP
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. The SBC\-2 standard (see
www.t10.org) has 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.
.PP
When this utility is used without options (apart from a DEVICE) 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). This usage will not
modify the disk.
.PP
When this utility is used with the "\-\-format" (or "\-F") option it will attempt
to format the given DEVICE. There is a 10 second pause during which time the
user is invited (twice 5 seconds apart) to abort sg_format. This occurs just
prior the SCSI FORMAT UNIT command being issued. See the NOTES section for
more information.
.PP
Recent SBC\-3 drafts add several "protection types" to the "protection
information" introduced in the SBC\-2 standard. See the "protection
information" section (section 4.18 in draft SBC\-3 rev 18). 8 bytes of
protection information are added 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 its standard INQUIRY response. The "FMTPINFO" field in
in the FORMAT UNIT command cdb plus the "Protection Field Usage" in the
parameter header are associated with protection information and can be set by
this utility.
.SH OPTIONS
Arguments to long options are mandatory for short options as well.
The options are arranged in alphabetical order based on the long
option name.
.TP
\fB\-C\fR, \fB\-\-cmplst\fR=0 | 1
sets the CMPLST ("complete list") bit in the FORMAT UNIT cdb to 0 or 1.
The default is 1 in which case the existing GLIST (grown list) is ignored.
If the value is 0 then the existing GLIST is taken into account. See the
LISTS section below. Active when the \fI\-\-format\fR option is given. In
most cases this bit should be left set; some MO disk drives need this bit
cleared. The SCSI to ATA Translation (SAT) standard (prior draft: sat\-r09)
requires this bit to be cleared.
.TP
\fB\-c\fR, \fB\-\-count\fR=\fICOUNT\fR
where \fICOUNT\fR is the number of blocks to be formatted or media to be
resized to. Can be used with either \fI\-\-format\fR or \fI\-\-resize\fR.
With \fI\-\-format\fR this option need not be given in which case it is
assumed to be zero. With \fI\-\-format\fR the interpretation of \fICOUNT\fR
is:
.br
  (\fICOUNT\fR > 0) : only format the first \fICOUNT\fR blocks and READ
.br
                CAPACITY will report \fICOUNT\fR blocks after format
.br
  (\fICOUNT\fR = 0) and block size unchanged : use existing block count
.br
  (\fICOUNT\fR = 0) and block size changed : recommended maximum block
.br
                                       count for new block size
.br
  (\fICOUNT\fR = \-1) : use recommended maximum block count
.br
  (\fICOUNT\fR < \-1) : illegal
.br
With \fI\-\-resize\fR this option must be given and \fICOUNT\fR has this
interpretation:
.br
  (\fICOUNT\fR > 0) : after resize READ CAPACITY will report \fICOUNT\fR
.br
                blocks
.br
  (\fICOUNT\fR = 0) : after resize READ CAPACITY will report 0 blocks
.br
  (\fICOUNT\fR = \-1) : after resize READ CAPACITY will report its
.br
                 maximum number of blocks
.br
  (\fICOUNT\fR < \-1) : illegal
.br
In both cases if the given \fICOUNT\fR exceeds the maximum number of
blocks (for the block size) then the disk reports an error.
See NOTES section below.
.TP
\fB\-D\fR, \fB\-\-dcrt\fR
this option sets the DCRT bit in the FORMAT UNIT command's parameter list
header. It will "disable certification". Certification verifies that blocks
are usable during the format process. Using this option may speed the format.
The default action of this utility (i.e. when this option is not given) is
to clear the DCRT bit thereby requesting "media certification". When the DCRT
bit is set, the FOV bit must also be set hence sg_format does that.
.TP
\fB\-e\fR, \fB\-\-early\fR
this option is active when \fI\-\-format\fR 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(8) or sg_requests(8)). This option and
\fI\-\-wait\fR cannot both be given.
.TP
\fB\-f\fR, \fB\-\-fmtpinfo\fR=\fIFPI\fR
sets the FMTPINFO field in the FORMAT UNIT cdb to a value between 0 and 3.
The default value is 0. The FMTPINFO field from SBC\-3 revision 16 is a 2
bit field (bits 7 and 6 of byte 1 in the cdb). Prior to that it was a single
bit field (bit 7 of byte 1 in the cdb) and there was an accompanying bit
called RTO_REQ (bit 6 of byte 1 in the cdb). The deprecated options "\-\-pinfo"
and "\-\-rto\-req" represent the older usage. This option should be used in
their place. This option has no action unless \fI\-\-format\fR is given.
.TP
\fB\-F\fR, \fB\-\-format\fR
issue a SCSI FORMAT UNIT command.
.B This will destroy all the data held on the media.
This option is required to change the block size of a disk. The user is given
a 10 second count down to ponder the wisdom of doing this, during which time
control\-C (amongst other Unix commands) can be used to kill this process
before it does any damage. See NOTES section for implementation details and
EXAMPLES section for typical use.
.TP
\fB\-h\fR, \fB\-\-help\fR
print out the usage information then exit.
.TP
\fB\-l\fR, \fB\-\-long\fR
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 option sets
the "longlba" flag in the MODE SENSE (10) command and uses READ CAPACITY (16)
rather than READ CAPACITY (10). This option does not set the LONGLIST bit
in the FORMAT UNIT command. The LONGLIST bit is set as required depending
other parameters (e.g. when '\-\-pie=PIE' is greater than zero).
.TP
\fB\-P\fR, \fB\-\-pfu\fR=\fIPFU\fR
sets the "Protection Field Usage" field in the parameter block associated
with a FORMAT UNIT command to \fIPFU\fR. The default value is 0, the only
other defined value currently is 1. Used together with \fI\-\-fmtpinfo=FPI\fR
to specify the "protection type" to format the disk to (see SBC\-3).
.TP
\fB\-p\fR, \fB\-\-pinfo\fR
The option is deprecated, use the \fI\-\-fmtpinfo=FPI\fR option instead.
If used, then it sets bit 7 of byte 1 in the FORMAT UNIT cdb.
Has no action unless \fI\-\-format\fR is given.
.TP
\fB\-q\fR, \fB\-\-pie\fR=\fIPIE\fR
sets the "Protection Interval Exponent" field in the parameter block
associated with a FORMAT UNIT command to \fIPIE\fR. The default value is 0.
This field first appeared in SBC\-3 revision 18. Has no action unless
\fI\-\-format\fR is given.
.TP
\fB\-r\fR, \fB\-\-resize\fR
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 \fI\-\-count=COUNT\fR 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 \fI\-\-format\fR
or a \fI\-\-size=SIZE\fR whose argument is different to the existing block
size.
.TP
\fB\-R\fR, \fB\-\-rto_req\fR
The option is deprecated, use the \fI\-\-fmtpinfo=FPI\fR option instead.
If used, then it sets bit 6 of byte 1 in the FORMAT UNIT cdb.
Has no action unless \fI\-\-format\fR is given.
.TP
\fB\-S\fR, \fB\-\-security\fR
sets the "Security Initialization" (SI) bit in the FORMAT UNIT command's
initialization pattern descriptor within the parameter list. According
to SBC\-3 the default initialization pattern "shall be written using a
security erasure write technique". The SI bit is found in SBC (1998)
and SBC\-2 (2005) so vendors should support it. SATA and parallel ATA
disks have a separate command called SECURITY ERASE UNIT to perform this
action. Recent versions of the hdparm utility can execute that ATA command.
.TP
\fB\-6\fR, \fB\-\-six\fR
Use 6 byte variants of MODE SENSE and MODE SELECT. The default action
is to use the 10 byte variants. Some MO drives need this option set
when doing a format.
.TP
\fB\-s\fR, \fB\-\-size\fR=\fISIZE\fR
where \fISIZE\fR is the 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 \fI\-\-format\fR 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 UNIT 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).
.TP
\fB\-v\fR, \fB\-\-verbose\fR
increase the level of verbosity, (i.e. debug output). "\-vvv" gives
the maximum debug output.
.TP
\fB\-V\fR, \fB\-\-version\fR
print the version string and then exit.
.TP
\fB\-w\fR, \fB\-\-wait\fR
this option only has an effect when used together with the \fI\-\-format\fR
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. \fI\-\-wait\fR)
is given then the "IMMED" bit is not set. If \fI\-\-wait\fR is given 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.
.SH LISTS
The SBC\-3 draft (revision 18) defines PLIST, CLIST, DLIST and GLIST in
section 4.10 on "Medium defects". Briefly, the PLIST is the "primary"
list of manufacturer detected defects, the CLIST ("certification" list)
contains those detected during the format operation, the DLIST is a list of
defects that can be given to the format operation. The GLIST is the grown
list which starts in the format process as CLIST+DLIST and can "grow" later
due to automatic reallocation (see the ARRE and AWRE bits in the
read\-write error recovery mode page (see sdparm(8))) and use of the
SCSI REASSIGN BLOCKS command (see sg_reassign(8)).
.PP
The CMPLST bit (controlled by the \fI\-\-cmplst=\fR0|1 option) determines
whether the existing GLIST, when the format operation is invoked,
is taken into account. The sg_format utility sets the FOV bit to zero
which causes DPRY=0, so the PLIST is taken into account, and DCRT=0, so
the CLIST is generated and used during the format process.
.PP
The sg_format utility does not permit a user to provide a defect
list (i.e. DLIST).
.SH NOTES
The SBC\-2 standard states that the REQUEST SENSE command should be used
for obtaining a progress indication when the format command is underway.
However, tests on a selection of recent disks shows that TEST UNIT READY
commands yield progress indications (but not REQUEST SENSE commands). So
the current version of this utility uses TEST UNIT READY commands to
poll the disk to find out the progress of the format. A new option may be
required to handle this when disks catch up.
.PP
When the \fI\-\-format\fR option is given without the \fI\-\-wait\fR option
then the SCSI FORMAT UNIT command is issued with the IMMED bit set which
causes the SCSI command to return after it has started the format operation.
The \fI\-\-early\fR option will cause sg_format to exit at that point.
Otherwise the \fIDEVICE\fR 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 process can be
terminated (e.g. with control\-C) without affecting the format operation
which continues. However a bus or device reset (or a power cycle) will
probably cause the device to become "format corrupt".
.PP
When the \fI\-\-format\fR and \fI\-\-wait\fR 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 some format operations). 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.
.PP
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.
.PP
The 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 \fI\-\-count=\fR\-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.
.PP
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.
.PP
Other utilities may be useful in finding information associated with
formatting. These include sg_inq(8) 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(8) utility can be
used to access and potentially change the now obsolete format mode page.
.PP
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.
.PP
The \fICOUNT\fR numeric argument may include a multiplicative suffix or be
given in hexadecimal. See the "NUMERIC ARGUMENTS" section in the
sg3_utils(8) man page.
.SH EXAMPLES
In the first example below simply find 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. No changes
are made:
.PP
   sg_format /dev/sdm
.PP
Now a simple format, leaving the block count and size as they were previously.
The FORMAT UNIT command is executed in IMMED mode and the device is polled
every 30 seconds to print out a progress indication:
.PP
   sg_format \-\-format /dev/sdm
.PP
Now the same format, but waiting (passively) until the format operation is
complete:
.PP
   sg_format \-\-format \-\-wait /dev/sdm
.PP
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:
.PP
   sg_format \-\-format \-\-size=520 /dev/sdm
.PP
Now a resize operation so that only the first 0x10000 (65536) blocks on a disk
are accessible. The remaining blocks remain unaltered.
.PP
   sg_format \-\-resize \-\-count=0x10000 /dev/sdm
.PP
Now resize the disk back to its normal (maximum) block count:
.PP
   sg_format \-\-resize \-\-count=\-1 /dev/sdm
.PP
Format with type 1 protection:
.PP
   sg_format \-\-format \-\-fmtpinfo=3 \-\-pfu /dev/sdm
.PP
.SH EXIT STATUS
The exit status of sg_format is 0 when it is successful. Otherwise see
the sg3_utils(8) man page. Unless the \fI\-\-wait\fR option is given, the
exit status may not reflect the success of otherwise of the format.
Using sg_turs(8) and sg_readcap(8) after the format operation may be wise.
.SH AUTHORS
Written by Grant Grundler, James Bottomley and Douglas Gilbert.
.SH "REPORTING BUGS"
Report bugs to <dgilbert at interlog dot com>.
.SH COPYRIGHT
Copyright \(co 2005\-2009 Grant Grundler, James Bottomley and Douglas Gilbert
.br
This software is distributed under the GPL version 2. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.SH "SEE ALSO"
.B sg_turs(8), sg_requests(8), sg_inq(8), sg_modes(8), sg_vpd(8),
.B sg_reassign(8), sg_readcap(8) [all in sg3_utils], sdparm(8),
.B scsiformat (old), hdparm(8)