sg_sanitize+sg_format: add --timeout=SEC option; sg_reassign+sg_write_same: fix ULONG_MAX problem

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

1 files changed, 31 insertions, 17 deletions

diff --git a/doc/sg_format.8 b/doc/sg_format.8
index 2e8cda2d..679e007f 100644
--- a/doc/sg_format.8
+++ b/doc/sg_format.8
@@ -1,4 +1,4 @@
-.TH SG_FORMAT "8" "February 2016" "sg3_utils\-1.42" SG3_UTILS
+.TH SG_FORMAT "8" "February 2016" "sg3_utils\-1.43" SG3_UTILS
 .SH NAME
 sg_format \- format, resize a SCSI disk or format a tape
 .SH SYNOPSIS
@@ -9,7 +9,8 @@ sg_format \- format, resize a SCSI disk or format a tape
 [\fI\-\-mode=MP\fR] [\fI\-\-pfu=PFU\fR] [\fI\-\-pie=PIE\fR] [\fI\-\-pinfo\fR]
 [\fI\-\-poll=PT\fR] [\fI\-\-resize\fR] [\fI\-\-rto_req\fR]
 [\fI\-\-security\fR] [\fI\-\-six\fR] [\fI\-\-size=SIZE\fR] [\fI\-\-tape=FM\fR]
-[\fI\-\-verbose\fR] [\fI\-\-verify\fR] [\fI\-\-version\fR] [\fI\-\-wait\fR]
+[\fI\-\-timeout=SEC\fR] [\fI\-\-verbose\fR] [\fI\-\-verify\fR]
+[\fI\-\-version\fR] [\fI\-\-wait\fR]
 \fIDEVICE\fR
 .SH DESCRIPTION
 .\" Add any additional description here
@@ -266,6 +267,18 @@ set to \fIFM\fR. This option is used to prepare a tape (i.e. the "medium")
 in a tape drive for use. Values for \fIFM\fR include 0 to do the "default"
 format; 1 to partition a volume and 2 to do a default format then partition.
 .TP
+\fB\-m\fR, \fB\-\-timeout\fR=\fISEC\fR
+where \fISEC\fR is the FORMAT UNIT or FORMAT MEDIUM command timeout in
+seconds. \fISEC\fR will only be used if it exceeds the internal timeout
+which is 20 seconds if the IMMED bit is set and 72000 seconds (20 hours)
+if the IMMED bit is not set. If the timeout is exceeded then the
+operating system will typically abort the command. Aborting a command
+may escalate to a LUN reset (or worse). A timeout may also leave
+the disk or tape format operation incomplete. And that may result in the
+disk or tape being in a "format corrupt" state requiring another format
+to remedy the situation. So for various reasons timeouts are best
+avoided.
+.TP
 \fB\-v\fR, \fB\-\-verbose\fR
 increase the level of verbosity, (i.e. debug output). "\-vvv" gives
 a lot more debug output.
@@ -280,12 +293,10 @@ print the version string and then exit.
 \fB\-w\fR, \fB\-\-wait\fR
 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 many hours on large disks. This
-utility sets a 15 hour timeout on such a FORMAT UNIT command! Some recent
-SSDs go to the other extreme of completing a format operation in 1.5
-seconds hence waiting is not an issue.
+given then the "IMMED" bit is not set. If \fI\-\-wait\fR is given then the
+FORMAT UNIT or FORMAT MEDIUM command waits until the format operation
+completes before returning its response. This can be many hours on large
+disks. See the \fI\-\-timeout=SEC\fR option.
 .SH LISTS
 The SBC\-3 draft (revision 36) defines PLIST, CLIST, DLIST and GLIST in
 section 4.13 on "Medium defects". Briefly, the PLIST is the "primary"
@@ -381,15 +392,18 @@ can be terminated (e.g. with control\-C) without affecting the format
 operation which continues. However a target 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 15 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.
+When the \fI\-\-format\fR (or \fI\-\-tape\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 20 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. Modern SCSI devices should yield a "not ready" sense key
+with an additional sense indicating a format is in progress. With older
+devices the user should take precautions that nothing attempts to access
+a device while it is being formatted.
 .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