diff --git a/doxygen/Doxyfile.in b/doxygen/Doxyfile.in index 29033f5de21..05f660b8763 100644 --- a/doxygen/Doxyfile.in +++ b/doxygen/Doxyfile.in @@ -689,6 +689,8 @@ FILE_PATTERNS = H5*public.h H5*module.h H5*develop.h H5FD*.h \ *.F90 \ *.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/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." ################################################################################ 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/hl/tools/h5watch/h5watch.h b/hl/tools/h5watch/h5watch.h new file mode 100644 index 00000000000..188707bba2b --- /dev/null +++ b/hl/tools/h5watch/h5watch.h @@ -0,0 +1,62 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * 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, --enable-error-stack=2. + * + * \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. + * + * \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/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 new file mode 100644 index 00000000000..b0a684f4ab9 --- /dev/null +++ b/tools/src/h5copy/h5copy.h @@ -0,0 +1,72 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * 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_h5copy_usage Usage + *

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 + * + * \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, --enable-error-stack=2. + * + * \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 + * + * \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..fcbf25bb02a --- /dev/null +++ b/tools/src/h5diff/h5diff_main.h @@ -0,0 +1,214 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * 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 an HDF5 file and objects in another or the same HDF5 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 + * + * \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, --enable-error-stack=2. + * + * \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 \b C. \b C must be a positive integer. + * \li --delta=D + * 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). \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), \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'. + * \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. + * \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 \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 + * + * \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/h5dump/h5dump.h b/tools/src/h5dump/h5dump.h index 5deb95190a9..879206dfa62 100644 --- a/tools/src/h5dump/h5dump.h +++ b/tools/src/h5dump/h5dump.h @@ -12,6 +12,187 @@ #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 display objects from an HDF5 file. + * + * \subsection subsec_cltools_h5dump_usage Usage + *

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, --enable-error-stack=2. + * + * \subsection subsec_cltools_h5dump_options Options + * \li --help Print a usage message 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, 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 + * \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. + * \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 + * \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.) + * \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 + * + * \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 + * \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 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://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]) + * \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 --attribute=/bar_none/foo quux.h5 + * + * \li 2) Attribute "high/low" of the group /bar_none in the file quux.h5 + * + * h5dump --attribute="/bar_none/high\/low" quux.h5 + * + * \li 3) Selecting a subset from dataset /foo in file 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 --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-dataset=/dset --packedbits=0,1,4,3 quux.h5 + * + * \li 6) Dataset foo in files 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 --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 --dataset=/foo --filedriver=multi mf + * + * \li 9) Dataset foo in family files fam00000.h5 fam00001.h5 and fam00002.h5 + * + * h5dump --dataset=/foo --filedriver=family fam%05d.h5 + * + */ + #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..5f101dac52c --- /dev/null +++ b/tools/src/h5format_convert/h5format_convert.h @@ -0,0 +1,58 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * 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, --enable-error-stack=2. + * + * \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 + * + * \subsubsection subsubsec_cltools_h5format_convert_examples Usage Examples + * \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 . + * + */ + +#endif /* H5FORMAT_CONVERT_H */ diff --git a/tools/src/h5import/h5import.h b/tools/src/h5import/h5import.h index 86a27889c9b..5b03780674e 100644 --- a/tools/src/h5import/h5import.h +++ b/tools/src/h5import/h5import.h @@ -19,6 +19,294 @@ #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 \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] \

+ * + * \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. + * + * \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 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. + * + * \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 + * + * \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 + * + * \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 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 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.
+ * + * \li RANK + * Integer denoting the number of dimensions. + * + * \li DIMENSION-SIZES + * Integers separated by spaces to denote the dimension sizes for the number of dimensions + * determined by rank. + * + * \li OUTPUT-CLASS + * 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. + * + * \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 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
+ * + * \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 + * \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 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 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 + * + * + */ + /* * state table tokens */ diff --git a/tools/src/h5jam/h5jam.h b/tools/src/h5jam/h5jam.h new file mode 100644 index 00000000000..7d3cca65535 --- /dev/null +++ b/tools/src/h5jam/h5jam.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 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 + * \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]

+ * + * \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. + * + * \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. + * + */ + +#endif /* H5JAM_H */ diff --git a/tools/src/h5ls/h5ls.h b/tools/src/h5ls/h5ls.h new file mode 100644 index 00000000000..d72c1be10d4 --- /dev/null +++ b/tools/src/h5ls/h5ls.h @@ -0,0 +1,108 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * 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, --enable-error-stack=2. + * + * \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 --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. + * + */ + +#endif /* H5LS_H */ diff --git a/tools/src/h5repack/h5repack.h b/tools/src/h5repack/h5repack.h index cc724a067cf..2977ffab6db 100644 --- a/tools/src/h5repack/h5repack.h +++ b/tools/src/h5repack/h5repack.h @@ -13,6 +13,231 @@ #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, --enable-error-stack=2. + * + * \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 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 + * 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 --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 + * \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 \b FSM_AGGR without 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. + * + * \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. + * 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: + *
  • 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 + * 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 + * 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)
+ * + * \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: + *
  • 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)
    • + *
  • CONTI (no parameter)
+ * + * \subsubsection subsubsec_cltools_h5repack_options_note NOTE + * 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 + * + * \subsection subsec_cltools_h5repack_examples Usage Examples + * + * \li 1) h5repack --verbose --filter=GZIP=1 file1 file2 + * + * GZIP compression with level 1 to all objects + * + * \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 --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 --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 --filter=SHUF --filter=GZIP=1 file1 file2 + * + * Add both filters SHUF and GZIP in this order to all datasets + * + * \li 6) h5repack --filter=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/src/h5stat/h5stat.h b/tools/src/h5stat/h5stat.h new file mode 100644 index 00000000000..848480eb2b3 --- /dev/null +++ b/tools/src/h5stat/h5stat.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 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, --enable-error-stack=2. + * + * \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=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. + * + */ + +#endif /* H5STAT_H */ diff --git a/tools/src/misc/h5clear.h b/tools/src/misc/h5clear.h new file mode 100644 index 00000000000..354b2f6ef33 --- /dev/null +++ b/tools/src/misc/h5clear.h @@ -0,0 +1,67 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * 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 h5clear + * + * \subsection subsec_cltools_h5clear_intro Introduction + * 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

+ * + * \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, --enable-error-stack=2. + * + * \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. + * + * \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 . + * + * \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 new file mode 100644 index 00000000000..e946681a6a9 --- /dev/null +++ b/tools/src/misc/h5debug.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 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..5faedc023a4 --- /dev/null +++ b/tools/src/misc/h5delete.h @@ -0,0 +1,30 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * 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..cb0b2740bcb --- /dev/null +++ b/tools/src/misc/h5mkgrp.h @@ -0,0 +1,53 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * 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, --enable-error-stack=2. + * + * \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 + * + */ + +#endif /* H5MKGRP_H */ diff --git a/tools/src/misc/h5repart.h b/tools/src/misc/h5repart.h new file mode 100644 index 00000000000..9452bd5b6f4 --- /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 */ 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)