From 744a20fc21be7437bb2449e6b6165702703a1349 Mon Sep 17 00:00:00 2001 From: bmribler <39579120+bmribler@users.noreply.github.com> Date: Mon, 23 Oct 2023 15:46:56 -0400 Subject: Add helpful text to h5clear (#3754) 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. --- 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