1.12 Move error-stack text to top of usage display #1564 (#1566)

6 files changed, 52 insertions, 31 deletions

diff --git a/tools/src/h5copy/h5copy.c b/tools/src/h5copy/h5copy.c
index 933e230..fc210cc 100644
--- a/tools/src/h5copy/h5copy.c
+++ b/tools/src/h5copy/h5copy.c
@@ -19,7 +19,7 @@
 #define PROGRAMNAME "h5copy"
 
 /* command-line options: short and long-named parameters */
-static const char *        s_opts    = "d:f:hi:o:ps:vVE";
+static const char *        s_opts    = "d:f:hi:o:ps:vVE*";
 static struct long_options l_opts[]  = {{"destination", require_arg, 'd'},
                                        {"flag", require_arg, 'f'},
                                        {"help", no_arg, 'h'},
@@ -29,7 +29,7 @@ static struct long_options l_opts[]  = {{"destination", require_arg, 'd'},
                                        {"source", require_arg, 's'},
                                        {"verbose", no_arg, 'v'},
                                        {"version", no_arg, 'V'},
-                                       {"enable-error-stack", no_arg, 'E'},
+                                       {"enable-error-stack", optional_arg, 'E'},
                                        {NULL, 0, '\0'}};
 char *                     fname_src = NULL;
 char *                     fname_dst = NULL;
@@ -93,15 +93,17 @@ usage(void)
     PRINTVALSTREAM(rawoutstream, "      -o, --output       output file name\n");
     PRINTVALSTREAM(rawoutstream, "      -s, --source       source object name\n");
     PRINTVALSTREAM(rawoutstream, "      -d, --destination  destination object name\n");
+    PRINTVALSTREAM(rawoutstream, "   ERROR\n");
+    PRINTVALSTREAM(rawoutstream,
+                   "     --enable-error-stack Prints messages from the HDF5 error stack as they occur.\n");
+    PRINTVALSTREAM(rawoutstream,
+                   "                          Optional value 2 also prints file open errors.\n");
     PRINTVALSTREAM(rawoutstream, "   OPTIONS\n");
     PRINTVALSTREAM(rawoutstream, "      -h, --help         Print a usage message and exit\n");
     PRINTVALSTREAM(rawoutstream,
                    "      -p, --parents      No error if existing, make parent groups as needed\n");
     PRINTVALSTREAM(rawoutstream, "      -v, --verbose      Print information about OBJECTS and OPTIONS\n");
     PRINTVALSTREAM(rawoutstream, "      -V, --version      Print version number and exit\n");
-    PRINTVALSTREAM(rawoutstream, "      --enable-error-stack\n");
-    PRINTVALSTREAM(rawoutstream,
-                   "                  Prints messages from the HDF5 error stack as they occur.\n");
     PRINTVALSTREAM(rawoutstream, "      -f, --flag         Flag type\n\n");
     PRINTVALSTREAM(rawoutstream, "      Flag type is one of the following strings:\n\n");
     PRINTVALSTREAM(rawoutstream, "      shallow     Copy only immediate members for groups\n\n");
@@ -288,7 +290,10 @@ main(int argc, char *argv[])
                 break;
 
             case 'E':
-                enable_error_stack = 1;
+                if (opt_arg != NULL)
+                    enable_error_stack = HDatoi(opt_arg);
+                else
+                    enable_error_stack = 1;
                 break;
 
             default:
diff --git a/tools/src/h5diff/h5diff_common.c b/tools/src/h5diff/h5diff_common.c
index 53ece8b..c032b7a 100644
--- a/tools/src/h5diff/h5diff_common.c
+++ b/tools/src/h5diff/h5diff_common.c
@@ -25,7 +25,7 @@ static int check_d_input(const char *);
  * Command-line options: The user can specify short or long-named
  * parameters.
  */
-static const char *        s_opts   = "hVrv*qn:d:p:NcelxE:A:S";
+static const char *        s_opts   = "hVrv*qn:d:p:NcelxE:A:S*";
 static struct long_options l_opts[] = {{"help", no_arg, 'h'},
                                        {"version", no_arg, 'V'},
                                        {"report", no_arg, 'r'},
@@ -41,7 +41,7 @@ static struct long_options l_opts[] = {{"help", no_arg, 'h'},
                                        {"no-dangling-links", no_arg, 'x'},
                                        {"exclude-path", require_arg, 'E'},
                                        {"exclude-attribute", require_arg, 'A'},
-                                       {"enable-error-stack", no_arg, 'S'},
+                                       {"enable-error-stack", optional_arg, 'S'},
                                        {"vol-value-1", require_arg, '1'},
                                        {"vol-name-1", require_arg, '2'},
                                        {"vol-info-1", require_arg, '3'},
@@ -294,7 +294,10 @@ parse_command_line(int argc, const char *const *argv, const char **fname1, const
                 break;
 
             case 'S':
-                enable_error_stack = 1;
+                if (opt_arg != NULL)
+                    enable_error_stack = HDatoi(opt_arg);
+                else
+                    enable_error_stack = 1;
                 break;
 
             case 'E':
@@ -614,6 +617,10 @@ usage(void)
     PRINTVALSTREAM(rawoutstream, "  [obj1]            Name of an HDF5 object, in absolute path\n");
     PRINTVALSTREAM(rawoutstream, "  [obj2]            Name of an HDF5 object, in absolute path\n");
     PRINTVALSTREAM(rawoutstream, "\n");
+    PRINTVALSTREAM(rawoutstream, "  ERROR\n");
+    PRINTVALSTREAM(rawoutstream,
+                   "   --enable-error-stack Prints messages from the HDF5 error stack as they occur.\n");
+    PRINTVALSTREAM(rawoutstream, "                        Optional value 2 also prints file open errors.\n");
     PRINTVALSTREAM(rawoutstream, "  OPTIONS\n");
     PRINTVALSTREAM(rawoutstream, "   -h, --help\n");
     PRINTVALSTREAM(rawoutstream, "         Print a usage message and exit.\n");
@@ -636,9 +643,6 @@ usage(void)
     PRINTVALSTREAM(rawoutstream, "          3 : All level 2 information plus file names.\n");
     PRINTVALSTREAM(rawoutstream, "   -q, --quiet\n");
     PRINTVALSTREAM(rawoutstream, "         Quiet mode. Do not produce output.\n");
-    PRINTVALSTREAM(rawoutstream, "   --enable-error-stack\n");
-    PRINTVALSTREAM(rawoutstream,
-                   "                   Prints messages from the HDF5 error stack as they occur.\n");
     PRINTVALSTREAM(rawoutstream,
                    "   --vol-value-1           Value (ID) of the VOL connector to use for opening the\n");
     PRINTVALSTREAM(rawoutstream, "                           first HDF5 file specified\n");
@@ -778,7 +782,7 @@ usage(void)
     PRINTVALSTREAM(rawoutstream, "\n");
     PRINTVALSTREAM(rawoutstream, " Modes of output:\n");
     PRINTVALSTREAM(rawoutstream,
-                   "  Default mode: print the number of differences found and where they occured\n");
+                   "  Default mode: print the number of differences found and where they occurred\n");
     PRINTVALSTREAM(rawoutstream, "  -r Report mode: print the above plus the differences\n");
     PRINTVALSTREAM(rawoutstream, "  -v Verbose mode: print the above plus a list of objects and warnings\n");
     PRINTVALSTREAM(rawoutstream, "  -q Quiet mode: do not print output\n");
diff --git a/tools/src/h5dump/h5dump.c b/tools/src/h5dump/h5dump.c
index 420bbc7..7c7a845 100644
--- a/tools/src/h5dump/h5dump.c
+++ b/tools/src/h5dump/h5dump.c
@@ -161,6 +161,12 @@ usage(const char *prog)
     PRINTVALSTREAM(rawoutstream, "  OPTIONS\n");
     PRINTVALSTREAM(rawoutstream, "     -h,   --help         Print a usage message and exit\n");
     PRINTVALSTREAM(rawoutstream, "     -V,   --version      Print version number and exit\n");
+    PRINTVALSTREAM(rawoutstream, "--------------- Error Options ---------------\n");
+    PRINTVALSTREAM(rawoutstream,
+                   "     --enable-error-stack Prints messages from the HDF5 error stack as they occur.\n");
+    PRINTVALSTREAM(rawoutstream,
+                   "                          Optional value 2 also prints file open errors.\n");
+    PRINTVALSTREAM(rawoutstream, "                          Default setting disables any error reporting.\n");
     PRINTVALSTREAM(rawoutstream, "--------------- File Options ---------------\n");
     PRINTVALSTREAM(rawoutstream, "     -n,   --contents     Print a list of the file contents and exit\n");
     PRINTVALSTREAM(rawoutstream, "                          Optional value 1 also prints attributes.\n");
@@ -242,10 +248,6 @@ usage(const char *prog)
     PRINTVALSTREAM(rawoutstream, "     -q Q, --sort_by=Q    Sort groups and attributes by index Q\n");
     PRINTVALSTREAM(rawoutstream, "     -z Z, --sort_order=Z Sort groups and attributes by order Z\n");
     PRINTVALSTREAM(rawoutstream,
-                   "     --enable-error-stack Prints messages from the HDF5 error stack as they occur.\n");
-    PRINTVALSTREAM(rawoutstream,
-                   "                          Optional value 2 also prints file open errors.\n");
-    PRINTVALSTREAM(rawoutstream,
                    "     --no-compact-subset  Disable compact form of subsetting and allow the use\n");
     PRINTVALSTREAM(rawoutstream, "                          of \"[\" in dataset names.\n");
     PRINTVALSTREAM(rawoutstream,
diff --git a/tools/src/h5ls/h5ls.c b/tools/src/h5ls/h5ls.c
index 6f65909..1ccf8b2 100644
--- a/tools/src/h5ls/h5ls.c
+++ b/tools/src/h5ls/h5ls.c
@@ -2520,7 +2520,7 @@ done:
  *              were borrowed from the GNU less(1).
  *
  * Return:      Success: Number of columns.
- *              Failure: Some default number of columms.
+ *              Failure: Some default number of columns.
  *-------------------------------------------------------------------------
  */
 static int
@@ -2684,7 +2684,7 @@ main(int argc, char *argv[])
     /* Initialize h5tools lib */
     h5tools_init();
 
-    /* Initialize fapl info struct */
+    /* Initialize fapl info structs */
     HDmemset(&vol_info, 0, sizeof(h5tools_vol_info_t));
 
     /* Build object display table */
@@ -2714,9 +2714,9 @@ main(int argc, char *argv[])
         }
         else if (!HDstrcmp(argv[argno], "--enable-error-stack")) {
             enable_error_stack = 1;
-            /* deprecated --errors */
         }
         else if (!HDstrcmp(argv[argno], "--errors")) {
+            /* deprecated --errors */
             enable_error_stack = 1;
         }
         else if (!HDstrcmp(argv[argno], "--follow-symlinks")) {
diff --git a/tools/src/h5repack/h5repack_main.c b/tools/src/h5repack/h5repack_main.c
index c83f8cc..29af231 100644
--- a/tools/src/h5repack/h5repack_main.c
+++ b/tools/src/h5repack/h5repack_main.c
@@ -31,7 +31,7 @@ const char *outfile = NULL;
  * Command-line options: The user can specify short or long-named
  * parameters.
  */
-static const char *        s_opts   = "a:b:c:d:e:f:hi:j:k:l:m:no:q:s:t:u:vz:EG:LM:P:S:T:VXW";
+static const char *        s_opts   = "a:b:c:d:e:f:hi:j:k:l:m:no:q:s:t:u:vz:E*G:LM:P:S:T:VXW";
 static struct long_options l_opts[] = {{"alignment", require_arg, 'a'},
                                        {"block", require_arg, 'b'},
                                        {"compact", require_arg, 'c'},
@@ -52,7 +52,7 @@ static struct long_options l_opts[] = {{"alignment", require_arg, 'a'},
                                        {"ublock", require_arg, 'u'},
                                        {"verbose", no_arg, 'v'},
                                        {"sort_order", require_arg, 'z'},
-                                       {"enable-error-stack", no_arg, 'E'},
+                                       {"enable-error-stack", optional_arg, 'E'},
                                        {"fs_pagesize", require_arg, 'G'},
                                        {"latest", no_arg, 'L'},
                                        {"metadata_block_size", require_arg, 'M'},
@@ -86,15 +86,17 @@ usage(const char *prog)
     PRINTSTREAM(rawoutstream, "usage: %s [OPTIONS] file1 file2\n", prog);
     PRINTVALSTREAM(rawoutstream, "  file1                    Input HDF5 File\n");
     PRINTVALSTREAM(rawoutstream, "  file2                    Output HDF5 File\n");
+    PRINTVALSTREAM(rawoutstream, "  ERROR\n");
+    PRINTVALSTREAM(rawoutstream,
+                   "   --enable-error-stack    Prints messages from the HDF5 error stack as they occur.\n");
+    PRINTVALSTREAM(rawoutstream,
+                   "                           Optional value 2 also prints file open errors.\n");
     PRINTVALSTREAM(rawoutstream, "  OPTIONS\n");
     PRINTVALSTREAM(rawoutstream, "   -h, --help              Print a usage message and exit\n");
     PRINTVALSTREAM(rawoutstream, "   -v, --verbose           Verbose mode, print object information\n");
     PRINTVALSTREAM(rawoutstream, "   -V, --version           Print version number and exit\n");
     PRINTVALSTREAM(rawoutstream, "   -n, --native            Use a native HDF5 type when repacking\n");
     PRINTVALSTREAM(rawoutstream,
-                   "   --enable-error-stack    Prints messages from the HDF5 error stack as they\n");
-    PRINTVALSTREAM(rawoutstream, "                           occur\n");
-    PRINTVALSTREAM(rawoutstream,
                    "   --src-vol-value         Value (ID) of the VOL connector to use for opening the\n");
     PRINTVALSTREAM(rawoutstream, "                           input HDF5 file specified\n");
     PRINTVALSTREAM(rawoutstream,
@@ -735,7 +737,10 @@ parse_command_line(int argc, const char *const *argv, pack_opt_t *options)
                 break;
 
             case 'E':
-                enable_error_stack = 1;
+                if (opt_arg != NULL)
+                    enable_error_stack = HDatoi(opt_arg);
+                else
+                    enable_error_stack = 1;
                 break;
 
             case '1':
diff --git a/tools/src/h5stat/h5stat.c b/tools/src/h5stat/h5stat.c
index 81acb89..fd485e7 100644
--- a/tools/src/h5stat/h5stat.c
+++ b/tools/src/h5stat/h5stat.c
@@ -169,7 +169,7 @@ struct handler_t {
     char **obj;
 };
 
-static const char *s_opts = "Aa:Ddm:EFfhGgl:sSTO:Vw:H:";
+static const char *s_opts = "Aa:Ddm:E*FfhGgl:sSTO:Vw:H:";
 /* e.g. "filemetadata" has to precede "file"; "groupmetadata" has to precede "group" etc. */
 static struct long_options l_opts[] = {{"help", no_arg, 'h'},
                                        {"filemetadata", no_arg, 'F'},
@@ -181,7 +181,7 @@ static struct long_options l_opts[] = {{"help", no_arg, 'h'},
                                        {"object", require_arg, 'O'},
                                        {"version", no_arg, 'V'},
                                        {"attribute", no_arg, 'A'},
-                                       {"enable-error-stack", no_arg, 'E'},
+                                       {"enable-error-stack", optional_arg, 'E'},
                                        {"numattrs", require_arg, 'a'},
                                        {"freespace", no_arg, 's'},
                                        {"summary", no_arg, 'S'},
@@ -211,6 +211,9 @@ usage(const char *prog)
     HDfflush(stdout);
     HDfprintf(stdout, "Usage: %s [OPTIONS] file\n", prog);
     HDfprintf(stdout, "\n");
+    HDfprintf(stdout, "      ERROR\n");
+    HDfprintf(stdout, "     --enable-error-stack  Prints messages from the HDF5 error stack as they occur\n");
+    HDfprintf(stdout, "                           Optional value 2 also prints file open errors\n");
     HDfprintf(stdout, "      OPTIONS\n");
     HDfprintf(stdout, "     -h, --help            Print a usage message and exit\n");
     HDfprintf(stdout, "     -V, --version         Print version number and exit\n");
@@ -235,7 +238,6 @@ usage(const char *prog)
     HDfprintf(stdout, "                           than 0.  The default threshold is 10.\n");
     HDfprintf(stdout, "     -s, --freespace       Print free space information\n");
     HDfprintf(stdout, "     -S, --summary         Print summary of file space information\n");
-    HDfprintf(stdout, "     --enable-error-stack  Prints messages from the HDF5 error stack as they occur\n");
     HDfprintf(stdout, "     --s3-cred=<cred>      Access file on S3, using provided credential\n");
     HDfprintf(stdout, "                           <cred> :: (region,id,key)\n");
     HDfprintf(stdout, "                           If <cred> == \"(,,)\", no authentication is used.\n");
@@ -852,7 +854,10 @@ parse_command_line(int argc, const char *const *argv, struct handler_t **hand_re
                 break;
 
             case 'E':
-                enable_error_stack = 1;
+                if (opt_arg != NULL)
+                    enable_error_stack = HDatoi(opt_arg);
+                else
+                    enable_error_stack = 1;
                 break;
 
             case 'F':
@@ -1752,7 +1757,7 @@ main(int argc, char *argv[])
             warn_msg("Unable to retrieve file size\n");
         HDassert(iter.filesize != 0);
 
-        /* Get storge info for file-level structures */
+        /* Get storage info for file-level structures */
         if (H5Fget_info2(fid, &finfo) < 0)
             warn_msg("Unable to retrieve file info\n");
         else {