From 45c1c875716ab27a7d9fe5f99d16e3353e78c466 Mon Sep 17 00:00:00 2001 From: bmribler <39579120+bmribler@users.noreply.github.com> Date: Mon, 23 Oct 2023 15:47:17 -0400 Subject: Improve the usage of h5clear (#3757) - Added text to the usage of h5clear to explain that this tool is not for fixing corrupted files but simply for helping in the inspection of the damage. - Fixed expected output for testing the modified usage. Fixed GH #3054 --- tools/src/misc/h5clear.c | 11 +++++++++-- tools/test/misc/expected/h5clear_missing_file.ddl | 11 +++++++++-- tools/test/misc/expected/h5clear_usage.ddl | 11 +++++++++-- 3 files changed, 27 insertions(+), 6 deletions(-) diff --git a/tools/src/misc/h5clear.c b/tools/src/misc/h5clear.c index 31f7c17..ea3e072 100644 --- a/tools/src/misc/h5clear.c +++ b/tools/src/misc/h5clear.c @@ -61,6 +61,13 @@ static struct h5_long_options l_opts[] = { static void usage(const char *prog) { + fprintf(stdout, "h5clear clears superblock status flag field, removes metadata cache image, prints\n"); + fprintf(stdout, "EOA and EOF, or sets EOA of a file. It is not a general repair tool and should not\n"); + fprintf(stdout, "be used to fix file corruption. If a process doesn't shut down cleanly, the\n"); + fprintf(stdout, "superblock mark can be left that prevents opening a file without SWMR. Then,\n"); + fprintf(stdout, "h5clear can be used to remove this superblock mark so that the file can be inspected\n"); + fprintf(stdout, "and appropriate actions can be taken.\n"); + fprintf(stdout, "\n"); fprintf(stdout, "usage: %s [OPTIONS] file_name\n", prog); fprintf(stdout, " OPTIONS\n"); fprintf(stdout, " -h, --help Print a usage message and exit\n"); @@ -73,8 +80,8 @@ usage(const char *prog) fprintf(stdout, " C is >= 0; C is optional and will default to 1M when not set.\n"); fprintf(stdout, - " This option helps to repair a crashed file where the stored EOA\n"); - fprintf(stdout, " in the superblock is different from the actual EOF.\n"); + " This option helps to repair a crashed SWMR file when the stored\n"); + fprintf(stdout, " EOA in the superblock is different from the actual EOF.\n"); fprintf(stdout, " The file's EOA and EOF will be the same after applying\n"); fprintf(stdout, " this option to the file.\n"); fprintf(stdout, "\n"); diff --git a/tools/test/misc/expected/h5clear_missing_file.ddl b/tools/test/misc/expected/h5clear_missing_file.ddl index c7a2118..fe659af 100644 --- a/tools/test/misc/expected/h5clear_missing_file.ddl +++ b/tools/test/misc/expected/h5clear_missing_file.ddl @@ -1,3 +1,10 @@ +h5clear clears superblock status flag field, removes metadata cache image, prints +EOA and EOF, or sets EOA of a file. It is not a general repair tool and should not +be used to fix file corruption. If a process doesn't shut down cleanly, the +superblock mark can be left that prevents opening a file without SWMR. Then, +h5clear can be used to remove this superblock mark so that the file can be inspected +and appropriate actions can be taken. + usage: h5clear [OPTIONS] file_name OPTIONS -h, --help Print a usage message and exit @@ -8,8 +15,8 @@ usage: h5clear [OPTIONS] file_name --increment=C Set the file's EOA to the maximum of (EOA, EOF) + C for the file . C is >= 0; C is optional and will default to 1M when not set. - This option helps to repair a crashed file where the stored EOA - in the superblock is different from the actual EOF. + This option helps to repair a crashed SWMR file when the stored + EOA in the superblock is different from the actual EOF. The file's EOA and EOF will be the same after applying this option to the file. diff --git a/tools/test/misc/expected/h5clear_usage.ddl b/tools/test/misc/expected/h5clear_usage.ddl index c7a2118..fe659af 100644 --- a/tools/test/misc/expected/h5clear_usage.ddl +++ b/tools/test/misc/expected/h5clear_usage.ddl @@ -1,3 +1,10 @@ +h5clear clears superblock status flag field, removes metadata cache image, prints +EOA and EOF, or sets EOA of a file. It is not a general repair tool and should not +be used to fix file corruption. If a process doesn't shut down cleanly, the +superblock mark can be left that prevents opening a file without SWMR. Then, +h5clear can be used to remove this superblock mark so that the file can be inspected +and appropriate actions can be taken. + usage: h5clear [OPTIONS] file_name OPTIONS -h, --help Print a usage message and exit @@ -8,8 +15,8 @@ usage: h5clear [OPTIONS] file_name --increment=C Set the file's EOA to the maximum of (EOA, EOF) + C for the file . C is >= 0; C is optional and will default to 1M when not set. - This option helps to repair a crashed file where the stored EOA - in the superblock is different from the actual EOF. + This option helps to repair a crashed SWMR file when the stored + EOA in the superblock is different from the actual EOF. The file's EOA and EOF will be the same after applying this option to the file. -- cgit v0.12