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

git-svn-id: svn://localhost/trunk@680 6180dd3e-e324-4e3e-922d-17de1ae2f315

Author: doug-gilbert

ChangeLog

@@ -2,8 +2,13 @@ Each utility has its own version number, date of last change and
 some description at the top of its ".c" file. All utilities in the main
 directory have their own "man" pages. There is also a sg3_utils man page.
 
-Changelog for sg3_utils-1.43 [20160224] [svn: r679]
+Changelog for sg3_utils-1.43 [20160226] [svn: r680]
   - sg_senddiag: add --timeout=SEC option
+  - sg_sanitize: add --timeout=SEC option
+  - sg_format: add --timeout=SEC option
+  - sg_reassign+sg_write_same: fix ULONG_MAX problem
+  - sg_turs+sg_requests: make both accept '--num=NUM'
+    and '--number=NUM' for mutual compatibility
   - shellcheck cleanup on scripts
 
 Changelog for sg3_utils-1.42 [20160217] [svn: r663]

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

doc/sg_requests.8

@@ -1,11 +1,12 @@
-.TH SG_REQUESTS "8" "May 2014" "sg3_utils\-1.39" SG3_UTILS
+.TH SG_REQUESTS "8" "February 2016" "sg3_utils\-1.43" SG3_UTILS
 .SH NAME
 sg_requests \- send one or more SCSI REQUEST SENSE commands
 .SH SYNOPSIS
 .B sg_requests
 [\fI\-\-desc\fR] [\fI\-\-help\fR] [\fI\-\-hex\fR] [\fI\-\-maxlen=LEN\fR]
-[\fI\-\-num=NUM\fR] [\fI\-\-progress\fR] [\fI\-\-raw\fR] [\fI\-\-status\fR]
-[\fI\-\-time\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR] \fIDEVICE\fR
+[\fI\-\-num=NUM\fR] [\fI\-\-number=NUM\fR] [\fI\-\-progress\fR]
+[\fI\-\-raw\fR] [\fI\-\-status\fR] [\fI\-\-time\fR] [\fI\-\-verbose\fR]
+[\fI\-\-version\fR] \fIDEVICE\fR
 .SH DESCRIPTION
 .\" Add any additional description here
 .PP
@@ -42,6 +43,9 @@ cdb's "allocation length" field. If not given (or \fILEN\fR is zero) then
 perform \fINUM\fR SCSI REQUEST SENSE commands, stopping when either \fINUM\fR
 is reached or an error occurs. The default value for \fINUM\fR is 1 .
 .TP
+\fB\-\-number\fR=\fINUM\fR
+same action as \fI\-\-num=NUM\fR. Added for compatibility with sg_turs.
+.TP
 \fB\-p\fR, \fB\-\-progress\fR
 show progress indication (a percentage) if available. If \fI\-\-number=NUM\fR
 is given, \fINUM\fR is greater than 1 and an initial progress indication
@@ -103,8 +107,8 @@ SBC\-3). Several long duration SCSI commands associated with tape drives also
 use the progress indication (see SSC\-3).
 .PP
 Early standards suggested that the SCSI TEST UNIT READY command be used for
-polling the progress indication. More recent standards seem to suggest
-the SCSI REQUEST SENSE command should be used instead.
+polling the progress indication (see the sg_turs utility). Since SPC\-3 the
+standards suggest that the SCSI REQUEST SENSE command should be used instead.
 .PP
 The \fIDEVICE\fR is opened with a read\-only flag (e.g. in Unix with the
 O_RDONLY flag).
@@ -116,9 +120,9 @@ Written by Douglas Gilbert.
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT
-Copyright \(co 2004\-2014 Douglas Gilbert
+Copyright \(co 2004\-2016 Douglas Gilbert
 .br
 This software is distributed under a FreeBSD license. There is NO
 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 .SH "SEE ALSO"
-.B sg3_utils
+.B sg_turs (sg3_utils)

doc/sg_sanitize.8

@@ -1,4 +1,4 @@
-.TH SG_SANITIZE "8" "November 2015" "sg3_utils\-1.42" SG3_UTILS
+.TH SG_SANITIZE "8" "February 2016" "sg3_utils\-1.43" SG3_UTILS
 .SH NAME
 sg_sanitize \- remove all user data from disk with SCSI SANITIZE command
 .SH SYNOPSIS
@@ -7,8 +7,8 @@ sg_sanitize \- remove all user data from disk with SCSI SANITIZE command
 [\fI\-\-desc\fR] [\fI\-\-early\fR] [\fI\-\-fail\fR] [\fI\-\-help\fR]
 [\fI\-\-invert\fR] [\fI\-\-ipl=LEN\fR] [\fI\-\-overwrite\fR]
 [\fI\-\-pattern=PF\fR] [\fI\-\-quick\fR] [\fI\-\-test=TE\fR]
-[\fI\-\-verbose\fR] [\fI\-\-version\fR] [\fI\-\-wait\fR] [\fI\-\-zero\fR]
-[\fI\-\-znr\fR] \fIDEVICE\fR
+[\fI\-\-timeout=SEC\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR]
+[\fI\-\-wait\fR] [\fI\-\-zero\fR] [\fI\-\-znr\fR] \fIDEVICE\fR
 .SH DESCRIPTION
 .\" Add any additional description here
 .PP
@@ -36,7 +36,7 @@ in case the wrong \fIDEVICE\fR has been given.
 If the \fI\-\-early\fR option is given then this utility will exit soon
 after starting the SANITIZE command with the IMMED bit set. The user can
 monitor the progress of the sanitize operation with
-the "sg_request \-\-num=9999 \-\-progress" which sends a REQUEST SENSE
+the "sg_requests \-\-num=9999 \-\-progress" which sends a REQUEST SENSE
 command every 30 seconds. Otherwise if the \fI\-\-wait\fR option is given
 then this utility will wait until the SANITIZE command completes (or fails)
 and that can be many hours.
@@ -124,6 +124,10 @@ set the TEST field in the overwrite service action parameter list. This
 only affects the "overwrite" sanitize operation. The default is to place
 0 in that field.
 .TP
+\fB\-t\fR, \fB\-\-timeout\fR=\fISEC\fR
+where \fISEC\fR is the number of seconds used for the timeout on the
+SANITIZE command.
+.TP
 \fB\-v\fR, \fB\-\-verbose\fR
 increase the level of verbosity, (i.e. debug output).
 .TP
@@ -230,7 +234,7 @@ Written by Douglas Gilbert.
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT
-Copyright \(co 2011\-2015 Douglas Gilbert
+Copyright \(co 2011\-2016 Douglas Gilbert
 .br
 This software is distributed under a FreeBSD license. There is NO
 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

doc/sg_sync.8

@@ -1,11 +1,11 @@
-.TH SG_SYNC "8" "July 2013" "sg3_utils\-1.37" SG3_UTILS
+.TH SG_SYNC "8" "February 2016" "sg3_utils\-1.43" SG3_UTILS
 .SH NAME
 sg_sync \- send SCSI SYNCHRONIZE CACHE command
 .SH SYNOPSIS
 .B sg_sync
 [\fI\-\-16\fR] [\fI\-\-count=COUNT\fR] [\fI\-\-group=GN\fR]
 [\fI\-\-help\fR] [\fI\-\-immed\fR] [\fI\-\-lba=LBA\fR] [\fI\-\-sync\-nv\fR]
-[\fI\-\-timeout=SECS\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR] \fIDEVICE\fR
+[\fI\-\-timeout=SEC\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR] \fIDEVICE\fR
 .SH DESCRIPTION
 .\" Add any additional description here
 .PP
@@ -58,8 +58,8 @@ option (or if there is no non\-volatile cache in the device) the
 synchronization is with the medium. The SYNC_NV bit was made obsolete in
 SBC\-3 revision 35d.
 .TP
-\fB\-t\fR, \fB\-\-timeout\fR=\fISECS\fR
-where \fISECS\fR is the number of seconds the OS allows the SYNCHRONIZE
+\fB\-t\fR, \fB\-\-timeout\fR=\fISEC\fR
+where \fISEC\fR is the number of seconds the OS allows the SYNCHRONIZE
 CACHE(16) to complete before it tries to cancel the command. Cancelling
 commands (typically with the task management function "abort task") is
 best avoided. Note this option is only active together with the \fI\-\-16\fR
@@ -89,7 +89,7 @@ Written by Douglas Gilbert.
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT
-Copyright \(co 2004\-2013 Douglas Gilbert
+Copyright \(co 2004\-2016 Douglas Gilbert
 .br
 This software is distributed under a FreeBSD license. There is NO
 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

doc/sg_turs.8

@@ -1,10 +1,11 @@
-.TH SG_TURS "8" "May 2014" "sg3_utils\-1.39" SG3_UTILS
+.TH SG_TURS "8" "Fenruary 2016" "sg3_utils\-1.43" SG3_UTILS
 .SH NAME
 sg_turs \- send one or more SCSI TEST UNIT READY commands
 .SH SYNOPSIS
 .B sg_turs
-[\fI\-\-help\fR] [\fI\-\-number=NUM\fR] [\fI\-\-progress\fR] [\fI\-\-time\fR]
-[\fI\-\-verbose\fR] [\fI\-\-version\fR] \fIDEVICE\fR
+[\fI\-\-help\fR] [\fI\-\-number=NUM\fR] [\fI\-\-num=NUM\fR]
+[\fI\-\-progress\fR] [\fI\-\-time\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR]
+\fIDEVICE\fR
 .PP
 .B sg_turs
 [\fI\-n=NUM\fR] [\fI\-p\fR]  [\fI\-t\fR] [\fI\-v\fR] [\fI\-V\fR]
@@ -34,6 +35,10 @@ g G GiB *1,073,741,824; and GB *1,000,000,000 . Also a suffix of the
 form "x<n>" multiplies the leading number by <n>. Alternatively a hex
 number may be given, prefixed by either '0x' or has a trailing 'h'.
 .TP
+\fB\-\-num\fR=\fINUM\fR
+same as \fI\-\-number=NUM\fR. Added for compatibility with sg_requests
+which has taken over the role of polling the progress indication.
+.TP
 \fB\-O\fR, \fB\-\-old\fR
 switch to older style options.
 .TP
@@ -57,7 +62,9 @@ print version string then exit.
 The progress indication is optionally part of the sense data. When a prior
 command that takes a long time to complete (and typically precludes other
 media access commands) is still underway, the progress indication can be used
-to determine how long before the device returns to its normal state.
+to determine how long before the device returns to its normal state. Around
+SPC\-3 T10 changed the preferred command for polling the progress indication
+from TEST UNIT READY to REQUEST SENSE (see the sg_requests utilty).
 .PP
 The SCSI FORMAT command for disks used with the IMMED bit set is an example
 of an operation that takes a significant amount of time and precludes other
@@ -108,9 +115,9 @@ print out version string then exit.
 .SH AUTHORS
 Written by D. Gilbert
 .SH COPYRIGHT
-Copyright \(co 2000\-2014 Douglas Gilbert
+Copyright \(co 2000\-2016 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_inq, sg_request (sg3_utils)
+.B sg_inq, sg_requests (sg3_utils)

lib/sg_cmds_extra.c

@@ -354,7 +354,7 @@ sg_ll_report_referrals(int sg_fd, uint64_t start_llba, int one_seg,
 }
 
 /* Invokes a SCSI SEND DIAGNOSTIC command. Foreground, extended self tests can
- * take a long time, if so set long_duration flag in which case the timout
+ * take a long time, if so set long_duration flag in which case the timeout
  * is set to 7200 seconds; if the value of long_duration is > 7200 then that
  * value is taken as the timeout value in seconds. Return of 0 -> success,
  * various SG_LIB_CAT_* positive values or -1 -> other errors */
@@ -372,21 +372,24 @@ sg_ll_send_diag(int sg_fd, int sf_code, int pf_bit, int sf_bit, int devofl_bit,
     senddiagCmdBlk[1] = (unsigned char)((sf_code << 5) | (pf_bit << 4) |
                         (sf_bit << 2) | (devofl_bit << 1) | unitofl_bit);
     sg_put_unaligned_be16((uint16_t)param_len, senddiagCmdBlk + 3);
+    if (long_duration > LONG_PT_TIMEOUT)
+        tmout = long_duration;
+    else
+        tmout = long_duration ? LONG_PT_TIMEOUT : DEF_PT_TIMEOUT;
 
     if (verbose) {
         pr2ws("    Send diagnostic cmd: ");
         for (k = 0; k < SEND_DIAGNOSTIC_CMDLEN; ++k)
             pr2ws("%02x ", senddiagCmdBlk[k]);
         pr2ws("\n");
-        if ((verbose > 1) && paramp && param_len) {
-            pr2ws("    Send diagnostic parameter list:\n");
-            dStrHexErr((const char *)paramp, param_len, -1);
+        if (verbose > 1) {
+            if (paramp && param_len) {
+                pr2ws("    Send diagnostic parameter list:\n");
+                dStrHexErr((const char *)paramp, param_len, -1);
+            }
+            pr2ws("    Send diagnostic timeout: %d seconds\n", tmout);
         }
     }
-    if (long_duration > LONG_PT_TIMEOUT)
-        tmout = long_duration;
-    else
-        tmout = long_duration ? LONG_PT_TIMEOUT : DEF_PT_TIMEOUT;
 
     ptvp = construct_scsi_pt_obj();
     if (NULL == ptvp) {
@@ -756,10 +759,13 @@ sg_ll_format_unit2(int sg_fd, int fmtpinfo, int longlist, int fmtdata,
         for (k = 0; k < 6; ++k)
             pr2ws("%02x ", fuCmdBlk[k]);
         pr2ws("\n");
-    }
-    if ((verbose > 1) && (param_len > 0)) {
-        pr2ws("    format parameter list:\n");
-        dStrHexErr((const char *)paramp, param_len, -1);
+        if (verbose > 1) {
+            if (param_len > 0) {
+                pr2ws("    format unit parameter list:\n");
+                dStrHexErr((const char *)paramp, param_len, -1);
+            }
+            pr2ws("    format unit timeout: %d seconds\n", tmout);
+        }
     }
 
     ptvp = construct_scsi_pt_obj();

src/sg_copy_results.c

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011-2015 Hannes Reinecke, SUSE Labs
+ * Copyright (c) 2011-2016 Hannes Reinecke, SUSE Labs
  * All rights reserved.
  * Use of this source code is governed by a BSD-style
  * license that can be found in the BSD_LICENSE file.
@@ -36,7 +36,7 @@
    and the optional list identifier passed as the list_id argument.
 */
 
-static const char * version_str = "1.12 20150227";
+static const char * version_str = "1.13 20160227";
 
 
 #define MAX_XFER_LEN 10000
@@ -408,7 +408,8 @@ main(int argc, char * argv[])
     if (sg_fd < 0) {
         pr2serr(ME "open error: %s: %s\n", device_name,
                 safe_strerror(-sg_fd));
-        return SG_LIB_FILE_ERROR;
+        ret = SG_LIB_FILE_ERROR;
+        goto finish;
     }
 
     if ((sa < 0) || (sa >= (int)(sizeof(rec_copy_name_arr) / sizeof(char *))))