sg_format: improve man page

git-svn-id: https://svn.bingwo.ca/repos/sg3_utils/trunk@223 6180dd3e-e324-4e3e-922d-17de1ae2f315

1 files changed, 38 insertions, 34 deletions

diff --git a/doc/sg_format.8 b/doc/sg_format.8
index 009cecc4..40625fb2 100644
--- a/doc/sg_format.8
+++ b/doc/sg_format.8
@@ -1,4 +1,4 @@
-.TH SG_FORMAT "8" "February 2009" "sg3_utils\-1.27" SG3_UTILS
+.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
@@ -31,15 +31,22 @@ 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 name) it prints
+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).
+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.17 in draft SBC\-3 rev 11). 8 bytes of
+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
@@ -140,13 +147,14 @@ EXAMPLES section for typical use.
 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 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.
+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
@@ -156,7 +164,7 @@ 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 a sets bit 7 of byte 1 in the FORMAT UNIT cdb.
+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
@@ -177,7 +185,7 @@ size.
 .TP
 \fB\-R\fR, \fB\-\-rto_req\fR
 The option is deprecated, use the \fI\-\-fmtpinfo=FPI\fR option instead.
-If used, then a sets bit 6 of byte 1 in the FORMAT UNIT cdb.
+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
@@ -187,7 +195,7 @@ 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 version of the hdparm utility can execute that ATA command.
+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
@@ -218,13 +226,13 @@ print the version string and then exit.
 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 gievn the
+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 11) defines PLIST, CLIST, DLIST and GLIST in
-section 4.9 on "Medium defects". Briefly, the PLIST is the "primary"
+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
@@ -240,8 +248,7 @@ 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). All protection information options are off by
-default.
+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.
@@ -251,21 +258,18 @@ 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 then there is a 10 second window
-during which the user is invited to abort sg_format. This is just prior the
-SCSI FORMAT UNIT command being issued. If the \fI\-\-wait\fR option is not
-given 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) may well cause the device to become "format
-corrupt".
+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