From 1df2bb198244719ea0c68011c5a3c72d9048d36a Mon Sep 17 00:00:00 2001 From: Allen Byrne Date: Fri, 21 Jun 2024 13:08:20 -0500 Subject: [PATCH 01/24] Add doxygen version of tools usage --- doxygen/Doxyfile.in | 1 + doxygen/dox/Tools.dox | 29 ++++ doxygen/dox/UsersGuide.dox | 2 + tools/src/h5copy/h5copy.h | 76 ++++++++++ tools/src/h5diff/h5diff_main.h | 232 +++++++++++++++++++++++++++++ tools/src/h5repack/h5repack.h | 221 +++++++++++++++++++++++++++ tools/test/h5copy/CMakeTests.cmake | 2 +- 7 files changed, 562 insertions(+), 1 deletion(-) create mode 100644 doxygen/dox/Tools.dox create mode 100644 tools/src/h5copy/h5copy.h create mode 100644 tools/src/h5diff/h5diff_main.h diff --git a/doxygen/Doxyfile.in b/doxygen/Doxyfile.in index 29033f5de21..1f95743cf9a 100644 --- a/doxygen/Doxyfile.in +++ b/doxygen/Doxyfile.in @@ -689,6 +689,7 @@ FILE_PATTERNS = H5*public.h H5*module.h H5*develop.h H5FD*.h \ *.F90 \ *.dox \ *.md \ + h5copy.h h5repack.h h5diff_main.h \ H5Cpp.h H5AbstractDs.h H5AtomType.h H5Attribute.h H5CommonFG.h H5CompType.h \ H5DataSet.h H5DataSpace.h H5DataType.h H5OcreatProp.h H5DaccProp.h H5DcreatProp.h \ H5DxferProp.h H5EnumType.h H5Exception.h H5FaccProp.h H5FcreatProp.h H5File.h \ diff --git a/doxygen/dox/Tools.dox b/doxygen/dox/Tools.dox new file mode 100644 index 00000000000..12d2ca1e205 --- /dev/null +++ b/doxygen/dox/Tools.dox @@ -0,0 +1,29 @@ +/** @page CommandTools Command Line Tools for HDF5 Files + +Navigate back: \ref index "Main" +
+ + +\section sec_cltools Command Line Tools for HDF5 Files +There are several command line tools provided with HDF5. +\li \ref sec_cltools_h5copy +\li \ref sec_cltools_h5diff +\li \ref sec_cltools_h5dump +\li \ref sec_cltools_h5format_convert +\li \ref sec_cltools_h5import +\li \ref sec_cltools_h5jam +\li \ref sec_cltools_h5ls +\li \ref sec_cltools_h5repack +\li \ref sec_cltools_h5stat +\li \ref sec_cltools_h5clear +\li \ref sec_cltools_h5debug +\li \ref sec_cltools_h5delete +\li \ref sec_cltools_h5mkgrp +\li \ref sec_cltools_h5repart +\li \ref sec_cltools_h5watch + + +
+Navigate back: \ref index "Main" + +*/ diff --git a/doxygen/dox/UsersGuide.dox b/doxygen/dox/UsersGuide.dox index ca478e41ec2..bf43ff75f71 100644 --- a/doxygen/dox/UsersGuide.dox +++ b/doxygen/dox/UsersGuide.dox @@ -316,6 +316,8 @@ HDF5 Release 1.14 \ref sec_map +\ref sec_cltools + \ref sec_addition \page AR_UG Additional Resources diff --git a/tools/src/h5copy/h5copy.h b/tools/src/h5copy/h5copy.h new file mode 100644 index 00000000000..cefcfb537b6 --- /dev/null +++ b/tools/src/h5copy/h5copy.h @@ -0,0 +1,76 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ + +#ifndef H5COPY_H +#define H5COPY_H + + +/** \page H5TOOL_CP_UG The HDF5 h5copy Tool + * + * \section sec_cltools_h5copy h5copy + * + * \subsection subsec_cltools_h5copy_intro Introduction + * With h5copy you can copy objects from an HDF5 file to another file. + * + * \subsection subsec_cltools_h5repack_usage Usage + *

h5copy [OPTIONS] [OBJECTS...]

+ * + * \subsection subsec_cltools_h5repack_objs Objects + * \li --input input file name + * \li --output output file name + * \li --source source object name + * \li --destination destination object name + + * \subsection subsec_cltools_h5copy_error Error Report Option + * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. + Optional value 2 also prints file open errors. + + * \subsection subsec_cltools_h5copy_options Options + * \li --help Print a usage message and exit + * \li --parents No error if existing, make parent groups as needed + * \li --verbose Print information about OBJECTS and OPTIONS + * \li --version Print version number and exit + * \li --flag Flag type + * + * \subsubsection subsubsec_cltools_h5copy_options_args Flag Type Options + Flag type is one of the following strings: + * \li shallow Copy only immediate members for groups + * \li soft Expand soft links into new objects + * \li ext Expand external links into new objects + * \li ref Copy references and any referenced objects, i.e., objects + that the references point to. + Referenced objects are copied in addition to the objects + specified on the command line and reference datasets are + populated with correct reference values. Copies of referenced + datasets outside the copy range specified on the command line + will normally have a different name from the original. + (Default:Without this option, reference value(s) in any + reference datasets are set to NULL and referenced objects are + not copied unless they are otherwise within the copy range + specified on the command line.) + * \li noattr Copy object without copying attributes + * \li allflags Switches all flags from the default to the non-default setting + + These flag types correspond to the following API symbols + + * \li #H5O_COPY_SHALLOW_HIERARCHY_FLAG + * \li #H5O_COPY_EXPAND_SOFT_LINK_FLAG + * \li #H5O_COPY_EXPAND_EXT_LINK_FLAG + * \li #H5O_COPY_EXPAND_REFERENCE_FLAG + * \li #H5O_COPY_WITHOUT_ATTR_FLAG + * \li #H5O_COPY_ALL + + * + */ + +#endif /* H5COPY_H */ + diff --git a/tools/src/h5diff/h5diff_main.h b/tools/src/h5diff/h5diff_main.h new file mode 100644 index 00000000000..3bb72e2d7d3 --- /dev/null +++ b/tools/src/h5diff/h5diff_main.h @@ -0,0 +1,232 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ + +#ifndef H5DIFF_H +#define H5DIFF_H + + +/** \page H5TOOL_DF_UG The HDF5 h5diff Tool + * + * \section sec_cltools_h5diff h5diff + * + * \subsection subsec_cltools_h5diff_intro Introduction + * With h5diff you can compare objects between a HDF5 file and another file. + * + * \subsection subsec_cltools_h5diff_options Usage +

h5diff [OPTIONS] file1 file2 [obj1[ obj2]]

+ * \li file1 File name of the first HDF5 file + * \li file2 File name of the second HDF5 file + * \li [obj1] Name of an HDF5 object, in absolute path + * \li [obj2] Name of an HDF5 object, in absolute path + + * \subsection subsec_cltools_h5diff_options Error Report + * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. + Optional value 2 also prints file open errors. + + * \subsection subsec_cltools_h5diff_options Options + * \li --help + Print a usage message and exit. + * \li --version + Print version number and exit. + * \li --report + Report mode. Print differences. + * \li --verbose + Verbose mode. Print differences information and list of objects. + * \li --verbose=N + Verbose mode with level. Print differences and list of objects. + Level of detail depends on value of N: + + * \li --quiet + Quiet mode. Do not produce output. + * \li --page-buffer-size=N Set the page buffer cache size, N=non-negative integers + * \li --vol-value-1 Value (ID) of the VOL connector to use for opening the + first HDF5 file specified + * \li --vol-name-1 Name of the VOL connector to use for opening the first + HDF5 file specified + * \li --vol-info-1 VOL-specific info to pass to the VOL connector used for + opening the first HDF5 file specified + * \li --vol-value-2 Value (ID) of the VOL connector to use for opening the + second HDF5 file specified + * \li --vol-name-2 Name of the VOL connector to use for opening the second + HDF5 file specified + * \li --vol-info-2 VOL-specific info to pass to the VOL connector used for + opening the second HDF5 file specified + If none of the above options are used to specify a VOL for a file, then + the VOL named by HDF5_VOL_CONNECTOR (or the native VOL connector, + if that environment variable is unset) will be used + * \li --vfd-value-1 Value (ID) of the VFL driver to use for opening the + first HDF5 file specified + * \li --vfd-name-1 Name of the VFL driver to use for opening the first + HDF5 file specified + * \li --vfd-info-1 VFD-specific info to pass to the VFL driver used for + opening the first HDF5 file specified + * \li --vfd-value-2 Value (ID) of the VFL driver to use for opening the + second HDF5 file specified + * \li --vfd-name-2 Name of the VFL driver to use for opening the second + HDF5 file specified + * \li --vfd-info-2 VFD-specific info to pass to the VFL driver used for + opening the second HDF5 file specified + * \li --follow-symlinks + Follow symbolic links (soft links and external links and compare the) + links' target objects. + If symbolic link(s) with the same name exist in the files being + compared, then determine whether the target of each link is an existing + object (dataset, group, or named datatype) or the link is a dangling + link (a soft or external link pointing to a target object that does + not yet exist). + + If any symbolic link specified in the call to h5diff does not exist, + h5diff treats it as an error and returns an exit code of 2. + * \li --no-dangling-links + Must be used with --follow-symlinks option; otherwise, h5diff shows + error message and returns an exit code of 2. + Check for any symbolic links (soft links or external links) that do not + resolve to an existing object (dataset, group, or named datatype). + If any dangling link is found, this situation is treated as an error + and h5diff returns an exit code of 2. + * \li --compare + List objects that are not comparable + * \li --nan + Avoid NaNs detection + * \li --count=C + Print differences up to C. C must be a positive integer. + * \li --delta=D + Print difference if (|a-b| > D). D must be a positive number. Where a + is the data point value in file1 and b is the data point value in file2. + Can not use with '--relative' or '--use-system-epsilon'. + * \li --relative=R + Print difference if (|(a-b)/b| > R). R must be a positive number. Where a + is the data point value in file1 and b is the data point value in file2. + Can not use with '--delta' or '--use-system-epsilon'. + * \li --use-system-epsilon + Print difference if (|a-b| > EPSILON), EPSILON is system defined value. Where a + is the data point value in file1 and b is the data point value in file2. + If the system epsilon is not defined,one of the following predefined + values will be used: + FLT_EPSILON = 1.19209E-07 for floating-point type + DBL_EPSILON = 2.22045E-16 for double precision type + Can not use with '--relative' or '--delta'. + * \li --exclude-path "path" + Exclude the specified path to an object when comparing files or groups. + If a group is excluded, all member objects will also be excluded. + The specified path is excluded wherever it occurs. + This flexibility enables the same option to exclude either objects that + exist only in one file or common objects that are known to differ. + + When comparing files, "path" is the absolute path to the excluded; + object; when comparing groups, "path" is similar to the relative + path from the group to the excluded object. This "path" can be + taken from the first section of the output of the --verbose option. + For example, if you are comparing the group /groupA in two files and + you want to exclude /groupA/groupB/groupC in both files, the exclude + option would read as follows: + --exclude-path "/groupB/groupC" + + If there are multiple paths to an object, only the specified path(s) + will be excluded; the comparison will include any path not explicitly + excluded. + This option can be used repeatedly to exclude multiple paths. + + * \li --exclude-attribute "path/to/object/with/attribute" + Exclude attributes on the specified path to an object when comparing files or groups. + + If there are multiple paths to an object, only the specified path(s) + will be excluded; the comparison will include any path not explicitly + excluded. + This option can be used repeatedly to exclude multiple paths. + + Modes of output: + * \li Default mode: print the number of differences found and where they occurred + * \li Report mode: print the above plus the differences + * \li Verbose mode: print the above plus a list of objects and warnings + * \li Quiet mode: do not print output + + File comparison: + If no objects [obj1[ obj2]] are specified, the h5diff comparison proceeds as + a comparison of the two files' root groups. That is, h5diff first compares + the names of root group members, generates a report of root group objects + that appear in only one file or in both files, and recursively compares + common objects. + + Object comparison: + * \li 1) Groups + First compares the names of member objects (relative path, from the + specified group) and generates a report of objects that appear in only + one group or in both groups. Common objects are then compared recursively. + * \li 2) Attributes and Datasets + Array rank and dimensions, datatypes, and data values are compared. + * \li 3) Datatypes + The comparison is based on the return value of H5Tequal. + * \li 4) Symbolic links + The paths to the target objects are compared. + (The option --follow-symlinks overrides the default behavior when + symbolic links are compared.). + + + * + * \subsubsection subsubsec_cltools_h5diff_subset Subsetting Options + * \li --no-compact-subset Disable compact form of subsetting and allow the use + of "[" in dataset names. + + Subsetting is available by using the fcompact form of subsetting, as follows: + obj1 /foo/mydataset[START;STRIDE;COUNT;BLOCK] + + It is not required to use all parameters, but until the last parameter value used, + all of the semicolons (;) are required, even when a parameter value is not specified. Example: + obj1 /foo/mydataset[START;;COUNT;BLOCK] + obj1 /foo/mydataset[START] + + The STRIDE, COUNT, and BLOCK parameters are optional and will default to 1 in + each dimension. START is optional and will default to 0 in each dimension. + Each of START, STRIDE, COUNT, and BLOCK must be a comma-separated list of integers with + one integer for each dimension of the dataset. + + Exit code: + * \li 0 if no differences + * \li 1 if differences found + * \li 2 if error + + * + * \subsubsection subsubsec_cltools_h5diff_examples Examples + * \li 1) h5diff file1 file2 /g1/dset1 /g1/dset2 + Compares object '/g1/dset1' in file1 with '/g1/dset2' in file2 + + * \li 2) h5diff file1 file2 /g1/dset1 + Compares object '/g1/dset1' in both files + + * \li 3) h5diff file1 file2 + Compares all objects in both files + + Notes: + file1 and file2 can be the same file. + Use h5diff file1 file1 /g1/dset1 /g1/dset2 to compare + '/g1/dset1' and '/g1/dset2' in the same file + + * + */ + +#endif /* H5DIFF_H */ + diff --git a/tools/src/h5repack/h5repack.h b/tools/src/h5repack/h5repack.h index cc724a067cf..c33848e4df5 100644 --- a/tools/src/h5repack/h5repack.h +++ b/tools/src/h5repack/h5repack.h @@ -13,6 +13,227 @@ #ifndef H5REPACK_H #define H5REPACK_H +/** \page H5TOOL_RP_UG The HDF5 h5repack Tool + * + * \section sec_cltools_h5repack h5repack + * + * \subsection subsec_cltools_h5repack_intro Introduction + * With h5repack you can write an HDF5 file to a new file and change the layout for objects in the new file. + * + * \subsection subsec_cltools_h5repack_usage Usage + *

h5repack [OPTIONS] file1 file2

+ * \li file1 Input HDF5 File + * \li file2 Output HDF5 File + * + * \subsection subsec_cltools_h5repack_error Error Report Option + * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. + * Optional value 2 also prints file open errors. + * + * \subsection subsec_cltools_h5repack_options Options + * \li --help : Print a usage message and exit + * \li --verbose=N : Verbose mode, print object information. + * N - is an integer greater than 1, 2 displays read/write timing + * \li --version : Print version number and exit + * \li --native : Use a native HDF5 type when repacking + * \li --page-buffer-size=N : Set the page buffer cache size, N=non-negative integers + * \li --src-vol-value : Value (ID) of the VOL connector to use for opening the + * input HDF5 file specified + * \li --src-vol-name : Name of the VOL connector to use for opening the input + * HDF5 file specified + * \li --src-vol-info : VOL-specific info to pass to the VOL connector used for + * opening the input HDF5 file specified + * \li --dst-vol-value : Value (ID) of the VOL connector to use for opening the + * output HDF5 file specified + * \li --dst-vol-name : Name of the VOL connector to use for opening the output + * HDF5 file specified + * \li --dst-vol-info : VOL-specific info to pass to the VOL connector used for + * opening the output HDF5 file specified + * \li --src-vfd-value : Value (ID) of the VFL driver to use for opening the + * input HDF5 file specified + * \li --src-vfd-name : Name of the VFL driver to use for opening the input + * HDF5 file specified + * \li --src-vfd-info : VFD-specific info to pass to the VFL driver used for + * opening the input HDF5 file specified + * \li --dst-vfd-value : Value (ID) of the VFL driver to use for opening the + * output HDF5 file specified + * \li --dst-vfd-name : Name of the VFL driver to use for opening the output + * HDF5 file specified + * \li --dst-vfd-info : VFD-specific info to pass to the VFL driver used for + * opening the output HDF5 file specified + * \li --latest : Use latest version of file format + * This option will take precedence over the options + * --low and --high + * \li --low=BOUND : The low bound for library release versions to use + * when creating objects in the file + * (default is #H5F_LIBVER_EARLIEST) + * \li --high=BOUND : The high bound for library release versions to use + * when creating objects in the file + * (default is #H5F_LIBVER_LATEST) + * \li --merge : Follow external soft link recursively and merge data + * \li --prune : Do not follow external soft links and remove link + * \li --merge --prune : Follow external link, merge data and remove dangling link + * \li --compact=L1 : Maximum number of links in header messages + * \li --indexed=L2 : Minimum number of links in the indexed format + * \li --ssize=S[:F] : Shared object header message minimum size + * \li --minimum=M : Do not apply the filter to datasets smaller than M + * \li --file=E : Name of file E with the -f and -l options + * \li --ublock=U : Name of file U with user block data to be added + * \li --block=B : Size of user block to be added + * \li --metadata_block_size=A : Metadata block size for #H5Pset_meta_block_size + * \li --threshold=T : Threshold value for #H5Pset_alignment + * \li --alignment=A : Alignment value for #H5Pset_alignment + * \li --sort_by=Q : Sort groups and attributes by index Q + * \li --sort_order=Z : Sort groups and attributes by order Z + * \li --filter=FILT : Filter type + * \li --layout=LAYT : Layout type + * \li --fs_strategy=FS_STRATEGY : File space management strategy for #H5Pset_file_space_strategy + * \li --fs_persist=FS_PERSIST : Persisting or not persisting free-space for #H5Pset_file_space_strategy + * \li ---fs_threshold=FS_THRESHOLD : Free-space section threshold for #H5Pset_file_space_strategy + * \li --fs_pagesize=FS_PAGESIZE : File space page size for #H5Pset_file_space_page_size + * + * \subsubsection subsubsec_cltools_h5repack_options_args Arguments to Certain Options + * \li M - is an integer greater than 1, size of dataset in bytes (default is 0) + * \li E - is a filename. + * \li S - is an integer + * \li U - is a filename. + * \li T - is an integer + * \li A - is an integer greater than zero + * \li Q - is the sort index type for the input file. It can be "name" or + * "creation_order" (default) + * \li Z - is the sort order type for the input file. It can be "descending" or + * "ascending" (default) + * \li B - is the user block size, any value that is 512 or greater and is + * a power of 2 (1024 default) + * \li F - is the shared object header message type, any of . If F is not specified, S applies to all messages + * + * \subsubsection subsubsec_cltools_h5repack_options_bound Library Version Bounds + * BOUND is an integer indicating the library release versions to use when + * creating objects in the file (see #H5Pset_libver_bounds()): + * \li 0: This is #H5F_LIBVER_EARLIEST in #H5F_libver_t struct + * \li 1: This is #H5F_LIBVER_V18 in #H5F_libver_t struct + * \li 2: This is #H5F_LIBVER_V110 in #H5F_libver_t struct + * \li 3: This is #H5F_LIBVER_V112 in #H5F_libver_t struct + * \li 4: This is #H5F_LIBVER_V114 in #H5F_libver_t struct + * \li 5: This is #H5F_LIBVER_V116 in #H5F_libver_t struct + * \li (#H5F_LIBVER_LATEST is aliased to #H5F_LIBVER_V116 for this release + * + * \subsubsection subsubsec_cltools_h5repack_options_fs File Strategy Settings + * FS_STRATEGY is a string indicating the file space strategy used: + * \li FSM_AGGR: + * The mechanisms used in managing file space are free-space + * managers, aggregators and virtual file driver. + * \li PAGE: + * The mechanisms used in managing file space are free-space + * managers with embedded paged aggregation and virtual file driver. + * \li AGGR: + * The mechanisms used in managing file space are aggregators and + * virtual file driver. + * \li NONE: + * The mechanisms used in managing file space are virtual file + * driver. + * \li The default strategy when not set is \bFSM_AGGR without persisting free- + * space. + * + * \li FS_PERSIST is 1 to persisting free-space or 0 to not persisting free-space. + * The default when not set is not persisting free-space. + * The value is ignored for \bAGGR and \bNONE strategies. + * + * \li FS_THRESHOLD is the minimum size (in bytes) of free-space sections to be + * tracked by the library. + * The default when not set is 1. + * The value is ignored for \bAGGR and \bNONE strategies. + * + * \li FS_PAGESIZE is the size (in bytes) >=512 that is used by the library when + * the file space strategy \bPAGE is used. + * The default when not set is 4096. + * + * \subsubsection subsubsec_cltools_h5repack_options_filt Applying a Third-party Filter + * FILT - is a string with the format: + * + * \li := + * + * \li is a comma separated list of object names, meaning apply + * compression only to those objects. If no names are specified, the filter + * is applied to all objects + * \li can be: + * + * \li is optional filter parameter information + * + * + * \subsubsection subsubsec_cltools_h5repack_options_lay Layout Settings + * LAYT - is a string with the format: + * + * \li := + * + * \li is a comma separated list of object names, meaning that + * layout information is supplied for those objects. If no names are + * specified, the layout type is applied to all objects + * \li can be: + * + * \li is optional layout information + * + * + * \subsection subsec_cltools_h5repack_usage Usage Examples + * Examples of use: + * + * \li 1) h5repack -v -f GZIP=1 file1 file2 + * + * GZIP compression with level 1 to all objects + * + * \li 2) h5repack -v -f dset1:SZIP=8,NN file1 file2 + * + * SZIP compression with 8 pixels per block and NN coding method to object dset1 + * + * \li 3) h5repack -v -l dset1,dset2:CHUNK=20x10 -f dset3,dset4,dset5:NONE file1 file2 + * + * Chunked layout, with a layout size of 20x10, to objects dset1 and dset2 + * and remove filters to objects dset3, dset4, dset5 + * + * \li 4) h5repack -L -c 10 -s 20:dtype file1 file2 + * + * Using latest file format with maximum compact group size of 10 and + * minimum shared datatype size of 20 + * + * \li 5) h5repack -f SHUF -f GZIP=1 file1 file2 + * + * Add both filters SHUF and GZIP in this order to all datasets + * + * \li 6) h5repack -f UD=307,0,1,9 file1 file2 + * + * Add bzip2 filter to all datasets + * + * \li 7) h5repack --low=0 --high=1 file1 file2 + * + * Set low=H5F_LIBVER_EARLIEST and high=H5F_LIBVER_V18 via + * H5Pset_libver_bounds() when creating the repacked file, file2 + * + * + */ + #include "H5private.h" #include "hdf5.h" #include "h5trav.h" diff --git a/tools/test/h5copy/CMakeTests.cmake b/tools/test/h5copy/CMakeTests.cmake index 0069eaf6aea..d4315ef134d 100644 --- a/tools/test/h5copy/CMakeTests.cmake +++ b/tools/test/h5copy/CMakeTests.cmake @@ -549,7 +549,7 @@ ADD_H5_TEST2 (grp_dsets_rename 2 ${HDF_FILE1}.h5 grp_dsets grp_rename -v -s grp_dsets -d /grp_rename/grp_dsets) endif () - # "Test copying objects into group hier. that doesn't exist yet in destination file" + # "Test copying objects into group that doesn't exist yet in destination file" ADD_H5_TEST (A_B1_simple 0 ${HDF_FILE1}.h5 -vp -s simple -d /A/B1/simple) ADD_H5_TEST (A_B2_simple2 0 ${HDF_FILE1}.h5 -vp -s simple -d /A/B2/simple2) ADD_H5_TEST (C_D_simple 0 ${HDF_FILE1}.h5 -vp -s /grp_dsets/simple -d /C/D/simple) From 14b78db236880fe390dfbb1c94c6d238f55def0d Mon Sep 17 00:00:00 2001 From: github-actions <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 21 Jun 2024 18:10:36 +0000 Subject: [PATCH 02/24] Committing clang-format changes --- tools/src/h5copy/h5copy.h | 2 -- tools/src/h5diff/h5diff_main.h | 6 ++---- tools/src/h5repack/h5repack.h | 9 +++++---- 3 files changed, 7 insertions(+), 10 deletions(-) diff --git a/tools/src/h5copy/h5copy.h b/tools/src/h5copy/h5copy.h index cefcfb537b6..8a8cbb293d7 100644 --- a/tools/src/h5copy/h5copy.h +++ b/tools/src/h5copy/h5copy.h @@ -13,7 +13,6 @@ #ifndef H5COPY_H #define H5COPY_H - /** \page H5TOOL_CP_UG The HDF5 h5copy Tool * * \section sec_cltools_h5copy h5copy @@ -73,4 +72,3 @@ */ #endif /* H5COPY_H */ - diff --git a/tools/src/h5diff/h5diff_main.h b/tools/src/h5diff/h5diff_main.h index 3bb72e2d7d3..548e44234d8 100644 --- a/tools/src/h5diff/h5diff_main.h +++ b/tools/src/h5diff/h5diff_main.h @@ -13,7 +13,6 @@ #ifndef H5DIFF_H #define H5DIFF_H - /** \page H5TOOL_DF_UG The HDF5 h5diff Tool * * \section sec_cltools_h5diff h5diff @@ -127,8 +126,8 @@ If the system epsilon is not defined,one of the following predefined values will be used: FLT_EPSILON = 1.19209E-07 for floating-point type - DBL_EPSILON = 2.22045E-16 for double precision type - Can not use with '--relative' or '--delta'. + DBL_EPSILON = 2.22045E-16 for double precision + type Can not use with '--relative' or '--delta'. * \li --exclude-path "path" Exclude the specified path to an object when comparing files or groups. If a group is excluded, all member objects will also be excluded. @@ -229,4 +228,3 @@ */ #endif /* H5DIFF_H */ - diff --git a/tools/src/h5repack/h5repack.h b/tools/src/h5repack/h5repack.h index c33848e4df5..40229d21f9d 100644 --- a/tools/src/h5repack/h5repack.h +++ b/tools/src/h5repack/h5repack.h @@ -86,10 +86,11 @@ * \li --sort_order=Z : Sort groups and attributes by order Z * \li --filter=FILT : Filter type * \li --layout=LAYT : Layout type - * \li --fs_strategy=FS_STRATEGY : File space management strategy for #H5Pset_file_space_strategy - * \li --fs_persist=FS_PERSIST : Persisting or not persisting free-space for #H5Pset_file_space_strategy - * \li ---fs_threshold=FS_THRESHOLD : Free-space section threshold for #H5Pset_file_space_strategy - * \li --fs_pagesize=FS_PAGESIZE : File space page size for #H5Pset_file_space_page_size + * \li --fs_strategy=FS_STRATEGY : File space management strategy for + * #H5Pset_file_space_strategy \li --fs_persist=FS_PERSIST : Persisting or not + * persisting free-space for #H5Pset_file_space_strategy \li ---fs_threshold=FS_THRESHOLD + * : Free-space section threshold for #H5Pset_file_space_strategy \li + * --fs_pagesize=FS_PAGESIZE : File space page size for #H5Pset_file_space_page_size * * \subsubsection subsubsec_cltools_h5repack_options_args Arguments to Certain Options * \li M - is an integer greater than 1, size of dataset in bytes (default is 0) From 109ae8ced8518529e7e2606150280998050b5444 Mon Sep 17 00:00:00 2001 From: Allen Byrne Date: Mon, 24 Jun 2024 12:31:10 -0500 Subject: [PATCH 03/24] Add additional tools doxygen --- doxygen/Doxyfile.in | 2 +- tools/src/h5copy/h5copy.h | 4 +- tools/src/h5dump/h5dump.h | 22 ++ tools/src/h5format_convert/h5format_convert.h | 56 +++ tools/src/h5import/h5import.h | 318 ++++++++++++++++++ tools/src/h5jam/h5jam.h | 71 ++++ tools/src/h5ls/h5ls.h | 109 ++++++ tools/src/h5repack/h5repack.h | 30 +- tools/src/h5stat/h5stat.h | 66 ++++ 9 files changed, 660 insertions(+), 18 deletions(-) create mode 100644 tools/src/h5format_convert/h5format_convert.h create mode 100644 tools/src/h5jam/h5jam.h create mode 100644 tools/src/h5ls/h5ls.h create mode 100644 tools/src/h5stat/h5stat.h diff --git a/doxygen/Doxyfile.in b/doxygen/Doxyfile.in index 1f95743cf9a..4db1be37767 100644 --- a/doxygen/Doxyfile.in +++ b/doxygen/Doxyfile.in @@ -689,7 +689,7 @@ FILE_PATTERNS = H5*public.h H5*module.h H5*develop.h H5FD*.h \ *.F90 \ *.dox \ *.md \ - h5copy.h h5repack.h h5diff_main.h \ + h5copy.h h5diff_main.h h5dump.h h5format_convert.h h5import.h h5jam.h h5ls.h h5repack.h h5stat.h \ H5Cpp.h H5AbstractDs.h H5AtomType.h H5Attribute.h H5CommonFG.h H5CompType.h \ H5DataSet.h H5DataSpace.h H5DataType.h H5OcreatProp.h H5DaccProp.h H5DcreatProp.h \ H5DxferProp.h H5EnumType.h H5Exception.h H5FaccProp.h H5FcreatProp.h H5File.h \ diff --git a/tools/src/h5copy/h5copy.h b/tools/src/h5copy/h5copy.h index 8a8cbb293d7..c9b30c52ea7 100644 --- a/tools/src/h5copy/h5copy.h +++ b/tools/src/h5copy/h5copy.h @@ -20,10 +20,10 @@ * \subsection subsec_cltools_h5copy_intro Introduction * With h5copy you can copy objects from an HDF5 file to another file. * - * \subsection subsec_cltools_h5repack_usage Usage + * \subsection subsec_cltools_h5copy_usage Usage *

h5copy [OPTIONS] [OBJECTS...]

* - * \subsection subsec_cltools_h5repack_objs Objects + * \subsection subsec_cltools_h5copy_objs Objects * \li --input input file name * \li --output output file name * \li --source source object name diff --git a/tools/src/h5dump/h5dump.h b/tools/src/h5dump/h5dump.h index 5deb95190a9..ce13333f3ba 100644 --- a/tools/src/h5dump/h5dump.h +++ b/tools/src/h5dump/h5dump.h @@ -12,6 +12,28 @@ #ifndef H5DUMP_H #define H5DUMP_H +/** \page H5TOOL_DP_UG The HDF5 h5dump Tool + * + * \section sec_cltools_h5dump h5dump + * + * \subsection subsec_cltools_h5dump_intro Introduction + * With h5dump you can dump objects from an HDF5 file to another file. + * + * \subsection subsec_cltools_h5dump_usage Usage + *

h5dump [OPTIONS] [OBJECTS...]

+ * + * \subsection subsec_cltools_h5dump_objs Objects + * + * \subsection subsec_cltools_h5dump_error Error Report Option + * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. + Optional value 2 also prints file open errors. + + * \subsection subsec_cltools_h5dump_options Options + * + * \subsubsection subsubsec_cltools_h5dump_options_args Flag Type Options + * + */ + #include "hdf5.h" #include "H5private.h" #include "h5tools.h" diff --git a/tools/src/h5format_convert/h5format_convert.h b/tools/src/h5format_convert/h5format_convert.h new file mode 100644 index 00000000000..f9e22cca9f6 --- /dev/null +++ b/tools/src/h5format_convert/h5format_convert.h @@ -0,0 +1,56 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +#ifndef H5FORMAT_CONVERT_H +#define H5FORMAT_CONVERT_H + +/** \page H5TOOL_FC_UG The HDF5 h5format_convert Tool + * + * \section sec_cltools_h5format_convert h5format_convert + * + * \subsection subsec_cltools_h5format_convert_intro Introduction + * With h5format_convert you can convert a datasets format in an HDF5 file. + * + * \subsection subsec_cltools_h5format_convert_usage Usage + *

h5format_convert [OPTIONS] file_name

+ * + * \subsection subsec_cltools_h5format_convert_error Error Report Option + * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. + Optional value 2 also prints file open errors. + + * \subsection subsec_cltools_h5format_convert_options Options + * \li --help: Print a usage message and exit + * \li --version: Print version number and exit + * \li --verbose: Turn on verbose mode + * \li --dname=dataset_name: Pathname for the dataset + * \li --noop: Perform all the steps except the actual conversion + * + * \subsubsection subsubsec_cltools_h5format_convert_examples Usage Examples + * \li 1) h5format_convert -dname=/group/dataset file_name + Convert the dataset \ in the HDF5 file \: + a. chunked dataset: convert the chunk indexing type to version 1 B-tree + b. compact/contiguous dataset: downgrade the layout version to 3 + c. virtual dataset: no action + + * \li 2) h5format_convert file_name + Convert all datasets in the HDF5 file \: + a. chunked dataset: convert the chunk indexing type to version 1 B-tree + b. compact/contiguous dataset: downgrade the layout version to 3 + c. virtual dataset: no action + + * \li 3) h5format_convert --noop -dname=/group/dataset file_name + Go through all the steps except the actual conversion when + converting the dataset \ in the HDF5 file \. + * + */ + +#endif /* H5FORMAT_CONVERT_H */ + diff --git a/tools/src/h5import/h5import.h b/tools/src/h5import/h5import.h index 86a27889c9b..e9f2e95cfe9 100644 --- a/tools/src/h5import/h5import.h +++ b/tools/src/h5import/h5import.h @@ -19,6 +19,324 @@ #ifndef H5IMPORT_H #define H5IMPORT_H +/** \page H5TOOL_IM_UG The HDF5 h5import Tool + * + * \section sec_cltools_h5import h5import + * + * \subsection subsec_cltools_h5import_intro Introduction + * With h5import you can convert data stored in one or more ASCII or binary files + into one or more datasets (in accordance with the + user-specified type and storage properties) in an existing + or new HDF5 file. + * + * \subsection subsec_cltools_h5import_desc Description + * The primary objective of the utility is to convert floating + point or integer data stored in ASCII text or binary form + into a data-set according to the type and storage properties + specified by the user. The utility can also accept ASCII + text files and store the contents in a compact form as an + array of one-dimensional strings. + + The input data to be written as a data-set can be provided + to the utility in one of the following forms: + \li 1. ASCII text file with numeric data (floating point or + integer data). + \li 2. Binary file with native floating point data (32-bit or + 64-bit) + \li 3. Binary file with native integer (signed or unsigned) + data (8-bit or 16-bit or 32-bit or 64-bit). + \li 4. ASCII text file containing strings (text data). + + Every input file is associated with a configuration file + also provided as an input to the utility. (See Section + "CONFIGURATION FILE" to know how it is to be organized). + The class, size and dimensions of the input data is + specified in this configuration file. A point to note is + that the floating point data in the ASCII text file may be + organized in the fixed floating form (for example 323.56) + or in a scientific notation (for example 3.23E+02). A + different input-class specification is to be used for both + forms. + + The utility extracts the input data from the input file + according to the specified parameters and saves it into + an H5 dataset. + + The user can specify output type and storage properties in + the configuration file. The user is required to specify the + path of the dataset. If the groups in the path leading to + the data-set do not exist, the groups will be created by the + utility. If no group is specified, the dataset will be + created under the root group. + + In addition to the name, the user is also required to + provide the class and size of output data to be written to + the dataset and may optionally specify the output-architecture, + and the output-byte-order. If output-architecture is not + specified the default is NATIVE. Output-byte-orders are fixed + for some architectures and may be specified only if output- + architecture is IEEE, UNIX or STD. + + Also, layout and other storage properties such as + compression, external storage and extendible data-sets may be + optionally specified. The layout and storage properties + denote how raw data is to be organized on the disk. If these + options are not specified the default is Contiguous layout + and storage. + + The dataset can be organized in any of the following ways: + \li 1. Contiguous. + \li 2. Chunked. + \li 3. External Storage File (has to be contiguous) + \li 4. Extendible data sets (has to be chunked) + \li 5. Compressed. (has to be chunked) + \li 6. Compressed & Extendible (has to be chunked) + + If the user wants to store raw data in a non-HDF file then + the external storage file option is to be used and the name + of the file is to be specified. + + If the user wants the dimensions of the data-set to be + unlimited, the extendible data set option can be chosen. + + The user may also specify the type of compression and the + level to which the data set must be compresses by setting + the compressed option. + * + * \subsection subsec_cltools_h5import_usage Usage + *

h5import -h[elp], OR h5import \ -c[onfig] \ [\ -c[config] \...] -o[utfile] \

+ + * \subsection subsec_cltools_h5import_options Options + * \li -h[elp]: Print a usage message and exit + * + * \subsubsection subsubsec_cltools_h5import_options_args Flag Type Options + * \li \: + Name of the Input file(s), containing a + single n-dimensional floating point or integer array + in either ASCII text, native floating point(32-bit + or 64-bit) or native integer(8-bit or 16-bit or + 32-bit or 64-bit). Data to be specified in the order + of fastest changing dimensions first. + + * \li -c[config] \: + Every input file should be associated with a + configuration file and this is done by the -c option. + is the name of the configuration file. + (See Section \ref subsec_cltools_h5import_config) + + * \li -o[utfile] \: + Name of the HDF5 output file. Data from one or more + input files are stored as one or more data sets in + \. The output file may be an existing file or + it maybe new in which case it will be created. + + + * \subsection subsec_cltools_h5import_config Configuration File + The configuration file is an ASCII text file and must be + the ddl formatted file (without data values) produced by h5dump + when used with the options '-o outfilename -b' of a single dataset (-d) + OR organized as "CONFIG-KEYWORD VALUE" pairs, one pair on each + line. + + The configuration file may have the following keywords each + followed by an acceptable value. + +
Required KEYWORDS
+ * \li PATH + * \li INPUT-CLASS + * \li INPUT-SIZE + * \li INPUT-BYTE-ORDER + * \li RANK + * \li DIMENSION-SIZES + * \li OUTPUT-CLASS + * \li OUTPUT-SIZE + +
Optional KEYWORDS
+ * \li OUTPUT-ARCHITECTURE + * \li OUTPUT-BYTE-ORDER + * \li CHUNKED-DIMENSION-SIZES + * \li COMPRESSION-TYPE + * \li COMPRESSION-PARAM + * \li EXTERNAL-STORAGE + * \li MAXIMUM-DIMENSIONS + + +
Values for keywords
+ * \li PATH: + Strings separated by spaces to represent + the path of the data-set. If the groups in + the path do not exist, they will be created. + For example, + PATH grp1/grp2/dataset1 + PATH: keyword + grp1: group under the root. If + non-existent will be created. + grp2: group under grp1. If + non-existent will be created + under grp1. + dataset1: the name of the data-set + to be created. + + * \li INPUT-CLASS: + String denoting the type of input data. + ("TEXTIN", "TEXTFP", "FP", "IN", + "STR", "TEXTUIN", "UIN"). + INPUT-CLASS "TEXTIN" denotes an ASCII text + file with signed integer data in ASCII form, + INPUT-CLASS "TEXTUIN" denotes an ASCII text + file with unsigned integer data in ASCII form, + "TEXTFP" denotes an ASCII text file containing + floating point data in the fixed notation + (325.34), + "FP" denotes a floating point binary file, + "IN" denotes a signed integer binary file, + "UIN" denotes an unsigned integer binary file, + & "STR" denotes an ASCII text file the + contents of which should be stored as an 1-D + array of strings. + If INPUT-CLASS is "STR", then RANK, + DIMENSION-SIZES, OUTPUT-CLASS, OUTPUT-SIZE, + OUTPUT-ARCHITECTURE and OUTPUT-BYTE-ORDER + will be ignored. + + + * \li INPUT-SIZE: + Integer denoting the size of the input data + (8, 16, 32, 64). + + For floating point, + INPUT-SIZE can be 32 or 64. + For integers (signed and unsigned) + INPUT-SIZE can be 8, 16, 32 or 64. + + * \li RANK: + Integer denoting the number of dimensions. + + * \li DIMENSION-SIZES: + Integers separated by spaces to denote the + dimension sizes for the no. of dimensions + determined by rank. + + * \li OUTPUT-CLASS: + String dentoting data type of the dataset to + be written ("IN","FP", "UIN") + + * \li OUTPUT-SIZE: + Integer denoting the size of the data in the + output dataset to be written. + If OUTPUT-CLASS is "FP", OUTPUT-SIZE can be + 32 or 64. + If OUTPUT-CLASS is "IN" or "UIN", OUTPUT-SIZE + can be 8, 16, 32 or 64. + + * \li OUTPUT-ARCHITECTURE: + STRING denoting the type of output + architecture. Can accept the following values + STD + IEEE + INTEL + CRAY + MIPS + ALPHA + NATIVE (default) + UNIX + + * \li OUTPUT-BYTE-ORDER: + String denoting the output-byte-order. Ignored + if the OUTPUT-ARCHITECTURE is not specified or + if it is IEEE, UNIX or STD. Can accept the + following values. + BE (default) + LE + + * \li CHUNKED-DIMENSION-SIZES: + Integers separated by spaces to denote the + dimension sizes of the chunk for the no. of + dimensions determined by rank. Required field + to denote that the dataset will be stored with + chunked storage. If this field is absent the + dataset will be stored with contiguous storage. + + * \li COMPRESSION-TYPE: + String denoting the type of compression to be + used with the chunked storage. Requires the + CHUNKED-DIMENSION-SIZES to be specified. The only + currently supported compression method is GZIP. + Will accept the following value + GZIP + + * \li COMPRESSION-PARAM: + Integer used to denote compression level and + this option is to be always specified when + the COMPRESSION-TYPE option is specified. The + values are applicable only to GZIP + compression. + Value 1-9: The level of Compression. + 1 will result in the fastest + compression while 9 will result in + the best compression ratio. The default + level of compression is 6. + + * \li EXTERNAL-STORAGE: + String to denote the name of the non-HDF5 file + to store data to. Cannot be used if CHUNKED- + DIMENSIONS or COMPRESSION-TYPE or EXTENDIBLE- + DATASET is specified. + Value : the name of the + external file as a string to be used. + + * \li MAXIMUM-DIMENSIONS: + Integers separated by spaces to denote the + maximum dimension sizes of all the + dimensions determined by rank. Requires the + CHUNKED-DIMENSION-SIZES to be specified. A value of + -1 for any dimension implies UNLIMITED + DIMENSION size for that particular dimension. + + * \subsection subsec_cltools_h5repack_usage Usage Examples + * \li 1. Configuration File may look like: + PATH work h5 pkamat First-set + INPUT-CLASS TEXTFP + RANK 3 + DIMENSION-SIZES 5 2 4 + OUTPUT-CLASS FP + OUTPUT-SIZE 64 + OUTPUT-ARCHITECTURE IEEE + OUTPUT-BYTE-ORDER LE + CHUNKED-DIMENSION-SIZES 2 2 2 +
+ The above configuration will accept a floating point array + (5 x 2 x 4) in an ASCII file with the rank and dimension sizes + specified and will save it in a chunked data-set (of pattern + 2 X 2 X 2) of 64-bit floating point in the little-endian order + and IEEE architecture. The dataset will be stored at + "/work/h5/pkamat/First-set" + + * \li 2. Another configuration could be: + PATH Second-set + INPUT-CLASS IN + RANK 5 + DIMENSION-SIZES 6 3 5 2 4 + OUTPUT-CLASS IN + OUTPUT-SIZE 32 + CHUNKED-DIMENSION-SIZES 2 2 2 2 2 + EXTENDIBLE-DATASET 1 3 + COMPRESSION-TYPE GZIP + COMPRESSION-PARAM 7 +
+ The above configuration will accept an integer array + (6 X 3 X 5 x 2 x 4) in a binary file with the rank and + dimension sizes specified and will save it in a chunked data-set + (of pattern 2 X 2 X 2 X 2 X 2) of 32-bit floating point in + native format (as output-architecture is not specified). The + first and the third dimension will be defined as unlimited. The + data-set will be compressed using GZIP and a compression level + of 7. + The dataset will be stored at "/Second-set" + + * + */ + /* * state table tokens */ diff --git a/tools/src/h5jam/h5jam.h b/tools/src/h5jam/h5jam.h new file mode 100644 index 00000000000..3b247a93e4f --- /dev/null +++ b/tools/src/h5jam/h5jam.h @@ -0,0 +1,71 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +#ifndef H5JAM_H +#define H5JAM_H + +/** \page H5TOOL_JAM_UG The HDF5 h5jam/h5unjam Tool + * + * \section sec_cltools_h5jam h5jam and h5unjam + * + * \subsection subsec_cltools_h5jam_intro Introduction + * h5jam: Adds user block to front of an HDF5 file and creates a new concatenated file. + * h5unjam: Splits user file and HDF5 file into two files: user block data and HDF5 data. + * + * \subsection subsec_cltools_h5jam_usage Usage + *

h5jam -i \ -u \ [-o \] [--clobber]

+ *

h5unjam -i \ [-o \ ] [-u \ | --delete]

+ * + * \subsection subsec_cltools_h5jam_error Error Report Option + * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. + Optional value 2 also prints file open errors. + + * \subsection subsec_cltools_h5jam_options h5jam Options + * \li -i in_file.h5: Specifies the input HDF5 file. + * \li -u in_user_file: Specifies the file to be inserted into the user block. + Can be any file format except an HDF5 format. + * \li -o out_file.h5: Specifies the output HDF5 file. + If not specified, the user block will be concatenated in + place to the input HDF5 file. + * \li --clobber: Wipes out any existing user block before concatenating + the given user block. + The size of the new user block will be the larger of; + - the size of existing user block in the input HDF5 file + - the size of user block required by new input user file + (size = 512 x 2N, N is positive integer.) + + * \li -h: Prints a usage message and exits. + * \li -V: Prints the HDF5 library version and exits. + * + * \subsubsection subsubsec_cltools_h5unjam_options h5unjam Options + * \li -i in_file.h5: Specifies the HDF5 as input. If the input HDF5 file + contains no user block, exit with an error message. + * \li -o out_file.h5: Specifies output HDF5 file without a user block. + If not specified, the user block will be removed from the + input HDF5 file. + * \li -u out_user_file: + Specifies the output file containing the data from the + user block. + Cannot be used with --delete option. + * \li --delete: Remove the user block from the input HDF5 file. The content + of the user block is discarded. + Cannot be used with the -u option. + + * \li -h: Prints a usage message and exits. + * \li -V: Prints the HDF5 library version and exits. + + If neither --delete: nor -u: is specified, the user block from the input file + will be displayed to stdout. + * + */ + +#endif /* H5JAM_H */ + diff --git a/tools/src/h5ls/h5ls.h b/tools/src/h5ls/h5ls.h new file mode 100644 index 00000000000..18d1b2e9996 --- /dev/null +++ b/tools/src/h5ls/h5ls.h @@ -0,0 +1,109 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +#ifndef H5LS_H +#define H5LS_H + +/** \page H5TOOL_LS_UG The HDF5 h5ls Tool + * + * \section sec_cltools_h5ls h5ls + * + * \subsection subsec_cltools_h5ls_intro Introduction + * With h5ls you can dump objects from an HDF5 file. + * + * \subsection subsec_cltools_h5ls_usage Usage + *

h5ls [OPTIONS] file[/OBJECT] [file[/[OBJECT]...]

+ * + * \subsection subsec_cltools_h5ls_objs file/OBJECT + Each object consists of an HDF5 file name optionally followed by a + slash and an object name within the file (if no object is specified + within the file then the contents of the root group are displayed). + The file name may include a printf(3C) integer format such as + "%05d" to open a file family. + * + * \subsection subsec_cltools_h5ls_error Error Report Option + * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. + Optional value 2 also prints file open errors. + + * \subsection subsec_cltools_h5ls_options Options + * \li --help: Print a usage message and exit + * \li --address: Print raw data address. If dataset is contiguous, address + is offset in file of beginning of raw data. If chunked, + returned list of addresses indicates offset of each chunk. + Must be used with -v, --verbose option. + Provides no information for non-dataset objects. + * \li --data: Print the values of datasets + * \li --follow-symlinks: + Follow symbolic links (soft links and external links) + to display target object information. + Without this option, h5ls identifies a symbolic link + as a soft link or external link and prints the value + assigned to the symbolic link; it does not provide any + information regarding the target object or determine + whether the link is a dangling link. + * \li --no-dangling-links: + Must be used with --follow-symlinks option; + otherwise, h5ls shows error message and returns an exit + code of 1. + Check for any symbolic links (soft links or external links) + that do not resolve to an existing object (dataset, group, + or named datatype). + If any dangling link is found, this situation is treated + as an error and h5ls returns an exit code of 1. + * \li --full: Print full path names instead of base names + * \li --group: Show information about a group, not its contents + * \li --label: Label members of compound datasets + * \li --recursive: List all groups recursively, avoiding cycles + * \li --string: Print 1-byte integer datasets as ASCII + * \li --simple: Use a machine-readable output format + * \li --width=N: Set the number of columns of output + * \li --verbose: Generate more verbose output + * \li --version: Print version number and exit + * \li --page-buffer-size=N: Set the page buffer cache size, N=non-negative integers + * \li --vfd=DRIVER: Use the specified virtual file driver + * \li --hexdump: Show raw data in hexadecimal format + * \li --s3-cred=C: Supply S3 authentication information to "ros3" vfd. + Accepts tuple of "(\,\,\)". + If absent or C-\>"(,,)", defaults to no-authentication. + Has no effect if vfd flag not set to "ros3". + * \li --hdfs-attrs=A: Supply configuration information to Hadoop VFD. + Accepts tuple of (\,\, + ...\,\,\) + If absent or A == '(,,,,)', all default values are used. + Has no effect if vfd flag is not 'hdfs'. + * \li --vol-value: Value (ID) of the VOL connector to use for opening the + HDF5 file specified + * \li --vol-name: Name of the VOL connector to use for opening the + HDF5 file specified + * \li --vol-info: VOL-specific info to pass to the VOL connector used for + opening the HDF5 file specified + If none of the above options are used to specify a VOL, then + the VOL named by HDF5_VOL_CONNECTOR (or the native VOL connector, + if that environment variable is unset) will be used + * \li --vfd-value: Value (ID) of the VFL driver to use for opening the + HDF5 file specified + * \li --vfd-name: Name of the VFL driver to use for opening the + HDF5 file specified + * \li --vfd-info: VFD-specific info to pass to the VFL driver used for + opening the HDF5 file specified + * + * \subsubsection subsubsec_cltools_h5ls_options_depre Deprecated Options + The following options have been removed in HDF5 1.12. Use the indicated + replacement option in all work. + * \li --external: Follow external links. + Replaced by --follow-symlinks. + * \li --errors: Show all HDF5 error reporting + Replaced by --enable-error-stack. + * + */ + +#endif /* H5LS_H */ + diff --git a/tools/src/h5repack/h5repack.h b/tools/src/h5repack/h5repack.h index 40229d21f9d..af102dcd11e 100644 --- a/tools/src/h5repack/h5repack.h +++ b/tools/src/h5repack/h5repack.h @@ -133,31 +133,31 @@ * \li NONE: * The mechanisms used in managing file space are virtual file * driver. - * \li The default strategy when not set is \bFSM_AGGR without persisting free- + * \li The default strategy when not set is \b FSM_AGGR without persisting free- * space. * * \li FS_PERSIST is 1 to persisting free-space or 0 to not persisting free-space. * The default when not set is not persisting free-space. - * The value is ignored for \bAGGR and \bNONE strategies. + * The value is ignored for \b AGGR and \b NONE strategies. * * \li FS_THRESHOLD is the minimum size (in bytes) of free-space sections to be * tracked by the library. * The default when not set is 1. - * The value is ignored for \bAGGR and \bNONE strategies. + * The value is ignored for \b AGGR and \b NONE strategies. * * \li FS_PAGESIZE is the size (in bytes) >=512 that is used by the library when - * the file space strategy \bPAGE is used. + * the file space strategy \b PAGE is used. * The default when not set is 4096. * * \subsubsection subsubsec_cltools_h5repack_options_filt Applying a Third-party Filter * FILT - is a string with the format: * - * \li := + * \li \:\=\ * - * \li is a comma separated list of object names, meaning apply + * \li \ is a comma separated list of object names, meaning apply * compression only to those objects. If no names are specified, the filter * is applied to all objects - * \li can be: + * \li \ can be: *
  • GZIP, to apply the HDF5 GZIP filter (GZIP compression)
    • *
  • SZIP, to apply the HDF5 SZIP filter (SZIP compression)
    • *
  • SHUF, to apply the HDF5 shuffle filter
    • @@ -166,16 +166,16 @@ *
  • SOFF, to apply the HDF5 Scale/Offset filter
    • *
  • UD, to apply a user defined filter
    • *
  • NONE, to remove all filters
- * \li is optional filter parameter information - *
  • GZIP= from 1-9
    • + * \li \ is optional filter parameter information + *
    • GZIP=\ from 1-9
      • *
    • SZIP= pixels per block is a even number in * 2-32 and coding method is either EC or NN
      • *
    • SHUF (no parameter)
      • *
    • FLET (no parameter)
      • *
    • NBIT (no parameter)
      • - *
    • SOFF= scale_factor is an integer and scale_type + *
    • SOFF=\ scale_factor is an integer and scale_type * is either IN or DS
      • - *
    • UD= + *
    • UD=\ * Required values: filter_number, filter_flag, cd_value_count, value1 * Optional values: value2 to valueN * filter_flag: 1 is OPTIONAL or 0 is MANDATORY
      • @@ -184,16 +184,16 @@ * \subsubsection subsubsec_cltools_h5repack_options_lay Layout Settings * LAYT - is a string with the format: * - * \li := + * \li \:\=\ * - * \li is a comma separated list of object names, meaning that + * \li \ is a comma separated list of object names, meaning that * layout information is supplied for those objects. If no names are * specified, the layout type is applied to all objects - * \li can be: + * \li \ can be: *
      • CHUNK, to apply chunking layout
        • *
      • COMPA, to apply compact layout
        • *
      • CONTI, to apply contiguous layout
      - * \li is optional layout information + * \li \ is optional layout information *
      • CHUNK=DIM[xDIM...xDIM], the chunk size of each dimension
        • *
      • COMPA (no parameter)
        • *
      • CONTI (no parameter)
      diff --git a/tools/src/h5stat/h5stat.h b/tools/src/h5stat/h5stat.h new file mode 100644 index 00000000000..b0083d0a5c8 --- /dev/null +++ b/tools/src/h5stat/h5stat.h @@ -0,0 +1,66 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +#ifndef H5STAT_H +#define H5STAT_H + +/** \page H5TOOL_ST_UG The HDF5 h5stat Tool + * + * \section sec_cltools_h5stat h5stat + * + * \subsection subsec_cltools_h5stat_intro Introduction + * With h5stat you can dump stats from an HDF5 file. + * + * \subsection subsec_cltools_h5stat_usage Usage + *

      h5stat [OPTIONS] file

      + * + * \subsection subsec_cltools_h5stat_error Error Report Option + * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. + Optional value 2 also prints file open errors. + + * \subsection subsec_cltools_h5stat_options Options + * \li --help: Print a usage message and exit + * \li --version: Print version number and exit + * \li --file: Print file information + * \li --filemetadata: Print file space information for file's metadata + * \li --group: Print group information + * \li --links=N: Set the threshold for the # of links when printing + information for small groups. N is an integer greater + than 0. The default threshold is 10. + * \li --groupmetadata : Print file space information for groups' metadata + * \li --dset: Print dataset information + * \li --dims=N: Set the threshold for the dimension sizes when printing + information for small datasets. N is an integer greater + than 0. The default threshold is 10. + * \li --dsetmetadata: Print file space information for datasets' metadata + * \li --dtypemetadata: Print datasets' datatype information + * \li --attribute: Print attribute information + * \li --numattrs=N: Set the threshold for the number of attributes when printing + information for small number of attributes. N is an integer greater + than 0. The default threshold is 10. + * \li --freespace: Print free space information + * \li --summary: Print summary of file space information + * \li --page-buffer-size=N: Set the page buffer cache size, N=non-negative integers + * \li --s3-cred=\: Access file on S3, using provided credential + \ :: (region,id,key) + If \ == "(,,)", no authentication is used. + * \li --hdfs-attrs=\: Access a file on HDFS with given configuration + attributes. + \ :: (\,\, + \,\, + \) + If an attribute is empty, a default value will be + used. + * + */ + +#endif /* H5STAT_H */ + From 882e84f3a7dc6dabb8676b6e6269659e2ba71a44 Mon Sep 17 00:00:00 2001 From: github-actions <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon, 24 Jun 2024 17:33:16 +0000 Subject: [PATCH 04/24] Committing clang-format changes --- tools/src/h5format_convert/h5format_convert.h | 1 - tools/src/h5import/h5import.h | 3 ++- tools/src/h5jam/h5jam.h | 5 ++--- tools/src/h5ls/h5ls.h | 1 - tools/src/h5stat/h5stat.h | 1 - 5 files changed, 4 insertions(+), 7 deletions(-) diff --git a/tools/src/h5format_convert/h5format_convert.h b/tools/src/h5format_convert/h5format_convert.h index f9e22cca9f6..03a2911db84 100644 --- a/tools/src/h5format_convert/h5format_convert.h +++ b/tools/src/h5format_convert/h5format_convert.h @@ -53,4 +53,3 @@ */ #endif /* H5FORMAT_CONVERT_H */ - diff --git a/tools/src/h5import/h5import.h b/tools/src/h5import/h5import.h index e9f2e95cfe9..08df1f10245 100644 --- a/tools/src/h5import/h5import.h +++ b/tools/src/h5import/h5import.h @@ -104,7 +104,8 @@ the compressed option. * * \subsection subsec_cltools_h5import_usage Usage - *

      h5import -h[elp], OR h5import \ -c[onfig] \ [\ -c[config] \...] -o[utfile] \

      + *

      h5import -h[elp], OR h5import \ -c[onfig] \ [\ -c[config] +\...] -o[utfile] \

      * \subsection subsec_cltools_h5import_options Options * \li -h[elp]: Print a usage message and exit diff --git a/tools/src/h5jam/h5jam.h b/tools/src/h5jam/h5jam.h index 3b247a93e4f..8eeba6bbdd0 100644 --- a/tools/src/h5jam/h5jam.h +++ b/tools/src/h5jam/h5jam.h @@ -62,10 +62,9 @@ * \li -h: Prints a usage message and exits. * \li -V: Prints the HDF5 library version and exits. - If neither --delete: nor -u: is specified, the user block from the input file - will be displayed to stdout. + If neither --delete: nor -u: is specified, the user block from the input + file will be displayed to stdout. * */ #endif /* H5JAM_H */ - diff --git a/tools/src/h5ls/h5ls.h b/tools/src/h5ls/h5ls.h index 18d1b2e9996..e59de0e035e 100644 --- a/tools/src/h5ls/h5ls.h +++ b/tools/src/h5ls/h5ls.h @@ -106,4 +106,3 @@ */ #endif /* H5LS_H */ - diff --git a/tools/src/h5stat/h5stat.h b/tools/src/h5stat/h5stat.h index b0083d0a5c8..074b57dc67f 100644 --- a/tools/src/h5stat/h5stat.h +++ b/tools/src/h5stat/h5stat.h @@ -63,4 +63,3 @@ */ #endif /* H5STAT_H */ - From 8a76c1dd85d6bb204792f549624870baa47bbcde Mon Sep 17 00:00:00 2001 From: Allen Byrne Date: Mon, 24 Jun 2024 13:38:23 -0500 Subject: [PATCH 05/24] Add more tools doxygen files --- doxygen/Doxyfile.in | 1 + hl/tools/h5watch/h5watch.h | 65 ++++++++++++++++++++++++++++++++++ tools/src/h5diff/h5diff_main.h | 4 +-- tools/src/h5import/h5import.h | 4 +-- tools/src/h5repack/h5repack.h | 2 +- tools/src/misc/h5clear.h | 64 +++++++++++++++++++++++++++++++++ tools/src/misc/h5debug.h | 32 +++++++++++++++++ tools/src/misc/h5delete.h | 31 ++++++++++++++++ tools/src/misc/h5mkgrp.h | 54 ++++++++++++++++++++++++++++ tools/src/misc/h5repart.h | 47 ++++++++++++++++++++++++ 10 files changed, 299 insertions(+), 5 deletions(-) create mode 100644 hl/tools/h5watch/h5watch.h create mode 100644 tools/src/misc/h5clear.h create mode 100644 tools/src/misc/h5debug.h create mode 100644 tools/src/misc/h5delete.h create mode 100644 tools/src/misc/h5mkgrp.h create mode 100644 tools/src/misc/h5repart.h diff --git a/doxygen/Doxyfile.in b/doxygen/Doxyfile.in index 4db1be37767..05f660b8763 100644 --- a/doxygen/Doxyfile.in +++ b/doxygen/Doxyfile.in @@ -690,6 +690,7 @@ FILE_PATTERNS = H5*public.h H5*module.h H5*develop.h H5FD*.h \ *.dox \ *.md \ h5copy.h h5diff_main.h h5dump.h h5format_convert.h h5import.h h5jam.h h5ls.h h5repack.h h5stat.h \ + h5watch.h h5clear.h h5debug.h h5delete.h h5mkgrp.h h5repart.h \ H5Cpp.h H5AbstractDs.h H5AtomType.h H5Attribute.h H5CommonFG.h H5CompType.h \ H5DataSet.h H5DataSpace.h H5DataType.h H5OcreatProp.h H5DaccProp.h H5DcreatProp.h \ H5DxferProp.h H5EnumType.h H5Exception.h H5FaccProp.h H5FcreatProp.h H5File.h \ diff --git a/hl/tools/h5watch/h5watch.h b/hl/tools/h5watch/h5watch.h new file mode 100644 index 00000000000..096117d3244 --- /dev/null +++ b/hl/tools/h5watch/h5watch.h @@ -0,0 +1,65 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +#ifndef H5WATCH_H +#define H5WATCH_H + +/** \page H5TOOL_WH_UG The HDF5 h5watch Tool + * + * \section sec_cltools_h5watch h5watch + * + * \subsection subsec_cltools_h5watch_intro Introduction + * With h5watch you can dump stats from an HDF5 file. + * + * \subsection subsec_cltools_h5watch_usage Usage + *

      h5watch [OPTIONS] [OBJECT]

      + * + * \subsection subsec_cltools_h5watch_error Error Report Option + * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. + Optional value 2 also prints file open errors. + + * \subsection subsec_cltools_h5watch_options Options + * \li --help: Print a usage message and exit + * \li --version: Print version number and exit + * \li --label: Label members of compound typed dataset. + * \li --simple: Use a machine-readable output format. + * \li --dim: Monitor changes in size of dataset dimensions only. + * \li --width=N: Set the number of columns to N for output. + A value of 0 sets the number of columns to the + maximum (65535). The default width is 80 columns. + * \li --polling=N: Set the polling interval to N (in seconds) when the + dataset will be checked for appended data. The default + polling interval is 1. + * \li --fields=\: + Display data for the fields specified in \ + for a compound data type. \ can be + specified as follows: +
      • 1) A comma-separated list of field names in a + compound data type. "," is the separator + for field names while "." is the separator + for a nested field.
        • +
      • 2) A single field name in a compound data type. + Can use this option multiple times.
      + Note that backslash is the escape character to avoid + characters in field names that conflict with the tool's + separators. + + * \subsection subsec_cltools_h5watch_objs Object + OBJECT is specified as [\/\/\] + * \li \: Name of the HDF5 file. It may be preceded by path + separated by slashes to the specified HDF5 file. + * \li \: Path separated by slashes to the specified dataset + * \li \: Name of the dataset + * + */ + +#endif /* H5WATCH_H */ + diff --git a/tools/src/h5diff/h5diff_main.h b/tools/src/h5diff/h5diff_main.h index 548e44234d8..9da8d171226 100644 --- a/tools/src/h5diff/h5diff_main.h +++ b/tools/src/h5diff/h5diff_main.h @@ -20,14 +20,14 @@ * \subsection subsec_cltools_h5diff_intro Introduction * With h5diff you can compare objects between a HDF5 file and another file. * - * \subsection subsec_cltools_h5diff_options Usage + * \subsection subsec_cltools_h5diff_usage Usage

      h5diff [OPTIONS] file1 file2 [obj1[ obj2]]

      * \li file1 File name of the first HDF5 file * \li file2 File name of the second HDF5 file * \li [obj1] Name of an HDF5 object, in absolute path * \li [obj2] Name of an HDF5 object, in absolute path - * \subsection subsec_cltools_h5diff_options Error Report + * \subsection subsec_cltools_h5diff_error Error Report * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. Optional value 2 also prints file open errors. diff --git a/tools/src/h5import/h5import.h b/tools/src/h5import/h5import.h index 08df1f10245..d8a3a12cc37 100644 --- a/tools/src/h5import/h5import.h +++ b/tools/src/h5import/h5import.h @@ -122,7 +122,7 @@ * \li -c[config] \: Every input file should be associated with a configuration file and this is done by the -c option. - is the name of the configuration file. + \ is the name of the configuration file. (See Section \ref subsec_cltools_h5import_config) * \li -o[utfile] \: @@ -294,7 +294,7 @@ -1 for any dimension implies UNLIMITED DIMENSION size for that particular dimension. - * \subsection subsec_cltools_h5repack_usage Usage Examples + * \subsection subsec_cltools_h5import_examples Usage Examples * \li 1. Configuration File may look like: PATH work h5 pkamat First-set INPUT-CLASS TEXTFP diff --git a/tools/src/h5repack/h5repack.h b/tools/src/h5repack/h5repack.h index af102dcd11e..128f0ca0d99 100644 --- a/tools/src/h5repack/h5repack.h +++ b/tools/src/h5repack/h5repack.h @@ -198,7 +198,7 @@ *
    • COMPA (no parameter)
      • *
    • CONTI (no parameter)
    * - * \subsection subsec_cltools_h5repack_usage Usage Examples + * \subsection subsec_cltools_h5repack_examples Usage Examples * Examples of use: * * \li 1) h5repack -v -f GZIP=1 file1 file2 diff --git a/tools/src/misc/h5clear.h b/tools/src/misc/h5clear.h new file mode 100644 index 00000000000..5bc9adcfa8a --- /dev/null +++ b/tools/src/misc/h5clear.h @@ -0,0 +1,64 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +#ifndef H5CLEAR_H +#define H5CLEAR_H + +/** \page H5TOOL_CR_UG The HDF5 h5clear Tool + * + * \section sec_cltools_h5clear h5stat + * + * \subsection subsec_cltools_h5clear_intro Introduction + * With h5clear you can clear the 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. + * + * \subsection subsec_cltools_h5clear_usage Usage + *

    h5clear [OPTIONS] file_name

    + * + * \subsection subsec_cltools_h5clear_error Error Report Option + * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. + Optional value 2 also prints file open errors. + + * \subsection subsec_cltools_h5clear_options Options + * \li --help: Print a usage message and exit + * \li --version: Print version number and exit + * \li --status: Clear the status_flags field in the file's superblock + * \li --image: Remove the metadata cache image from the file + * \li --filesize : Print the file's EOA and EOF + * \li --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 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. + * + * \subsection subsec_cltools_h5clear_examples Usage Examples + * \li h5clear -s file_name + Clear the status_flags field in the superblock of the HDF5 file \. + + * \li h5clear -m file_name + Remove the metadata cache image from the HDF5 file \. + + * \li h5clear --increment file_name + Set the EOA to the maximum of (EOA, EOF) + 1M for the file \. + + * \li h5clear --increment=512 file_name + Set the EOA to the maximum of (EOA, EOF) + 512 for the file \. + + */ + +#endif /* H5CLEAR_H */ + diff --git a/tools/src/misc/h5debug.h b/tools/src/misc/h5debug.h new file mode 100644 index 00000000000..177b2a5dfbc --- /dev/null +++ b/tools/src/misc/h5debug.h @@ -0,0 +1,32 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +#ifndef H5DEBUG_H +#define H5DEBUG_H + +/** \page H5TOOL_DG_UG The HDF5 h5debug Tool + * + * \section sec_cltools_h5debug h5debug + * + * \subsection subsec_cltools_h5debug_intro Introduction + * With h5debug you can debug an existing HDF5 file at a low level. + * + * \subsection subsec_cltools_h5debug_usage Usage + *

    h5debug filename [signature-addr [extra]*]

    + + * \subsection subsec_cltools_h5debug_options Options + * \li signature-addr: Primary data structure to dump + * \li extra: Extra arguments for primary data structure + * + */ + +#endif /* H5DEBUG_H */ + diff --git a/tools/src/misc/h5delete.h b/tools/src/misc/h5delete.h new file mode 100644 index 00000000000..f806c2f2d09 --- /dev/null +++ b/tools/src/misc/h5delete.h @@ -0,0 +1,31 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +#ifndef H5DELETE_H +#define H5DELETE_H + +/** \page H5TOOL_DT_UG The HDF5 h5delete Tool + * + * \section sec_cltools_h5delete h5delete + * + * \subsection subsec_cltools_h5delete_intro Introduction + * With h5delete you can delete an HDF5 file. + * + * \subsection subsec_cltools_h5delete_usage Usage + *

    h5delete [-f] \

    + + * \subsection subsec_cltools_h5delete_options Options + * \li -f: Suppress output + * + */ + +#endif /* H5DELETE_H */ + diff --git a/tools/src/misc/h5mkgrp.h b/tools/src/misc/h5mkgrp.h new file mode 100644 index 00000000000..b12501491e2 --- /dev/null +++ b/tools/src/misc/h5mkgrp.h @@ -0,0 +1,54 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +#ifndef H5MKGRP_H +#define H5MKGRP_H + +/** \page H5TOOL_MG_UG The HDF5 h5mkgrp Tool + * + * \section sec_cltools_h5mkgrp h5mkgrp + * + * \subsection subsec_cltools_h5mkgrp_intro Introduction + * With h5mkgrp you can create group(s) in an HDF5 file + * + * \subsection subsec_cltools_h5mkgrp_usage Usage + *

    h5mkgrp [OPTIONS] FILE GROUP

    + * + * \subsection subsec_cltools_h5mkgrp_error Error Report Option + * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. + Optional value 2 also prints file open errors. + + * \subsection subsec_cltools_h5mkgrp_options Options + * \li --help: Print a usage message and exit + * \li --version: Print version number and exit + * \li --verbose: Print information about OBJECTS and OPTIONS + * \li --latest: Use latest version of file format to create groups + * \li --parents: No error if existing, make parent groups as needed + * \li --vol-value: Value (ID) of the VOL connector to use for opening the + HDF5 file specified + * \li --vol-name: Name of the VOL connector to use for opening the + HDF5 file specified + * \li --vol-info: VOL-specific info to pass to the VOL connector used for + opening the HDF5 file specified + If none of the above options are used to specify a VOL, then + the VOL named by HDF5_VOL_CONNECTOR (or the native VOL connector, + if that environment variable is unset) will be used + * \li --vfd-value: Value (ID) of the VFL driver to use for opening the + HDF5 file specified + * \li --vfd-name: Name of the VFL driver to use for opening the + HDF5 file specified + * \li --vfd-info: VFD-specific info to pass to the VFL driver used for + opening the HDF5 file specified + * + */ + +#endif /* H5MKGRP_H */ + diff --git a/tools/src/misc/h5repart.h b/tools/src/misc/h5repart.h new file mode 100644 index 00000000000..f800601eab5 --- /dev/null +++ b/tools/src/misc/h5repart.h @@ -0,0 +1,47 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +#ifndef H5REPART_H +#define H5REPART_H + +/** \page H5TOOL_RT_UG The HDF5 h5repart Tool + * + * \section sec_cltools_h5repart h5repart + * + * \subsection subsec_cltools_h5repart_intro Introduction + * With h5repart you can repartition a file family. This program can be used to + * split a single file into a family of files, join a family of + * files into a single file, or copy one family to another while + * changing the size of the family members. It can also be used + * to copy a single file to a single file with holes. + * + * \subsection subsec_cltools_h5repart_usage Usage + *

    h5repart [OPTIONS] SRC DST

    + * + * \subsection subsec_cltools_h5repart_objs SRC/DST + * \li SRC: The name of the source file + * \li DST: The name of the destination files + + * \subsection subsec_cltools_h5repart_options Options + * \li -v: Produce verbose output + * \li -V: Print version number and exit + * \li -b N: The I/O block size, defaults to 1kB + * \li -m N: The destination member size or 1GB + * \li -family_to_sec2: Deprecated version of -family_to_single (below) + * \li -family_to_single: Change file driver from family to the default single-file VFD (windows or sec2) + * + Sizes may be suffixed with 'g' for GB, 'm' for MB or 'k' for kB. + File family names include an integer printf format such as '%%d' + * + */ + +#endif /* H5REPART_H */ + From 0cd0f0906fa4e461c9f1a019a90ab2a49cf27b9a Mon Sep 17 00:00:00 2001 From: github-actions <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon, 24 Jun 2024 18:40:28 +0000 Subject: [PATCH 06/24] Committing clang-format changes --- hl/tools/h5watch/h5watch.h | 1 - tools/src/misc/h5clear.h | 1 - tools/src/misc/h5debug.h | 1 - tools/src/misc/h5delete.h | 1 - tools/src/misc/h5mkgrp.h | 1 - tools/src/misc/h5repart.h | 4 ++-- 6 files changed, 2 insertions(+), 7 deletions(-) diff --git a/hl/tools/h5watch/h5watch.h b/hl/tools/h5watch/h5watch.h index 096117d3244..e86db4e4089 100644 --- a/hl/tools/h5watch/h5watch.h +++ b/hl/tools/h5watch/h5watch.h @@ -62,4 +62,3 @@ */ #endif /* H5WATCH_H */ - diff --git a/tools/src/misc/h5clear.h b/tools/src/misc/h5clear.h index 5bc9adcfa8a..287a3034e8b 100644 --- a/tools/src/misc/h5clear.h +++ b/tools/src/misc/h5clear.h @@ -61,4 +61,3 @@ and appropriate actions can be taken. */ #endif /* H5CLEAR_H */ - diff --git a/tools/src/misc/h5debug.h b/tools/src/misc/h5debug.h index 177b2a5dfbc..1318d7752b7 100644 --- a/tools/src/misc/h5debug.h +++ b/tools/src/misc/h5debug.h @@ -29,4 +29,3 @@ */ #endif /* H5DEBUG_H */ - diff --git a/tools/src/misc/h5delete.h b/tools/src/misc/h5delete.h index f806c2f2d09..52bb299efc1 100644 --- a/tools/src/misc/h5delete.h +++ b/tools/src/misc/h5delete.h @@ -28,4 +28,3 @@ */ #endif /* H5DELETE_H */ - diff --git a/tools/src/misc/h5mkgrp.h b/tools/src/misc/h5mkgrp.h index b12501491e2..d0d8ccf4ed5 100644 --- a/tools/src/misc/h5mkgrp.h +++ b/tools/src/misc/h5mkgrp.h @@ -51,4 +51,3 @@ */ #endif /* H5MKGRP_H */ - diff --git a/tools/src/misc/h5repart.h b/tools/src/misc/h5repart.h index f800601eab5..0c8d76baaf6 100644 --- a/tools/src/misc/h5repart.h +++ b/tools/src/misc/h5repart.h @@ -36,7 +36,8 @@ * \li -b N: The I/O block size, defaults to 1kB * \li -m N: The destination member size or 1GB * \li -family_to_sec2: Deprecated version of -family_to_single (below) - * \li -family_to_single: Change file driver from family to the default single-file VFD (windows or sec2) + * \li -family_to_single: Change file driver from family to the default single-file + VFD (windows or sec2) * Sizes may be suffixed with 'g' for GB, 'm' for MB or 'k' for kB. File family names include an integer printf format such as '%%d' @@ -44,4 +45,3 @@ */ #endif /* H5REPART_H */ - From 479c7495c56ac58faca36a34f90dc0c525ad4e84 Mon Sep 17 00:00:00 2001 From: Allen Byrne Date: Mon, 24 Jun 2024 13:54:24 -0500 Subject: [PATCH 07/24] Correct unterminated alias lines --- doxygen/aliases | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doxygen/aliases b/doxygen/aliases index fd0afb5d54e..19656fac29b 100644 --- a/doxygen/aliases +++ b/doxygen/aliases @@ -387,8 +387,8 @@ ALIASES += str_pad_type="
    #H5T_STR_NULLTERM0Null ALIASES += see_virtual=" \see Supporting Functions: H5Pget_layout(), H5Pset_layout(), H5Sget_regular_hyperslab(), H5Sis_regular_hyperslab(), H5Sselect_hyperslab() \see VDS Functions: H5Pget_virtual_count(), H5Pget_virtual_dsetname(), H5Pget_virtual_filename(), H5Pget_virtual_prefix(), H5Pget_virtual_printf_gap(), H5Pget_virtual_srcspace(), H5Pget_virtual_view(), H5Pget_virtual_vspace(), H5Pset_virtual(), H5Pset_virtual_prefix(), H5Pset_virtual_printf_gap(), H5Pset_virtual_view()" ALIASES += obj_info_fields="
    FlagPurpose
    #H5O_INFO_BASICFill in the fileno, addr, type, and rc fields
    #H5O_INFO_TIMEFill in the atime, mtime, ctime, and btime fields
    #H5O_INFO_NUM_ATTRS Fill in the num_attrs field
    #H5O_INFO_HDRFill in the num_attrs field
    #H5O_INFO_META_SIZEFill in the meta_size field
    #H5O_INFO_ALL#H5O_INFO_BASIC | #H5O_INFO_TIME | #H5O_INFO_NUM_ATTRS | #H5O_INFO_HDR | #H5O_INFO_META_SIZE
    " -ALIASES += details_namelen{2}="Up to \p size characters of the \1 name are returned in \p name; additional characters, if any, are not returned to the user application.\n\n If the length of the \1 name, which determines the required value of \p size, is unknown, a preliminary call to \2() with the last two parameters set to NULL and zero respectively can be made. The return value of this call will be the size in bytes of the \1 name. That value, plus 1 for a NULL terminator, must then be assigned to \p size for a second \2() call, which will retrieve the actual \1 name. -ALIASES += details_namelen_plusone{2}="Up to \p size characters of the \1 name are returned in \p name; additional characters, if any, are not returned to the user application.\n\n If the length of the \1 name, which determines the required value of \p size, is unknown, a preliminary call to \2() with the last two parameters set to NULL and zero respectively can be made. The return value of this call will be the size in bytes of the \1 name plus 1 for a NULL terminator. That value must then be assigned to \p size for a second \2() call, which will retrieve the actual \1 name. +ALIASES += details_namelen{2}="Up to \p size characters of the \1 name are returned in \p name; additional characters, if any, are not returned to the user application.\n\n If the length of the \1 name, which determines the required value of \p size, is unknown, a preliminary call to \2() with the last two parameters set to NULL and zero respectively can be made. The return value of this call will be the size in bytes of the \1 name. That value, plus 1 for a NULL terminator, must then be assigned to \p size for a second \2() call, which will retrieve the actual \1 name." +ALIASES += details_namelen_plusone{2}="Up to \p size characters of the \1 name are returned in \p name; additional characters, if any, are not returned to the user application.\n\n If the length of the \1 name, which determines the required value of \p size, is unknown, a preliminary call to \2() with the last two parameters set to NULL and zero respectively can be made. The return value of this call will be the size in bytes of the \1 name plus 1 for a NULL terminator. That value must then be assigned to \p size for a second \2() call, which will retrieve the actual \1 name." ################################################################################ From e5253a55556d7de6ce07008888c9899feb2ddbf1 Mon Sep 17 00:00:00 2001 From: Allen Byrne Date: Mon, 24 Jun 2024 17:39:42 -0500 Subject: [PATCH 08/24] Correct formatting add h5dump --- hl/tools/h5watch/h5watch.h | 38 +++---- tools/src/h5diff/h5diff_main.h | 6 +- tools/src/h5dump/h5dump.h | 174 +++++++++++++++++++++++++++++++-- tools/src/h5import/h5import.h | 25 ++--- tools/src/h5jam/h5jam.h | 4 +- tools/src/h5ls/h5ls.h | 56 +++++------ tools/src/h5repack/h5repack.h | 88 +++++++++-------- tools/src/misc/h5clear.h | 2 +- 8 files changed, 280 insertions(+), 113 deletions(-) diff --git a/hl/tools/h5watch/h5watch.h b/hl/tools/h5watch/h5watch.h index e86db4e4089..9fb19789776 100644 --- a/hl/tools/h5watch/h5watch.h +++ b/hl/tools/h5watch/h5watch.h @@ -27,21 +27,21 @@ Optional value 2 also prints file open errors. * \subsection subsec_cltools_h5watch_options Options - * \li --help: Print a usage message and exit - * \li --version: Print version number and exit - * \li --label: Label members of compound typed dataset. - * \li --simple: Use a machine-readable output format. - * \li --dim: Monitor changes in size of dataset dimensions only. - * \li --width=N: Set the number of columns to N for output. - A value of 0 sets the number of columns to the - maximum (65535). The default width is 80 columns. - * \li --polling=N: Set the polling interval to N (in seconds) when the - dataset will be checked for appended data. The default - polling interval is 1. - * \li --fields=\: - Display data for the fields specified in \ - for a compound data type. \ can be - specified as follows: + * \li --help Print a usage message and exit + * \li --version Print version number and exit + * \li --label Label members of compound typed dataset. + * \li --simple Use a machine-readable output format. + * \li --dim Monitor changes in size of dataset dimensions only. + * \li --width=N Set the number of columns to N for output. + A value of 0 sets the number of columns to the + maximum (65535). The default width is 80 columns. + * \li --polling=N Set the polling interval to N (in seconds) when the + dataset will be checked for appended data. The default + polling interval is 1. + * \li --fields=\ + Display data for the fields specified in \ + for a compound data type. \ can be + specified as follows:
    • 1) A comma-separated list of field names in a compound data type. "," is the separator for field names while "." is the separator @@ -54,10 +54,10 @@ * \subsection subsec_cltools_h5watch_objs Object OBJECT is specified as [\/\/\] - * \li \: Name of the HDF5 file. It may be preceded by path - separated by slashes to the specified HDF5 file. - * \li \: Path separated by slashes to the specified dataset - * \li \: Name of the dataset + * \li \ Name of the HDF5 file. It may be preceded by path + separated by slashes to the specified HDF5 file. + * \li \ Path separated by slashes to the specified dataset + * \li \ Name of the dataset * */ diff --git a/tools/src/h5diff/h5diff_main.h b/tools/src/h5diff/h5diff_main.h index 9da8d171226..e7dd2c8146e 100644 --- a/tools/src/h5diff/h5diff_main.h +++ b/tools/src/h5diff/h5diff_main.h @@ -198,9 +198,9 @@ obj1 /foo/mydataset[START;;COUNT;BLOCK] obj1 /foo/mydataset[START] - The STRIDE, COUNT, and BLOCK parameters are optional and will default to 1 in - each dimension. START is optional and will default to 0 in each dimension. - Each of START, STRIDE, COUNT, and BLOCK must be a comma-separated list of integers with + The \b STRIDE, \b COUNT, and \b BLOCK parameters are optional and will default to 1 in + each dimension. \b START is optional and will default to 0 in each dimension. + Each of \b START, \b STRIDE, \b COUNT, and \b BLOCK must be a comma-separated list of integers with one integer for each dimension of the dataset. Exit code: diff --git a/tools/src/h5dump/h5dump.h b/tools/src/h5dump/h5dump.h index ce13333f3ba..ed5594ec3b0 100644 --- a/tools/src/h5dump/h5dump.h +++ b/tools/src/h5dump/h5dump.h @@ -17,20 +17,180 @@ * \section sec_cltools_h5dump h5dump * * \subsection subsec_cltools_h5dump_intro Introduction - * With h5dump you can dump objects from an HDF5 file to another file. + * With h5dump you can ddisplay objects from an HDF5 file. * * \subsection subsec_cltools_h5dump_usage Usage - *

      h5dump [OPTIONS] [OBJECTS...]

      - * - * \subsection subsec_cltools_h5dump_objs Objects + *

      h5dump [OPTIONS] [files

      * * \subsection subsec_cltools_h5dump_error Error Report Option * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. - Optional value 2 also prints file open errors. - + * Optional value 2 also prints file open errors. + * * \subsection subsec_cltools_h5dump_options Options + * \li --help Print a usage message and exit + * \li --version Print version number and exit + * + * \subsection subsec_cltools_h5dump_options_file File Options + * \li --contents Print a list of the file contents and exit + Optional value 1 also prints attributes. + * \li --superblock Print the content of the super block + * \li --header Print the header only; no data is displayed + * \li --filedriver=D Specify which driver to open the file with + * \li --output=F Output raw data into file F + * \li --binary=B Binary file output, of form B + * \li --ddl=F Output ddl text into file F + Use blank(empty) filename F to suppress ddl display + * \li --page-buffer-size=N Set the page buffer cache size, N=non-negative integers + * \li --s3-cred=\ Supply S3 authentication information to "ros3" vfd. + \ :: "(,,)" + If absent or \ -> "(,,)", no authentication. + Has no effect if filedriver is not "ros3". + * \li --hdfs-attrs=\ Supply configuration information for HDFS file access. + For use with "--filedriver=hdfs" + \ :: (\,\, + \,\, + \) + Any absent attribute will use a default value. + * \li --vol-value Value (ID) of the VOL connector to use for opening the + HDF5 file specified + * \li --vol-name Name of the VOL connector to use for opening the + HDF5 file specified + * \li --vol-info VOL-specific info to pass to the VOL connector used for + opening the HDF5 file specified + If none of the above options are used to specify a VOL, then + the VOL named by \b HDF5_VOL_CONNECTOR (or the native VOL connector, + if that environment variable is unset) will be used + * \li--vfd-value Value (ID) of the VFL driver to use for opening the + HDF5 file specified + * \li --vfd-name Name of the VFL driver to use for opening the + HDF5 file specified + * \li --vfd-info VFD-specific info to pass to the VFL driver used for + opening the HDF5 file specified + * + * \subsection subsec_cltools_h5dump_options_obj Object Options + * \li --attribute=P Print the specified attribute + If an attribute name contains a slash (/), escape the + slash with a preceding backslash (\). + (See example section below.) + * \li --dataset=P Print the specified dataset + * \li --group=P Print the specified group and all members + * \li --soft-link=P Print the value(s) of the specified soft link + * \li --datatype=P Print the specified named datatype + * \li --any_path=P Print any attribute, dataset, group, datatype, or link that matches P + P can be the absolute path or just a relative path. + * \li --onlyattr Print the header and value of attributes + Optional value 0 suppresses printing attributes. + * \li --vds-view-first-missing Set the VDS bounds to first missing mapped elements. + * \li --vds-gap-size=N Set the missing file gap size, N=non-negative integers + * + * \subsection subsec_cltools_h5dump_options_prop Object Property Options + * \li --object-ids Print the object ids + * \li --properties Print dataset filters, storage layout and fill value + * \li --packedbits=L Print packed bits as unsigned integers, using mask + format L for an integer dataset specified with + option -d. L is a list of offset,length values, + separated by commas. Offset is the beginning bit in + the data value and length is the number of bits of + the mask. + * \li --region Print dataset pointed by region references + * + * \subsection subsec_cltools_h5dump_options_fmt Formatting Options + * \li --escape Escape non printing characters + * \li --string Print 1-byte integer datasets as ASCII + * \li --noindex Do not print array indices with the data + * \li --format=T Set the floating point output format + * \li --sort_by=Q Sort groups and attributes by index Q + * \li --sort_order=Z Sort groups and attributes by order Z + * \li --no-compact-subset Disable compact form of subsetting and allow the use + of "[" in dataset names. + * \li --width=N Set the number of columns of output. A value of 0 (zero) + sets the number of columns to the maximum (65535). + Default width is 80 columns. + * + * \subsection subsec_cltools_h5dump_options_xml XML Options + * \li --xml Output in XML using Schema + * \li --use-dtd Output in XML using DTD + * \li --xml-dtd=U Use the DTD or schema at U + * \li --xml-ns=S (XML Schema) Use qualified names n the XML + ":": no namespace, default: "hdf5:" + E.g., to dump a file called "-f", use h5dump -- -f * - * \subsubsection subsubsec_cltools_h5dump_options_args Flag Type Options + * \subsection subsec_cltools_h5dump_options_subset Subsetting Options + * Subsetting is available by using the following options with a dataset + * option. Subsetting is done by selecting a hyperslab from the data. + * Thus, the options mirror those for performing a hyperslab selection. + * One of the \b START, \b COUNT, \b STRIDE, or \b BLOCK parameters are mandatory if you do subsetting. + * The \b STRIDE, \b COUNT, and \b BLOCK parameters are optional and will default to 1 in + * each dimension. \b START is optional and will default to 0 in each dimension. + * + * \li --start=START Offset of start of subsetting selection + * \li --stride=STRIDE Hyperslab stride + * \li --count=COUNT Number of blocks to include in selection + * \li --block=BLOCK Size of block in hyperslab + * \b START, \b COUNT, \b STRIDE, and \b BLOCK - is a list of integers the number of which are equal to the + * number of dimensions in the dataspace being queried + * (Alternate compact form of subsetting is described in the Reference Manual) + * + * \subsubsection subsubsec_cltools_h5dump_options_args Option Argument Conventions + * \li D - is the file driver to use in opening the file. Acceptable values are available from + https://portal.hdfgroup.org/documentation/hdf5-docs/registered_virtual_file_drivers_vfds.html. + Without the file driver flag, the file will be opened with each driver in + turn and in the order specified above until one driver succeeds + in opening the file. + See examples below for family, split, and multi driver special file name usage. + + * \li F - is a filename. + * \li P - is the full path from the root group to the object. + * \li N - is an integer greater than 1. + * \li T - is a string containing the floating point format, e.g '%.3f' + * \li U - is a URI reference (as defined in [IETF RFC 2396], + updated by [IETF RFC 2732]) + * \li B - is the form of binary output: NATIVE for a memory type, FILE for the + file type, LE or BE for pre-existing little or big endian types. + Must be used with -o (output file) and it is recommended that + -d (dataset) is used. B is an optional argument, defaults to NATIVE + * \li Q - is the sort index type. It can be "creation_order" or "name" (default) + * \li Z - is the sort order type. It can be "descending" or "ascending" (default) + * + * \subsection subsec_cltools_h5dump_examples Usage Examples + + \li 1) Attribute foo of the group /bar_none in file quux.h5 + + h5dump -a /bar_none/foo quux.h5 + + Attribute "high/low" of the group /bar_none in the file quux.h5 + + h5dump -a "/bar_none/high\/low" quux.h5 + + \li 2) Selecting a subset from dataset /foo in file quux.h5 + + h5dump -d /foo -s "0,1" -S "1,1" -c "2,3" -k "2,2" quux.h5 + + \li 3) Saving dataset 'dset' in file quux.h5 to binary file 'out.bin' + using a little-endian type + + h5dump -d /dset -b LE -o out.bin quux.h5 + + \li 4) Display two packed bits (bits 0-1 and bits 4-6) in the dataset /dset + + h5dump -d /dset -M 0,1,4,3 quux.h5 + + \li 5) Dataset foo in files file1.h5 file2.h5 file3.h5 + + h5dump -d /foo file1.h5 file2.h5 file3.h5 + + \li 6) Dataset foo in split files splitfile-m.h5 splitfile-r.h5 + + h5dump -d /foo -f split splitfile + + \li 7) Dataset foo in multi files mf-s.h5, mf-b.h5, mf-r.h5, mf-g.h5, mf-l.h5 and mf-o.h5 + + h5dump -d /foo -f multi mf + + \li 8) Dataset foo in family files fam00000.h5 fam00001.h5 and fam00002.h5 + + h5dump -d /foo -f family fam%05d.h5 + * */ diff --git a/tools/src/h5import/h5import.h b/tools/src/h5import/h5import.h index d8a3a12cc37..465bc2bb8b1 100644 --- a/tools/src/h5import/h5import.h +++ b/tools/src/h5import/h5import.h @@ -107,10 +107,10 @@ *

      h5import -h[elp], OR h5import \ -c[onfig] \ [\ -c[config] \...] -o[utfile] \

      - * \subsection subsec_cltools_h5import_options Options + * \subsection subsec_cltools_h5import_help Help * \li -h[elp]: Print a usage message and exit * - * \subsubsection subsubsec_cltools_h5import_options_args Flag Type Options + * \subsubsection subsubsec_cltools_h5import_options Program Options * \li \: Name of the Input file(s), containing a single n-dimensional floating point or integer array @@ -142,7 +142,7 @@ The configuration file may have the following keywords each followed by an acceptable value. -
      Required KEYWORDS
      + * \subsubsection subsubsec_cltools_h5import_config_req Required KEYWORDS * \li PATH * \li INPUT-CLASS * \li INPUT-SIZE @@ -152,7 +152,7 @@ * \li OUTPUT-CLASS * \li OUTPUT-SIZE -
      Optional KEYWORDS
      + * \subsubsection subsubsec_cltools_h5import_config_opt Optional KEYWORDS * \li OUTPUT-ARCHITECTURE * \li OUTPUT-BYTE-ORDER * \li CHUNKED-DIMENSION-SIZES @@ -162,7 +162,7 @@ * \li MAXIMUM-DIMENSIONS -
      Values for keywords
      + * \subsubsection subsubsec_cltools_h5import_config_val Values for keywords * \li PATH: Strings separated by spaces to represent the path of the data-set. If the groups in @@ -204,7 +204,6 @@ * \li INPUT-SIZE: Integer denoting the size of the input data (8, 16, 32, 64). - For floating point, INPUT-SIZE can be 32 or 64. For integers (signed and unsigned) @@ -295,7 +294,8 @@ DIMENSION size for that particular dimension. * \subsection subsec_cltools_h5import_examples Usage Examples - * \li 1. Configuration File may look like: + * \li Configuration File may look like + * \code PATH work h5 pkamat First-set INPUT-CLASS TEXTFP RANK 3 @@ -304,8 +304,8 @@ OUTPUT-SIZE 64 OUTPUT-ARCHITECTURE IEEE OUTPUT-BYTE-ORDER LE - CHUNKED-DIMENSION-SIZES 2 2 2 -
      + CHUNKED-DIMENSION-SIZES 2 2 2 + \endcode The above configuration will accept a floating point array (5 x 2 x 4) in an ASCII file with the rank and dimension sizes specified and will save it in a chunked data-set (of pattern @@ -313,18 +313,19 @@ and IEEE architecture. The dataset will be stored at "/work/h5/pkamat/First-set" - * \li 2. Another configuration could be: + * \li Another configuration could be + * \code PATH Second-set INPUT-CLASS IN RANK 5 DIMENSION-SIZES 6 3 5 2 4 OUTPUT-CLASS IN OUTPUT-SIZE 32 - CHUNKED-DIMENSION-SIZES 2 2 2 2 2 + CHUNKED-DIMENSION-SIZES 2 2 2 2 2 EXTENDIBLE-DATASET 1 3 COMPRESSION-TYPE GZIP COMPRESSION-PARAM 7 -
      + \endcode The above configuration will accept an integer array (6 X 3 X 5 x 2 x 4) in a binary file with the rank and dimension sizes specified and will save it in a chunked data-set diff --git a/tools/src/h5jam/h5jam.h b/tools/src/h5jam/h5jam.h index 8eeba6bbdd0..d6d91b60371 100644 --- a/tools/src/h5jam/h5jam.h +++ b/tools/src/h5jam/h5jam.h @@ -17,8 +17,8 @@ * \section sec_cltools_h5jam h5jam and h5unjam * * \subsection subsec_cltools_h5jam_intro Introduction - * h5jam: Adds user block to front of an HDF5 file and creates a new concatenated file. - * h5unjam: Splits user file and HDF5 file into two files: user block data and HDF5 data. + * \li h5jam: Adds user block to front of an HDF5 file and creates a new concatenated file. + * \li h5unjam: Splits user file and HDF5 file into two files: user block data and HDF5 data. * * \subsection subsec_cltools_h5jam_usage Usage *

      h5jam -i \ -u \ [-o \] [--clobber]

      diff --git a/tools/src/h5ls/h5ls.h b/tools/src/h5ls/h5ls.h index e59de0e035e..2b18379ac0b 100644 --- a/tools/src/h5ls/h5ls.h +++ b/tools/src/h5ls/h5ls.h @@ -34,14 +34,14 @@ Optional value 2 also prints file open errors. * \subsection subsec_cltools_h5ls_options Options - * \li --help: Print a usage message and exit - * \li --address: Print raw data address. If dataset is contiguous, address + * \li --help Print a usage message and exit + * \li --address Print raw data address. If dataset is contiguous, address is offset in file of beginning of raw data. If chunked, returned list of addresses indicates offset of each chunk. Must be used with -v, --verbose option. Provides no information for non-dataset objects. - * \li --data: Print the values of datasets - * \li --follow-symlinks: + * \li --data Print the values of datasets + * \li --follow-symlinks Follow symbolic links (soft links and external links) to display target object information. Without this option, h5ls identifies a symbolic link @@ -49,8 +49,8 @@ assigned to the symbolic link; it does not provide any information regarding the target object or determine whether the link is a dangling link. - * \li --no-dangling-links: - Must be used with --follow-symlinks option; + * \li --no-dangling-links + Must be used with --follow-symlinks option; otherwise, h5ls shows error message and returns an exit code of 1. Check for any symbolic links (soft links or external links) @@ -58,49 +58,49 @@ or named datatype). If any dangling link is found, this situation is treated as an error and h5ls returns an exit code of 1. - * \li --full: Print full path names instead of base names - * \li --group: Show information about a group, not its contents - * \li --label: Label members of compound datasets - * \li --recursive: List all groups recursively, avoiding cycles - * \li --string: Print 1-byte integer datasets as ASCII - * \li --simple: Use a machine-readable output format - * \li --width=N: Set the number of columns of output - * \li --verbose: Generate more verbose output - * \li --version: Print version number and exit - * \li --page-buffer-size=N: Set the page buffer cache size, N=non-negative integers - * \li --vfd=DRIVER: Use the specified virtual file driver - * \li --hexdump: Show raw data in hexadecimal format - * \li --s3-cred=C: Supply S3 authentication information to "ros3" vfd. + * \li --full Print full path names instead of base names + * \li --group Show information about a group, not its contents + * \li --label Label members of compound datasets + * \li --recursive List all groups recursively, avoiding cycles + * \li --string Print 1-byte integer datasets as ASCII + * \li --simple Use a machine-readable output format + * \li --width=N Set the number of columns of output + * \li --verbose Generate more verbose output + * \li --version Print version number and exit + * \li --page-buffer-size=N Set the page buffer cache size, N=non-negative integers + * \li --vfd=DRIVER Use the specified virtual file driver + * \li --hexdump Show raw data in hexadecimal format + * \li --s3-cred=C Supply S3 authentication information to "ros3" vfd. Accepts tuple of "(\,\,\)". If absent or C-\>"(,,)", defaults to no-authentication. Has no effect if vfd flag not set to "ros3". - * \li --hdfs-attrs=A: Supply configuration information to Hadoop VFD. + * \li --hdfs-attrs=A Supply configuration information to Hadoop VFD. Accepts tuple of (\,\, ...\,\,\) If absent or A == '(,,,,)', all default values are used. Has no effect if vfd flag is not 'hdfs'. - * \li --vol-value: Value (ID) of the VOL connector to use for opening the + * \li --vol-value Value (ID) of the VOL connector to use for opening the HDF5 file specified - * \li --vol-name: Name of the VOL connector to use for opening the + * \li --vol-name Name of the VOL connector to use for opening the HDF5 file specified - * \li --vol-info: VOL-specific info to pass to the VOL connector used for + * \li --vol-info VOL-specific info to pass to the VOL connector used for opening the HDF5 file specified If none of the above options are used to specify a VOL, then the VOL named by HDF5_VOL_CONNECTOR (or the native VOL connector, if that environment variable is unset) will be used - * \li --vfd-value: Value (ID) of the VFL driver to use for opening the + * \li --vfd-value Value (ID) of the VFL driver to use for opening the HDF5 file specified - * \li --vfd-name: Name of the VFL driver to use for opening the + * \li --vfd-name Name of the VFL driver to use for opening the HDF5 file specified - * \li --vfd-info: VFD-specific info to pass to the VFL driver used for + * \li --vfd-info VFD-specific info to pass to the VFL driver used for opening the HDF5 file specified * * \subsubsection subsubsec_cltools_h5ls_options_depre Deprecated Options The following options have been removed in HDF5 1.12. Use the indicated replacement option in all work. - * \li --external: Follow external links. + * \li --external Follow external links. Replaced by --follow-symlinks. - * \li --errors: Show all HDF5 error reporting + * \li --errors Show all HDF5 error reporting Replaced by --enable-error-stack. * */ diff --git a/tools/src/h5repack/h5repack.h b/tools/src/h5repack/h5repack.h index 128f0ca0d99..f3b54a74d83 100644 --- a/tools/src/h5repack/h5repack.h +++ b/tools/src/h5repack/h5repack.h @@ -30,67 +30,69 @@ * Optional value 2 also prints file open errors. * * \subsection subsec_cltools_h5repack_options Options - * \li --help : Print a usage message and exit - * \li --verbose=N : Verbose mode, print object information. + * \li --help : Print a usage message and exit + * \li --verbose=N : Verbose mode, print object information. * N - is an integer greater than 1, 2 displays read/write timing - * \li --version : Print version number and exit - * \li --native : Use a native HDF5 type when repacking - * \li --page-buffer-size=N : Set the page buffer cache size, N=non-negative integers - * \li --src-vol-value : Value (ID) of the VOL connector to use for opening the + * \li --version : Print version number and exit + * \li --native : Use a native HDF5 type when repacking + * \li --page-buffer-size=N : Set the page buffer cache size, N=non-negative integers + * \li --src-vol-value : Value (ID) of the VOL connector to use for opening the * input HDF5 file specified - * \li --src-vol-name : Name of the VOL connector to use for opening the input + * \li --src-vol-name : Name of the VOL connector to use for opening the input * HDF5 file specified - * \li --src-vol-info : VOL-specific info to pass to the VOL connector used for + * \li --src-vol-info : VOL-specific info to pass to the VOL connector used for * opening the input HDF5 file specified - * \li --dst-vol-value : Value (ID) of the VOL connector to use for opening the + * \li --dst-vol-value : Value (ID) of the VOL connector to use for opening the * output HDF5 file specified - * \li --dst-vol-name : Name of the VOL connector to use for opening the output + * \li --dst-vol-name : Name of the VOL connector to use for opening the output * HDF5 file specified - * \li --dst-vol-info : VOL-specific info to pass to the VOL connector used for + * \li --dst-vol-info : VOL-specific info to pass to the VOL connector used for * opening the output HDF5 file specified - * \li --src-vfd-value : Value (ID) of the VFL driver to use for opening the + * \li --src-vfd-value : Value (ID) of the VFL driver to use for opening the * input HDF5 file specified - * \li --src-vfd-name : Name of the VFL driver to use for opening the input + * \li --src-vfd-name : Name of the VFL driver to use for opening the input * HDF5 file specified - * \li --src-vfd-info : VFD-specific info to pass to the VFL driver used for + * \li --src-vfd-info : VFD-specific info to pass to the VFL driver used for * opening the input HDF5 file specified - * \li --dst-vfd-value : Value (ID) of the VFL driver to use for opening the + * \li --dst-vfd-value : Value (ID) of the VFL driver to use for opening the * output HDF5 file specified - * \li --dst-vfd-name : Name of the VFL driver to use for opening the output + * \li --dst-vfd-name : Name of the VFL driver to use for opening the output * HDF5 file specified - * \li --dst-vfd-info : VFD-specific info to pass to the VFL driver used for + * \li --dst-vfd-info : VFD-specific info to pass to the VFL driver used for * opening the output HDF5 file specified - * \li --latest : Use latest version of file format + * \li --latest : Use latest version of file format * This option will take precedence over the options * --low and --high - * \li --low=BOUND : The low bound for library release versions to use + * \li --low=BOUND : The low bound for library release versions to use * when creating objects in the file * (default is #H5F_LIBVER_EARLIEST) - * \li --high=BOUND : The high bound for library release versions to use + * \li --high=BOUND : The high bound for library release versions to use * when creating objects in the file * (default is #H5F_LIBVER_LATEST) - * \li --merge : Follow external soft link recursively and merge data - * \li --prune : Do not follow external soft links and remove link - * \li --merge --prune : Follow external link, merge data and remove dangling link - * \li --compact=L1 : Maximum number of links in header messages - * \li --indexed=L2 : Minimum number of links in the indexed format - * \li --ssize=S[:F] : Shared object header message minimum size - * \li --minimum=M : Do not apply the filter to datasets smaller than M - * \li --file=E : Name of file E with the -f and -l options - * \li --ublock=U : Name of file U with user block data to be added - * \li --block=B : Size of user block to be added + * \li --merge : Follow external soft link recursively and merge data + * \li --prune : Do not follow external soft links and remove link + * \li --merge --prune : Follow external link, merge data and remove dangling link + * \li --compact=L1 : Maximum number of links in header messages + * \li --indexed=L2 : Minimum number of links in the indexed format + * \li --ssize=S[:F] : Shared object header message minimum size + * \li --minimum=M : Do not apply the filter to datasets smaller than M + * \li --file=E : Name of file E with the -f and -l options + * \li --ublock=U : Name of file U with user block data to be added + * \li --block=B : Size of user block to be added * \li --metadata_block_size=A : Metadata block size for #H5Pset_meta_block_size - * \li --threshold=T : Threshold value for #H5Pset_alignment - * \li --alignment=A : Alignment value for #H5Pset_alignment - * \li --sort_by=Q : Sort groups and attributes by index Q - * \li --sort_order=Z : Sort groups and attributes by order Z - * \li --filter=FILT : Filter type - * \li --layout=LAYT : Layout type + * \li --threshold=T : Threshold value for #H5Pset_alignment + * \li --alignment=A : Alignment value for #H5Pset_alignment + * \li --sort_by=Q : Sort groups and attributes by index Q + * \li --sort_order=Z : Sort groups and attributes by order Z + * \li --filter=FILT : Filter type + * \li --layout=LAYT : Layout type * \li --fs_strategy=FS_STRATEGY : File space management strategy for - * #H5Pset_file_space_strategy \li --fs_persist=FS_PERSIST : Persisting or not - * persisting free-space for #H5Pset_file_space_strategy \li ---fs_threshold=FS_THRESHOLD - * : Free-space section threshold for #H5Pset_file_space_strategy \li - * --fs_pagesize=FS_PAGESIZE : File space page size for #H5Pset_file_space_page_size + * #H5Pset_file_space_strategy + * \li --fs_persist=FS_PERSIST : Persisting or not + * persisting free-space for #H5Pset_file_space_strategy + * \li ---fs_threshold=FS_THRESHOLD : Free-space section + * threshold for #H5Pset_file_space_strategy + * \li --fs_pagesize=FS_PAGESIZE : File space page size for #H5Pset_file_space_page_size * * \subsubsection subsubsec_cltools_h5repack_options_args Arguments to Certain Options * \li M - is an integer greater than 1, size of dataset in bytes (default is 0) @@ -198,8 +200,12 @@ *
    • COMPA (no parameter)
      • *
    • CONTI (no parameter)
    * + * \subsubsection subsubsec_cltools_h5repack_options_note NOTE + * The environment variable H5TOOLS_BUFSIZEcan be set to + * the number of MBs to change the default hyperslab buffer size from 32MB. + * \code setenv H5TOOLS_BUFSIZE=64 to double the hyperslab buffer. \endcode + * * \subsection subsec_cltools_h5repack_examples Usage Examples - * Examples of use: * * \li 1) h5repack -v -f GZIP=1 file1 file2 * diff --git a/tools/src/misc/h5clear.h b/tools/src/misc/h5clear.h index 287a3034e8b..5ede807c55c 100644 --- a/tools/src/misc/h5clear.h +++ b/tools/src/misc/h5clear.h @@ -14,7 +14,7 @@ /** \page H5TOOL_CR_UG The HDF5 h5clear Tool * - * \section sec_cltools_h5clear h5stat + * \section sec_cltools_h5clear h5clear * * \subsection subsec_cltools_h5clear_intro Introduction * With h5clear you can clear the superblock status flag field, removes metadata cache image, prints From 373d9320eac434786fe421218734927da8c2c42d Mon Sep 17 00:00:00 2001 From: github-actions <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon, 24 Jun 2024 22:41:32 +0000 Subject: [PATCH 09/24] Committing clang-format changes --- tools/src/h5dump/h5dump.h | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/tools/src/h5dump/h5dump.h b/tools/src/h5dump/h5dump.h index ed5594ec3b0..369f2755ac4 100644 --- a/tools/src/h5dump/h5dump.h +++ b/tools/src/h5dump/h5dump.h @@ -132,12 +132,11 @@ * (Alternate compact form of subsetting is described in the Reference Manual) * * \subsubsection subsubsec_cltools_h5dump_options_args Option Argument Conventions - * \li D - is the file driver to use in opening the file. Acceptable values are available from - https://portal.hdfgroup.org/documentation/hdf5-docs/registered_virtual_file_drivers_vfds.html. - Without the file driver flag, the file will be opened with each driver in - turn and in the order specified above until one driver succeeds - in opening the file. - See examples below for family, split, and multi driver special file name usage. + * \li D - is the file driver to use in opening the file. Acceptable values are available + from https://portal.hdfgroup.org/documentation/hdf5-docs/registered_virtual_file_drivers_vfds.html. Without + the file driver flag, the file will be opened with each driver in turn and in the order specified above until + one driver succeeds in opening the file. See examples below for family, split, and multi driver special file + name usage. * \li F - is a filename. * \li P - is the full path from the root group to the object. From 5c09f397ed0efef57bffdacfd7a28b561e695e2e Mon Sep 17 00:00:00 2001 From: Allen Byrne Date: Tue, 25 Jun 2024 10:50:09 -0500 Subject: [PATCH 10/24] Cleanup text --- hl/tools/h5watch/h5watch.h | 6 +- tools/src/h5copy/h5copy.h | 2 +- tools/src/h5diff/h5diff_main.h | 27 +- tools/src/h5dump/h5dump.h | 2 +- tools/src/h5format_convert/h5format_convert.h | 10 +- tools/src/h5import/h5import.h | 357 +++++++++--------- tools/src/h5ls/h5ls.h | 2 +- tools/src/h5repack/h5repack.h | 122 +++--- tools/src/h5stat/h5stat.h | 36 +- tools/src/misc/h5clear.h | 12 +- tools/src/misc/h5mkgrp.h | 22 +- 11 files changed, 294 insertions(+), 304 deletions(-) diff --git a/hl/tools/h5watch/h5watch.h b/hl/tools/h5watch/h5watch.h index 9fb19789776..0d6b7c0971e 100644 --- a/hl/tools/h5watch/h5watch.h +++ b/hl/tools/h5watch/h5watch.h @@ -28,7 +28,7 @@ * \subsection subsec_cltools_h5watch_options Options * \li --help Print a usage message and exit - * \li --version Print version number and exit + * \li --version Print the library version number and exit * \li --label Label members of compound typed dataset. * \li --simple Use a machine-readable output format. * \li --dim Monitor changes in size of dataset dimensions only. @@ -47,13 +47,13 @@ for field names while "." is the separator for a nested field.
  • 2) A single field name in a compound data type. - Can use this option multiple times.
    • + This option can be used multiple times. Note that backslash is the escape character to avoid characters in field names that conflict with the tool's separators. * \subsection subsec_cltools_h5watch_objs Object - OBJECT is specified as [\/\/\] + OBJECT is specified as [\/\/\] * \li \ Name of the HDF5 file. It may be preceded by path separated by slashes to the specified HDF5 file. * \li \ Path separated by slashes to the specified dataset diff --git a/tools/src/h5copy/h5copy.h b/tools/src/h5copy/h5copy.h index c9b30c52ea7..0956ee6ef3b 100644 --- a/tools/src/h5copy/h5copy.h +++ b/tools/src/h5copy/h5copy.h @@ -37,7 +37,7 @@ * \li --help Print a usage message and exit * \li --parents No error if existing, make parent groups as needed * \li --verbose Print information about OBJECTS and OPTIONS - * \li --version Print version number and exit + * \li --version Print the library version number and exit * \li --flag Flag type * * \subsubsection subsubsec_cltools_h5copy_options_args Flag Type Options diff --git a/tools/src/h5diff/h5diff_main.h b/tools/src/h5diff/h5diff_main.h index e7dd2c8146e..293622248ea 100644 --- a/tools/src/h5diff/h5diff_main.h +++ b/tools/src/h5diff/h5diff_main.h @@ -32,23 +32,17 @@ Optional value 2 also prints file open errors. * \subsection subsec_cltools_h5diff_options Options - * \li --help - Print a usage message and exit. - * \li --version - Print version number and exit. - * \li --report - Report mode. Print differences. - * \li --verbose - Verbose mode. Print differences information and list of objects. - * \li --verbose=N - Verbose mode with level. Print differences and list of objects. + * \li --help Print a usage message and exit. + * \li --version Print the library version number and exit. + * \li --report Report mode. Print differences. + * \li --verbose Verbose mode. Print differences information and list of objects. + * \li --verbose=N Verbose mode with level. Print differences and list of objects. Level of detail depends on value of N:
    • 0 : Identical to '-v' or '--verbose'.
    • 1 : All level 0 information plus one-line attribute status summary.
    • 2 : All level 1 information plus extended attribute status report.
    • 3 : All level 2 information plus file names.
    - * \li --quiet - Quiet mode. Do not produce output. + * \li --quiet Quiet mode. Do not produce output. * \li --page-buffer-size=N Set the page buffer cache size, N=non-negative integers * \li --vol-value-1 Value (ID) of the VOL connector to use for opening the first HDF5 file specified @@ -106,12 +100,9 @@ resolve to an existing object (dataset, group, or named datatype). If any dangling link is found, this situation is treated as an error and h5diff returns an exit code of 2. - * \li --compare - List objects that are not comparable - * \li --nan - Avoid NaNs detection - * \li --count=C - Print differences up to C. C must be a positive integer. + * \li --compare List objects that are not comparable + * \li --nan Avoid NaNs detection + * \li --count=C Print differences up to C. C must be a positive integer. * \li --delta=D Print difference if (|a-b| > D). D must be a positive number. Where a is the data point value in file1 and b is the data point value in file2. diff --git a/tools/src/h5dump/h5dump.h b/tools/src/h5dump/h5dump.h index 369f2755ac4..8c85ccc9229 100644 --- a/tools/src/h5dump/h5dump.h +++ b/tools/src/h5dump/h5dump.h @@ -28,7 +28,7 @@ * * \subsection subsec_cltools_h5dump_options Options * \li --help Print a usage message and exit - * \li --version Print version number and exit + * \li --version Print the library version number and exit * * \subsection subsec_cltools_h5dump_options_file File Options * \li --contents Print a list of the file contents and exit diff --git a/tools/src/h5format_convert/h5format_convert.h b/tools/src/h5format_convert/h5format_convert.h index 03a2911db84..490aaf6bfd6 100644 --- a/tools/src/h5format_convert/h5format_convert.h +++ b/tools/src/h5format_convert/h5format_convert.h @@ -27,11 +27,11 @@ Optional value 2 also prints file open errors. * \subsection subsec_cltools_h5format_convert_options Options - * \li --help: Print a usage message and exit - * \li --version: Print version number and exit - * \li --verbose: Turn on verbose mode - * \li --dname=dataset_name: Pathname for the dataset - * \li --noop: Perform all the steps except the actual conversion + * \li --help Print a usage message and exit + * \li --version Print the library version number and exit + * \li --verbose Turn on verbose mode + * \li --dname=dataset_name Pathname for the dataset + * \li --noop Perform all the steps except the actual conversion * * \subsubsection subsubsec_cltools_h5format_convert_examples Usage Examples * \li 1) h5format_convert -dname=/group/dataset file_name diff --git a/tools/src/h5import/h5import.h b/tools/src/h5import/h5import.h index 465bc2bb8b1..00454220305 100644 --- a/tools/src/h5import/h5import.h +++ b/tools/src/h5import/h5import.h @@ -25,166 +25,166 @@ * * \subsection subsec_cltools_h5import_intro Introduction * With h5import you can convert data stored in one or more ASCII or binary files - into one or more datasets (in accordance with the - user-specified type and storage properties) in an existing - or new HDF5 file. + into one or more datasets (in accordance with the + user-specified type and storage properties) in an existing + or new HDF5 file. * * \subsection subsec_cltools_h5import_desc Description - * The primary objective of the utility is to convert floating - point or integer data stored in ASCII text or binary form - into a data-set according to the type and storage properties - specified by the user. The utility can also accept ASCII - text files and store the contents in a compact form as an - array of one-dimensional strings. - - The input data to be written as a data-set can be provided - to the utility in one of the following forms: - \li 1. ASCII text file with numeric data (floating point or - integer data). - \li 2. Binary file with native floating point data (32-bit or - 64-bit) - \li 3. Binary file with native integer (signed or unsigned) - data (8-bit or 16-bit or 32-bit or 64-bit). - \li 4. ASCII text file containing strings (text data). - - Every input file is associated with a configuration file - also provided as an input to the utility. (See Section - "CONFIGURATION FILE" to know how it is to be organized). - The class, size and dimensions of the input data is - specified in this configuration file. A point to note is - that the floating point data in the ASCII text file may be - organized in the fixed floating form (for example 323.56) - or in a scientific notation (for example 3.23E+02). A - different input-class specification is to be used for both - forms. - - The utility extracts the input data from the input file - according to the specified parameters and saves it into - an H5 dataset. - - The user can specify output type and storage properties in - the configuration file. The user is required to specify the - path of the dataset. If the groups in the path leading to - the data-set do not exist, the groups will be created by the - utility. If no group is specified, the dataset will be - created under the root group. - - In addition to the name, the user is also required to - provide the class and size of output data to be written to - the dataset and may optionally specify the output-architecture, - and the output-byte-order. If output-architecture is not - specified the default is NATIVE. Output-byte-orders are fixed - for some architectures and may be specified only if output- - architecture is IEEE, UNIX or STD. - - Also, layout and other storage properties such as - compression, external storage and extendible data-sets may be - optionally specified. The layout and storage properties - denote how raw data is to be organized on the disk. If these - options are not specified the default is Contiguous layout - and storage. - - The dataset can be organized in any of the following ways: - \li 1. Contiguous. - \li 2. Chunked. - \li 3. External Storage File (has to be contiguous) - \li 4. Extendible data sets (has to be chunked) - \li 5. Compressed. (has to be chunked) - \li 6. Compressed & Extendible (has to be chunked) - - If the user wants to store raw data in a non-HDF file then - the external storage file option is to be used and the name - of the file is to be specified. - - If the user wants the dimensions of the data-set to be - unlimited, the extendible data set option can be chosen. - - The user may also specify the type of compression and the - level to which the data set must be compresses by setting - the compressed option. + * The primary objective of the utility is to convert floating + point or integer data stored in \b ASCII text or binary form + into a data-set according to the type and storage properties + specified by the user. The utility can also accept \b ASCII + text files and store the contents in a compact form as an + array of one-dimensional strings. + + The input data to be written as a data-set can be provided + to the utility in one of the following forms: + \li 1. ASCII text file with numeric data (floating point or + integer data) + \li 2. Binary file with native floating point data (32-bit or + 64-bit) + \li 3. Binary file with native integer (signed or unsigned) + data (8-bit or 16-bit or 32-bit or 64-bit) + \li 4. ASCII text file containing strings (text data) + + Every input file is associated with a configuration file + also provided as an input to the utility. (See Section + \ref subsec_cltools_h5import_config to know how it is to be organized). + The class, size and dimensions of the input data is + specified in this configuration file. A point to note is + that the floating point data in the \b ASCII text file may be + organized in the fixed floating form (for example 323.56) + or in a scientific notation (for example 3.23E+02). A + different input-class specification is to be used for both + forms. + + The utility extracts the input data from the input file + according to the specified parameters and saves it into + an HDF5 dataset. + + The user can specify output type and storage properties in + the configuration file. The user is required to specify the + path of the dataset. If the groups in the path leading to + the dataset do not exist, the groups will be created by the + utility. If no group is specified, the dataset will be + created under the root group. + + In addition to the name, the user is also required to + provide the class and size of output data to be written to + the dataset and may optionally specify the output-architecture, + and the output-byte-order. If output-architecture is not + specified the default is \b NATIVE. Output-byte-orders are fixed + for some architectures and may be specified only if output- + architecture is \b IEEE, \b UNIX or \b STD. + + Also, layout and other storage properties such as + compression, external storage and extendible datasets may be + optionally specified. The layout and storage properties + denote how raw data is to be organized on the disk. If these + options are not specified, the default is \b Contiguous layout + and storage. + + The dataset can be organized in any of the following ways: + \li 1. Contiguous + \li 2. Chunked + \li 3. External Storage File (has to be contiguous) + \li 4. Extendible data sets (has to be chunked) + \li 5. Compressed (has to be chunked) + \li 6. Compressed & Extendible (has to be chunked) + + If the user wants to store raw data in a non-HDF file then + the external storage file option is to be used and the name + of the file is to be specified. + + If the user wants the dimensions of the data-set to be + unlimited, the extendible data set option can be chosen. + + The user may also specify the type of compression and the + level to which the data set must be compresses by setting + the compressed option. * * \subsection subsec_cltools_h5import_usage Usage *

    h5import -h[elp], OR h5import \ -c[onfig] \ [\ -c[config] \...] -o[utfile] \

    * \subsection subsec_cltools_h5import_help Help - * \li -h[elp]: Print a usage message and exit + * \li -h[elp] Print a usage message and exit * * \subsubsection subsubsec_cltools_h5import_options Program Options - * \li \: - Name of the Input file(s), containing a - single n-dimensional floating point or integer array - in either ASCII text, native floating point(32-bit - or 64-bit) or native integer(8-bit or 16-bit or - 32-bit or 64-bit). Data to be specified in the order - of fastest changing dimensions first. - - * \li -c[config] \: - Every input file should be associated with a - configuration file and this is done by the -c option. - \ is the name of the configuration file. - (See Section \ref subsec_cltools_h5import_config) - - * \li -o[utfile] \: - Name of the HDF5 output file. Data from one or more - input files are stored as one or more data sets in - \. The output file may be an existing file or - it maybe new in which case it will be created. + * \li \ + Name of the Input file(s), containing a + single n-dimensional floating point or integer array + in either ASCII text, native floating point(32-bit + or 64-bit) or native integer(8-bit or 16-bit or + 32-bit or 64-bit). Data to be specified in the order + of fastest changing dimensions first. + + * \li -c[config] \ + Every input file should be associated with a + configuration file and this is done by the -c option. + \ is the name of the configuration file. + (See Section \ref subsec_cltools_h5import_config). + + * \li -o[utfile] \ + Name of the HDF5 output file. Data from one or more + input files are stored as one or more data sets in + \. The output file may be an existing file or + it maybe new in which case it will be created. * \subsection subsec_cltools_h5import_config Configuration File - The configuration file is an ASCII text file and must be - the ddl formatted file (without data values) produced by h5dump - when used with the options '-o outfilename -b' of a single dataset (-d) - OR organized as "CONFIG-KEYWORD VALUE" pairs, one pair on each - line. + The configuration file is an ASCII text file and must be + the ddl formatted file (without data values) produced by \b h5dump + when used with the options \code -o outfilename -b \endcode of a single dataset (-d) + OR organized as CONFIG-KEYWORD VALUE pairs, one pair on each + line. - The configuration file may have the following keywords each - followed by an acceptable value. + The configuration file may have the following keywords each + followed by an acceptable value. * \subsubsection subsubsec_cltools_h5import_config_req Required KEYWORDS - * \li PATH - * \li INPUT-CLASS - * \li INPUT-SIZE - * \li INPUT-BYTE-ORDER - * \li RANK - * \li DIMENSION-SIZES - * \li OUTPUT-CLASS - * \li OUTPUT-SIZE + * \li PATH + * \li INPUT-CLASS + * \li INPUT-SIZE + * \li INPUT-BYTE-ORDER + * \li RANK + * \li DIMENSION-SIZES + * \li OUTPUT-CLASS + * \li OUTPUT-SIZE * \subsubsection subsubsec_cltools_h5import_config_opt Optional KEYWORDS - * \li OUTPUT-ARCHITECTURE - * \li OUTPUT-BYTE-ORDER - * \li CHUNKED-DIMENSION-SIZES - * \li COMPRESSION-TYPE - * \li COMPRESSION-PARAM - * \li EXTERNAL-STORAGE - * \li MAXIMUM-DIMENSIONS - + * \li OUTPUT-ARCHITECTURE + * \li OUTPUT-BYTE-ORDER + * \li CHUNKED-DIMENSION-SIZES + * \li COMPRESSION-TYPE + * \li COMPRESSION-PARAM + * \li EXTERNAL-STORAGE + * \li MAXIMUM-DIMENSIONS * \subsubsection subsubsec_cltools_h5import_config_val Values for keywords - * \li PATH: + * \li PATH Strings separated by spaces to represent the path of the data-set. If the groups in the path do not exist, they will be created. For example, - PATH grp1/grp2/dataset1 - PATH: keyword - grp1: group under the root. If - non-existent will be created. - grp2: group under grp1. If +
    • PATH grp1/grp2/dataset1
      • +
    • PATH: keyword
      • +
    • grp1: group under the root. If + non-existent will be created
      • +
    • grp2: group under grp1. If non-existent will be created - under grp1. - dataset1: the name of the data-set - to be created. + under grp1
      • +
    • dataset1: the name of the data-set + to be created
    - * \li INPUT-CLASS: + * \li INPUT-CLASS String denoting the type of input data. - ("TEXTIN", "TEXTFP", "FP", "IN", - "STR", "TEXTUIN", "UIN"). - INPUT-CLASS "TEXTIN" denotes an ASCII text +
    • "TEXTIN
    • TEXTFP
      • +
    • FP
    • IN
    • STR
      • +
    • TEXTUIN
    • UIN
    + \b INPUT-CLASS "TEXTIN" denotes an ASCII text file with signed integer data in ASCII form, - INPUT-CLASS "TEXTUIN" denotes an ASCII text + \b INPUT-CLASS "TEXTUIN" denotes an ASCII text file with unsigned integer data in ASCII form, "TEXTFP" denotes an ASCII text file containing floating point data in the fixed notation @@ -195,61 +195,61 @@ & "STR" denotes an ASCII text file the contents of which should be stored as an 1-D array of strings. - If INPUT-CLASS is "STR", then RANK, - DIMENSION-SIZES, OUTPUT-CLASS, OUTPUT-SIZE, - OUTPUT-ARCHITECTURE and OUTPUT-BYTE-ORDER + If \b INPUT-CLASS is "STR", then \b RANK, + \b DIMENSION-SIZES, \b OUTPUT-CLASS, \b OUTPUT-SIZE, + \b OUTPUT-ARCHITECTURE and \b OUTPUT-BYTE-ORDER will be ignored. - * \li INPUT-SIZE: + * \li INPUT-SIZE Integer denoting the size of the input data (8, 16, 32, 64). - For floating point, - INPUT-SIZE can be 32 or 64. - For integers (signed and unsigned) - INPUT-SIZE can be 8, 16, 32 or 64. +
    • For floating point, + \b INPUT-SIZE can be 32 or 64.
      • +
    • For integers (signed and unsigned) + \b INPUT-SIZE can be 8, 16, 32 or 64.
    - * \li RANK: + * \li RANK Integer denoting the number of dimensions. - * \li DIMENSION-SIZES: + * \li DIMENSION-SIZES Integers separated by spaces to denote the dimension sizes for the no. of dimensions determined by rank. - * \li OUTPUT-CLASS: + * \li OUTPUT-CLASS String dentoting data type of the dataset to be written ("IN","FP", "UIN") - * \li OUTPUT-SIZE: + * \li OUTPUT-SIZE Integer denoting the size of the data in the output dataset to be written. - If OUTPUT-CLASS is "FP", OUTPUT-SIZE can be + If \b OUTPUT-CLASS is "FP", \b OUTPUT-SIZE can be 32 or 64. - If OUTPUT-CLASS is "IN" or "UIN", OUTPUT-SIZE + If \b OUTPUT-CLASS is "IN" or "UIN", \b OUTPUT-SIZE can be 8, 16, 32 or 64. - * \li OUTPUT-ARCHITECTURE: - STRING denoting the type of output + * \li OUTPUT-ARCHITECTURE + \b STRING denoting the type of output architecture. Can accept the following values - STD - IEEE - INTEL - CRAY - MIPS - ALPHA - NATIVE (default) - UNIX - - * \li OUTPUT-BYTE-ORDER: +
    • STD
      • +
    • IEEE
      • +
    • INTEL + CRAY
      • +
    • MIPS
      • +
    • ALPHA
      • +
    • NATIVE (default)
      • +
    • UNIX
    + + * \li OUTPUT-BYTE-ORDER String denoting the output-byte-order. Ignored - if the OUTPUT-ARCHITECTURE is not specified or - if it is IEEE, UNIX or STD. Can accept the + if the \b OUTPUT-ARCHITECTURE is not specified or + if it is \b IEEE, \b UNIX or \b STD. Can accept the following values. - BE (default) - LE +
    • BE (default)
      • +
    • LE
    - * \li CHUNKED-DIMENSION-SIZES: + * \li CHUNKED-DIMENSION-SIZES Integers separated by spaces to denote the dimension sizes of the chunk for the no. of dimensions determined by rank. Required field @@ -257,19 +257,19 @@ chunked storage. If this field is absent the dataset will be stored with contiguous storage. - * \li COMPRESSION-TYPE: + * \li COMPRESSION-TYPE String denoting the type of compression to be used with the chunked storage. Requires the - CHUNKED-DIMENSION-SIZES to be specified. The only - currently supported compression method is GZIP. + \b CHUNKED-DIMENSION-SIZES to be specified. The only + currently supported compression method is \b GZIP. Will accept the following value - GZIP +
    • GZIP
    - * \li COMPRESSION-PARAM: + * \li COMPRESSION-PARAM Integer used to denote compression level and this option is to be always specified when - the COMPRESSION-TYPE option is specified. The - values are applicable only to GZIP + the \b COMPRESSION-TYPE option is specified. The + values are applicable only to \b GZIP compression. Value 1-9: The level of Compression. 1 will result in the fastest @@ -277,21 +277,20 @@ the best compression ratio. The default level of compression is 6. - * \li EXTERNAL-STORAGE: + * \li EXTERNAL-STORAGE String to denote the name of the non-HDF5 file - to store data to. Cannot be used if CHUNKED- - DIMENSIONS or COMPRESSION-TYPE or EXTENDIBLE- - DATASET is specified. - Value : the name of the + to store data to. Cannot be used if \b CHUNKED-DIMENSIONS + or \b COMPRESSION-TYPE or \b EXTENDIBLE-DATASET is specified. + Value \: the name of the external file as a string to be used. - * \li MAXIMUM-DIMENSIONS: + * \li MAXIMUM-DIMENSIONS Integers separated by spaces to denote the maximum dimension sizes of all the dimensions determined by rank. Requires the - CHUNKED-DIMENSION-SIZES to be specified. A value of - -1 for any dimension implies UNLIMITED - DIMENSION size for that particular dimension. + \b CHUNKED-DIMENSION-SIZES to be specified. A value of + -1 for any dimension implies \b UNLIMITED + \b DIMENSION size for that particular dimension. * \subsection subsec_cltools_h5import_examples Usage Examples * \li Configuration File may look like diff --git a/tools/src/h5ls/h5ls.h b/tools/src/h5ls/h5ls.h index 2b18379ac0b..ce79c02ca81 100644 --- a/tools/src/h5ls/h5ls.h +++ b/tools/src/h5ls/h5ls.h @@ -66,7 +66,7 @@ * \li --simple Use a machine-readable output format * \li --width=N Set the number of columns of output * \li --verbose Generate more verbose output - * \li --version Print version number and exit + * \li --version Print the library version number and exit * \li --page-buffer-size=N Set the page buffer cache size, N=non-negative integers * \li --vfd=DRIVER Use the specified virtual file driver * \li --hexdump Show raw data in hexadecimal format diff --git a/tools/src/h5repack/h5repack.h b/tools/src/h5repack/h5repack.h index f3b54a74d83..f531a30e457 100644 --- a/tools/src/h5repack/h5repack.h +++ b/tools/src/h5repack/h5repack.h @@ -30,69 +30,69 @@ * Optional value 2 also prints file open errors. * * \subsection subsec_cltools_h5repack_options Options - * \li --help : Print a usage message and exit - * \li --verbose=N : Verbose mode, print object information. + * \li --help Print a usage message and exit + * \li --verbose=N Verbose mode, print object information. * N - is an integer greater than 1, 2 displays read/write timing - * \li --version : Print version number and exit - * \li --native : Use a native HDF5 type when repacking - * \li --page-buffer-size=N : Set the page buffer cache size, N=non-negative integers - * \li --src-vol-value : Value (ID) of the VOL connector to use for opening the + * \li --version Print the library version number and exit + * \li --native Use a native HDF5 type when repacking + * \li --page-buffer-size=N Set the page buffer cache size, N=non-negative integers + * \li --src-vol-value Value (ID) of the VOL connector to use for opening the * input HDF5 file specified - * \li --src-vol-name : Name of the VOL connector to use for opening the input + * \li --src-vol-name Name of the VOL connector to use for opening the input * HDF5 file specified - * \li --src-vol-info : VOL-specific info to pass to the VOL connector used for + * \li --src-vol-info VOL-specific info to pass to the VOL connector used for * opening the input HDF5 file specified - * \li --dst-vol-value : Value (ID) of the VOL connector to use for opening the + * \li --dst-vol-value Value (ID) of the VOL connector to use for opening the * output HDF5 file specified - * \li --dst-vol-name : Name of the VOL connector to use for opening the output + * \li --dst-vol-name Name of the VOL connector to use for opening the output * HDF5 file specified - * \li --dst-vol-info : VOL-specific info to pass to the VOL connector used for + * \li --dst-vol-info VOL-specific info to pass to the VOL connector used for * opening the output HDF5 file specified - * \li --src-vfd-value : Value (ID) of the VFL driver to use for opening the + * \li --src-vfd-value Value (ID) of the VFL driver to use for opening the * input HDF5 file specified - * \li --src-vfd-name : Name of the VFL driver to use for opening the input + * \li --src-vfd-name Name of the VFL driver to use for opening the input * HDF5 file specified - * \li --src-vfd-info : VFD-specific info to pass to the VFL driver used for + * \li --src-vfd-info VFD-specific info to pass to the VFL driver used for * opening the input HDF5 file specified - * \li --dst-vfd-value : Value (ID) of the VFL driver to use for opening the + * \li --dst-vfd-value Value (ID) of the VFL driver to use for opening the * output HDF5 file specified - * \li --dst-vfd-name : Name of the VFL driver to use for opening the output + * \li --dst-vfd-name Name of the VFL driver to use for opening the output * HDF5 file specified - * \li --dst-vfd-info : VFD-specific info to pass to the VFL driver used for + * \li --dst-vfd-info VFD-specific info to pass to the VFL driver used for * opening the output HDF5 file specified - * \li --latest : Use latest version of file format + * \li --latest Use latest version of file format * This option will take precedence over the options * --low and --high - * \li --low=BOUND : The low bound for library release versions to use + * \li --low=BOUND The low bound for library release versions to use * when creating objects in the file * (default is #H5F_LIBVER_EARLIEST) - * \li --high=BOUND : The high bound for library release versions to use + * \li --high=BOUND The high bound for library release versions to use * when creating objects in the file * (default is #H5F_LIBVER_LATEST) - * \li --merge : Follow external soft link recursively and merge data - * \li --prune : Do not follow external soft links and remove link - * \li --merge --prune : Follow external link, merge data and remove dangling link - * \li --compact=L1 : Maximum number of links in header messages - * \li --indexed=L2 : Minimum number of links in the indexed format - * \li --ssize=S[:F] : Shared object header message minimum size - * \li --minimum=M : Do not apply the filter to datasets smaller than M - * \li --file=E : Name of file E with the -f and -l options - * \li --ublock=U : Name of file U with user block data to be added - * \li --block=B : Size of user block to be added - * \li --metadata_block_size=A : Metadata block size for #H5Pset_meta_block_size - * \li --threshold=T : Threshold value for #H5Pset_alignment - * \li --alignment=A : Alignment value for #H5Pset_alignment - * \li --sort_by=Q : Sort groups and attributes by index Q - * \li --sort_order=Z : Sort groups and attributes by order Z - * \li --filter=FILT : Filter type - * \li --layout=LAYT : Layout type - * \li --fs_strategy=FS_STRATEGY : File space management strategy for + * \li --merge Follow external soft link recursively and merge data + * \li --prune Do not follow external soft links and remove link + * \li --merge --prune Follow external link, merge data and remove dangling link + * \li --compact=L1 Maximum number of links in header messages + * \li --indexed=L2 Minimum number of links in the indexed format + * \li --ssize=S[:F] Shared object header message minimum size + * \li --minimum=M Do not apply the filter to datasets smaller than M + * \li --file=E Name of file E with the -f and -l options + * \li --ublock=U Name of file U with user block data to be added + * \li --block=B Size of user block to be added + * \li --metadata_block_size=A Metadata block size for #H5Pset_meta_block_size + * \li --threshold=T Threshold value for #H5Pset_alignment + * \li --alignment=A Alignment value for #H5Pset_alignment + * \li --sort_by=Q Sort groups and attributes by index Q + * \li --sort_order=Z Sort groups and attributes by order Z + * \li --filter=FILT Filter type + * \li --layout=LAYT Layout type + * \li --fs_strategy=FS_STRATEGY File space management strategy for * #H5Pset_file_space_strategy - * \li --fs_persist=FS_PERSIST : Persisting or not + * \li --fs_persist=FS_PERSIST Persisting or not * persisting free-space for #H5Pset_file_space_strategy * \li ---fs_threshold=FS_THRESHOLD : Free-space section * threshold for #H5Pset_file_space_strategy - * \li --fs_pagesize=FS_PAGESIZE : File space page size for #H5Pset_file_space_page_size + * \li --fs_pagesize=FS_PAGESIZE File space page size for #H5Pset_file_space_page_size * * \subsubsection subsubsec_cltools_h5repack_options_args Arguments to Certain Options * \li M - is an integer greater than 1, size of dataset in bytes (default is 0) @@ -113,26 +113,26 @@ * \subsubsection subsubsec_cltools_h5repack_options_bound Library Version Bounds * BOUND is an integer indicating the library release versions to use when * creating objects in the file (see #H5Pset_libver_bounds()): - * \li 0: This is #H5F_LIBVER_EARLIEST in #H5F_libver_t struct - * \li 1: This is #H5F_LIBVER_V18 in #H5F_libver_t struct - * \li 2: This is #H5F_LIBVER_V110 in #H5F_libver_t struct - * \li 3: This is #H5F_LIBVER_V112 in #H5F_libver_t struct - * \li 4: This is #H5F_LIBVER_V114 in #H5F_libver_t struct - * \li 5: This is #H5F_LIBVER_V116 in #H5F_libver_t struct + * \li 0 This is #H5F_LIBVER_EARLIEST in #H5F_libver_t struct + * \li 1 This is #H5F_LIBVER_V18 in #H5F_libver_t struct + * \li 2 This is #H5F_LIBVER_V110 in #H5F_libver_t struct + * \li 3 This is #H5F_LIBVER_V112 in #H5F_libver_t struct + * \li 4 This is #H5F_LIBVER_V114 in #H5F_libver_t struct + * \li 5 This is #H5F_LIBVER_V116 in #H5F_libver_t struct * \li (#H5F_LIBVER_LATEST is aliased to #H5F_LIBVER_V116 for this release * * \subsubsection subsubsec_cltools_h5repack_options_fs File Strategy Settings * FS_STRATEGY is a string indicating the file space strategy used: - * \li FSM_AGGR: + * \li FSM_AGGR * The mechanisms used in managing file space are free-space * managers, aggregators and virtual file driver. - * \li PAGE: + * \li PAGE * The mechanisms used in managing file space are free-space * managers with embedded paged aggregation and virtual file driver. - * \li AGGR: + * \li AGGR * The mechanisms used in managing file space are aggregators and * virtual file driver. - * \li NONE: + * \li NONE * The mechanisms used in managing file space are virtual file * driver. * \li The default strategy when not set is \b FSM_AGGR without persisting free- @@ -160,14 +160,14 @@ * compression only to those objects. If no names are specified, the filter * is applied to all objects * \li \ can be: - *
    • GZIP, to apply the HDF5 GZIP filter (GZIP compression)
      • - *
    • SZIP, to apply the HDF5 SZIP filter (SZIP compression)
      • - *
    • SHUF, to apply the HDF5 shuffle filter
      • - *
    • FLET, to apply the HDF5 checksum filter
      • - *
    • NBIT, to apply the HDF5 NBIT filter (NBIT compression)
      • - *
    • SOFF, to apply the HDF5 Scale/Offset filter
      • - *
    • UD, to apply a user defined filter
      • - *
    • NONE, to remove all filters
    + *
    • GZIP to apply the HDF5 GZIP filter (GZIP compression)
      • + *
    • SZIP to apply the HDF5 SZIP filter (SZIP compression)
      • + *
    • SHUF to apply the HDF5 shuffle filter
      • + *
    • FLET to apply the HDF5 checksum filter
      • + *
    • NBIT to apply the HDF5 NBIT filter (NBIT compression)
      • + *
    • SOFF to apply the HDF5 Scale/Offset filter
      • + *
    • UD to apply a user defined filter
      • + *
    • NONE to remove all filters
    * \li \ is optional filter parameter information *
    • GZIP=\ from 1-9
      • *
    • SZIP= pixels per block is a even number in @@ -192,9 +192,9 @@ * layout information is supplied for those objects. If no names are * specified, the layout type is applied to all objects * \li \ can be: - *
      • CHUNK, to apply chunking layout
        • - *
      • COMPA, to apply compact layout
        • - *
      • CONTI, to apply contiguous layout
      + *
      • CHUNK to apply chunking layout
        • + *
      • COMPA to apply compact layout
        • + *
      • CONTI to apply contiguous layout
      * \li \ is optional layout information *
      • CHUNK=DIM[xDIM...xDIM], the chunk size of each dimension
        • *
      • COMPA (no parameter)
        • diff --git a/tools/src/h5stat/h5stat.h b/tools/src/h5stat/h5stat.h index 074b57dc67f..26a544e7bbb 100644 --- a/tools/src/h5stat/h5stat.h +++ b/tools/src/h5stat/h5stat.h @@ -27,32 +27,32 @@ Optional value 2 also prints file open errors. * \subsection subsec_cltools_h5stat_options Options - * \li --help: Print a usage message and exit - * \li --version: Print version number and exit - * \li --file: Print file information - * \li --filemetadata: Print file space information for file's metadata - * \li --group: Print group information - * \li --links=N: Set the threshold for the # of links when printing + * \li --help Print a usage message and exit + * \li --version Print the library version number and exit + * \li --file Print file information + * \li --filemetadata Print file space information for file's metadata + * \li --group Print group information + * \li --links=N Set the threshold for the # of links when printing information for small groups. N is an integer greater than 0. The default threshold is 10. - * \li --groupmetadata : Print file space information for groups' metadata - * \li --dset: Print dataset information - * \li --dims=N: Set the threshold for the dimension sizes when printing + * \li --groupmetadata Print file space information for groups' metadata + * \li --dset Print dataset information + * \li --dims=N Set the threshold for the dimension sizes when printing information for small datasets. N is an integer greater than 0. The default threshold is 10. - * \li --dsetmetadata: Print file space information for datasets' metadata - * \li --dtypemetadata: Print datasets' datatype information - * \li --attribute: Print attribute information - * \li --numattrs=N: Set the threshold for the number of attributes when printing + * \li --dsetmetadata Print file space information for datasets' metadata + * \li --dtypemetadata Print datasets' datatype information + * \li --attribute Print attribute information + * \li --numattrs=N Set the threshold for the number of attributes when printing information for small number of attributes. N is an integer greater than 0. The default threshold is 10. - * \li --freespace: Print free space information - * \li --summary: Print summary of file space information - * \li --page-buffer-size=N: Set the page buffer cache size, N=non-negative integers - * \li --s3-cred=\: Access file on S3, using provided credential + * \li --freespace Print free space information + * \li --summary Print summary of file space information + * \li --page-buffer-size=N Set the page buffer cache size, N=non-negative integers + * \li --s3-cred=\ Access file on S3, using provided credential \ :: (region,id,key) If \ == "(,,)", no authentication is used. - * \li --hdfs-attrs=\: Access a file on HDFS with given configuration + * \li --hdfs-attrs=\ Access a file on HDFS with given configuration attributes. \ :: (\,\, \,\, diff --git a/tools/src/misc/h5clear.h b/tools/src/misc/h5clear.h index 5ede807c55c..675aee0366b 100644 --- a/tools/src/misc/h5clear.h +++ b/tools/src/misc/h5clear.h @@ -32,12 +32,12 @@ and appropriate actions can be taken. Optional value 2 also prints file open errors. * \subsection subsec_cltools_h5clear_options Options - * \li --help: Print a usage message and exit - * \li --version: Print version number and exit - * \li --status: Clear the status_flags field in the file's superblock - * \li --image: Remove the metadata cache image from the file - * \li --filesize : Print the file's EOA and EOF - * \li --increment=C: Set the file's EOA to the maximum of (EOA, EOF) + C for + * \li --help Print a usage message and exit + * \li --version Print the library version number and exit + * \li --status Clear the status_flags field in the file's superblock + * \li --image Remove the metadata cache image from the file + * \li --filesize Print the file's EOA and EOF + * \li --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 SWMR file when the stored diff --git a/tools/src/misc/h5mkgrp.h b/tools/src/misc/h5mkgrp.h index d0d8ccf4ed5..e41216b85aa 100644 --- a/tools/src/misc/h5mkgrp.h +++ b/tools/src/misc/h5mkgrp.h @@ -27,25 +27,25 @@ Optional value 2 also prints file open errors. * \subsection subsec_cltools_h5mkgrp_options Options - * \li --help: Print a usage message and exit - * \li --version: Print version number and exit - * \li --verbose: Print information about OBJECTS and OPTIONS - * \li --latest: Use latest version of file format to create groups - * \li --parents: No error if existing, make parent groups as needed - * \li --vol-value: Value (ID) of the VOL connector to use for opening the + * \li --help Print a usage message and exit + * \li --version Print the library version number and exit + * \li --verbose Print information about OBJECTS and OPTIONS + * \li --latest Use latest version of file format to create groups + * \li --parents No error if existing, make parent groups as needed + * \li --vol-value Value (ID) of the VOL connector to use for opening the HDF5 file specified - * \li --vol-name: Name of the VOL connector to use for opening the + * \li --vol-name Name of the VOL connector to use for opening the HDF5 file specified - * \li --vol-info: VOL-specific info to pass to the VOL connector used for + * \li --vol-info VOL-specific info to pass to the VOL connector used for opening the HDF5 file specified If none of the above options are used to specify a VOL, then the VOL named by HDF5_VOL_CONNECTOR (or the native VOL connector, if that environment variable is unset) will be used - * \li --vfd-value: Value (ID) of the VFL driver to use for opening the + * \li --vfd-value Value (ID) of the VFL driver to use for opening the HDF5 file specified - * \li --vfd-name: Name of the VFL driver to use for opening the + * \li --vfd-name Name of the VFL driver to use for opening the HDF5 file specified - * \li --vfd-info: VFD-specific info to pass to the VFL driver used for + * \li --vfd-info VFD-specific info to pass to the VFL driver used for opening the HDF5 file specified * */ From 1c2e5d4e4f939875745d5c8e11cf7409206e8eee Mon Sep 17 00:00:00 2001 From: Allen Byrne Date: Tue, 25 Jun 2024 12:05:06 -0500 Subject: [PATCH 11/24] Fix typo --- tools/src/h5import/h5import.h | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/tools/src/h5import/h5import.h b/tools/src/h5import/h5import.h index 00454220305..8a7f8d802da 100644 --- a/tools/src/h5import/h5import.h +++ b/tools/src/h5import/h5import.h @@ -179,7 +179,7 @@ * \li INPUT-CLASS String denoting the type of input data. -
        • "TEXTIN
        • TEXTFP
          • +
          • TEXTIN
          • TEXTFP
          • FP
          • IN
          • STR
          • TEXTUIN
          • UIN
          \b INPUT-CLASS "TEXTIN" denotes an ASCII text @@ -234,8 +234,8 @@ architecture. Can accept the following values
          • STD
          • IEEE
            • -
          • INTEL - CRAY
            • +
          • INTEL
            • +
          • CRAY
          • MIPS
          • ALPHA
          • NATIVE (default)
            • @@ -333,7 +333,7 @@ first and the third dimension will be defined as unlimited. The data-set will be compressed using GZIP and a compression level of 7. - The dataset will be stored at "/Second-set" + The dataset will be stored at \code /Second-set \endcode * */ From 7aa818e4cdea8d68c0ae64e7bc32fba42931d9d3 Mon Sep 17 00:00:00 2001 From: Allen Byrne Date: Tue, 25 Jun 2024 15:00:41 -0500 Subject: [PATCH 12/24] Cleanup text in the tools doxygen code. Add release note. --- release_docs/RELEASE.txt | 4 + tools/src/h5copy/h5copy.h | 79 ++-- tools/src/h5diff/h5diff_main.h | 355 +++++++++--------- tools/src/h5dump/h5dump.h | 178 +++++---- tools/src/h5format_convert/h5format_convert.h | 48 +-- tools/src/h5import/h5import.h | 2 +- tools/src/h5jam/h5jam.h | 72 ++-- tools/src/h5ls/h5ls.h | 150 ++++---- tools/src/h5repack/h5repack.h | 178 +++++---- tools/src/h5stat/h5stat.h | 72 ++-- tools/src/misc/h5clear.h | 72 ++-- tools/src/misc/h5debug.h | 8 +- tools/src/misc/h5delete.h | 6 +- tools/src/misc/h5mkgrp.h | 48 +-- tools/src/misc/h5repart.h | 30 +- 15 files changed, 646 insertions(+), 656 deletions(-) diff --git a/release_docs/RELEASE.txt b/release_docs/RELEASE.txt index 8b43f5ecddb..29bd8a48f4b 100644 --- a/release_docs/RELEASE.txt +++ b/release_docs/RELEASE.txt @@ -765,6 +765,10 @@ New Features Tools: ------ + - Add doxygen files for the tools + + Implement the tools usage text as pages in doxygen. + - Add option to adjust the page buffer size in tools The page buffer cache size for a file can now be adjusted using the diff --git a/tools/src/h5copy/h5copy.h b/tools/src/h5copy/h5copy.h index 0956ee6ef3b..aaec294b0ce 100644 --- a/tools/src/h5copy/h5copy.h +++ b/tools/src/h5copy/h5copy.h @@ -21,53 +21,52 @@ * With h5copy you can copy objects from an HDF5 file to another file. * * \subsection subsec_cltools_h5copy_usage Usage - *

            h5copy [OPTIONS] [OBJECTS...]

            + *

            h5copy [OPTIONS] [OBJECTS...]

            * * \subsection subsec_cltools_h5copy_objs Objects - * \li --input input file name - * \li --output output file name - * \li --source source object name - * \li --destination destination object name - + * \li --input input file name + * \li --output output file name + * \li --source source object name + * \li --destination destination object name + * * \subsection subsec_cltools_h5copy_error Error Report Option - * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. + * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. Optional value 2 also prints file open errors. - + * * \subsection subsec_cltools_h5copy_options Options - * \li --help Print a usage message and exit - * \li --parents No error if existing, make parent groups as needed - * \li --verbose Print information about OBJECTS and OPTIONS - * \li --version Print the library version number and exit - * \li --flag Flag type + * \li --help Print a usage message and exit + * \li --parents No error if existing, make parent groups as needed + * \li --verbose Print information about OBJECTS and OPTIONS + * \li --version Print the library version number and exit + * \li --flag Flag type * * \subsubsection subsubsec_cltools_h5copy_options_args Flag Type Options - Flag type is one of the following strings: - * \li shallow Copy only immediate members for groups - * \li soft Expand soft links into new objects - * \li ext Expand external links into new objects - * \li ref Copy references and any referenced objects, i.e., objects - that the references point to. - Referenced objects are copied in addition to the objects - specified on the command line and reference datasets are - populated with correct reference values. Copies of referenced - datasets outside the copy range specified on the command line - will normally have a different name from the original. - (Default:Without this option, reference value(s) in any - reference datasets are set to NULL and referenced objects are - not copied unless they are otherwise within the copy range - specified on the command line.) - * \li noattr Copy object without copying attributes - * \li allflags Switches all flags from the default to the non-default setting - - These flag types correspond to the following API symbols - - * \li #H5O_COPY_SHALLOW_HIERARCHY_FLAG - * \li #H5O_COPY_EXPAND_SOFT_LINK_FLAG - * \li #H5O_COPY_EXPAND_EXT_LINK_FLAG - * \li #H5O_COPY_EXPAND_REFERENCE_FLAG - * \li #H5O_COPY_WITHOUT_ATTR_FLAG - * \li #H5O_COPY_ALL - + * Flag type is one of the following strings: + * \li shallow Copy only immediate members for groups + * \li soft Expand soft links into new objects + * \li ext Expand external links into new objects + * \li ref Copy references and any referenced objects, i.e., objects + * that the references point to.
            + * Referenced objects are copied in addition to the objects + * specified on the command line and reference datasets are + * populated with correct reference values. Copies of referenced + * datasets outside the copy range specified on the command line + * will normally have a different name from the original.
            + * (Default:Without this option, reference value(s) in any + * reference datasets are set to NULL and referenced objects are + * not copied unless they are otherwise within the copy range + * specified on the command line.) + * \li noattr Copy object without copying attributes + * \li allflags Switches all flags from the default to the non-default setting + * + * These flag types correspond to the following API symbols + * \li #H5O_COPY_SHALLOW_HIERARCHY_FLAG + * \li #H5O_COPY_EXPAND_SOFT_LINK_FLAG + * \li #H5O_COPY_EXPAND_EXT_LINK_FLAG + * \li #H5O_COPY_EXPAND_REFERENCE_FLAG + * \li #H5O_COPY_WITHOUT_ATTR_FLAG + * \li #H5O_COPY_ALL + * * */ diff --git a/tools/src/h5diff/h5diff_main.h b/tools/src/h5diff/h5diff_main.h index 293622248ea..9ffa0fdffca 100644 --- a/tools/src/h5diff/h5diff_main.h +++ b/tools/src/h5diff/h5diff_main.h @@ -18,203 +18,200 @@ * \section sec_cltools_h5diff h5diff * * \subsection subsec_cltools_h5diff_intro Introduction - * With h5diff you can compare objects between a HDF5 file and another file. + * With h5diff you can compare objects between a HDF5 file and another file. * * \subsection subsec_cltools_h5diff_usage Usage -

            h5diff [OPTIONS] file1 file2 [obj1[ obj2]]

            - * \li file1 File name of the first HDF5 file - * \li file2 File name of the second HDF5 file - * \li [obj1] Name of an HDF5 object, in absolute path - * \li [obj2] Name of an HDF5 object, in absolute path - + *

            h5diff [OPTIONS] file1 file2 [obj1[ obj2]]

            + * \li file1 File name of the first HDF5 file + * \li file2 File name of the second HDF5 file + * \li [obj1] Name of an HDF5 object, in absolute path + * \li [obj2] Name of an HDF5 object, in absolute path + * * \subsection subsec_cltools_h5diff_error Error Report - * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. - Optional value 2 also prints file open errors. - + * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. + * Optional value 2 also prints file open errors. + * * \subsection subsec_cltools_h5diff_options Options - * \li --help Print a usage message and exit. - * \li --version Print the library version number and exit. - * \li --report Report mode. Print differences. - * \li --verbose Verbose mode. Print differences information and list of objects. - * \li --verbose=N Verbose mode with level. Print differences and list of objects. - Level of detail depends on value of N: -
            • 0 : Identical to '-v' or '--verbose'.
              • -
            • 1 : All level 0 information plus one-line attribute status summary.
              • -
            • 2 : All level 1 information plus extended attribute status report.
              • -
            • 3 : All level 2 information plus file names.
            - * \li --quiet Quiet mode. Do not produce output. - * \li --page-buffer-size=N Set the page buffer cache size, N=non-negative integers - * \li --vol-value-1 Value (ID) of the VOL connector to use for opening the - first HDF5 file specified - * \li --vol-name-1 Name of the VOL connector to use for opening the first - HDF5 file specified - * \li --vol-info-1 VOL-specific info to pass to the VOL connector used for - opening the first HDF5 file specified - * \li --vol-value-2 Value (ID) of the VOL connector to use for opening the - second HDF5 file specified - * \li --vol-name-2 Name of the VOL connector to use for opening the second - HDF5 file specified - * \li --vol-info-2 VOL-specific info to pass to the VOL connector used for - opening the second HDF5 file specified - If none of the above options are used to specify a VOL for a file, then - the VOL named by HDF5_VOL_CONNECTOR (or the native VOL connector, - if that environment variable is unset) will be used - * \li --vfd-value-1 Value (ID) of the VFL driver to use for opening the - first HDF5 file specified - * \li --vfd-name-1 Name of the VFL driver to use for opening the first - HDF5 file specified - * \li --vfd-info-1 VFD-specific info to pass to the VFL driver used for - opening the first HDF5 file specified - * \li --vfd-value-2 Value (ID) of the VFL driver to use for opening the - second HDF5 file specified - * \li --vfd-name-2 Name of the VFL driver to use for opening the second - HDF5 file specified - * \li --vfd-info-2 VFD-specific info to pass to the VFL driver used for - opening the second HDF5 file specified - * \li --follow-symlinks - Follow symbolic links (soft links and external links and compare the) - links' target objects. - If symbolic link(s) with the same name exist in the files being - compared, then determine whether the target of each link is an existing - object (dataset, group, or named datatype) or the link is a dangling - link (a soft or external link pointing to a target object that does - not yet exist). -
            • If both symbolic links are dangling links, they are treated as being - the same; by default, h5diff returns an exit code of 0. - If, however, --no-dangling-links is used with --follow-symlinks, - this situation is treated as an error and h5diff returns an - exit code of 2.
              • -
            • If only one of the two links is a dangling link,they are treated as - being different and h5diff returns an exit code of 1. - If, however, --no-dangling-links is used with --follow-symlinks, - this situation is treated as an error and h5diff returns an - exit code of 2.
              • -
            • If both symbolic links point to existing objects, h5diff compares the - two objects.
            - If any symbolic link specified in the call to h5diff does not exist, - h5diff treats it as an error and returns an exit code of 2. - * \li --no-dangling-links - Must be used with --follow-symlinks option; otherwise, h5diff shows - error message and returns an exit code of 2. - Check for any symbolic links (soft links or external links) that do not - resolve to an existing object (dataset, group, or named datatype). - If any dangling link is found, this situation is treated as an error - and h5diff returns an exit code of 2. - * \li --compare List objects that are not comparable - * \li --nan Avoid NaNs detection - * \li --count=C Print differences up to C. C must be a positive integer. - * \li --delta=D - Print difference if (|a-b| > D). D must be a positive number. Where a - is the data point value in file1 and b is the data point value in file2. - Can not use with '--relative' or '--use-system-epsilon'. - * \li --relative=R - Print difference if (|(a-b)/b| > R). R must be a positive number. Where a - is the data point value in file1 and b is the data point value in file2. - Can not use with '--delta' or '--use-system-epsilon'. - * \li --use-system-epsilon - Print difference if (|a-b| > EPSILON), EPSILON is system defined value. Where a - is the data point value in file1 and b is the data point value in file2. - If the system epsilon is not defined,one of the following predefined - values will be used: - FLT_EPSILON = 1.19209E-07 for floating-point type - DBL_EPSILON = 2.22045E-16 for double precision - type Can not use with '--relative' or '--delta'. - * \li --exclude-path "path" - Exclude the specified path to an object when comparing files or groups. - If a group is excluded, all member objects will also be excluded. - The specified path is excluded wherever it occurs. - This flexibility enables the same option to exclude either objects that - exist only in one file or common objects that are known to differ. - - When comparing files, "path" is the absolute path to the excluded; - object; when comparing groups, "path" is similar to the relative - path from the group to the excluded object. This "path" can be - taken from the first section of the output of the --verbose option. - For example, if you are comparing the group /groupA in two files and - you want to exclude /groupA/groupB/groupC in both files, the exclude - option would read as follows: - --exclude-path "/groupB/groupC" - - If there are multiple paths to an object, only the specified path(s) - will be excluded; the comparison will include any path not explicitly - excluded. - This option can be used repeatedly to exclude multiple paths. - - * \li --exclude-attribute "path/to/object/with/attribute" - Exclude attributes on the specified path to an object when comparing files or groups. - - If there are multiple paths to an object, only the specified path(s) - will be excluded; the comparison will include any path not explicitly - excluded. - This option can be used repeatedly to exclude multiple paths. - - Modes of output: - * \li Default mode: print the number of differences found and where they occurred - * \li Report mode: print the above plus the differences - * \li Verbose mode: print the above plus a list of objects and warnings - * \li Quiet mode: do not print output - - File comparison: - If no objects [obj1[ obj2]] are specified, the h5diff comparison proceeds as - a comparison of the two files' root groups. That is, h5diff first compares - the names of root group members, generates a report of root group objects - that appear in only one file or in both files, and recursively compares - common objects. - - Object comparison: + * \li --help Print a usage message and exit. + * \li --version Print the library version number and exit. + * \li --report Report mode. Print differences. + * \li --verbose Verbose mode. Print differences information and list of objects. + * \li --verbose=N Verbose mode with level. Print differences and list of objects. + * Level of detail depends on value of N: + *
            • 0 Identical to '-v' or '--verbose'.
              • + *
            • 1 All level 0 information plus one-line attribute status summary.
              • + *
            • 2 All level 1 information plus extended attribute status report.
              • + *
            • 3 All level 2 information plus file names.
            + * \li --quiet Quiet mode. Do not produce output. + * \li --page-buffer-size=N Set the page buffer cache size, N=non-negative integers + * \li --vol-value-1 Value (ID) of the VOL connector to use for opening the + * first HDF5 file specified + * \li --vol-name-1 Name of the VOL connector to use for opening the first + * HDF5 file specified + * \li --vol-info-1 VOL-specific info to pass to the VOL connector used for + * opening the first HDF5 file specified + * \li --vol-value-2 Value (ID) of the VOL connector to use for opening the + * second HDF5 file specified + * \li --vol-name-2 Name of the VOL connector to use for opening the second + * HDF5 file specified + * \li --vol-info-2 VOL-specific info to pass to the VOL connector used for + * opening the second HDF5 file specified + * If none of the above options are used to specify a VOL for a file, then + * the VOL named by HDF5_VOL_CONNECTOR (or the native VOL connector, + * if that environment variable is unset) will be used + * \li --vfd-value-1 Value (ID) of the VFL driver to use for opening the + * first HDF5 file specified + * \li --vfd-name-1 Name of the VFL driver to use for opening the first + * HDF5 file specified + * \li --vfd-info-1 VFD-specific info to pass to the VFL driver used for + * opening the first HDF5 file specified + * \li --vfd-value-2 Value (ID) of the VFL driver to use for opening the + * second HDF5 file specified + * \li --vfd-name-2 Name of the VFL driver to use for opening the second + * HDF5 file specified + * \li --vfd-info-2 VFD-specific info to pass to the VFL driver used for + * opening the second HDF5 file specified + * \li --follow-symlinks + * Follow symbolic links (soft links and external links and compare the) + * links' target objects. + * If symbolic link(s) with the same name exist in the files being + * compared, then determine whether the target of each link is an existing + * object (dataset, group, or named datatype) or the link is a dangling + * link (a soft or external link pointing to a target object that does + * not yet exist). + *
            • If both symbolic links are dangling links, they are treated as being + * the same; by default, h5diff returns an exit code of 0. + * If, however, --no-dangling-links is used with --follow-symlinks, + * this situation is treated as an error and h5diff returns an + * exit code of 2.
              • + *
            • If only one of the two links is a dangling link,they are treated as + * being different and h5diff returns an exit code of 1. + * If, however, --no-dangling-links is used with --follow-symlinks, + * this situation is treated as an error and h5diff returns an + * exit code of 2.
              • + *
            • If both symbolic links point to existing objects, h5diff compares the + * two objects.
            + * If any symbolic link specified in the call to h5diff does not exist, + * h5diff treats it as an error and returns an exit code of 2. + * \li --no-dangling-links + * Must be used with --follow-symlinks option; otherwise, h5diff shows + * error message and returns an exit code of 2. + * Check for any symbolic links (soft links or external links) that do not + * resolve to an existing object (dataset, group, or named datatype). + * If any dangling link is found, this situation is treated as an error + * and h5diff returns an exit code of 2. + * \li --compare List objects that are not comparable + * \li --nan Avoid NaNs detection + * \li --count=C Print differences up to C. C must be a positive integer. + * \li --delta=D + * Print difference if (|a-b| > D). D must be a positive number. Where a + * is the data point value in file1 and b is the data point value in file2. + * Can not use with '--relative' or '--use-system-epsilon'. + * \li --relative=R + * Print difference if (|(a-b)/b| > R). R must be a positive number. Where a + * is the data point value in file1 and b is the data point value in file2. + * Can not use with '--delta' or '--use-system-epsilon'. + * \li --use-system-epsilon + * Print difference if (|a-b| > EPSILON), EPSILON is system defined value. Where a + * is the data point value in file1 and b is the data point value in file2. + * If the system epsilon is not defined,one of the following predefined + * values will be used: + *
            • FLT_EPSILON = 1.19209E-07 for floating-point type
              • + *
            • DBL_EPSILON = 2.22045E-16 for double precision
            + * type Can not use with '--relative' or '--delta'. + * \li --exclude-path "path" + * Exclude the specified path to an object when comparing files or groups. + * If a group is excluded, all member objects will also be excluded. + * The specified path is excluded wherever it occurs. + * This flexibility enables the same option to exclude either objects that + * exist only in one file or common objects that are known to differ.
            + * When comparing files, "path" is the absolute path to the excluded; + * object; when comparing groups, "path" is similar to the relative + * path from the group to the excluded object. This "path" can be + * taken from the first section of the output of the --verbose option. + * For example, if you are comparing the group + * /groupA in two files and + * you want to exclude + * /groupA/groupB/groupC + * in both files, the exclude option would read as follows:
            + * --exclude-path "/groupB/groupC" + *
            + * If there are multiple paths to an object, only the specified path(s) + * will be excluded; the comparison will include any path not explicitly + * excluded.
            + * This option can be used repeatedly to exclude multiple paths. + * \li --exclude-attribute "path/to/object/with/attribute" + * Exclude attributes on the specified path to an object when comparing files or groups.
            + * If there are multiple paths to an object, only the specified path(s) + * will be excluded; the comparison will include any path not explicitly + * excluded.
            + * This option can be used repeatedly to exclude multiple paths. + * + * \subsubsection subsubsec_cltools_h5diff_modee Modes of output + * \li Default mode print the number of differences found and where they occurred + * \li Report mode print the above plus the differences + * \li Verbose mode print the above plus a list of objects and warnings + * \li Quiet mode do not print output + * + * \subsubsection subsubsec_cltools_h5diff_file File comparison + * If no objects [obj1[ obj2]] are specified, the h5diff comparison proceeds as + * a comparison of the two files' root groups. That is, h5diff first compares + * the names of root group members, generates a report of root group objects + * that appear in only one file or in both files, and recursively compares + * common objects. + * + * \subsubsection subsubsec_cltools_h5diff_object Object comparison * \li 1) Groups - First compares the names of member objects (relative path, from the - specified group) and generates a report of objects that appear in only - one group or in both groups. Common objects are then compared recursively. + * First compares the names of member objects (relative path, from the + * specified group) and generates a report of objects that appear in only + * one group or in both groups. Common objects are then compared recursively. * \li 2) Attributes and Datasets - Array rank and dimensions, datatypes, and data values are compared. + * Array rank and dimensions, datatypes, and data values are compared. * \li 3) Datatypes - The comparison is based on the return value of H5Tequal. + * The comparison is based on the return value of H5Tequal. * \li 4) Symbolic links - The paths to the target objects are compared. - (The option --follow-symlinks overrides the default behavior when - symbolic links are compared.). - - + * The paths to the target objects are compared. + * (The option --follow-symlinks overrides the default behavior when + * symbolic links are compared.). * * \subsubsection subsubsec_cltools_h5diff_subset Subsetting Options * \li --no-compact-subset Disable compact form of subsetting and allow the use - of "[" in dataset names. - - Subsetting is available by using the fcompact form of subsetting, as follows: - obj1 /foo/mydataset[START;STRIDE;COUNT;BLOCK] - - It is not required to use all parameters, but until the last parameter value used, - all of the semicolons (;) are required, even when a parameter value is not specified. Example: - obj1 /foo/mydataset[START;;COUNT;BLOCK] - obj1 /foo/mydataset[START] - - The \b STRIDE, \b COUNT, and \b BLOCK parameters are optional and will default to 1 in - each dimension. \b START is optional and will default to 0 in each dimension. - Each of \b START, \b STRIDE, \b COUNT, and \b BLOCK must be a comma-separated list of integers with - one integer for each dimension of the dataset. - - Exit code: + * of "[" in dataset names. + * + * Subsetting is available by using the fcompact form of subsetting, as follows: + * obj1 /foo/mydataset[START;STRIDE;COUNT;BLOCK] + * + * It is not required to use all parameters, but until the last parameter value used, + * all of the semicolons (;) are required, even when a parameter value is not specified. + * + * Example: + * obj1 /foo/mydataset[START;;COUNT;BLOCK] + * obj1 /foo/mydataset[START] + * + * The \b STRIDE, \b COUNT, and \b BLOCK parameters are optional and will default to 1 in + * each dimension. \b START is optional and will default to 0 in each dimension. + * Each of \b START, \b STRIDE, \b COUNT, and \b BLOCK must be a comma-separated list of integers with + * one integer for each dimension of the dataset. + * + * \subsubsection subsubsec_cltools_h5diff_exit Exit code * \li 0 if no differences * \li 1 if differences found * \li 2 if error - * * \subsubsection subsubsec_cltools_h5diff_examples Examples * \li 1) h5diff file1 file2 /g1/dset1 /g1/dset2 - Compares object '/g1/dset1' in file1 with '/g1/dset2' in file2 - + * Compares object '/g1/dset1' in file1 with '/g1/dset2' in file2 + * * \li 2) h5diff file1 file2 /g1/dset1 - Compares object '/g1/dset1' in both files - - * \li 3) h5diff file1 file2 - Compares all objects in both files - - Notes: - file1 and file2 can be the same file. - Use h5diff file1 file1 /g1/dset1 /g1/dset2 to compare - '/g1/dset1' and '/g1/dset2' in the same file - + * Compares object '/g1/dset1' in both files + * + * \li 3) h5diff file1 file2 + * Compares all objects in both files + * + * Notes: + * file1 and file2 can be the same file. + * Use h5diff file1 file1 /g1/dset1 /g1/dset2 to compare + * '/g1/dset1' and '/g1/dset2' in the same file * */ diff --git a/tools/src/h5dump/h5dump.h b/tools/src/h5dump/h5dump.h index 8c85ccc9229..0fc0bcfdb8b 100644 --- a/tools/src/h5dump/h5dump.h +++ b/tools/src/h5dump/h5dump.h @@ -17,14 +17,14 @@ * \section sec_cltools_h5dump h5dump * * \subsection subsec_cltools_h5dump_intro Introduction - * With h5dump you can ddisplay objects from an HDF5 file. + * With h5dump you can display objects from an HDF5 file. * * \subsection subsec_cltools_h5dump_usage Usage - *

            h5dump [OPTIONS] [files

            + *

            h5dump [OPTIONS] [files

            * * \subsection subsec_cltools_h5dump_error Error Report Option - * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. - * Optional value 2 also prints file open errors. + * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. + * Optional value 2 also prints file open errors. * * \subsection subsec_cltools_h5dump_options Options * \li --help Print a usage message and exit @@ -32,54 +32,50 @@ * * \subsection subsec_cltools_h5dump_options_file File Options * \li --contents Print a list of the file contents and exit - Optional value 1 also prints attributes. + * Optional value 1 also prints attributes. * \li --superblock Print the content of the super block * \li --header Print the header only; no data is displayed - * \li --filedriver=D Specify which driver to open the file with + * \li --filedriver=D Specify which driver to open the file with * \li --output=F Output raw data into file F * \li --binary=B Binary file output, of form B * \li --ddl=F Output ddl text into file F - Use blank(empty) filename F to suppress ddl display + * Use blank(empty) filename F to suppress ddl display * \li --page-buffer-size=N Set the page buffer cache size, N=non-negative integers * \li --s3-cred=\ Supply S3 authentication information to "ros3" vfd. - \ :: "(,,)" - If absent or \ -> "(,,)", no authentication. - Has no effect if filedriver is not "ros3". + * \code \ :: "(,,)" \endcode + * If absent or \code \ -> "(,,)" \endcode, no authentication. + * Has no effect if filedriver is not "ros3". * \li --hdfs-attrs=\ Supply configuration information for HDFS file access. - For use with "--filedriver=hdfs" - \ :: (\,\, - \,\, - \) - Any absent attribute will use a default value. - * \li --vol-value Value (ID) of the VOL connector to use for opening the - HDF5 file specified - * \li --vol-name Name of the VOL connector to use for opening the - HDF5 file specified - * \li --vol-info VOL-specific info to pass to the VOL connector used for - opening the HDF5 file specified - If none of the above options are used to specify a VOL, then - the VOL named by \b HDF5_VOL_CONNECTOR (or the native VOL connector, - if that environment variable is unset) will be used - * \li--vfd-value Value (ID) of the VFL driver to use for opening the - HDF5 file specified - * \li --vfd-name Name of the VFL driver to use for opening the - HDF5 file specified - * \li --vfd-info VFD-specific info to pass to the VFL driver used for - opening the HDF5 file specified + * For use with --filedriver=hdfs + * \code \ :: (\,\, + * \,\, + * \) \endcode + * Any absent attribute will use a default value. + * \li --vol-value Value (ID) of the VOL connector to use for opening the HDF5 file specified + * \li --vol-name Name of the VOL connector to use for opening the HDF5 file specified + * \li --vol-info VOL-specific info to pass to the VOL connector used for + * opening the HDF5 file specified.
            + * If none of the above options are used to specify a VOL, then + * the VOL named by \b HDF5_VOL_CONNECTOR (or the native VOL connector, + * if that environment variable is unset) will be used + * \li--vfd-value Value (ID) of the VFL driver to use for opening the HDF5 file specified + * \li --vfd-name Name of the VFL driver to use for opening the HDF5 file specified + * \li --vfd-info VFD-specific info to pass to the VFL driver used for + * opening the HDF5 file specified * * \subsection subsec_cltools_h5dump_options_obj Object Options * \li --attribute=P Print the specified attribute - If an attribute name contains a slash (/), escape the - slash with a preceding backslash (\). - (See example section below.) + * If an attribute name contains a slash (/), escape the + * slash with a preceding backslash (\). + * (See example section below.) * \li --dataset=P Print the specified dataset * \li --group=P Print the specified group and all members * \li --soft-link=P Print the value(s) of the specified soft link * \li --datatype=P Print the specified named datatype * \li --any_path=P Print any attribute, dataset, group, datatype, or link that matches P - P can be the absolute path or just a relative path. + * P can be the absolute path or just a relative path. * \li --onlyattr Print the header and value of attributes - Optional value 0 suppresses printing attributes. + * Optional value 0 suppresses printing attributes. * \li --vds-view-first-missing Set the VDS bounds to first missing mapped elements. * \li --vds-gap-size=N Set the missing file gap size, N=non-negative integers * @@ -87,11 +83,11 @@ * \li --object-ids Print the object ids * \li --properties Print dataset filters, storage layout and fill value * \li --packedbits=L Print packed bits as unsigned integers, using mask - format L for an integer dataset specified with - option -d. L is a list of offset,length values, - separated by commas. Offset is the beginning bit in - the data value and length is the number of bits of - the mask. + * format L for an integer dataset specified with + * option -d. L is a list of offset,length values, + * separated by commas. Offset is the beginning bit in + * the data value and length is the number of bits of + * the mask. * \li --region Print dataset pointed by region references * * \subsection subsec_cltools_h5dump_options_fmt Formatting Options @@ -102,18 +98,18 @@ * \li --sort_by=Q Sort groups and attributes by index Q * \li --sort_order=Z Sort groups and attributes by order Z * \li --no-compact-subset Disable compact form of subsetting and allow the use - of "[" in dataset names. + * of "[" in dataset names. * \li --width=N Set the number of columns of output. A value of 0 (zero) - sets the number of columns to the maximum (65535). - Default width is 80 columns. + * sets the number of columns to the maximum (65535). + * Default width is 80 columns. * * \subsection subsec_cltools_h5dump_options_xml XML Options * \li --xml Output in XML using Schema * \li --use-dtd Output in XML using DTD * \li --xml-dtd=U Use the DTD or schema at U * \li --xml-ns=S (XML Schema) Use qualified names n the XML - ":": no namespace, default: "hdf5:" - E.g., to dump a file called "-f", use h5dump -- -f + * ":": no namespace, default: "hdf5:" + * E.g., to dump a file called "-f", use h5dump -- -f * * \subsection subsec_cltools_h5dump_options_subset Subsetting Options * Subsetting is available by using the following options with a dataset @@ -133,63 +129,61 @@ * * \subsubsection subsubsec_cltools_h5dump_options_args Option Argument Conventions * \li D - is the file driver to use in opening the file. Acceptable values are available - from https://portal.hdfgroup.org/documentation/hdf5-docs/registered_virtual_file_drivers_vfds.html. Without - the file driver flag, the file will be opened with each driver in turn and in the order specified above until - one driver succeeds in opening the file. See examples below for family, split, and multi driver special file - name usage. - + * from https://support.hdfgroup.org/documentation/HDF5/registered_virtual_file_drivers_vfds.html. Without + * the file driver flag, the file will be opened with each driver in turn and in the order specified above until + * one driver succeeds in opening the file. See examples below for family, split, and multi driver special file + * name usage. + * * \li F - is a filename. * \li P - is the full path from the root group to the object. * \li N - is an integer greater than 1. * \li T - is a string containing the floating point format, e.g '%.3f' * \li U - is a URI reference (as defined in [IETF RFC 2396], - updated by [IETF RFC 2732]) + * updated by [IETF RFC 2732]) * \li B - is the form of binary output: NATIVE for a memory type, FILE for the - file type, LE or BE for pre-existing little or big endian types. - Must be used with -o (output file) and it is recommended that - -d (dataset) is used. B is an optional argument, defaults to NATIVE + * file type, LE or BE for pre-existing little or big endian types. + * Must be used with -o (output file) and it is recommended that + * -d (dataset) is used. B is an optional argument, defaults to NATIVE * \li Q - is the sort index type. It can be "creation_order" or "name" (default) * \li Z - is the sort order type. It can be "descending" or "ascending" (default) * * \subsection subsec_cltools_h5dump_examples Usage Examples - - \li 1) Attribute foo of the group /bar_none in file quux.h5 - - h5dump -a /bar_none/foo quux.h5 - - Attribute "high/low" of the group /bar_none in the file quux.h5 - - h5dump -a "/bar_none/high\/low" quux.h5 - - \li 2) Selecting a subset from dataset /foo in file quux.h5 - - h5dump -d /foo -s "0,1" -S "1,1" -c "2,3" -k "2,2" quux.h5 - - \li 3) Saving dataset 'dset' in file quux.h5 to binary file 'out.bin' - using a little-endian type - - h5dump -d /dset -b LE -o out.bin quux.h5 - - \li 4) Display two packed bits (bits 0-1 and bits 4-6) in the dataset /dset - - h5dump -d /dset -M 0,1,4,3 quux.h5 - - \li 5) Dataset foo in files file1.h5 file2.h5 file3.h5 - - h5dump -d /foo file1.h5 file2.h5 file3.h5 - - \li 6) Dataset foo in split files splitfile-m.h5 splitfile-r.h5 - - h5dump -d /foo -f split splitfile - - \li 7) Dataset foo in multi files mf-s.h5, mf-b.h5, mf-r.h5, mf-g.h5, mf-l.h5 and mf-o.h5 - - h5dump -d /foo -f multi mf - - \li 8) Dataset foo in family files fam00000.h5 fam00001.h5 and fam00002.h5 - - h5dump -d /foo -f family fam%05d.h5 - + * + * \li 1) Attribute foo of the group /bar_none in file quux.h5 + * + * h5dump -a /bar_none/foo quux.h5 + * + * \li 2) Attribute "high/low" of the group /bar_none in the file quux.h5 + * + * h5dump -a "/bar_none/high\/low" quux.h5 + * + * \li 3) Selecting a subset from dataset /foo in file quux.h5 + * + * h5dump -d /foo -s "0,1" -S "1,1" -c "2,3" -k "2,2" quux.h5 + * + * \li 4) Saving dataset 'dset' in file quux.h5 to binary file 'out.bin' using a little-endian type + * + * h5dump -d /dset -b LE -o out.bin quux.h5 + * + * \li 5) Display two packed bits (bits 0-1 and bits 4-6) in the dataset /dset + * + * h5dump -d /dset -M 0,1,4,3 quux.h5 + * + * \li 6) Dataset foo in files file1.h5 file2.h5 file3.h5 + * + * h5dump -d /foo file1.h5 file2.h5 file3.h5 + * + * \li 7) Dataset foo in split files splitfile-m.h5 splitfile-r.h5 + * + * h5dump -d /foo -f split splitfile + * + * \li 8) Dataset foo in multi files mf-s.h5, mf-b.h5, mf-r.h5, mf-g.h5, mf-l.h5 and mf-o.h5 + * + * h5dump -d /foo -f multi mf + * + * \li 9) Dataset foo in family files fam00000.h5 fam00001.h5 and fam00002.h5 + * + * h5dump -d /foo -f family fam%05d.h5 * */ diff --git a/tools/src/h5format_convert/h5format_convert.h b/tools/src/h5format_convert/h5format_convert.h index 490aaf6bfd6..2d7112b5da6 100644 --- a/tools/src/h5format_convert/h5format_convert.h +++ b/tools/src/h5format_convert/h5format_convert.h @@ -20,35 +20,35 @@ * With h5format_convert you can convert a datasets format in an HDF5 file. * * \subsection subsec_cltools_h5format_convert_usage Usage - *

            h5format_convert [OPTIONS] file_name

            + *

            h5format_convert [OPTIONS] file_name

            * * \subsection subsec_cltools_h5format_convert_error Error Report Option - * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. - Optional value 2 also prints file open errors. - + * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. + * Optional value 2 also prints file open errors. + * * \subsection subsec_cltools_h5format_convert_options Options - * \li --help Print a usage message and exit - * \li --version Print the library version number and exit - * \li --verbose Turn on verbose mode - * \li --dname=dataset_name Pathname for the dataset - * \li --noop Perform all the steps except the actual conversion + * \li --help Print a usage message and exit + * \li --version Print the library version number and exit + * \li --verbose Turn on verbose mode + * \li --dname=dataset_name Pathname for the dataset + * \li --noop Perform all the steps except the actual conversion * * \subsubsection subsubsec_cltools_h5format_convert_examples Usage Examples - * \li 1) h5format_convert -dname=/group/dataset file_name - Convert the dataset \ in the HDF5 file \: - a. chunked dataset: convert the chunk indexing type to version 1 B-tree - b. compact/contiguous dataset: downgrade the layout version to 3 - c. virtual dataset: no action - - * \li 2) h5format_convert file_name - Convert all datasets in the HDF5 file \: - a. chunked dataset: convert the chunk indexing type to version 1 B-tree - b. compact/contiguous dataset: downgrade the layout version to 3 - c. virtual dataset: no action - - * \li 3) h5format_convert --noop -dname=/group/dataset file_name - Go through all the steps except the actual conversion when - converting the dataset \ in the HDF5 file \. + * \li 1) \code h5format_convert -dname=/group/dataset file_name \endcode + * Convert the dataset \ in the HDF5 file \: + *
            • a. chunked dataset: convert the chunk indexing type to version 1 B-tree
              • + *
            • b. compact/contiguous dataset: downgrade the layout version to 3
              • + *
            • c. virtual dataset: no action
            + * + * \li 2) \code h5format_convert file_name \endcode + * Convert all datasets in the HDF5 file \: + *
            • a. chunked dataset: convert the chunk indexing type to version 1 B-tree
              • + *
            • b. compact/contiguous dataset: downgrade the layout version to 3
              • + *
            • c. virtual dataset: no action
            + * + * \li 3) \code h5format_convert --noop -dname=/group/dataset file_name \endcode + * Go through all the steps except the actual conversion when + * converting the dataset \ in the HDF5 file \. * */ diff --git a/tools/src/h5import/h5import.h b/tools/src/h5import/h5import.h index 8a7f8d802da..4632f64855e 100644 --- a/tools/src/h5import/h5import.h +++ b/tools/src/h5import/h5import.h @@ -164,7 +164,7 @@ * \subsubsection subsubsec_cltools_h5import_config_val Values for keywords * \li PATH Strings separated by spaces to represent - the path of the data-set. If the groups in + the path of the dataset. If the groups in the path do not exist, they will be created. For example,
            • PATH grp1/grp2/dataset1
              • diff --git a/tools/src/h5jam/h5jam.h b/tools/src/h5jam/h5jam.h index d6d91b60371..a4e9ff5929e 100644 --- a/tools/src/h5jam/h5jam.h +++ b/tools/src/h5jam/h5jam.h @@ -22,48 +22,42 @@ * * \subsection subsec_cltools_h5jam_usage Usage *

              h5jam -i \ -u \ [-o \] [--clobber]

              - *

              h5unjam -i \ [-o \ ] [-u \ | --delete]

              + *

              h5unjam -i \ [-o \ ] [-u \ | --delete]

              * - * \subsection subsec_cltools_h5jam_error Error Report Option - * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. - Optional value 2 also prints file open errors. - * \subsection subsec_cltools_h5jam_options h5jam Options - * \li -i in_file.h5: Specifies the input HDF5 file. - * \li -u in_user_file: Specifies the file to be inserted into the user block. - Can be any file format except an HDF5 format. - * \li -o out_file.h5: Specifies the output HDF5 file. - If not specified, the user block will be concatenated in - place to the input HDF5 file. - * \li --clobber: Wipes out any existing user block before concatenating - the given user block. - The size of the new user block will be the larger of; - - the size of existing user block in the input HDF5 file - - the size of user block required by new input user file - (size = 512 x 2N, N is positive integer.) - - * \li -h: Prints a usage message and exits. - * \li -V: Prints the HDF5 library version and exits. + * \li -i in_file.h5 Specifies the input HDF5 file. + * \li -u in_user_file Specifies the file to be inserted into the user block. + * Can be any file format except an HDF5 format. + * \li -o out_file.h5 Specifies the output HDF5 file. + * If not specified, the user block will be concatenated in + * place to the input HDF5 file. + * \li --clobber Wipes out any existing user block before concatenating + * the given user block. + * The size of the new user block will be the larger of: + * - the size of existing user block in the input HDF5 file + * - the size of user block required by new input user file + * (size = 512 x 2N, N is positive integer.) + * \li -h Prints a usage message and exits. + * \li -V Prints the HDF5 library version and exits. * - * \subsubsection subsubsec_cltools_h5unjam_options h5unjam Options - * \li -i in_file.h5: Specifies the HDF5 as input. If the input HDF5 file - contains no user block, exit with an error message. - * \li -o out_file.h5: Specifies output HDF5 file without a user block. - If not specified, the user block will be removed from the - input HDF5 file. - * \li -u out_user_file: - Specifies the output file containing the data from the - user block. - Cannot be used with --delete option. - * \li --delete: Remove the user block from the input HDF5 file. The content - of the user block is discarded. - Cannot be used with the -u option. - - * \li -h: Prints a usage message and exits. - * \li -V: Prints the HDF5 library version and exits. - - If neither --delete: nor -u: is specified, the user block from the input - file will be displayed to stdout. + * \subsection subsec_cltools_h5unjam_options h5unjam Options + * \li -i in_file.h5 Specifies the HDF5 as input. If the input HDF5 file + * contains no user block, exit with an error message. + * \li -o out_file.h5 Specifies output HDF5 file without a user block. + * If not specified, the user block will be removed from the + * input HDF5 file. + * \li -u out_user_file + * Specifies the output file containing the data from the + * user block. + * Cannot be used with --delete option. + * \li --delete Remove the user block from the input HDF5 file. The content + * of the user block is discarded. + * Cannot be used with the -u option. + * \li -h Prints a usage message and exits. + * \li -V Prints the HDF5 library version and exits. + * + * If neither --delete: nor -u: is specified, the user block from the input + * file will be displayed to stdout. * */ diff --git a/tools/src/h5ls/h5ls.h b/tools/src/h5ls/h5ls.h index ce79c02ca81..382e9dd6bad 100644 --- a/tools/src/h5ls/h5ls.h +++ b/tools/src/h5ls/h5ls.h @@ -20,88 +20,88 @@ * With h5ls you can dump objects from an HDF5 file. * * \subsection subsec_cltools_h5ls_usage Usage - *

              h5ls [OPTIONS] file[/OBJECT] [file[/[OBJECT]...]

              + *

              h5ls [OPTIONS] file[/OBJECT] [file[/[OBJECT]...]

              * * \subsection subsec_cltools_h5ls_objs file/OBJECT - Each object consists of an HDF5 file name optionally followed by a - slash and an object name within the file (if no object is specified - within the file then the contents of the root group are displayed). - The file name may include a printf(3C) integer format such as - "%05d" to open a file family. + * Each object consists of an HDF5 file name optionally followed by a + * slash and an object name within the file (if no object is specified + * within the file then the contents of the root group are displayed). + * The file name may include a printf(3C) integer format such as + * "%05d" to open a file family. * * \subsection subsec_cltools_h5ls_error Error Report Option - * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. - Optional value 2 also prints file open errors. - + * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. + * Optional value 2 also prints file open errors. + * * \subsection subsec_cltools_h5ls_options Options - * \li --help Print a usage message and exit - * \li --address Print raw data address. If dataset is contiguous, address - is offset in file of beginning of raw data. If chunked, - returned list of addresses indicates offset of each chunk. - Must be used with -v, --verbose option. - Provides no information for non-dataset objects. - * \li --data Print the values of datasets - * \li --follow-symlinks - Follow symbolic links (soft links and external links) - to display target object information. - Without this option, h5ls identifies a symbolic link - as a soft link or external link and prints the value - assigned to the symbolic link; it does not provide any - information regarding the target object or determine - whether the link is a dangling link. - * \li --no-dangling-links - Must be used with --follow-symlinks option; - otherwise, h5ls shows error message and returns an exit - code of 1. - Check for any symbolic links (soft links or external links) - that do not resolve to an existing object (dataset, group, - or named datatype). - If any dangling link is found, this situation is treated - as an error and h5ls returns an exit code of 1. - * \li --full Print full path names instead of base names - * \li --group Show information about a group, not its contents - * \li --label Label members of compound datasets - * \li --recursive List all groups recursively, avoiding cycles - * \li --string Print 1-byte integer datasets as ASCII - * \li --simple Use a machine-readable output format - * \li --width=N Set the number of columns of output - * \li --verbose Generate more verbose output - * \li --version Print the library version number and exit - * \li --page-buffer-size=N Set the page buffer cache size, N=non-negative integers - * \li --vfd=DRIVER Use the specified virtual file driver - * \li --hexdump Show raw data in hexadecimal format - * \li --s3-cred=C Supply S3 authentication information to "ros3" vfd. - Accepts tuple of "(\,\,\)". - If absent or C-\>"(,,)", defaults to no-authentication. - Has no effect if vfd flag not set to "ros3". - * \li --hdfs-attrs=A Supply configuration information to Hadoop VFD. - Accepts tuple of (\,\, - ...\,\,\) - If absent or A == '(,,,,)', all default values are used. - Has no effect if vfd flag is not 'hdfs'. - * \li --vol-value Value (ID) of the VOL connector to use for opening the - HDF5 file specified - * \li --vol-name Name of the VOL connector to use for opening the - HDF5 file specified - * \li --vol-info VOL-specific info to pass to the VOL connector used for - opening the HDF5 file specified - If none of the above options are used to specify a VOL, then - the VOL named by HDF5_VOL_CONNECTOR (or the native VOL connector, - if that environment variable is unset) will be used - * \li --vfd-value Value (ID) of the VFL driver to use for opening the - HDF5 file specified - * \li --vfd-name Name of the VFL driver to use for opening the - HDF5 file specified - * \li --vfd-info VFD-specific info to pass to the VFL driver used for - opening the HDF5 file specified + * \li --help Print a usage message and exit + * \li --address Print raw data address. If dataset is contiguous, address + * is offset in file of beginning of raw data. If chunked, + * returned list of addresses indicates offset of each chunk. + * Must be used with --verbose option. + * Provides no information for non-dataset objects. + * \li --data Print the values of datasets + * \li --follow-symlinks + * Follow symbolic links (soft links and external links) + * to display target object information. + * Without this option, h5ls identifies a symbolic link + * as a soft link or external link and prints the value + * assigned to the symbolic link; it does not provide any + * information regarding the target object or determine + * whether the link is a dangling link. + * \li --no-dangling-links + * Must be used with --follow-symlinks option; + * otherwise, h5ls shows error message and returns an exit + * code of 1.
              + * Check for any symbolic links (soft links or external links) + * that do not resolve to an existing object (dataset, group, + * or named datatype).
              + * If any dangling link is found, this situation is treated + * as an error and h5ls returns an exit code of 1. + * \li --full Print full path names instead of base names + * \li --group Show information about a group, not its contents + * \li --label Label members of compound datasets + * \li --recursive List all groups recursively, avoiding cycles + * \li --string Print 1-byte integer datasets as ASCII + * \li --simple Use a machine-readable output format + * \li --width=N Set the number of columns of output + * \li --verbose Generate more verbose output + * \li --version Print the library version number and exit + * \li --page-buffer-size=N Set the page buffer cache size, N=non-negative integers + * \li --vfd=DRIVER Use the specified virtual file driver + * \li --hexdump Show raw data in hexadecimal format + * \li --s3-cred=C Supply S3 authentication information to "ros3" vfd. + * Accepts tuple of \code (\,\,\) \endcode. + * If absent or C = \code (,,) \endcode defaults to no-authentication. + * Has no effect if vfd flag not set to "ros3". + * \li --hdfs-attrs=A Supply configuration information to Hadoop VFD. + * Accepts tuple of \code (\,\, + * ...\,\,\) \endcode + * If absent or A == \code (,,,,) \endcode all default values are used. + * Has no effect if vfd flag is not 'hdfs'. + * \li --vol-value Value (ID) of the VOL connector to use for opening the + * HDF5 file specified + * \li --vol-name Name of the VOL connector to use for opening the + * HDF5 file specified + * \li --vol-info VOL-specific info to pass to the VOL connector used for + * opening the HDF5 file specified + * If none of the above options are used to specify a VOL, then + * the VOL named by HDF5_VOL_CONNECTOR (or the native VOL connector, + * if that environment variable is unset) will be used + * \li --vfd-value Value (ID) of the VFL driver to use for opening the + * HDF5 file specified + * \li --vfd-name Name of the VFL driver to use for opening the + * HDF5 file specified + * \li --vfd-info VFD-specific info to pass to the VFL driver used for + * opening the HDF5 file specified * * \subsubsection subsubsec_cltools_h5ls_options_depre Deprecated Options - The following options have been removed in HDF5 1.12. Use the indicated - replacement option in all work. - * \li --external Follow external links. - Replaced by --follow-symlinks. - * \li --errors Show all HDF5 error reporting - Replaced by --enable-error-stack. + * The following options have been removed in HDF5 1.12. Use the indicated + * replacement option in all work. + * \li --external Follow external links. + * Replaced by --follow-symlinks. + * \li --errors Show all HDF5 error reporting + * Replaced by --enable-error-stack. * */ diff --git a/tools/src/h5repack/h5repack.h b/tools/src/h5repack/h5repack.h index f531a30e457..aaccc0bae05 100644 --- a/tools/src/h5repack/h5repack.h +++ b/tools/src/h5repack/h5repack.h @@ -21,145 +21,143 @@ * With h5repack you can write an HDF5 file to a new file and change the layout for objects in the new file. * * \subsection subsec_cltools_h5repack_usage Usage - *

              h5repack [OPTIONS] file1 file2

              - * \li file1 Input HDF5 File - * \li file2 Output HDF5 File + *

              h5repack [OPTIONS] file1 file2

              + * \li file1 Input HDF5 File + * \li file2 Output HDF5 File * * \subsection subsec_cltools_h5repack_error Error Report Option - * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. + * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. * Optional value 2 also prints file open errors. * * \subsection subsec_cltools_h5repack_options Options - * \li --help Print a usage message and exit - * \li --verbose=N Verbose mode, print object information. + * \li --help Print a usage message and exit + * \li --verbose=N Verbose mode, print object information. * N - is an integer greater than 1, 2 displays read/write timing - * \li --version Print the library version number and exit - * \li --native Use a native HDF5 type when repacking - * \li --page-buffer-size=N Set the page buffer cache size, N=non-negative integers - * \li --src-vol-value Value (ID) of the VOL connector to use for opening the + * \li --version Print the library version number and exit + * \li --native Use a native HDF5 type when repacking + * \li --page-buffer-size=N Set the page buffer cache size, N=non-negative integers + * \li --src-vol-value Value (ID) of the VOL connector to use for opening the * input HDF5 file specified - * \li --src-vol-name Name of the VOL connector to use for opening the input + * \li --src-vol-name Name of the VOL connector to use for opening the input * HDF5 file specified - * \li --src-vol-info VOL-specific info to pass to the VOL connector used for + * \li --src-vol-info VOL-specific info to pass to the VOL connector used for * opening the input HDF5 file specified - * \li --dst-vol-value Value (ID) of the VOL connector to use for opening the + * \li --dst-vol-value Value (ID) of the VOL connector to use for opening the * output HDF5 file specified - * \li --dst-vol-name Name of the VOL connector to use for opening the output + * \li --dst-vol-name Name of the VOL connector to use for opening the output * HDF5 file specified - * \li --dst-vol-info VOL-specific info to pass to the VOL connector used for + * \li --dst-vol-info VOL-specific info to pass to the VOL connector used for * opening the output HDF5 file specified - * \li --src-vfd-value Value (ID) of the VFL driver to use for opening the + * \li --src-vfd-value Value (ID) of the VFL driver to use for opening the * input HDF5 file specified - * \li --src-vfd-name Name of the VFL driver to use for opening the input + * \li --src-vfd-name Name of the VFL driver to use for opening the input * HDF5 file specified - * \li --src-vfd-info VFD-specific info to pass to the VFL driver used for + * \li --src-vfd-info VFD-specific info to pass to the VFL driver used for * opening the input HDF5 file specified - * \li --dst-vfd-value Value (ID) of the VFL driver to use for opening the + * \li --dst-vfd-value Value (ID) of the VFL driver to use for opening the * output HDF5 file specified - * \li --dst-vfd-name Name of the VFL driver to use for opening the output + * \li --dst-vfd-name Name of the VFL driver to use for opening the output * HDF5 file specified - * \li --dst-vfd-info VFD-specific info to pass to the VFL driver used for + * \li --dst-vfd-info VFD-specific info to pass to the VFL driver used for * opening the output HDF5 file specified - * \li --latest Use latest version of file format + * \li --latest Use latest version of file format * This option will take precedence over the options * --low and --high - * \li --low=BOUND The low bound for library release versions to use + * \li --low=BOUND The low bound for library release versions to use * when creating objects in the file * (default is #H5F_LIBVER_EARLIEST) - * \li --high=BOUND The high bound for library release versions to use + * \li --high=BOUND The high bound for library release versions to use * when creating objects in the file * (default is #H5F_LIBVER_LATEST) - * \li --merge Follow external soft link recursively and merge data - * \li --prune Do not follow external soft links and remove link - * \li --merge --prune Follow external link, merge data and remove dangling link - * \li --compact=L1 Maximum number of links in header messages - * \li --indexed=L2 Minimum number of links in the indexed format - * \li --ssize=S[:F] Shared object header message minimum size - * \li --minimum=M Do not apply the filter to datasets smaller than M - * \li --file=E Name of file E with the -f and -l options - * \li --ublock=U Name of file U with user block data to be added - * \li --block=B Size of user block to be added - * \li --metadata_block_size=A Metadata block size for #H5Pset_meta_block_size - * \li --threshold=T Threshold value for #H5Pset_alignment - * \li --alignment=A Alignment value for #H5Pset_alignment - * \li --sort_by=Q Sort groups and attributes by index Q - * \li --sort_order=Z Sort groups and attributes by order Z - * \li --filter=FILT Filter type - * \li --layout=LAYT Layout type - * \li --fs_strategy=FS_STRATEGY File space management strategy for + * \li --merge Follow external soft link recursively and merge data + * \li --prune Do not follow external soft links and remove link + * \li --merge --prune Follow external link, merge data and remove dangling link + * \li --compact=L1 Maximum number of links in header messages + * \li --indexed=L2 Minimum number of links in the indexed format + * \li --ssize=S[:F] Shared object header message minimum size + * \li --minimum=M Do not apply the filter to datasets smaller than M + * \li --file=E Name of file E with the -f and -l options + * \li --ublock=U Name of file U with user block data to be added + * \li --block=B Size of user block to be added + * \li --metadata_block_size=A Metadata block size for #H5Pset_meta_block_size + * \li --threshold=T Threshold value for #H5Pset_alignment + * \li --alignment=A Alignment value for #H5Pset_alignment + * \li --sort_by=Q Sort groups and attributes by index Q + * \li --sort_order=Z Sort groups and attributes by order Z + * \li --filter=FILT Filter type + * \li --layout=LAYT Layout type + * \li --fs_strategy=FS_STRATEGY File space management strategy for * #H5Pset_file_space_strategy - * \li --fs_persist=FS_PERSIST Persisting or not + * \li --fs_persist=FS_PERSIST Persisting or not * persisting free-space for #H5Pset_file_space_strategy - * \li ---fs_threshold=FS_THRESHOLD : Free-space section + * \li ---fs_threshold=FS_THRESHOLD : Free-space section * threshold for #H5Pset_file_space_strategy * \li --fs_pagesize=FS_PAGESIZE File space page size for #H5Pset_file_space_page_size * * \subsubsection subsubsec_cltools_h5repack_options_args Arguments to Certain Options - * \li M - is an integer greater than 1, size of dataset in bytes (default is 0) - * \li E - is a filename. - * \li S - is an integer - * \li U - is a filename. - * \li T - is an integer - * \li A - is an integer greater than zero - * \li Q - is the sort index type for the input file. It can be "name" or - * "creation_order" (default) - * \li Z - is the sort order type for the input file. It can be "descending" or + * \li M - is an integer greater than 1, size of dataset in bytes (default is 0) + * \li E - is a filename. + * \li S - is an integer + * \li U - is a filename. + * \li T - is an integer + * \li A - is an integer greater than zero + * \li Q - is the sort index type for the input file. It can be "name" or + * "creation_order" (default) + * \li Z - is the sort order type for the input file. It can be "descending" or * "ascending" (default) - * \li B - is the user block size, any value that is 512 or greater and is + * \li B - is the user block size, any value that is 512 or greater and is * a power of 2 (1024 default) - * \li F - is the shared object header message type, any of F - is the shared object header message type, any of . If F is not specified, S applies to all messages * * \subsubsection subsubsec_cltools_h5repack_options_bound Library Version Bounds - * BOUND is an integer indicating the library release versions to use when + * BOUND is an integer indicating the library release versions to use when * creating objects in the file (see #H5Pset_libver_bounds()): - * \li 0 This is #H5F_LIBVER_EARLIEST in #H5F_libver_t struct - * \li 1 This is #H5F_LIBVER_V18 in #H5F_libver_t struct - * \li 2 This is #H5F_LIBVER_V110 in #H5F_libver_t struct - * \li 3 This is #H5F_LIBVER_V112 in #H5F_libver_t struct - * \li 4 This is #H5F_LIBVER_V114 in #H5F_libver_t struct - * \li 5 This is #H5F_LIBVER_V116 in #H5F_libver_t struct - * \li (#H5F_LIBVER_LATEST is aliased to #H5F_LIBVER_V116 for this release + * \li 0 This is #H5F_LIBVER_EARLIEST in #H5F_libver_t struct + * \li 1 This is #H5F_LIBVER_V18 in #H5F_libver_t struct + * \li 2 This is #H5F_LIBVER_V110 in #H5F_libver_t struct + * \li 3 This is #H5F_LIBVER_V112 in #H5F_libver_t struct + * \li 4 This is #H5F_LIBVER_V114 in #H5F_libver_t struct + * \li 5 This is #H5F_LIBVER_V116 in #H5F_libver_t struct + * \li #H5F_LIBVER_LATEST is aliased to #H5F_LIBVER_V116 for this release * * \subsubsection subsubsec_cltools_h5repack_options_fs File Strategy Settings - * FS_STRATEGY is a string indicating the file space strategy used: - * \li FSM_AGGR + * FS_STRATEGY is a string indicating the file space strategy used: + * \li FSM_AGGR * The mechanisms used in managing file space are free-space * managers, aggregators and virtual file driver. - * \li PAGE + * \li PAGE * The mechanisms used in managing file space are free-space * managers with embedded paged aggregation and virtual file driver. - * \li AGGR + * \li AGGR * The mechanisms used in managing file space are aggregators and * virtual file driver. - * \li NONE + * \li NONE * The mechanisms used in managing file space are virtual file * driver. - * \li The default strategy when not set is \b FSM_AGGR without persisting free- - * space. + * \li The default strategy when not set is \b FSM_AGGR without persisting free-space. * - * \li FS_PERSIST is 1 to persisting free-space or 0 to not persisting free-space. + * \li FS_PERSIST is 1 to persisting free-space or 0 to not persisting free-space. * The default when not set is not persisting free-space. * The value is ignored for \b AGGR and \b NONE strategies. * - * \li FS_THRESHOLD is the minimum size (in bytes) of free-space sections to be - * tracked by the library. - * The default when not set is 1. + * \li FS_THRESHOLD is the minimum size (in bytes) of free-space sections to be + * tracked by the library. The default when not set is 1. * The value is ignored for \b AGGR and \b NONE strategies. * - * \li FS_PAGESIZE is the size (in bytes) >=512 that is used by the library when - * the file space strategy \b PAGE is used. + * \li FS_PAGESIZE is the size (in bytes) >=512 that is used by the library when + * the file space strategy \b PAGE is used. * The default when not set is 4096. * * \subsubsection subsubsec_cltools_h5repack_options_filt Applying a Third-party Filter - * FILT - is a string with the format: + * FILT - is a string with the format: * - * \li \:\=\ + * \li \:\=\ * - * \li \ is a comma separated list of object names, meaning apply + * \li \ is a comma separated list of object names, meaning apply * compression only to those objects. If no names are specified, the filter * is applied to all objects - * \li \ can be: + * \li \ can be: *
              • GZIP to apply the HDF5 GZIP filter (GZIP compression)
                • *
              • SZIP to apply the HDF5 SZIP filter (SZIP compression)
                • *
              • SHUF to apply the HDF5 shuffle filter
                • @@ -168,7 +166,7 @@ *
              • SOFF to apply the HDF5 Scale/Offset filter
                • *
              • UD to apply a user defined filter
                • *
              • NONE to remove all filters
              - * \li \ is optional filter parameter information + * \li \ is optional filter parameter information *
              • GZIP=\ from 1-9
                • *
              • SZIP= pixels per block is a even number in * 2-32 and coding method is either EC or NN
                • @@ -178,30 +176,30 @@ *
              • SOFF=\ scale_factor is an integer and scale_type * is either IN or DS
                • *
              • UD=\ - * Required values: filter_number, filter_flag, cd_value_count, value1 - * Optional values: value2 to valueN - * filter_flag: 1 is OPTIONAL or 0 is MANDATORY
                • + *
                • Required values filter_number, filter_flag, cd_value_count, value1
                  • + *
                • Optional values value2 to valueN
                  • + *
                • filter_flag 1 is OPTIONAL or 0 is MANDATORY
                *
              • NONE (no parameter)
              * * \subsubsection subsubsec_cltools_h5repack_options_lay Layout Settings - * LAYT - is a string with the format: + * LAYT - is a string with the format: * - * \li \:\=\ + * \li \:\=\ * - * \li \ is a comma separated list of object names, meaning that + * \li \ is a comma separated list of object names, meaning that * layout information is supplied for those objects. If no names are * specified, the layout type is applied to all objects - * \li \ can be: + * \li \ can be: *
              • CHUNK to apply chunking layout
                • *
              • COMPA to apply compact layout
                • *
              • CONTI to apply contiguous layout
              - * \li \ is optional layout information + * \li \ is optional layout information *
              • CHUNK=DIM[xDIM...xDIM], the chunk size of each dimension
                • *
              • COMPA (no parameter)
                • *
              • CONTI (no parameter)
              * * \subsubsection subsubsec_cltools_h5repack_options_note NOTE - * The environment variable H5TOOLS_BUFSIZEcan be set to + * The environment variable H5TOOLS_BUFSIZE can be set to * the number of MBs to change the default hyperslab buffer size from 32MB. * \code setenv H5TOOLS_BUFSIZE=64 to double the hyperslab buffer. \endcode * diff --git a/tools/src/h5stat/h5stat.h b/tools/src/h5stat/h5stat.h index 26a544e7bbb..84049498c93 100644 --- a/tools/src/h5stat/h5stat.h +++ b/tools/src/h5stat/h5stat.h @@ -20,45 +20,45 @@ * With h5stat you can dump stats from an HDF5 file. * * \subsection subsec_cltools_h5stat_usage Usage - *

              h5stat [OPTIONS] file

              + *

              h5stat [OPTIONS] file

              * * \subsection subsec_cltools_h5stat_error Error Report Option - * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. - Optional value 2 also prints file open errors. - + * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. + * Optional value 2 also prints file open errors. + * * \subsection subsec_cltools_h5stat_options Options - * \li --help Print a usage message and exit - * \li --version Print the library version number and exit - * \li --file Print file information - * \li --filemetadata Print file space information for file's metadata - * \li --group Print group information - * \li --links=N Set the threshold for the # of links when printing - information for small groups. N is an integer greater - than 0. The default threshold is 10. - * \li --groupmetadata Print file space information for groups' metadata - * \li --dset Print dataset information - * \li --dims=N Set the threshold for the dimension sizes when printing - information for small datasets. N is an integer greater - than 0. The default threshold is 10. - * \li --dsetmetadata Print file space information for datasets' metadata - * \li --dtypemetadata Print datasets' datatype information - * \li --attribute Print attribute information - * \li --numattrs=N Set the threshold for the number of attributes when printing - information for small number of attributes. N is an integer greater - than 0. The default threshold is 10. - * \li --freespace Print free space information - * \li --summary Print summary of file space information - * \li --page-buffer-size=N Set the page buffer cache size, N=non-negative integers - * \li --s3-cred=\ Access file on S3, using provided credential - \ :: (region,id,key) - If \ == "(,,)", no authentication is used. - * \li --hdfs-attrs=\ Access a file on HDFS with given configuration - attributes. - \ :: (\,\, - \,\, - \) - If an attribute is empty, a default value will be - used. + * \li --help Print a usage message and exit + * \li --version Print the library version number and exit + * \li --file Print file information + * \li --filemetadata Print file space information for file's metadata + * \li --group Print group information + * \li --links=N Set the threshold for the # of links when printing + * information for small groups. N is an integer greater + * than 0. The default threshold is 10. + * \li --groupmetadata Print file space information for groups' metadata + * \li --dset Print dataset information + * \li --dims=N Set the threshold for the dimension sizes when printing + * information for small datasets. N is an integer greater + * than 0. The default threshold is 10. + * \li --dsetmetadata Print file space information for datasets' metadata + * \li --dtypemetadata Print datasets' datatype information + * \li --attribute Print attribute information + * \li --numattrs=N Set the threshold for the number of attributes when printing + * information for small number of attributes. N is an integer greater + * than 0. The default threshold is 10. + * \li --freespace Print free space information + * \li --summary Print summary of file space information + * \li --page-buffer-size=N Set the page buffer cache size, N=non-negative integers + * \li --s3-cred=C Supply S3 authentication information to "ros3" vfd. + * Accepts tuple of \code (\,\,\) \endcode. + * If absent or C = \code (,,) \endcode defaults to no-authentication. + * Has no effect if vfd flag not set to "ros3". + * \li --hdfs-attrs=A Supply configuration information to Hadoop VFD. + * Accepts tuple of \code (\,\, + * ...\,\,\) \endcode + * If absent or A == \code (,,,,) \endcode all default values are used. + * Has no effect if vfd flag is not 'hdfs'.
              + * If an attribute is empty, a default value will be used. * */ diff --git a/tools/src/misc/h5clear.h b/tools/src/misc/h5clear.h index 675aee0366b..7bfb6a05cd2 100644 --- a/tools/src/misc/h5clear.h +++ b/tools/src/misc/h5clear.h @@ -17,47 +17,51 @@ * \section sec_cltools_h5clear h5clear * * \subsection subsec_cltools_h5clear_intro Introduction - * With h5clear you can clear the 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. + * With h5clear you can clear the superblock status flag field, remove the metadata cache image, print + * the EOA and EOF, or set the 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. * * \subsection subsec_cltools_h5clear_usage Usage - *

              h5clear [OPTIONS] file_name

              + *

              h5clear [OPTIONS] file_name

              * * \subsection subsec_cltools_h5clear_error Error Report Option - * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. - Optional value 2 also prints file open errors. - + * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. + * Optional value 2 also prints file open errors. + * * \subsection subsec_cltools_h5clear_options Options - * \li --help Print a usage message and exit - * \li --version Print the library version number and exit - * \li --status Clear the status_flags field in the file's superblock - * \li --image Remove the metadata cache image from the file - * \li --filesize Print the file's EOA and EOF - * \li --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 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. + * \li --help Print a usage message and exit + * \li --version Print the library version number and exit + * \li --status Clear the status_flags field in the file's superblock + * \li --image Remove the metadata cache image from the file + * \li --filesize Print the file's EOA and EOF + * \li --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 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. * * \subsection subsec_cltools_h5clear_examples Usage Examples - * \li h5clear -s file_name - Clear the status_flags field in the superblock of the HDF5 file \. - - * \li h5clear -m file_name - Remove the metadata cache image from the HDF5 file \. - - * \li h5clear --increment file_name - Set the EOA to the maximum of (EOA, EOF) + 1M for the file \. - - * \li h5clear --increment=512 file_name - Set the EOA to the maximum of (EOA, EOF) + 512 for the file \. - + * \li 1) h5clear -s file_name + * + * Clear the status_flags field in the superblock of the HDF5 file \. + * + * \li 2) h5clear -m file_name + * + * Remove the metadata cache image from the HDF5 file \. + * + * \li 3) h5clear --increment file_name + * + * Set the EOA to the maximum of (EOA, EOF) + 1M for the file \. + * + * \li 4) h5clear --increment=512 file_name + * + * Set the EOA to the maximum of (EOA, EOF) + 512 for the file \. + * */ #endif /* H5CLEAR_H */ diff --git a/tools/src/misc/h5debug.h b/tools/src/misc/h5debug.h index 1318d7752b7..0b7cd3cfea2 100644 --- a/tools/src/misc/h5debug.h +++ b/tools/src/misc/h5debug.h @@ -20,11 +20,11 @@ * With h5debug you can debug an existing HDF5 file at a low level. * * \subsection subsec_cltools_h5debug_usage Usage - *

              h5debug filename [signature-addr [extra]*]

              - + *

              h5debug filename [signature-addr [extra]*]

              + * * \subsection subsec_cltools_h5debug_options Options - * \li signature-addr: Primary data structure to dump - * \li extra: Extra arguments for primary data structure + * \li signature-addr Primary data structure to dump + * \li extra Extra arguments for primary data structure * */ diff --git a/tools/src/misc/h5delete.h b/tools/src/misc/h5delete.h index 52bb299efc1..1bc00d7add6 100644 --- a/tools/src/misc/h5delete.h +++ b/tools/src/misc/h5delete.h @@ -20,10 +20,10 @@ * With h5delete you can delete an HDF5 file. * * \subsection subsec_cltools_h5delete_usage Usage - *

              h5delete [-f] \

              - + *

              h5delete [-f] \

              + * * \subsection subsec_cltools_h5delete_options Options - * \li -f: Suppress output + * \li -f Suppress output * */ diff --git a/tools/src/misc/h5mkgrp.h b/tools/src/misc/h5mkgrp.h index e41216b85aa..9fb6d12800d 100644 --- a/tools/src/misc/h5mkgrp.h +++ b/tools/src/misc/h5mkgrp.h @@ -20,33 +20,33 @@ * With h5mkgrp you can create group(s) in an HDF5 file * * \subsection subsec_cltools_h5mkgrp_usage Usage - *

              h5mkgrp [OPTIONS] FILE GROUP

              + *

              h5mkgrp [OPTIONS] FILE GROUP

              * * \subsection subsec_cltools_h5mkgrp_error Error Report Option - * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. - Optional value 2 also prints file open errors. - + * \li--enable-error-stack Prints messages from the HDF5 error stack as they occur. + * Optional value 2 also prints file open errors. + * * \subsection subsec_cltools_h5mkgrp_options Options - * \li --help Print a usage message and exit - * \li --version Print the library version number and exit - * \li --verbose Print information about OBJECTS and OPTIONS - * \li --latest Use latest version of file format to create groups - * \li --parents No error if existing, make parent groups as needed - * \li --vol-value Value (ID) of the VOL connector to use for opening the - HDF5 file specified - * \li --vol-name Name of the VOL connector to use for opening the - HDF5 file specified - * \li --vol-info VOL-specific info to pass to the VOL connector used for - opening the HDF5 file specified - If none of the above options are used to specify a VOL, then - the VOL named by HDF5_VOL_CONNECTOR (or the native VOL connector, - if that environment variable is unset) will be used - * \li --vfd-value Value (ID) of the VFL driver to use for opening the - HDF5 file specified - * \li --vfd-name Name of the VFL driver to use for opening the - HDF5 file specified - * \li --vfd-info VFD-specific info to pass to the VFL driver used for - opening the HDF5 file specified + * \li --help Print a usage message and exit + * \li --version Print the library version number and exit + * \li --verbose Print information about OBJECTS and OPTIONS + * \li --latest Use latest version of file format to create groups + * \li --parents No error if existing, make parent groups as needed + * \li --vol-value Value (ID) of the VOL connector to use for opening the + * HDF5 file specified + * \li --vol-name Name of the VOL connector to use for opening the + * HDF5 file specified + * \li --vol-info VOL-specific info to pass to the VOL connector used for + * opening the HDF5 file specified.
              + * If none of the above options are used to specify a VOL, then + * the VOL named by HDF5_VOL_CONNECTOR (or the native VOL connector, + * if that environment variable is unset) will be used + * \li --vfd-value Value (ID) of the VFL driver to use for opening the + * HDF5 file specified + * \li --vfd-name Name of the VFL driver to use for opening the + * HDF5 file specified + * \li --vfd-info VFD-specific info to pass to the VFL driver used for + * opening the HDF5 file specified * */ diff --git a/tools/src/misc/h5repart.h b/tools/src/misc/h5repart.h index 0c8d76baaf6..1adec24b1b4 100644 --- a/tools/src/misc/h5repart.h +++ b/tools/src/misc/h5repart.h @@ -17,30 +17,30 @@ * \section sec_cltools_h5repart h5repart * * \subsection subsec_cltools_h5repart_intro Introduction - * With h5repart you can repartition a file family. This program can be used to + * With h5repart you can repartition a file family. This program can be used to * split a single file into a family of files, join a family of * files into a single file, or copy one family to another while - * changing the size of the family members. It can also be used + * changing the size of the family members. It can also be used * to copy a single file to a single file with holes. * * \subsection subsec_cltools_h5repart_usage Usage - *

              h5repart [OPTIONS] SRC DST

              + *

              h5repart [OPTIONS] SRC DST

              * * \subsection subsec_cltools_h5repart_objs SRC/DST - * \li SRC: The name of the source file - * \li DST: The name of the destination files - + * \li SRC The name of the source file + * \li DST The name of the destination files + * * \subsection subsec_cltools_h5repart_options Options - * \li -v: Produce verbose output - * \li -V: Print version number and exit - * \li -b N: The I/O block size, defaults to 1kB - * \li -m N: The destination member size or 1GB - * \li -family_to_sec2: Deprecated version of -family_to_single (below) - * \li -family_to_single: Change file driver from family to the default single-file - VFD (windows or sec2) + * \li -v Produce verbose output + * \li -V Print version number and exit + * \li -b N The I/O block size, defaults to 1kB + * \li -m N The destination member size or 1GB + * \li -family_to_sec2 Deprecated version of -family_to_single (below) + * \li -family_to_single Change file driver from family to the default single-file + * VFD (windows or sec2) * - Sizes may be suffixed with 'g' for GB, 'm' for MB or 'k' for kB. - File family names include an integer printf format such as '%%d' + * Sizes may be suffixed with 'g' for GB, 'm' for MB or 'k' for kB. + * File family names include an integer printf format such as '%%d' * */ From c0a73d3b20f7ded0e1527b773b021ae3e4261de9 Mon Sep 17 00:00:00 2001 From: github-actions <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 25 Jun 2024 20:02:34 +0000 Subject: [PATCH 13/24] Committing clang-format changes --- tools/src/h5diff/h5diff_main.h | 49 +++++++++++++--------------------- tools/src/h5dump/h5dump.h | 6 ++--- tools/src/h5repack/h5repack.h | 7 +++-- 3 files changed, 25 insertions(+), 37 deletions(-) diff --git a/tools/src/h5diff/h5diff_main.h b/tools/src/h5diff/h5diff_main.h index 9ffa0fdffca..2791931b109 100644 --- a/tools/src/h5diff/h5diff_main.h +++ b/tools/src/h5diff/h5diff_main.h @@ -116,36 +116,25 @@ * is the data point value in file1 and b is the data point value in file2. * If the system epsilon is not defined,one of the following predefined * values will be used: - *
              • FLT_EPSILON = 1.19209E-07 for floating-point type
                • - *
              • DBL_EPSILON = 2.22045E-16 for double precision
              - * type Can not use with '--relative' or '--delta'. - * \li --exclude-path "path" - * Exclude the specified path to an object when comparing files or groups. - * If a group is excluded, all member objects will also be excluded. - * The specified path is excluded wherever it occurs. - * This flexibility enables the same option to exclude either objects that - * exist only in one file or common objects that are known to differ.
              - * When comparing files, "path" is the absolute path to the excluded; - * object; when comparing groups, "path" is similar to the relative - * path from the group to the excluded object. This "path" can be - * taken from the first section of the output of the --verbose option. - * For example, if you are comparing the group - * /groupA in two files and - * you want to exclude - * /groupA/groupB/groupC - * in both files, the exclude option would read as follows:
              - * --exclude-path "/groupB/groupC" - *
              - * If there are multiple paths to an object, only the specified path(s) - * will be excluded; the comparison will include any path not explicitly - * excluded.
              - * This option can be used repeatedly to exclude multiple paths. - * \li --exclude-attribute "path/to/object/with/attribute" - * Exclude attributes on the specified path to an object when comparing files or groups.
              - * If there are multiple paths to an object, only the specified path(s) - * will be excluded; the comparison will include any path not explicitly - * excluded.
              - * This option can be used repeatedly to exclude multiple paths. + *
              • FLT_EPSILON = 1.19209E-07 for + * floating-point type
              • DBL_EPSILON = 2.22045E-16 + * for double precision
              type Can not use with '--relative' or '--delta'. \li --exclude-path + * "path" Exclude the specified path to an object when comparing files or groups. If a group is + * excluded, all member objects will also be excluded. The specified path is excluded wherever it occurs. This + * flexibility enables the same option to exclude either objects that exist only in one file or common objects + * that are known to differ.
              When comparing files, "path" is the absolute path to the excluded; object; + * when comparing groups, "path" is similar to the relative path from the group to the excluded object. This + * "path" can be taken from the first section of the output of the --verbose option. For example, if you are + * comparing the group /groupA in two files and you want to + * exclude /groupA/groupB/groupC in both files, the exclude + * option would read as follows:
              --exclude-path + * "/groupB/groupC"
              If there are multiple paths to an object, only the specified path(s) will be + * excluded; the comparison will include any path not explicitly excluded.
              This option can be used + * repeatedly to exclude multiple paths. \li --exclude-attribute + * "path/to/object/with/attribute" Exclude attributes on the specified path to an object when + * comparing files or groups.
              If there are multiple paths to an object, only the specified path(s) will + * be excluded; the comparison will include any path not explicitly excluded.
              This option can be used + * repeatedly to exclude multiple paths. * * \subsubsection subsubsec_cltools_h5diff_modee Modes of output * \li Default mode print the number of differences found and where they occurred diff --git a/tools/src/h5dump/h5dump.h b/tools/src/h5dump/h5dump.h index 0fc0bcfdb8b..c72d7ef8611 100644 --- a/tools/src/h5dump/h5dump.h +++ b/tools/src/h5dump/h5dump.h @@ -130,9 +130,9 @@ * \subsubsection subsubsec_cltools_h5dump_options_args Option Argument Conventions * \li D - is the file driver to use in opening the file. Acceptable values are available * from https://support.hdfgroup.org/documentation/HDF5/registered_virtual_file_drivers_vfds.html. Without - * the file driver flag, the file will be opened with each driver in turn and in the order specified above until - * one driver succeeds in opening the file. See examples below for family, split, and multi driver special file - * name usage. + * the file driver flag, the file will be opened with each driver in turn and in the order specified above + * until one driver succeeds in opening the file. See examples below for family, split, and multi driver + * special file name usage. * * \li F - is a filename. * \li P - is the full path from the root group to the object. diff --git a/tools/src/h5repack/h5repack.h b/tools/src/h5repack/h5repack.h index aaccc0bae05..45e613511f2 100644 --- a/tools/src/h5repack/h5repack.h +++ b/tools/src/h5repack/h5repack.h @@ -176,10 +176,9 @@ *
            • SOFF=\ scale_factor is an integer and scale_type * is either IN or DS
              • *
            • UD=\ - *
              • Required values filter_number, filter_flag, cd_value_count, value1
                • - *
              • Optional values value2 to valueN
                • - *
              • filter_flag 1 is OPTIONAL or 0 is MANDATORY
              • - *
            • NONE (no parameter)
            + *
            • Required values filter_number, filter_flag, cd_value_count, + * value1
            • Optional values value2 to valueN
            • filter_flag 1 + * is OPTIONAL or 0 is MANDATORY
          • NONE (no parameter)
          * * \subsubsection subsubsec_cltools_h5repack_options_lay Layout Settings * LAYT - is a string with the format: From 655d269f647c4fbc56e4f27d565e29d1184b0abc Mon Sep 17 00:00:00 2001 From: Allen Byrne Date: Tue, 25 Jun 2024 16:57:15 -0500 Subject: [PATCH 14/24] Fix some doxygen display issues --- hl/tools/h5watch/h5watch.h | 68 +++-- tools/src/h5copy/h5copy.h | 5 +- tools/src/h5diff/h5diff_main.h | 65 ++-- tools/src/h5dump/h5dump.h | 6 +- tools/src/h5format_convert/h5format_convert.h | 35 ++- tools/src/h5import/h5import.h | 280 ++++++++---------- tools/src/h5jam/h5jam.h | 10 +- tools/src/h5ls/h5ls.h | 8 +- tools/src/h5repack/h5repack.h | 22 +- tools/src/h5stat/h5stat.h | 2 +- tools/src/misc/h5clear.h | 10 +- tools/src/misc/h5debug.h | 2 +- tools/src/misc/h5delete.h | 2 +- tools/src/misc/h5mkgrp.h | 2 +- tools/src/misc/h5repart.h | 6 +- 15 files changed, 250 insertions(+), 273 deletions(-) diff --git a/hl/tools/h5watch/h5watch.h b/hl/tools/h5watch/h5watch.h index 0d6b7c0971e..20c82ecaf03 100644 --- a/hl/tools/h5watch/h5watch.h +++ b/hl/tools/h5watch/h5watch.h @@ -17,47 +17,45 @@ * \section sec_cltools_h5watch h5watch * * \subsection subsec_cltools_h5watch_intro Introduction - * With h5watch you can dump stats from an HDF5 file. + * With h5watch, you can dump stats from an HDF5 file. * * \subsection subsec_cltools_h5watch_usage Usage - *

          h5watch [OPTIONS] [OBJECT]

          + *

          h5watch [OPTIONS] [OBJECT]

          * * \subsection subsec_cltools_h5watch_error Error Report Option - * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. - Optional value 2 also prints file open errors. - + * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. + * Optional value 2 also prints file open errors. + * * \subsection subsec_cltools_h5watch_options Options - * \li --help Print a usage message and exit - * \li --version Print the library version number and exit - * \li --label Label members of compound typed dataset. - * \li --simple Use a machine-readable output format. - * \li --dim Monitor changes in size of dataset dimensions only. - * \li --width=N Set the number of columns to N for output. - A value of 0 sets the number of columns to the - maximum (65535). The default width is 80 columns. - * \li --polling=N Set the polling interval to N (in seconds) when the - dataset will be checked for appended data. The default - polling interval is 1. - * \li --fields=\ - Display data for the fields specified in \ - for a compound data type. \ can be - specified as follows: -
          • 1) A comma-separated list of field names in a - compound data type. "," is the separator - for field names while "." is the separator - for a nested field.
            • -
          • 2) A single field name in a compound data type. - This option can be used multiple times.
          - Note that backslash is the escape character to avoid - characters in field names that conflict with the tool's - separators. - + * \li --help Print a usage message and exit + * \li --version Print the library version number and exit + * \li --label Label members of compound typed dataset. + * \li --simple Use a machine-readable output format. + * \li --dim Monitor changes in size of dataset dimensions only. + * \li --width=N Set the number of columns to N for output.
          + * A value of 0 sets the number of columns to the + * maximum (65535). The default width is 80 columns. + * \li --polling=N Set the polling interval to N (in seconds) when the + * dataset will be checked for appended data. + * The default polling interval is 1. + * \li --fields=\ + * Display data for the fields specified in \ + * for a compound data type. + * \ can be specified as follows: + *
          • 1) A comma-separated list of field names in a + * compound data type. "," is the separatorfor field names while "." is the separator + * for a nested field.
            • + *
          • 2) A single field name in a compound data type. + * This option can be used multiple times.
          + * Note that backslash is the escape character to avoid + * characters in field names that conflict with the tool's separators. + * * \subsection subsec_cltools_h5watch_objs Object - OBJECT is specified as [\/\/\] - * \li \ Name of the HDF5 file. It may be preceded by path - separated by slashes to the specified HDF5 file. - * \li \ Path separated by slashes to the specified dataset - * \li \ Name of the dataset + * OBJECT is specified as [\/\/\] + * \li \ Name of the HDF5 file. It may be preceded by path + * separated by slashes to the specified HDF5 file. + * \li \ Path separated by slashes to the specified dataset + * \li \ Name of the dataset * */ diff --git a/tools/src/h5copy/h5copy.h b/tools/src/h5copy/h5copy.h index aaec294b0ce..38889afe938 100644 --- a/tools/src/h5copy/h5copy.h +++ b/tools/src/h5copy/h5copy.h @@ -18,7 +18,7 @@ * \section sec_cltools_h5copy h5copy * * \subsection subsec_cltools_h5copy_intro Introduction - * With h5copy you can copy objects from an HDF5 file to another file. + * With h5copy, you can copy objects from an HDF5 file to another file. * * \subsection subsec_cltools_h5copy_usage Usage *

          h5copy [OPTIONS] [OBJECTS...]

          @@ -52,7 +52,7 @@ * populated with correct reference values. Copies of referenced * datasets outside the copy range specified on the command line * will normally have a different name from the original.
          - * (Default:Without this option, reference value(s) in any + * (Default: Without this option, reference value(s) in any * reference datasets are set to NULL and referenced objects are * not copied unless they are otherwise within the copy range * specified on the command line.) @@ -67,7 +67,6 @@ * \li #H5O_COPY_WITHOUT_ATTR_FLAG * \li #H5O_COPY_ALL * - * */ #endif /* H5COPY_H */ diff --git a/tools/src/h5diff/h5diff_main.h b/tools/src/h5diff/h5diff_main.h index 2791931b109..2a4df559193 100644 --- a/tools/src/h5diff/h5diff_main.h +++ b/tools/src/h5diff/h5diff_main.h @@ -18,7 +18,7 @@ * \section sec_cltools_h5diff h5diff * * \subsection subsec_cltools_h5diff_intro Introduction - * With h5diff you can compare objects between a HDF5 file and another file. + * With h5diff, you can compare objects between a HDF5 file and another file. * * \subsection subsec_cltools_h5diff_usage Usage *

          h5diff [OPTIONS] file1 file2 [obj1[ obj2]]

          @@ -55,7 +55,7 @@ * \li --vol-name-2 Name of the VOL connector to use for opening the second * HDF5 file specified * \li --vol-info-2 VOL-specific info to pass to the VOL connector used for - * opening the second HDF5 file specified + * opening the second HDF5 file specified.
          * If none of the above options are used to specify a VOL for a file, then * the VOL named by HDF5_VOL_CONNECTOR (or the native VOL connector, * if that environment variable is unset) will be used @@ -73,7 +73,7 @@ * opening the second HDF5 file specified * \li --follow-symlinks * Follow symbolic links (soft links and external links and compare the) - * links' target objects. + * links' target objects.
          * If symbolic link(s) with the same name exist in the files being * compared, then determine whether the target of each link is an existing * object (dataset, group, or named datatype) or the link is a dangling @@ -94,8 +94,8 @@ * If any symbolic link specified in the call to h5diff does not exist, * h5diff treats it as an error and returns an exit code of 2. * \li --no-dangling-links - * Must be used with --follow-symlinks option; otherwise, h5diff shows - * error message and returns an exit code of 2. + * Must be used with --follow-symlinks option; otherwise, h5diff shows + * error message and returns an exit code of 2.
          * Check for any symbolic links (soft links or external links) that do not * resolve to an existing object (dataset, group, or named datatype). * If any dangling link is found, this situation is treated as an error @@ -116,25 +116,30 @@ * is the data point value in file1 and b is the data point value in file2. * If the system epsilon is not defined,one of the following predefined * values will be used: - *
          • FLT_EPSILON = 1.19209E-07 for - * floating-point type
          • DBL_EPSILON = 2.22045E-16 - * for double precision
          type Can not use with '--relative' or '--delta'. \li --exclude-path - * "path" Exclude the specified path to an object when comparing files or groups. If a group is - * excluded, all member objects will also be excluded. The specified path is excluded wherever it occurs. This - * flexibility enables the same option to exclude either objects that exist only in one file or common objects - * that are known to differ.
          When comparing files, "path" is the absolute path to the excluded; object; - * when comparing groups, "path" is similar to the relative path from the group to the excluded object. This - * "path" can be taken from the first section of the output of the --verbose option. For example, if you are - * comparing the group /groupA in two files and you want to - * exclude /groupA/groupB/groupC in both files, the exclude - * option would read as follows:
          --exclude-path - * "/groupB/groupC"
          If there are multiple paths to an object, only the specified path(s) will be - * excluded; the comparison will include any path not explicitly excluded.
          This option can be used - * repeatedly to exclude multiple paths. \li --exclude-attribute - * "path/to/object/with/attribute" Exclude attributes on the specified path to an object when - * comparing files or groups.
          If there are multiple paths to an object, only the specified path(s) will - * be excluded; the comparison will include any path not explicitly excluded.
          This option can be used - * repeatedly to exclude multiple paths. + *
          • FLT_EPSILON = 1.19209E-07 for + * floating-point type
            • + *
          • DBL_EPSILON = 2.22045E-16 + * for double precision
          + * type Can not use with '--relative' or '--delta'. + * \li --exclude-path "path" Exclude the specified path to an object when + * comparing files or groups. If a group is excluded, all member objects will also be excluded. + * The specified path is excluded wherever it occurs. This flexibility enables the same option + * to exclude either objects that exist only in one file or common objects that are known to differ.
          + * When comparing files, "path" is the absolute path to the excluded object; + * when comparing groups, "path" is similar to the relative path from the group to the excluded object. This + * "path" can be taken from the first section of the output of the --verbose option.
          + * For example, if you are comparing the group /groupA + * in two files and you want to exclude /groupA/groupB/groupC + * in both files, the exclude option would read as follows:
          + * --exclude-path "/groupB/groupC"
          + * If there are multiple paths to an object, only the specified path(s) will be + * excluded; the comparison will include any path not explicitly excluded.
          + * This option can be used repeatedly to exclude multiple paths. + * \li --exclude-attribute "path/to/object/with/attribute" Exclude attributes on the + * specified path to an object when comparing files or groups.
          + * If there are multiple paths to an object, only the specified path(s) will + * be excluded; the comparison will include any path not explicitly excluded.
          + * This option can be used repeatedly to exclude multiple paths. * * \subsubsection subsubsec_cltools_h5diff_modee Modes of output * \li Default mode print the number of differences found and where they occurred @@ -189,18 +194,20 @@ * * \subsubsection subsubsec_cltools_h5diff_examples Examples * \li 1) h5diff file1 file2 /g1/dset1 /g1/dset2 - * Compares object '/g1/dset1' in file1 with '/g1/dset2' in file2 + * + * Compares object '/g1/dset1' in file1 with '/g1/dset2' in file2 * * \li 2) h5diff file1 file2 /g1/dset1 - * Compares object '/g1/dset1' in both files + * + * Compares object '/g1/dset1' in both files * * \li 3) h5diff file1 file2 - * Compares all objects in both files + * + * Compares all objects in both files * * Notes: * file1 and file2 can be the same file. - * Use h5diff file1 file1 /g1/dset1 /g1/dset2 to compare - * '/g1/dset1' and '/g1/dset2' in the same file + * Use h5diff file1 file1 /g1/dset1 /g1/dset2 to compare '/g1/dset1' and '/g1/dset2' in the same file * */ diff --git a/tools/src/h5dump/h5dump.h b/tools/src/h5dump/h5dump.h index c72d7ef8611..a009f1d6f39 100644 --- a/tools/src/h5dump/h5dump.h +++ b/tools/src/h5dump/h5dump.h @@ -17,7 +17,7 @@ * \section sec_cltools_h5dump h5dump * * \subsection subsec_cltools_h5dump_intro Introduction - * With h5dump you can display objects from an HDF5 file. + * With h5dump, you can display objects from an HDF5 file. * * \subsection subsec_cltools_h5dump_usage Usage *

          h5dump [OPTIONS] [files

          @@ -114,7 +114,7 @@ * \subsection subsec_cltools_h5dump_options_subset Subsetting Options * Subsetting is available by using the following options with a dataset * option. Subsetting is done by selecting a hyperslab from the data. - * Thus, the options mirror those for performing a hyperslab selection. + * Thus, the options mirror those for performing a hyperslab selection.
          * One of the \b START, \b COUNT, \b STRIDE, or \b BLOCK parameters are mandatory if you do subsetting. * The \b STRIDE, \b COUNT, and \b BLOCK parameters are optional and will default to 1 in * each dimension. \b START is optional and will default to 0 in each dimension. @@ -124,7 +124,7 @@ * \li --count=COUNT Number of blocks to include in selection * \li --block=BLOCK Size of block in hyperslab * \b START, \b COUNT, \b STRIDE, and \b BLOCK - is a list of integers the number of which are equal to the - * number of dimensions in the dataspace being queried + * number of dimensions in the dataspace being queried.
          * (Alternate compact form of subsetting is described in the Reference Manual) * * \subsubsection subsubsec_cltools_h5dump_options_args Option Argument Conventions diff --git a/tools/src/h5format_convert/h5format_convert.h b/tools/src/h5format_convert/h5format_convert.h index 2d7112b5da6..b632ac43a7c 100644 --- a/tools/src/h5format_convert/h5format_convert.h +++ b/tools/src/h5format_convert/h5format_convert.h @@ -17,7 +17,7 @@ * \section sec_cltools_h5format_convert h5format_convert * * \subsection subsec_cltools_h5format_convert_intro Introduction - * With h5format_convert you can convert a datasets format in an HDF5 file. + * With h5format_convert, you can convert a datasets format in an HDF5 file. * * \subsection subsec_cltools_h5format_convert_usage Usage *

          h5format_convert [OPTIONS] file_name

          @@ -34,21 +34,24 @@ * \li --noop Perform all the steps except the actual conversion * * \subsubsection subsubsec_cltools_h5format_convert_examples Usage Examples - * \li 1) \code h5format_convert -dname=/group/dataset file_name \endcode - * Convert the dataset \ in the HDF5 file \: - *
          • a. chunked dataset: convert the chunk indexing type to version 1 B-tree
            • - *
          • b. compact/contiguous dataset: downgrade the layout version to 3
            • - *
          • c. virtual dataset: no action
          - * - * \li 2) \code h5format_convert file_name \endcode - * Convert all datasets in the HDF5 file \: - *
          • a. chunked dataset: convert the chunk indexing type to version 1 B-tree
            • - *
          • b. compact/contiguous dataset: downgrade the layout version to 3
            • - *
          • c. virtual dataset: no action
          - * - * \li 3) \code h5format_convert --noop -dname=/group/dataset file_name \endcode - * Go through all the steps except the actual conversion when - * converting the dataset \ in the HDF5 file \. + * \li 1) h5format_convert -dname=/group/dataset file_name + * + * Convert the dataset in the HDF5 file : + * - chunked dataset: convert the chunk indexing type to version 1 B-tree + * - compact/contiguous dataset: downgrade the layout version to 3 + * - virtual dataset: no action + * + * \li 2) h5format_convert file_name + * + * Convert all datasets in the HDF5 file : + * - chunked dataset: convert the chunk indexing type to version 1 B-tree + * - compact/contiguous dataset: downgrade the layout version to 3 + * - virtual dataset: no action + * + * \li 3) h5format_convert --noop -dname=/group/dataset file_name + * + * Go through all the steps except the actual conversion when + * converting the dataset in the HDF5 file . * */ diff --git a/tools/src/h5import/h5import.h b/tools/src/h5import/h5import.h index 4632f64855e..a70a8211b9e 100644 --- a/tools/src/h5import/h5import.h +++ b/tools/src/h5import/h5import.h @@ -24,7 +24,7 @@ * \section sec_cltools_h5import h5import * * \subsection subsec_cltools_h5import_intro Introduction - * With h5import you can convert data stored in one or more ASCII or binary files + * With h5import, you can convert data stored in one or more ASCII or binary files into one or more datasets (in accordance with the user-specified type and storage properties) in an existing or new HDF5 file. @@ -55,8 +55,7 @@ that the floating point data in the \b ASCII text file may be organized in the fixed floating form (for example 323.56) or in a scientific notation (for example 3.23E+02). A - different input-class specification is to be used for both - forms. + different input-class specification is to be used for both forms. The utility extracts the input data from the input file according to the specified parameters and saves it into @@ -73,7 +72,7 @@ provide the class and size of output data to be written to the dataset and may optionally specify the output-architecture, and the output-byte-order. If output-architecture is not - specified the default is \b NATIVE. Output-byte-orders are fixed + specified, the default is \b NATIVE. Output-byte-orders are fixed for some architectures and may be specified only if output- architecture is \b IEEE, \b UNIX or \b STD. @@ -87,10 +86,10 @@ The dataset can be organized in any of the following ways: \li 1. Contiguous \li 2. Chunked - \li 3. External Storage File (has to be contiguous) - \li 4. Extendible data sets (has to be chunked) - \li 5. Compressed (has to be chunked) - \li 6. Compressed & Extendible (has to be chunked) + \li 3. External Storage File (has to be contiguous) + \li 4. Extendible data sets(has to be chunked) + \li 5. Compressed (has to be chunked) + \li 6. Compressed & Extendible (has to be chunked) If the user wants to store raw data in a non-HDF file then the external storage file option is to be used and the name @@ -131,7 +130,6 @@ \. The output file may be an existing file or it maybe new in which case it will be created. - * \subsection subsec_cltools_h5import_config Configuration File The configuration file is an ASCII text file and must be the ddl formatted file (without data values) produced by \b h5dump @@ -162,135 +160,107 @@ * \li MAXIMUM-DIMENSIONS * \subsubsection subsubsec_cltools_h5import_config_val Values for keywords - * \li PATH - Strings separated by spaces to represent - the path of the dataset. If the groups in - the path do not exist, they will be created. - For example, -
          • PATH grp1/grp2/dataset1
            • -
          • PATH: keyword
            • -
          • grp1: group under the root. If - non-existent will be created
            • -
          • grp2: group under grp1. If - non-existent will be created - under grp1
            • -
          • dataset1: the name of the data-set - to be created
          - - * \li INPUT-CLASS - String denoting the type of input data. -
          • TEXTIN
          • TEXTFP
            • -
          • FP
          • IN
          • STR
            • -
          • TEXTUIN
          • UIN
          - \b INPUT-CLASS "TEXTIN" denotes an ASCII text - file with signed integer data in ASCII form, - \b INPUT-CLASS "TEXTUIN" denotes an ASCII text - file with unsigned integer data in ASCII form, - "TEXTFP" denotes an ASCII text file containing - floating point data in the fixed notation - (325.34), - "FP" denotes a floating point binary file, - "IN" denotes a signed integer binary file, - "UIN" denotes an unsigned integer binary file, - & "STR" denotes an ASCII text file the - contents of which should be stored as an 1-D - array of strings. - If \b INPUT-CLASS is "STR", then \b RANK, - \b DIMENSION-SIZES, \b OUTPUT-CLASS, \b OUTPUT-SIZE, - \b OUTPUT-ARCHITECTURE and \b OUTPUT-BYTE-ORDER - will be ignored. - - - * \li INPUT-SIZE - Integer denoting the size of the input data - (8, 16, 32, 64). -
          • For floating point, - \b INPUT-SIZE can be 32 or 64.
            • -
          • For integers (signed and unsigned) - \b INPUT-SIZE can be 8, 16, 32 or 64.
          - - * \li RANK - Integer denoting the number of dimensions. - - * \li DIMENSION-SIZES - Integers separated by spaces to denote the - dimension sizes for the no. of dimensions - determined by rank. - - * \li OUTPUT-CLASS - String dentoting data type of the dataset to - be written ("IN","FP", "UIN") - - * \li OUTPUT-SIZE - Integer denoting the size of the data in the - output dataset to be written. - If \b OUTPUT-CLASS is "FP", \b OUTPUT-SIZE can be - 32 or 64. - If \b OUTPUT-CLASS is "IN" or "UIN", \b OUTPUT-SIZE - can be 8, 16, 32 or 64. - - * \li OUTPUT-ARCHITECTURE - \b STRING denoting the type of output - architecture. Can accept the following values -
          • STD
            • -
          • IEEE
            • -
          • INTEL
            • -
          • CRAY
            • -
          • MIPS
            • -
          • ALPHA
            • -
          • NATIVE (default)
            • -
          • UNIX
          - - * \li OUTPUT-BYTE-ORDER - String denoting the output-byte-order. Ignored - if the \b OUTPUT-ARCHITECTURE is not specified or - if it is \b IEEE, \b UNIX or \b STD. Can accept the - following values. -
          • BE (default)
            • -
          • LE
          - - * \li CHUNKED-DIMENSION-SIZES - Integers separated by spaces to denote the - dimension sizes of the chunk for the no. of - dimensions determined by rank. Required field - to denote that the dataset will be stored with - chunked storage. If this field is absent the - dataset will be stored with contiguous storage. - - * \li COMPRESSION-TYPE - String denoting the type of compression to be - used with the chunked storage. Requires the - \b CHUNKED-DIMENSION-SIZES to be specified. The only - currently supported compression method is \b GZIP. - Will accept the following value -
          • GZIP
          - - * \li COMPRESSION-PARAM - Integer used to denote compression level and - this option is to be always specified when - the \b COMPRESSION-TYPE option is specified. The - values are applicable only to \b GZIP - compression. - Value 1-9: The level of Compression. - 1 will result in the fastest - compression while 9 will result in - the best compression ratio. The default - level of compression is 6. - - * \li EXTERNAL-STORAGE - String to denote the name of the non-HDF5 file - to store data to. Cannot be used if \b CHUNKED-DIMENSIONS - or \b COMPRESSION-TYPE or \b EXTENDIBLE-DATASET is specified. - Value \: the name of the - external file as a string to be used. - - * \li MAXIMUM-DIMENSIONS - Integers separated by spaces to denote the - maximum dimension sizes of all the - dimensions determined by rank. Requires the - \b CHUNKED-DIMENSION-SIZES to be specified. A value of - -1 for any dimension implies \b UNLIMITED - \b DIMENSION size for that particular dimension. + * \li PATH + Strings separated by spaces to represent + the path of the dataset. If the groups in + the path do not exist, they will be created. + For example, +
          • PATH grp1/grp2/dataset1
            • +
          • PATH: keyword
            • +
          • grp1: group under the root. If non-existent will be created
            • +
          • grp2: group under grp1. If non-existent will be created under grp1
            • +
          • dataset1: the name of the data-set to be created
          + + * \li INPUT-CLASS + String denoting the type of input data. +
          • TEXTIN
            • +
          • TEXTFP
            • +
          • FP
            • +
          • IN
            • +
          • STR
            • +
          • TEXTUIN
            • +
          • UIN
          + \b INPUT-CLASS "TEXTIN" denotes an ASCII text file with signed integer data in ASCII form, + \b INPUT-CLASS "TEXTUIN" denotes an ASCII text file with unsigned integer data in ASCII form, + "TEXTFP" denotes an ASCII text file containing floating point data in the fixed notation + (325.34),
          + "FP" denotes a floating point binary file, + "IN" denotes a signed integer binary file, + "UIN" denotes an unsigned integer binary file, + & "STR" denotes an ASCII text file the contents of which should be stored as an 1-D + array of strings.
          + If \b INPUT-CLASS is "STR", then \b RANK, + \b DIMENSION-SIZES, \b OUTPUT-CLASS, \b OUTPUT-SIZE, + \b OUTPUT-ARCHITECTURE and \b OUTPUT-BYTE-ORDER + will be ignored. + + + * \li INPUT-SIZE + Integer denoting the size of the input data (8, 16, 32, 64). +
          • For floating point, \b INPUT-SIZE can be 32 or 64.
            • +
          • For integers (signed and unsigned) \b INPUT-SIZE can be 8, 16, 32 or 64.
          + + * \li RANK + Integer denoting the number of dimensions. + + * \li DIMENSION-SIZES + Integers separated by spaces to denote the dimension sizes for the no. of dimensions + determined by rank. + + * \li OUTPUT-CLASS + String dentoting data type of the dataset to be written ("IN","FP", "UIN") + + * \li OUTPUT-SIZE + Integer denoting the size of the data in the output dataset to be written. + If \b OUTPUT-CLASS is "FP", \b OUTPUT-SIZE can be 32 or 64. + If \b OUTPUT-CLASS is "IN" or "UIN", \b OUTPUT-SIZE can be 8, 16, 32 or 64. + + * \li OUTPUT-ARCHITECTURE + \b STRING denoting the type of output architecture. Can accept the following values +
          • STD
            • +
          • IEEE
            • +
          • INTEL
            • +
          • CRAY
            • +
          • MIPS
            • +
          • ALPHA
            • +
          • NATIVE (default)
            • +
          • UNIX
          + + * \li OUTPUT-BYTE-ORDER + String denoting the output-byte-order. Ignored if the \b OUTPUT-ARCHITECTURE is not specified or + if it is \b IEEE, \b UNIX or \b STD. Can accept the following values. +
          • BE (default)
            • +
          • LE
          + + * \li CHUNKED-DIMENSION-SIZES + Integers separated by spaces to denote the dimension sizes of the chunk for the no. of + dimensions determined by rank. Required field to denote that the dataset will be stored with + chunked storage. If this field is absent the dataset will be stored with contiguous storage. + + * \li COMPRESSION-TYPE + String denoting the type of compression to be used with the chunked storage. Requires the + \b CHUNKED-DIMENSION-SIZES to be specified. The only currently supported compression method is \b GZIP. + Will accept the following value +
          • GZIP
          + + * \li COMPRESSION-PARAM + Integer used to denote compression level and this option is to be always specified when + the \b COMPRESSION-TYPE option is specified. The values are applicable only to \b GZIP + compression.
          + Value 1-9: The level of Compression.
          + 1 will result in the fastest compression while 9 will result in + the best compression ratio.
          + The default level of compression is 6. + + * \li EXTERNAL-STORAGE + String to denote the name of the non-HDF5 file to store data to. Cannot be used if \b CHUNKED-DIMENSIONS + or \b COMPRESSION-TYPE or \b EXTENDIBLE-DATASET is specified. + Value \: the name of the external file as a string to be used. + + * \li MAXIMUM-DIMENSIONS + Integers separated by spaces to denote the maximum dimension sizes of all the + dimensions determined by rank. Requires the \b CHUNKED-DIMENSION-SIZES to be specified. A value of + -1 for any dimension implies \b UNLIMITED \b DIMENSION size for that particular dimension. * \subsection subsec_cltools_h5import_examples Usage Examples * \li Configuration File may look like @@ -305,14 +275,14 @@ OUTPUT-BYTE-ORDER LE CHUNKED-DIMENSION-SIZES 2 2 2 \endcode - The above configuration will accept a floating point array - (5 x 2 x 4) in an ASCII file with the rank and dimension sizes - specified and will save it in a chunked data-set (of pattern - 2 X 2 X 2) of 64-bit floating point in the little-endian order - and IEEE architecture. The dataset will be stored at - "/work/h5/pkamat/First-set" - - * \li Another configuration could be + The above configuration will accept a floating point array + (5 x 2 x 4) in an ASCII file with the rank and dimension sizes + specified and will save it in a chunked data-set (of pattern + 2 X 2 X 2) of 64-bit floating point in the little-endian order + and IEEE architecture. The dataset will be stored at + "/work/h5/pkamat/First-set" + + * \li Another configuration could be * \code PATH Second-set INPUT-CLASS IN @@ -325,15 +295,15 @@ COMPRESSION-TYPE GZIP COMPRESSION-PARAM 7 \endcode - The above configuration will accept an integer array - (6 X 3 X 5 x 2 x 4) in a binary file with the rank and - dimension sizes specified and will save it in a chunked data-set - (of pattern 2 X 2 X 2 X 2 X 2) of 32-bit floating point in - native format (as output-architecture is not specified). The - first and the third dimension will be defined as unlimited. The - data-set will be compressed using GZIP and a compression level - of 7. - The dataset will be stored at \code /Second-set \endcode + The above configuration will accept an integer array + (6 X 3 X 5 x 2 x 4) in a binary file with the rank and + dimension sizes specified and will save it in a chunked data-set + (of pattern 2 X 2 X 2 X 2 X 2) of 32-bit floating point in + native format (as output-architecture is not specified). The + first and the third dimension will be defined as unlimited. The + data-set will be compressed using GZIP and a compression level + of 7.
          + The dataset will be stored at \code /Second-set \endcode * */ diff --git a/tools/src/h5jam/h5jam.h b/tools/src/h5jam/h5jam.h index a4e9ff5929e..8d0fe1bcfdf 100644 --- a/tools/src/h5jam/h5jam.h +++ b/tools/src/h5jam/h5jam.h @@ -17,12 +17,12 @@ * \section sec_cltools_h5jam h5jam and h5unjam * * \subsection subsec_cltools_h5jam_intro Introduction - * \li h5jam: Adds user block to front of an HDF5 file and creates a new concatenated file. - * \li h5unjam: Splits user file and HDF5 file into two files: user block data and HDF5 data. + * \li h5jam Adds user block to the front of an HDF5 file and creates a new concatenated file. + * \li h5unjam Splits an HDF5 file into two files, one containing the user block data and the other the HDF5 data. * * \subsection subsec_cltools_h5jam_usage Usage - *

          h5jam -i \ -u \ [-o \] [--clobber]

          - *

          h5unjam -i \ [-o \ ] [-u \ | --delete]

          + *

          h5jam -i \ -u \ [-o \] [--clobber]

          + *

          h5unjam -i \ [-o \ ] [-u \ | --delete]

          * * \subsection subsec_cltools_h5jam_options h5jam Options * \li -i in_file.h5 Specifies the input HDF5 file. @@ -56,7 +56,7 @@ * \li -h Prints a usage message and exits. * \li -V Prints the HDF5 library version and exits. * - * If neither --delete: nor -u: is specified, the user block from the input + * If neither --delete nor -u is specified, the user block from the input * file will be displayed to stdout. * */ diff --git a/tools/src/h5ls/h5ls.h b/tools/src/h5ls/h5ls.h index 382e9dd6bad..c9d814a2a66 100644 --- a/tools/src/h5ls/h5ls.h +++ b/tools/src/h5ls/h5ls.h @@ -17,7 +17,7 @@ * \section sec_cltools_h5ls h5ls * * \subsection subsec_cltools_h5ls_intro Introduction - * With h5ls you can dump objects from an HDF5 file. + * With h5ls, you can dump objects from an HDF5 file. * * \subsection subsec_cltools_h5ls_usage Usage *

          h5ls [OPTIONS] file[/OBJECT] [file[/[OBJECT]...]

          @@ -43,7 +43,7 @@ * \li --data Print the values of datasets * \li --follow-symlinks * Follow symbolic links (soft links and external links) - * to display target object information. + * to display target object information.
          * Without this option, h5ls identifies a symbolic link * as a soft link or external link and prints the value * assigned to the symbolic link; it does not provide any @@ -98,9 +98,9 @@ * \subsubsection subsubsec_cltools_h5ls_options_depre Deprecated Options * The following options have been removed in HDF5 1.12. Use the indicated * replacement option in all work. - * \li --external Follow external links. + * \li --external Follow external links.
          * Replaced by --follow-symlinks. - * \li --errors Show all HDF5 error reporting + * \li --errors Show all HDF5 error reporting
          * Replaced by --enable-error-stack. * */ diff --git a/tools/src/h5repack/h5repack.h b/tools/src/h5repack/h5repack.h index 45e613511f2..9ca26b17003 100644 --- a/tools/src/h5repack/h5repack.h +++ b/tools/src/h5repack/h5repack.h @@ -18,7 +18,7 @@ * \section sec_cltools_h5repack h5repack * * \subsection subsec_cltools_h5repack_intro Introduction - * With h5repack you can write an HDF5 file to a new file and change the layout for objects in the new file. + * With h5repack, you can write an HDF5 file to a new file and change the layout for objects in the new file. * * \subsection subsec_cltools_h5repack_usage Usage *

          h5repack [OPTIONS] file1 file2

          @@ -206,34 +206,34 @@ * * \li 1) h5repack -v -f GZIP=1 file1 file2 * - * GZIP compression with level 1 to all objects + * GZIP compression with level 1 to all objects * * \li 2) h5repack -v -f dset1:SZIP=8,NN file1 file2 * - * SZIP compression with 8 pixels per block and NN coding method to object dset1 + * SZIP compression with 8 pixels per block and NN coding method to object dset1 * * \li 3) h5repack -v -l dset1,dset2:CHUNK=20x10 -f dset3,dset4,dset5:NONE file1 file2 * - * Chunked layout, with a layout size of 20x10, to objects dset1 and dset2 - * and remove filters to objects dset3, dset4, dset5 + * Chunked layout, with a layout size of 20x10, to objects dset1 and dset2 + * and remove filters to objects dset3, dset4, dset5 * * \li 4) h5repack -L -c 10 -s 20:dtype file1 file2 * - * Using latest file format with maximum compact group size of 10 and - * minimum shared datatype size of 20 + * Using latest file format with maximum compact group size of 10 and + * minimum shared datatype size of 20 * * \li 5) h5repack -f SHUF -f GZIP=1 file1 file2 * - * Add both filters SHUF and GZIP in this order to all datasets + * Add both filters SHUF and GZIP in this order to all datasets * * \li 6) h5repack -f UD=307,0,1,9 file1 file2 * - * Add bzip2 filter to all datasets + * Add bzip2 filter to all datasets * * \li 7) h5repack --low=0 --high=1 file1 file2 * - * Set low=H5F_LIBVER_EARLIEST and high=H5F_LIBVER_V18 via - * H5Pset_libver_bounds() when creating the repacked file, file2 + * Set low=H5F_LIBVER_EARLIEST and high=H5F_LIBVER_V18 via + * H5Pset_libver_bounds() when creating the repacked file, file2 * * */ diff --git a/tools/src/h5stat/h5stat.h b/tools/src/h5stat/h5stat.h index 84049498c93..ee8f9d9f7f0 100644 --- a/tools/src/h5stat/h5stat.h +++ b/tools/src/h5stat/h5stat.h @@ -17,7 +17,7 @@ * \section sec_cltools_h5stat h5stat * * \subsection subsec_cltools_h5stat_intro Introduction - * With h5stat you can dump stats from an HDF5 file. + * With h5stat, you can dump stats from an HDF5 file. * * \subsection subsec_cltools_h5stat_usage Usage *

          h5stat [OPTIONS] file

          diff --git a/tools/src/misc/h5clear.h b/tools/src/misc/h5clear.h index 7bfb6a05cd2..728c0a51614 100644 --- a/tools/src/misc/h5clear.h +++ b/tools/src/misc/h5clear.h @@ -17,7 +17,7 @@ * \section sec_cltools_h5clear h5clear * * \subsection subsec_cltools_h5clear_intro Introduction - * With h5clear you can clear the superblock status flag field, remove the metadata cache image, print + * With h5clear, you can clear the superblock status flag field, remove the metadata cache image, print * the EOA and EOF, or set the 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, @@ -48,19 +48,19 @@ * \subsection subsec_cltools_h5clear_examples Usage Examples * \li 1) h5clear -s file_name * - * Clear the status_flags field in the superblock of the HDF5 file \. + * Clear the status_flags field in the superblock of the HDF5 file . * * \li 2) h5clear -m file_name * - * Remove the metadata cache image from the HDF5 file \. + * Remove the metadata cache image from the HDF5 file . * * \li 3) h5clear --increment file_name * - * Set the EOA to the maximum of (EOA, EOF) + 1M for the file \. + * Set the EOA to the maximum of (EOA, EOF) + 1M for the file . * * \li 4) h5clear --increment=512 file_name * - * Set the EOA to the maximum of (EOA, EOF) + 512 for the file \. + * Set the EOA to the maximum of (EOA, EOF) + 512 for the file\. * */ diff --git a/tools/src/misc/h5debug.h b/tools/src/misc/h5debug.h index 0b7cd3cfea2..e946681a6a9 100644 --- a/tools/src/misc/h5debug.h +++ b/tools/src/misc/h5debug.h @@ -17,7 +17,7 @@ * \section sec_cltools_h5debug h5debug * * \subsection subsec_cltools_h5debug_intro Introduction - * With h5debug you can debug an existing HDF5 file at a low level. + * With h5debug, you can debug an existing HDF5 file at a low level. * * \subsection subsec_cltools_h5debug_usage Usage *

          h5debug filename [signature-addr [extra]*]

          diff --git a/tools/src/misc/h5delete.h b/tools/src/misc/h5delete.h index 1bc00d7add6..5faedc023a4 100644 --- a/tools/src/misc/h5delete.h +++ b/tools/src/misc/h5delete.h @@ -17,7 +17,7 @@ * \section sec_cltools_h5delete h5delete * * \subsection subsec_cltools_h5delete_intro Introduction - * With h5delete you can delete an HDF5 file. + * With h5delete, you can delete an HDF5 file. * * \subsection subsec_cltools_h5delete_usage Usage *

          h5delete [-f] \

          diff --git a/tools/src/misc/h5mkgrp.h b/tools/src/misc/h5mkgrp.h index 9fb6d12800d..4af8f176c9c 100644 --- a/tools/src/misc/h5mkgrp.h +++ b/tools/src/misc/h5mkgrp.h @@ -17,7 +17,7 @@ * \section sec_cltools_h5mkgrp h5mkgrp * * \subsection subsec_cltools_h5mkgrp_intro Introduction - * With h5mkgrp you can create group(s) in an HDF5 file + * With h5mkgrp, you can create group(s) in an HDF5 file * * \subsection subsec_cltools_h5mkgrp_usage Usage *

          h5mkgrp [OPTIONS] FILE GROUP

          diff --git a/tools/src/misc/h5repart.h b/tools/src/misc/h5repart.h index 1adec24b1b4..9452bd5b6f4 100644 --- a/tools/src/misc/h5repart.h +++ b/tools/src/misc/h5repart.h @@ -17,7 +17,7 @@ * \section sec_cltools_h5repart h5repart * * \subsection subsec_cltools_h5repart_intro Introduction - * With h5repart you can repartition a file family. This program can be used to + * With h5repart, you can repartition a file family. This program can be used to * split a single file into a family of files, join a family of * files into a single file, or copy one family to another while * changing the size of the family members. It can also be used @@ -39,8 +39,8 @@ * \li -family_to_single Change file driver from family to the default single-file * VFD (windows or sec2) * - * Sizes may be suffixed with 'g' for GB, 'm' for MB or 'k' for kB. - * File family names include an integer printf format such as '%%d' + * Sizes may be suffixed with 'g' for GB, 'm' for MB or 'k' for kB. + * File family names include an integer printf format such as '%%d' * */ From a68e83f75aa8f0bf93245dbde067612867b3212f Mon Sep 17 00:00:00 2001 From: github-actions <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 25 Jun 2024 21:59:07 +0000 Subject: [PATCH 15/24] Committing clang-format changes --- tools/src/h5diff/h5diff_main.h | 20 +++++++++----------- tools/src/h5jam/h5jam.h | 3 ++- 2 files changed, 11 insertions(+), 12 deletions(-) diff --git a/tools/src/h5diff/h5diff_main.h b/tools/src/h5diff/h5diff_main.h index 2a4df559193..c4f5b6986de 100644 --- a/tools/src/h5diff/h5diff_main.h +++ b/tools/src/h5diff/h5diff_main.h @@ -129,17 +129,15 @@ * when comparing groups, "path" is similar to the relative path from the group to the excluded object. This * "path" can be taken from the first section of the output of the --verbose option.
          * For example, if you are comparing the group /groupA - * in two files and you want to exclude /groupA/groupB/groupC - * in both files, the exclude option would read as follows:
          - * --exclude-path "/groupB/groupC"
          - * If there are multiple paths to an object, only the specified path(s) will be - * excluded; the comparison will include any path not explicitly excluded.
          - * This option can be used repeatedly to exclude multiple paths. - * \li --exclude-attribute "path/to/object/with/attribute" Exclude attributes on the - * specified path to an object when comparing files or groups.
          - * If there are multiple paths to an object, only the specified path(s) will - * be excluded; the comparison will include any path not explicitly excluded.
          - * This option can be used repeatedly to exclude multiple paths. + * in two files and you want to exclude /groupA/groupB/groupC in both files, the exclude option would + * read as follows:
          --exclude-path "/groupB/groupC" + *
          If there are multiple paths to an object, only the specified path(s) will be excluded; the + * comparison will include any path not explicitly excluded.
          This option can be used repeatedly to + * exclude multiple paths. \li --exclude-attribute "path/to/object/with/attribute" Exclude + * attributes on the specified path to an object when comparing files or groups.
          If there are multiple + * paths to an object, only the specified path(s) will be excluded; the comparison will include any path not + * explicitly excluded.
          This option can be used repeatedly to exclude multiple paths. * * \subsubsection subsubsec_cltools_h5diff_modee Modes of output * \li Default mode print the number of differences found and where they occurred diff --git a/tools/src/h5jam/h5jam.h b/tools/src/h5jam/h5jam.h index 8d0fe1bcfdf..7d3cca65535 100644 --- a/tools/src/h5jam/h5jam.h +++ b/tools/src/h5jam/h5jam.h @@ -18,7 +18,8 @@ * * \subsection subsec_cltools_h5jam_intro Introduction * \li h5jam Adds user block to the front of an HDF5 file and creates a new concatenated file. - * \li h5unjam Splits an HDF5 file into two files, one containing the user block data and the other the HDF5 data. + * \li h5unjam Splits an HDF5 file into two files, one containing the user block data and the other the HDF5 + * data. * * \subsection subsec_cltools_h5jam_usage Usage *

          h5jam -i \ -u \ [-o \] [--clobber]

          From 2654e65368347482b55044a9377d8f049442942b Mon Sep 17 00:00:00 2001 From: Allen Byrne Date: Tue, 25 Jun 2024 17:03:23 -0500 Subject: [PATCH 16/24] Fix formatting --- tools/src/h5diff/h5diff_main.h | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/tools/src/h5diff/h5diff_main.h b/tools/src/h5diff/h5diff_main.h index c4f5b6986de..d53b2879408 100644 --- a/tools/src/h5diff/h5diff_main.h +++ b/tools/src/h5diff/h5diff_main.h @@ -129,15 +129,19 @@ * when comparing groups, "path" is similar to the relative path from the group to the excluded object. This * "path" can be taken from the first section of the output of the --verbose option.
          * For example, if you are comparing the group /groupA - * in two files and you want to exclude /groupA/groupB/groupC in both files, the exclude option would - * read as follows:
          --exclude-path "/groupB/groupC" - *
          If there are multiple paths to an object, only the specified path(s) will be excluded; the - * comparison will include any path not explicitly excluded.
          This option can be used repeatedly to - * exclude multiple paths. \li --exclude-attribute "path/to/object/with/attribute" Exclude - * attributes on the specified path to an object when comparing files or groups.
          If there are multiple - * paths to an object, only the specified path(s) will be excluded; the comparison will include any path not - * explicitly excluded.
          This option can be used repeatedly to exclude multiple paths. + * in two files and you want to exclude + * /groupA/groupB/groupC in both files, + * the exclude option would read as follows:
          + * --exclude-path "/groupB/groupC"
          + * If there are multiple paths to an object, only the specified path(s) will be excluded; the + * comparison will include any path not explicitly excluded.
          + * This option can be used repeatedly to + * exclude multiple paths. + * \li --exclude-attribute "path/to/object/with/attribute" Exclude + * attributes on the specified path to an object when comparing files or groups.
          + * If there are multiple paths to an object, only the specified path(s) will be excluded; + * the comparison will include any path not explicitly excluded.
          + * This option can be used repeatedly to exclude multiple paths. * * \subsubsection subsubsec_cltools_h5diff_modee Modes of output * \li Default mode print the number of differences found and where they occurred From cbbb59bfce5c1cc256542a2bdbe5f02e672aa093 Mon Sep 17 00:00:00 2001 From: Allen Byrne Date: Wed, 26 Jun 2024 15:48:01 -0500 Subject: [PATCH 17/24] Use long form options in examples --- tools/src/h5dump/h5dump.h | 18 +++++++++--------- tools/src/h5repack/h5repack.h | 14 +++++++------- 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/tools/src/h5dump/h5dump.h b/tools/src/h5dump/h5dump.h index a009f1d6f39..bab0bce7904 100644 --- a/tools/src/h5dump/h5dump.h +++ b/tools/src/h5dump/h5dump.h @@ -151,39 +151,39 @@ * * \li 1) Attribute foo of the group /bar_none in file quux.h5 * - * h5dump -a /bar_none/foo quux.h5 + * h5dump --attribute=/bar_none/foo quux.h5 * * \li 2) Attribute "high/low" of the group /bar_none in the file quux.h5 * - * h5dump -a "/bar_none/high\/low" quux.h5 + * h5dump --attribute="/bar_none/high\/low" quux.h5 * * \li 3) Selecting a subset from dataset /foo in file quux.h5 * - * h5dump -d /foo -s "0,1" -S "1,1" -c "2,3" -k "2,2" quux.h5 + * h5dump --dataset=/foo --start="0,1" --stride="1,1" --count="2,3" --block="2,2" quux.h5 * * \li 4) Saving dataset 'dset' in file quux.h5 to binary file 'out.bin' using a little-endian type * - * h5dump -d /dset -b LE -o out.bin quux.h5 + * h5dump --dataset=/dset --binary=LE --output=out.bin quux.h5 * * \li 5) Display two packed bits (bits 0-1 and bits 4-6) in the dataset /dset * - * h5dump -d /dset -M 0,1,4,3 quux.h5 + * h5dump -d-dataset=/dset --packedbits=0,1,4,3 quux.h5 * * \li 6) Dataset foo in files file1.h5 file2.h5 file3.h5 * - * h5dump -d /foo file1.h5 file2.h5 file3.h5 + * h5dump --dataset=/foo file1.h5 file2.h5 file3.h5 * * \li 7) Dataset foo in split files splitfile-m.h5 splitfile-r.h5 * - * h5dump -d /foo -f split splitfile + * h5dump --dataset=/foo --filedriver=split splitfile * * \li 8) Dataset foo in multi files mf-s.h5, mf-b.h5, mf-r.h5, mf-g.h5, mf-l.h5 and mf-o.h5 * - * h5dump -d /foo -f multi mf + * h5dump --dataset=/foo --filedriver=multi mf * * \li 9) Dataset foo in family files fam00000.h5 fam00001.h5 and fam00002.h5 * - * h5dump -d /foo -f family fam%05d.h5 + * h5dump --dataset=/foo --filedriver=family fam%05d.h5 * */ diff --git a/tools/src/h5repack/h5repack.h b/tools/src/h5repack/h5repack.h index 9ca26b17003..40e1ac3b1fb 100644 --- a/tools/src/h5repack/h5repack.h +++ b/tools/src/h5repack/h5repack.h @@ -90,7 +90,7 @@ * #H5Pset_file_space_strategy * \li --fs_persist=FS_PERSIST Persisting or not * persisting free-space for #H5Pset_file_space_strategy - * \li ---fs_threshold=FS_THRESHOLD : Free-space section + * \li --fs_threshold=FS_THRESHOLD : Free-space section * threshold for #H5Pset_file_space_strategy * \li --fs_pagesize=FS_PAGESIZE File space page size for #H5Pset_file_space_page_size * @@ -204,29 +204,29 @@ * * \subsection subsec_cltools_h5repack_examples Usage Examples * - * \li 1) h5repack -v -f GZIP=1 file1 file2 + * \li 1) h5repack --verbose --filter=GZIP=1 file1 file2 * * GZIP compression with level 1 to all objects * - * \li 2) h5repack -v -f dset1:SZIP=8,NN file1 file2 + * \li 2) h5repack --verbose --filter=dset1:SZIP=8,NN file1 file2 * * SZIP compression with 8 pixels per block and NN coding method to object dset1 * - * \li 3) h5repack -v -l dset1,dset2:CHUNK=20x10 -f dset3,dset4,dset5:NONE file1 file2 + * \li 3) h5repack --verbose --layout=dset1,dset2:CHUNK=20x10 --filter=dset3,dset4,dset5:NONE file1 file2 * * Chunked layout, with a layout size of 20x10, to objects dset1 and dset2 * and remove filters to objects dset3, dset4, dset5 * - * \li 4) h5repack -L -c 10 -s 20:dtype file1 file2 + * \li 4) h5repack --latest --compact=10 --ssize=20:dtype file1 file2 * * Using latest file format with maximum compact group size of 10 and * minimum shared datatype size of 20 * - * \li 5) h5repack -f SHUF -f GZIP=1 file1 file2 + * \li 5) h5repack --filter=SHUF --filter=GZIP=1 file1 file2 * * Add both filters SHUF and GZIP in this order to all datasets * - * \li 6) h5repack -f UD=307,0,1,9 file1 file2 + * \li 6) h5repack --filter=UD=307,0,1,9 file1 file2 * * Add bzip2 filter to all datasets * From c57d0c3c23166f7780b24d127a51f8a52dd5e5a8 Mon Sep 17 00:00:00 2001 From: Allen Byrne Date: Thu, 27 Jun 2024 07:47:09 -0500 Subject: [PATCH 18/24] Fix sentence typo and sentences --- hl/tools/h5watch/h5watch.h | 4 ++-- tools/src/h5copy/h5copy.h | 2 +- tools/src/h5diff/h5diff_main.h | 10 +++++----- tools/src/h5dump/h5dump.h | 10 ++++++++-- tools/src/h5format_convert/h5format_convert.h | 2 +- tools/src/h5ls/h5ls.h | 2 +- tools/src/h5repack/h5repack.h | 2 +- tools/src/h5stat/h5stat.h | 2 +- tools/src/misc/h5clear.h | 2 +- tools/src/misc/h5mkgrp.h | 2 +- 10 files changed, 22 insertions(+), 16 deletions(-) diff --git a/hl/tools/h5watch/h5watch.h b/hl/tools/h5watch/h5watch.h index 20c82ecaf03..188707bba2b 100644 --- a/hl/tools/h5watch/h5watch.h +++ b/hl/tools/h5watch/h5watch.h @@ -24,7 +24,7 @@ * * \subsection subsec_cltools_h5watch_error Error Report Option * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. - * Optional value 2 also prints file open errors. + * Optional value 2 also prints file open errors, --enable-error-stack=2. * * \subsection subsec_cltools_h5watch_options Options * \li --help Print a usage message and exit @@ -43,7 +43,7 @@ * for a compound data type. * \ can be specified as follows: *
          • 1) A comma-separated list of field names in a - * compound data type. "," is the separatorfor field names while "." is the separator + * compound data type. "," is the separator for field names while "." is the separator * for a nested field.
            • *
          • 2) A single field name in a compound data type. * This option can be used multiple times.
          diff --git a/tools/src/h5copy/h5copy.h b/tools/src/h5copy/h5copy.h index 38889afe938..b0a684f4ab9 100644 --- a/tools/src/h5copy/h5copy.h +++ b/tools/src/h5copy/h5copy.h @@ -31,7 +31,7 @@ * * \subsection subsec_cltools_h5copy_error Error Report Option * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. - Optional value 2 also prints file open errors. + Optional value 2 also prints file open errors, --enable-error-stack=2. * * \subsection subsec_cltools_h5copy_options Options * \li --help Print a usage message and exit diff --git a/tools/src/h5diff/h5diff_main.h b/tools/src/h5diff/h5diff_main.h index d53b2879408..a45398bef8b 100644 --- a/tools/src/h5diff/h5diff_main.h +++ b/tools/src/h5diff/h5diff_main.h @@ -29,7 +29,7 @@ * * \subsection subsec_cltools_h5diff_error Error Report * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. - * Optional value 2 also prints file open errors. + * Optional value 2 also prints file open errors, --enable-error-stack=2. * * \subsection subsec_cltools_h5diff_options Options * \li --help Print a usage message and exit. @@ -72,7 +72,7 @@ * \li --vfd-info-2 VFD-specific info to pass to the VFL driver used for * opening the second HDF5 file specified * \li --follow-symlinks - * Follow symbolic links (soft links and external links and compare the) + * Follow symbolic links (soft links and external links) and compare the * links' target objects.
          * If symbolic link(s) with the same name exist in the files being * compared, then determine whether the target of each link is an existing @@ -104,15 +104,15 @@ * \li --nan Avoid NaNs detection * \li --count=C Print differences up to C. C must be a positive integer. * \li --delta=D - * Print difference if (|a-b| > D). D must be a positive number. Where a + * Print difference if (|a-b| > D). D must be a positive number, where a * is the data point value in file1 and b is the data point value in file2. * Can not use with '--relative' or '--use-system-epsilon'. * \li --relative=R - * Print difference if (|(a-b)/b| > R). R must be a positive number. Where a + * Print difference if (|(a-b)/b| > R). R must be a positive number, where a * is the data point value in file1 and b is the data point value in file2. * Can not use with '--delta' or '--use-system-epsilon'. * \li --use-system-epsilon - * Print difference if (|a-b| > EPSILON), EPSILON is system defined value. Where a + * Print difference if (|a-b| > EPSILON), EPSILON is system defined value, where a * is the data point value in file1 and b is the data point value in file2. * If the system epsilon is not defined,one of the following predefined * values will be used: diff --git a/tools/src/h5dump/h5dump.h b/tools/src/h5dump/h5dump.h index bab0bce7904..26622c0bf30 100644 --- a/tools/src/h5dump/h5dump.h +++ b/tools/src/h5dump/h5dump.h @@ -24,7 +24,7 @@ * * \subsection subsec_cltools_h5dump_error Error Report Option * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. - * Optional value 2 also prints file open errors. + * Optional value 2 also prints file open errors, --enable-error-stack=2. * * \subsection subsec_cltools_h5dump_options Options * \li --help Print a usage message and exit @@ -120,10 +120,16 @@ * each dimension. \b START is optional and will default to 0 in each dimension. * * \li --start=START Offset of start of subsetting selection + * \b START - is a list of integers the number of which are equal to the + * number of dimensions in the dataspace being queried.
          * \li --stride=STRIDE Hyperslab stride + * \b COUNT - is a list of integers the number of which are equal to the + * number of dimensions in the dataspace being queried.
          * \li --count=COUNT Number of blocks to include in selection + * \b STRIDE - is a list of integers the number of which are equal to the + * number of dimensions in the dataspace being queried.
          * \li --block=BLOCK Size of block in hyperslab - * \b START, \b COUNT, \b STRIDE, and \b BLOCK - is a list of integers the number of which are equal to the + * \b BLOCK - is a list of integers the number of which are equal to the * number of dimensions in the dataspace being queried.
          * (Alternate compact form of subsetting is described in the Reference Manual) * diff --git a/tools/src/h5format_convert/h5format_convert.h b/tools/src/h5format_convert/h5format_convert.h index b632ac43a7c..d91d163ad04 100644 --- a/tools/src/h5format_convert/h5format_convert.h +++ b/tools/src/h5format_convert/h5format_convert.h @@ -24,7 +24,7 @@ * * \subsection subsec_cltools_h5format_convert_error Error Report Option * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. - * Optional value 2 also prints file open errors. + * Optional value 2 also prints file open errors, --enable-error-stack=2. * * \subsection subsec_cltools_h5format_convert_options Options * \li --help Print a usage message and exit diff --git a/tools/src/h5ls/h5ls.h b/tools/src/h5ls/h5ls.h index c9d814a2a66..d72c1be10d4 100644 --- a/tools/src/h5ls/h5ls.h +++ b/tools/src/h5ls/h5ls.h @@ -31,7 +31,7 @@ * * \subsection subsec_cltools_h5ls_error Error Report Option * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. - * Optional value 2 also prints file open errors. + * Optional value 2 also prints file open errors, --enable-error-stack=2. * * \subsection subsec_cltools_h5ls_options Options * \li --help Print a usage message and exit diff --git a/tools/src/h5repack/h5repack.h b/tools/src/h5repack/h5repack.h index 40e1ac3b1fb..5bb6261191c 100644 --- a/tools/src/h5repack/h5repack.h +++ b/tools/src/h5repack/h5repack.h @@ -27,7 +27,7 @@ * * \subsection subsec_cltools_h5repack_error Error Report Option * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. - * Optional value 2 also prints file open errors. + * Optional value 2 also prints file open errors, --enable-error-stack=2. * * \subsection subsec_cltools_h5repack_options Options * \li --help Print a usage message and exit diff --git a/tools/src/h5stat/h5stat.h b/tools/src/h5stat/h5stat.h index ee8f9d9f7f0..848480eb2b3 100644 --- a/tools/src/h5stat/h5stat.h +++ b/tools/src/h5stat/h5stat.h @@ -24,7 +24,7 @@ * * \subsection subsec_cltools_h5stat_error Error Report Option * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. - * Optional value 2 also prints file open errors. + * Optional value 2 also prints file open errors, --enable-error-stack=2. * * \subsection subsec_cltools_h5stat_options Options * \li --help Print a usage message and exit diff --git a/tools/src/misc/h5clear.h b/tools/src/misc/h5clear.h index 728c0a51614..354b2f6ef33 100644 --- a/tools/src/misc/h5clear.h +++ b/tools/src/misc/h5clear.h @@ -29,7 +29,7 @@ * * \subsection subsec_cltools_h5clear_error Error Report Option * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. - * Optional value 2 also prints file open errors. + * Optional value 2 also prints file open errors, --enable-error-stack=2. * * \subsection subsec_cltools_h5clear_options Options * \li --help Print a usage message and exit diff --git a/tools/src/misc/h5mkgrp.h b/tools/src/misc/h5mkgrp.h index 4af8f176c9c..cb0b2740bcb 100644 --- a/tools/src/misc/h5mkgrp.h +++ b/tools/src/misc/h5mkgrp.h @@ -24,7 +24,7 @@ * * \subsection subsec_cltools_h5mkgrp_error Error Report Option * \li--enable-error-stack Prints messages from the HDF5 error stack as they occur. - * Optional value 2 also prints file open errors. + * Optional value 2 also prints file open errors, --enable-error-stack=2. * * \subsection subsec_cltools_h5mkgrp_options Options * \li --help Print a usage message and exit From 76cf2818ce3b56406a2622b4c50ce3a4ca3e3872 Mon Sep 17 00:00:00 2001 From: Allen Byrne Date: Thu, 27 Jun 2024 07:53:08 -0500 Subject: [PATCH 19/24] Add enhanced text explanation --- tools/src/h5dump/h5dump.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tools/src/h5dump/h5dump.h b/tools/src/h5dump/h5dump.h index 26622c0bf30..64dc54a3743 100644 --- a/tools/src/h5dump/h5dump.h +++ b/tools/src/h5dump/h5dump.h @@ -31,8 +31,8 @@ * \li --version Print the library version number and exit * * \subsection subsec_cltools_h5dump_options_file File Options - * \li --contents Print a list of the file contents and exit - * Optional value 1 also prints attributes. + * \li --contents Print a list of the file contents, group and dataset + * names and exit. Optional value 1 also prints attributes, --contents=1. * \li --superblock Print the content of the super block * \li --header Print the header only; no data is displayed * \li --filedriver=D Specify which driver to open the file with From 7768d81ac043dfc304564e813051139771862100 Mon Sep 17 00:00:00 2001 From: Allen Byrne Date: Tue, 2 Jul 2024 08:29:20 -0500 Subject: [PATCH 20/24] Update some explanations for better grammer. --- tools/src/h5diff/h5diff_main.h | 16 ++++++++-------- tools/src/h5dump/h5dump.h | 12 ++++++------ 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/tools/src/h5diff/h5diff_main.h b/tools/src/h5diff/h5diff_main.h index a45398bef8b..4662628caa4 100644 --- a/tools/src/h5diff/h5diff_main.h +++ b/tools/src/h5diff/h5diff_main.h @@ -18,7 +18,7 @@ * \section sec_cltools_h5diff h5diff * * \subsection subsec_cltools_h5diff_intro Introduction - * With h5diff, you can compare objects between a HDF5 file and another file. + * With h5diff, you can compare objects between an HDF5 file and objects in another or the same HDF5 file. * * \subsection subsec_cltools_h5diff_usage Usage *

          h5diff [OPTIONS] file1 file2 [obj1[ obj2]]

          @@ -102,18 +102,18 @@ * and h5diff returns an exit code of 2. * \li --compare List objects that are not comparable * \li --nan Avoid NaNs detection - * \li --count=C Print differences up to C. C must be a positive integer. + * \li --count=C Print differences up to \b C. \b C must be a positive integer. * \li --delta=D - * Print difference if (|a-b| > D). D must be a positive number, where a + * Print difference if (|a-b| > D). \b D must be a positive number, where \b a * is the data point value in file1 and b is the data point value in file2. * Can not use with '--relative' or '--use-system-epsilon'. * \li --relative=R - * Print difference if (|(a-b)/b| > R). R must be a positive number, where a - * is the data point value in file1 and b is the data point value in file2. + * Print difference if (|(a-b)/b| > R). \b R must be a positive number, where \b a + * is the data point value in file1 and \b b is the data point value in file2. * Can not use with '--delta' or '--use-system-epsilon'. * \li --use-system-epsilon - * Print difference if (|a-b| > EPSILON), EPSILON is system defined value, where a - * is the data point value in file1 and b is the data point value in file2. + * Print difference if (|a-b| > EPSILON), \b EPSILON is system defined value, where \b a + * is the data point value in file1 and \b b is the data point value in file2. * If the system epsilon is not defined,one of the following predefined * values will be used: *
          • FLT_EPSILON = 1.19209E-07 for @@ -168,7 +168,7 @@ * \li 4) Symbolic links * The paths to the target objects are compared. * (The option --follow-symlinks overrides the default behavior when - * symbolic links are compared.). + * symbolic links are compared.) * * \subsubsection subsubsec_cltools_h5diff_subset Subsetting Options * \li --no-compact-subset Disable compact form of subsetting and allow the use diff --git a/tools/src/h5dump/h5dump.h b/tools/src/h5dump/h5dump.h index 64dc54a3743..879206dfa62 100644 --- a/tools/src/h5dump/h5dump.h +++ b/tools/src/h5dump/h5dump.h @@ -31,8 +31,8 @@ * \li --version Print the library version number and exit * * \subsection subsec_cltools_h5dump_options_file File Options - * \li --contents Print a list of the file contents, group and dataset - * names and exit. Optional value 1 also prints attributes, --contents=1. + * \li --contents Print a list of the file contents, group and dataset, + * names and values, then exit. Optional value 1 also prints attributes, --contents=1. * \li --superblock Print the content of the super block * \li --header Print the header only; no data is displayed * \li --filedriver=D Specify which driver to open the file with @@ -120,16 +120,16 @@ * each dimension. \b START is optional and will default to 0 in each dimension. * * \li --start=START Offset of start of subsetting selection - * \b START - is a list of integers the number of which are equal to the + * \b START - is a list of integers, the number of which are equal to the * number of dimensions in the dataspace being queried.
            * \li --stride=STRIDE Hyperslab stride - * \b COUNT - is a list of integers the number of which are equal to the + * \b COUNT - is a list of integers, the number of which are equal to the * number of dimensions in the dataspace being queried.
            * \li --count=COUNT Number of blocks to include in selection - * \b STRIDE - is a list of integers the number of which are equal to the + * \b STRIDE - is a list of integers, the number of which are equal to the * number of dimensions in the dataspace being queried.
            * \li --block=BLOCK Size of block in hyperslab - * \b BLOCK - is a list of integers the number of which are equal to the + * \b BLOCK - is a list of integers, the number of which are equal to the * number of dimensions in the dataspace being queried.
            * (Alternate compact form of subsetting is described in the Reference Manual) * From 0a6a802f661b42b4cccd689e1295a876153f3cdd Mon Sep 17 00:00:00 2001 From: github-actions <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 2 Jul 2024 13:31:07 +0000 Subject: [PATCH 21/24] Committing clang-format changes --- tools/src/h5diff/h5diff_main.h | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/tools/src/h5diff/h5diff_main.h b/tools/src/h5diff/h5diff_main.h index 4662628caa4..fcbf25bb02a 100644 --- a/tools/src/h5diff/h5diff_main.h +++ b/tools/src/h5diff/h5diff_main.h @@ -112,12 +112,10 @@ * is the data point value in file1 and \b b is the data point value in file2. * Can not use with '--delta' or '--use-system-epsilon'. * \li --use-system-epsilon - * Print difference if (|a-b| > EPSILON), \b EPSILON is system defined value, where \b a - * is the data point value in file1 and \b b is the data point value in file2. - * If the system epsilon is not defined,one of the following predefined - * values will be used: - *
            • FLT_EPSILON = 1.19209E-07 for - * floating-point type
              • + * Print difference if (|a-b| > EPSILON), \b EPSILON is system defined value, where + * \b a is the data point value in file1 and \b b is the data point value in file2. If the system epsilon is + * not defined,one of the following predefined values will be used:
              • FLT_EPSILON = 1.19209E-07 for floating-point type
                • *
              • DBL_EPSILON = 2.22045E-16 * for double precision
              * type Can not use with '--relative' or '--delta'. From 740211203985ee9da456324564e4281c5bbcddc3 Mon Sep 17 00:00:00 2001 From: Allen Byrne Date: Tue, 9 Jul 2024 16:44:02 -0500 Subject: [PATCH 22/24] Fix typos --- tools/src/h5format_convert/h5format_convert.h | 4 +- tools/src/h5import/h5import.h | 458 +++++++++--------- 2 files changed, 230 insertions(+), 232 deletions(-) diff --git a/tools/src/h5format_convert/h5format_convert.h b/tools/src/h5format_convert/h5format_convert.h index d91d163ad04..5f101dac52c 100644 --- a/tools/src/h5format_convert/h5format_convert.h +++ b/tools/src/h5format_convert/h5format_convert.h @@ -34,7 +34,7 @@ * \li --noop Perform all the steps except the actual conversion * * \subsubsection subsubsec_cltools_h5format_convert_examples Usage Examples - * \li 1) h5format_convert -dname=/group/dataset file_name + * \li 1) h5format_convert --dname=/group/dataset file_name * * Convert the dataset in the HDF5 file : * - chunked dataset: convert the chunk indexing type to version 1 B-tree @@ -48,7 +48,7 @@ * - compact/contiguous dataset: downgrade the layout version to 3 * - virtual dataset: no action * - * \li 3) h5format_convert --noop -dname=/group/dataset file_name + * \li 3) h5format_convert --noop --dname=/group/dataset file_name * * Go through all the steps except the actual conversion when * converting the dataset in the HDF5 file . diff --git a/tools/src/h5import/h5import.h b/tools/src/h5import/h5import.h index a70a8211b9e..89d50d4a21d 100644 --- a/tools/src/h5import/h5import.h +++ b/tools/src/h5import/h5import.h @@ -25,121 +25,120 @@ * * \subsection subsec_cltools_h5import_intro Introduction * With h5import, you can convert data stored in one or more ASCII or binary files - into one or more datasets (in accordance with the - user-specified type and storage properties) in an existing - or new HDF5 file. + * into one or more datasets (in accordance with the + * user-specified type and storage properties) in an existing + * or new HDF5 file. * * \subsection subsec_cltools_h5import_desc Description * The primary objective of the utility is to convert floating - point or integer data stored in \b ASCII text or binary form - into a data-set according to the type and storage properties - specified by the user. The utility can also accept \b ASCII - text files and store the contents in a compact form as an - array of one-dimensional strings. - - The input data to be written as a data-set can be provided - to the utility in one of the following forms: - \li 1. ASCII text file with numeric data (floating point or - integer data) - \li 2. Binary file with native floating point data (32-bit or - 64-bit) - \li 3. Binary file with native integer (signed or unsigned) - data (8-bit or 16-bit or 32-bit or 64-bit) - \li 4. ASCII text file containing strings (text data) - - Every input file is associated with a configuration file - also provided as an input to the utility. (See Section - \ref subsec_cltools_h5import_config to know how it is to be organized). - The class, size and dimensions of the input data is - specified in this configuration file. A point to note is - that the floating point data in the \b ASCII text file may be - organized in the fixed floating form (for example 323.56) - or in a scientific notation (for example 3.23E+02). A - different input-class specification is to be used for both forms. - - The utility extracts the input data from the input file - according to the specified parameters and saves it into - an HDF5 dataset. - - The user can specify output type and storage properties in - the configuration file. The user is required to specify the - path of the dataset. If the groups in the path leading to - the dataset do not exist, the groups will be created by the - utility. If no group is specified, the dataset will be - created under the root group. - - In addition to the name, the user is also required to - provide the class and size of output data to be written to - the dataset and may optionally specify the output-architecture, - and the output-byte-order. If output-architecture is not - specified, the default is \b NATIVE. Output-byte-orders are fixed - for some architectures and may be specified only if output- - architecture is \b IEEE, \b UNIX or \b STD. - - Also, layout and other storage properties such as - compression, external storage and extendible datasets may be - optionally specified. The layout and storage properties - denote how raw data is to be organized on the disk. If these - options are not specified, the default is \b Contiguous layout - and storage. - - The dataset can be organized in any of the following ways: - \li 1. Contiguous - \li 2. Chunked - \li 3. External Storage File (has to be contiguous) - \li 4. Extendible data sets(has to be chunked) - \li 5. Compressed (has to be chunked) - \li 6. Compressed & Extendible (has to be chunked) - - If the user wants to store raw data in a non-HDF file then - the external storage file option is to be used and the name - of the file is to be specified. - - If the user wants the dimensions of the data-set to be - unlimited, the extendible data set option can be chosen. - - The user may also specify the type of compression and the - level to which the data set must be compresses by setting - the compressed option. + * point or integer data stored in \b ASCII text or binary form + * into a dataset according to the type and storage properties + * specified by the user. The utility can also accept \b ASCII + * text files and store the contents in a compact form as an + * array of one-dimensional strings. + * + * The input data to be written as a dataset can be provided + * to the utility in one of the following forms: + * \li 1. ASCII text file with numeric data (floating point or + * integer data) + * \li 2. Binary file with native floating point data (32-bit or + * 64-bit) + * \li 3. Binary file with native integer (signed or unsigned) + * data (8-bit or 16-bit or 32-bit or 64-bit) + * \li 4. ASCII text file containing strings (text data) + * + * Every input file is associated with a configuration file + * also provided as an input to the utility. (See Section + * \ref subsec_cltools_h5import_config to know how it is to be organized). + * The class, size and dimensions of the input data is + * specified in this configuration file. A point to note is + * that the floating point data in the \b ASCII text file may be + * organized in the fixed floating form (for example 323.56) + * or in scientific notation (for example 3.23E+02). A + * different input-class specification is to be used for both forms. + * + * The utility extracts the input data from the input file + * according to the specified parameters and saves it into + * an HDF5 dataset. + * + * The user can specify output type and storage properties in + * the configuration file. The user is required to specify the + * path of the dataset. If the groups in the path leading to + * the dataset do not exist, the groups will be created by the + * utility. If no group is specified, the dataset will be + * created under the root group. + * + * In addition to the name, the user is also required to + * provide the class and size of output data to be written to + * the dataset and may optionally specify the output-architecture, + * and the output-byte-order. If output-architecture is not + * specified, the default is \b NATIVE. Output-byte-orders are fixed + * for some architectures and may be specified only if output- + * architecture is \b IEEE, \b UNIX or \b STD. + * + * Also, layout and other storage properties such as + * compression, external storage and extendible datasets may be + * optionally specified. The layout and storage properties + * denote how raw data is to be organized on the disk. If these + * options are not specified, the default is \b Contiguous layout + * and storage. + * + * The dataset can be organized in any of the following ways: + * \li 1. Contiguous + * \li 2. Chunked + * \li 3. External Storage File (has to be contiguous) + * \li 4. Extendible data sets(has to be chunked) + * \li 5. Compressed (has to be chunked) + * \li 6. Compressed & Extendible (has to be chunked) + * + * If the user wants to store raw data in a non-HDF5 file then + * the external storage file option is to be used and the name + * of the file is to be specified. + * + * If the user wants the dimensions of the dataset to be + * unlimited, the extendible data set option can be chosen. + * + * The user may also specify the type of compression and the + * level to which the data set must be compressed by setting + * the compressed option. * * \subsection subsec_cltools_h5import_usage Usage - *

              h5import -h[elp], OR h5import \ -c[onfig] \ [\ -c[config] -\...] -o[utfile] \

              - + *

              h5import -h[elp], OR h5import \ -c[onfig] \ [\ -c[config]\...] -o[utfile] \

              + * * \subsection subsec_cltools_h5import_help Help * \li -h[elp] Print a usage message and exit * * \subsubsection subsubsec_cltools_h5import_options Program Options * \li \ - Name of the Input file(s), containing a - single n-dimensional floating point or integer array - in either ASCII text, native floating point(32-bit - or 64-bit) or native integer(8-bit or 16-bit or - 32-bit or 64-bit). Data to be specified in the order - of fastest changing dimensions first. - + * Name of the Input file(s), containing a + * single n-dimensional floating point or integer array + * in either ASCII text, native floating point(32-bit + * or 64-bit) or native integer(8-bit or 16-bit or + * 32-bit or 64-bit). Data to be specified in the order + * of fastest changing dimensions first. + * * \li -c[config] \ - Every input file should be associated with a - configuration file and this is done by the -c option. - \ is the name of the configuration file. - (See Section \ref subsec_cltools_h5import_config). - + * Every input file should be associated with a + * configuration file and this is done by the -c option. + * \ is the name of the configuration file. + * (See Section \ref subsec_cltools_h5import_config). + * * \li -o[utfile] \ - Name of the HDF5 output file. Data from one or more - input files are stored as one or more data sets in - \. The output file may be an existing file or - it maybe new in which case it will be created. - + * Name of the HDF5 output file. Data from one or more + * input files are stored as one or more data sets in + * \. The output file may be an existing file or + * it may be new, in which case it will be created. + * * \subsection subsec_cltools_h5import_config Configuration File - The configuration file is an ASCII text file and must be - the ddl formatted file (without data values) produced by \b h5dump - when used with the options \code -o outfilename -b \endcode of a single dataset (-d) - OR organized as CONFIG-KEYWORD VALUE pairs, one pair on each - line. - - The configuration file may have the following keywords each - followed by an acceptable value. - + * The configuration file is an ASCII text file and must be + * the ddl formatted file (without data values) produced by \b h5dump + * when used with the options \code -o outfilename -b \endcode of a single dataset (-d) + * OR organized as CONFIG-KEYWORD VALUE pairs, one pair on each + * line. + * + * The configuration file may have the following keywords each + * followed by an acceptable value. + * * \subsubsection subsubsec_cltools_h5import_config_req Required KEYWORDS * \li PATH * \li INPUT-CLASS @@ -149,7 +148,7 @@ * \li DIMENSION-SIZES * \li OUTPUT-CLASS * \li OUTPUT-SIZE - +* * \subsubsection subsubsec_cltools_h5import_config_opt Optional KEYWORDS * \li OUTPUT-ARCHITECTURE * \li OUTPUT-BYTE-ORDER @@ -158,153 +157,152 @@ * \li COMPRESSION-PARAM * \li EXTERNAL-STORAGE * \li MAXIMUM-DIMENSIONS - + * * \subsubsection subsubsec_cltools_h5import_config_val Values for keywords * \li PATH - Strings separated by spaces to represent - the path of the dataset. If the groups in - the path do not exist, they will be created. - For example, -
              • PATH grp1/grp2/dataset1
                • -
              • PATH: keyword
                • -
              • grp1: group under the root. If non-existent will be created
                • -
              • grp2: group under grp1. If non-existent will be created under grp1
                • -
              • dataset1: the name of the data-set to be created
              - + * Strings separated by spaces to represent + * the path of the dataset. If the groups in + * the path do not exist, they will be created. + * For example, + *
              • PATH grp1/grp2/dataset1
                • + *
              • PATH: keyword
                • + *
              • grp1: group under the root. If non-existent will be created
                • + *
              • grp2: group under grp1. If non-existent will be created under grp1
                • + *
              • dataset1: the name of the dataset to be created
              + * * \li INPUT-CLASS - String denoting the type of input data. -
              • TEXTIN
                • -
              • TEXTFP
                • -
              • FP
                • -
              • IN
                • -
              • STR
                • -
              • TEXTUIN
                • -
              • UIN
              - \b INPUT-CLASS "TEXTIN" denotes an ASCII text file with signed integer data in ASCII form, - \b INPUT-CLASS "TEXTUIN" denotes an ASCII text file with unsigned integer data in ASCII form, - "TEXTFP" denotes an ASCII text file containing floating point data in the fixed notation - (325.34),
              - "FP" denotes a floating point binary file, - "IN" denotes a signed integer binary file, - "UIN" denotes an unsigned integer binary file, - & "STR" denotes an ASCII text file the contents of which should be stored as an 1-D - array of strings.
              - If \b INPUT-CLASS is "STR", then \b RANK, - \b DIMENSION-SIZES, \b OUTPUT-CLASS, \b OUTPUT-SIZE, - \b OUTPUT-ARCHITECTURE and \b OUTPUT-BYTE-ORDER - will be ignored. - - + * String denoting the type of input data. + *
              • TEXTIN
                • + *
              • TEXTFP
                • + *
              • FP
                • + *
              • IN
                • + *
              • STR
                • + *
              • TEXTUIN
                • + *
              • UIN
              + * \b INPUT-CLASS "TEXTIN" denotes an ASCII text file with signed integer data in ASCII form, + * \b INPUT-CLASS "TEXTUIN" denotes an ASCII text file with unsigned integer data in ASCII form, + * "TEXTFP" denotes an ASCII text file containing floating point data in the fixed notation + * (325.34),
              + * "FP" denotes a floating point binary file, + * "IN" denotes a signed integer binary file, + * "UIN" denotes an unsigned integer binary file, + * & "STR" denotes an ASCII text file the contents of which should be stored as a 1-D + * array of strings.
              + * If \b INPUT-CLASS is "STR", then \b RANK, + * \b DIMENSION-SIZES, \b OUTPUT-CLASS, \b OUTPUT-SIZE, + * \b OUTPUT-ARCHITECTURE and \b OUTPUT-BYTE-ORDER + * will be ignored. + * * \li INPUT-SIZE - Integer denoting the size of the input data (8, 16, 32, 64). -
              • For floating point, \b INPUT-SIZE can be 32 or 64.
                • -
              • For integers (signed and unsigned) \b INPUT-SIZE can be 8, 16, 32 or 64.
              - + * Integer denoting the size of the input data (8, 16, 32, 64). + *
              • For floating point, \b INPUT-SIZE can be 32 or 64.
                • + *
              • For integers (signed and unsigned) \b INPUT-SIZE can be 8, 16, 32 or 64.
              + * * \li RANK - Integer denoting the number of dimensions. - + * Integer denoting the number of dimensions. + * * \li DIMENSION-SIZES - Integers separated by spaces to denote the dimension sizes for the no. of dimensions - determined by rank. - + * Integers separated by spaces to denote the dimension sizes for the number of dimensions + * determined by rank. + * * \li OUTPUT-CLASS - String dentoting data type of the dataset to be written ("IN","FP", "UIN") - + * String denoting data type of the dataset to be written ("IN","FP", "UIN") + * * \li OUTPUT-SIZE - Integer denoting the size of the data in the output dataset to be written. - If \b OUTPUT-CLASS is "FP", \b OUTPUT-SIZE can be 32 or 64. - If \b OUTPUT-CLASS is "IN" or "UIN", \b OUTPUT-SIZE can be 8, 16, 32 or 64. - + * Integer denoting the size of the data in the output dataset to be written. + * If \b OUTPUT-CLASS is "FP", \b OUTPUT-SIZE can be 32 or 64. + * If \b OUTPUT-CLASS is "IN" or "UIN", \b OUTPUT-SIZE can be 8, 16, 32 or 64. + * * \li OUTPUT-ARCHITECTURE - \b STRING denoting the type of output architecture. Can accept the following values -
              • STD
                • -
              • IEEE
                • -
              • INTEL
                • -
              • CRAY
                • -
              • MIPS
                • -
              • ALPHA
                • -
              • NATIVE (default)
                • -
              • UNIX
              - + * \b STRING denoting the type of output architecture. Can accept the following values + *
              • STD
                • + *
              • IEEE
                • + *
              • INTEL
                • + *
              • CRAY
                • + *
              • MIPS
                • + *
              • ALPHA
                • + *
              • NATIVE (default)
                • + *
              • UNIX
              + * * \li OUTPUT-BYTE-ORDER - String denoting the output-byte-order. Ignored if the \b OUTPUT-ARCHITECTURE is not specified or - if it is \b IEEE, \b UNIX or \b STD. Can accept the following values. -
              • BE (default)
                • -
              • LE
              - + * String denoting the output-byte-order. Ignored if the \b OUTPUT-ARCHITECTURE is not specified or + * if it is \b IEEE, \b UNIX or \b STD. Can accept the following values. + *
              • BE (default)
                • + *
              • LE
              + * * \li CHUNKED-DIMENSION-SIZES - Integers separated by spaces to denote the dimension sizes of the chunk for the no. of - dimensions determined by rank. Required field to denote that the dataset will be stored with - chunked storage. If this field is absent the dataset will be stored with contiguous storage. - + * Integers separated by spaces to denote the dimension sizes of the chunk for the number of + * dimensions determined by rank. Required field to denote that the dataset will be stored with + * chunked storage. If this field is absent the dataset will be stored with contiguous storage. + * * \li COMPRESSION-TYPE - String denoting the type of compression to be used with the chunked storage. Requires the - \b CHUNKED-DIMENSION-SIZES to be specified. The only currently supported compression method is \b GZIP. - Will accept the following value -
              • GZIP
              - + * String denoting the type of compression to be used with the chunked storage. Requires the + * \b CHUNKED-DIMENSION-SIZES to be specified. The only currently supported compression method is \b GZIP. + * Will accept the following value + *
              • GZIP
              + * * \li COMPRESSION-PARAM - Integer used to denote compression level and this option is to be always specified when - the \b COMPRESSION-TYPE option is specified. The values are applicable only to \b GZIP - compression.
              - Value 1-9: The level of Compression.
              - 1 will result in the fastest compression while 9 will result in - the best compression ratio.
              - The default level of compression is 6. - + * Integer used to denote compression level and this option is to be always specified when + * the \b COMPRESSION-TYPE option is specified. The values are applicable only to \b GZIP + * compression.
              + * Value 1-9: The level of Compression.
              + * 1 will result in the fastest compression while 9 will result in + * the best compression ratio.
              + * The default level of compression is 6. + * * \li EXTERNAL-STORAGE - String to denote the name of the non-HDF5 file to store data to. Cannot be used if \b CHUNKED-DIMENSIONS - or \b COMPRESSION-TYPE or \b EXTENDIBLE-DATASET is specified. - Value \: the name of the external file as a string to be used. - + * String to denote the name of the non-HDF5 file to store data to. Cannot be used if \b CHUNKED-DIMENSIONS + * or \b COMPRESSION-TYPE or \b EXTENDIBLE-DATASET is specified. + * Value \: the name of the external file as a string to be used. + * * \li MAXIMUM-DIMENSIONS - Integers separated by spaces to denote the maximum dimension sizes of all the - dimensions determined by rank. Requires the \b CHUNKED-DIMENSION-SIZES to be specified. A value of - -1 for any dimension implies \b UNLIMITED \b DIMENSION size for that particular dimension. - + * Integers separated by spaces to denote the maximum dimension sizes of all the + * dimensions determined by rank. Requires the \b CHUNKED-DIMENSION-SIZES to be specified. A value of + * -1 for any dimension implies \b UNLIMITED \b DIMENSION size for that particular dimension. + * * \subsection subsec_cltools_h5import_examples Usage Examples * \li Configuration File may look like * \code - PATH work h5 pkamat First-set - INPUT-CLASS TEXTFP - RANK 3 - DIMENSION-SIZES 5 2 4 - OUTPUT-CLASS FP - OUTPUT-SIZE 64 - OUTPUT-ARCHITECTURE IEEE - OUTPUT-BYTE-ORDER LE - CHUNKED-DIMENSION-SIZES 2 2 2 - \endcode - The above configuration will accept a floating point array - (5 x 2 x 4) in an ASCII file with the rank and dimension sizes - specified and will save it in a chunked data-set (of pattern - 2 X 2 X 2) of 64-bit floating point in the little-endian order - and IEEE architecture. The dataset will be stored at - "/work/h5/pkamat/First-set" - + * PATH work h5 pkamat First-set + * INPUT-CLASS TEXTFP + * RANK 3 + * DIMENSION-SIZES 5 2 4 + * OUTPUT-CLASS FP + * OUTPUT-SIZE 64 + * OUTPUT-ARCHITECTURE IEEE + * OUTPUT-BYTE-ORDER LE + * CHUNKED-DIMENSION-SIZES 2 2 2 + * \endcode + * The above configuration will accept a floating point array + * (5 x 2 x 4) in an ASCII file with the rank and dimension sizes + * specified and will save it in a chunked dataset (of pattern + * 2 X 2 X 2) of 64-bit floating point in the little-endian order + * and IEEE architecture. The dataset will be stored at + * "/work/h5/pkamat/First-set" + * * \li Another configuration could be * \code - PATH Second-set - INPUT-CLASS IN - RANK 5 - DIMENSION-SIZES 6 3 5 2 4 - OUTPUT-CLASS IN - OUTPUT-SIZE 32 - CHUNKED-DIMENSION-SIZES 2 2 2 2 2 - EXTENDIBLE-DATASET 1 3 - COMPRESSION-TYPE GZIP - COMPRESSION-PARAM 7 - \endcode - The above configuration will accept an integer array - (6 X 3 X 5 x 2 x 4) in a binary file with the rank and - dimension sizes specified and will save it in a chunked data-set - (of pattern 2 X 2 X 2 X 2 X 2) of 32-bit floating point in - native format (as output-architecture is not specified). The - first and the third dimension will be defined as unlimited. The - data-set will be compressed using GZIP and a compression level - of 7.
              - The dataset will be stored at \code /Second-set \endcode - + * PATH Second-set + * INPUT-CLASS IN + * RANK 5 + * DIMENSION-SIZES 6 3 5 2 4 + * OUTPUT-CLASS IN + * OUTPUT-SIZE 32 + * CHUNKED-DIMENSION-SIZES 2 2 2 2 2 + * EXTENDIBLE-DATASET 1 3 + * COMPRESSION-TYPE GZIP + * COMPRESSION-PARAM 7 + * \endcode + * The above configuration will accept an integer array + * (6 X 3 X 5 x 2 x 4) in a binary file with the rank and + * dimension sizes specified and will save it in a chunked dataset + * (of pattern 2 X 2 X 2 X 2 X 2) of 32-bit floating point in + * native format (as output-architecture is not specified). The + * first and the third dimension will be defined as unlimited. The + * dataset will be compressed using GZIP and a compression level + * of 7.
              + * The dataset will be stored at \code /Second-set \endcode + * * */ From 6d216996bdd8ee4ea8f1f0e78f5feda0a145a6fc Mon Sep 17 00:00:00 2001 From: github-actions <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 9 Jul 2024 21:45:50 +0000 Subject: [PATCH 23/24] Committing clang-format changes --- tools/src/h5import/h5import.h | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/tools/src/h5import/h5import.h b/tools/src/h5import/h5import.h index 89d50d4a21d..5b03780674e 100644 --- a/tools/src/h5import/h5import.h +++ b/tools/src/h5import/h5import.h @@ -103,7 +103,8 @@ * the compressed option. * * \subsection subsec_cltools_h5import_usage Usage - *

              h5import -h[elp], OR h5import \ -c[onfig] \ [\ -c[config]\...] -o[utfile] \

              + *

              h5import -h[elp], OR h5import \ -c[onfig] \ [\ + * -c[config]\...] -o[utfile] \

              * * \subsection subsec_cltools_h5import_help Help * \li -h[elp] Print a usage message and exit @@ -148,7 +149,7 @@ * \li DIMENSION-SIZES * \li OUTPUT-CLASS * \li OUTPUT-SIZE -* + * * \subsubsection subsubsec_cltools_h5import_config_opt Optional KEYWORDS * \li OUTPUT-ARCHITECTURE * \li OUTPUT-BYTE-ORDER @@ -251,9 +252,9 @@ * The default level of compression is 6. * * \li EXTERNAL-STORAGE - * String to denote the name of the non-HDF5 file to store data to. Cannot be used if \b CHUNKED-DIMENSIONS - * or \b COMPRESSION-TYPE or \b EXTENDIBLE-DATASET is specified. - * Value \: the name of the external file as a string to be used. + * String to denote the name of the non-HDF5 file to store data to. Cannot be used if \b + * CHUNKED-DIMENSIONS or \b COMPRESSION-TYPE or \b EXTENDIBLE-DATASET is specified. Value + * \: the name of the external file as a string to be used. * * \li MAXIMUM-DIMENSIONS * Integers separated by spaces to denote the maximum dimension sizes of all the From 01c8644457334208d1a53410cdb5bb4fea941fde Mon Sep 17 00:00:00 2001 From: Allen Byrne Date: Thu, 11 Jul 2024 15:37:21 -0500 Subject: [PATCH 24/24] Fix option references --- tools/src/h5repack/h5repack.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tools/src/h5repack/h5repack.h b/tools/src/h5repack/h5repack.h index 5bb6261191c..2977ffab6db 100644 --- a/tools/src/h5repack/h5repack.h +++ b/tools/src/h5repack/h5repack.h @@ -76,7 +76,7 @@ * \li --indexed=L2 Minimum number of links in the indexed format * \li --ssize=S[:F] Shared object header message minimum size * \li --minimum=M Do not apply the filter to datasets smaller than M - * \li --file=E Name of file E with the -f and -l options + * \li --file=E Name of file E with the --file and --layout options * \li --ublock=U Name of file U with user block data to be added * \li --block=B Size of user block to be added * \li --metadata_block_size=A Metadata block size for #H5Pset_meta_block_size @@ -137,7 +137,7 @@ * driver. * \li The default strategy when not set is \b FSM_AGGR without persisting free-space. * - * \li FS_PERSIST is 1 to persisting free-space or 0 to not persisting free-space. + * \li FS_PERSIST is 1 for persisting free-space or 0 for not persisting free-space. * The default when not set is not persisting free-space. * The value is ignored for \b AGGR and \b NONE strategies. *