Last modified: 23 August 2013
Tool Name: h5dump
Syntax:
  `h5dump [`OPTIONS`]` files

Purpose:
  Displays HDF5 file contents.

Description:
  `h5dump` enables the user to examine the contents of an HDF5 file and dump those contents, in human readable form, to an ASCII file.

  `h5dump` dumps HDF5 file content to standard output. It can display the contents of the entire HDF5 file or selected objects, which can be groups, datasets, a subset of a dataset, links, attributes, or datatypes.

  The `--header` option displays object header information only.

  Names are the absolute names of the objects. `h5dump` displays objects in the order same as the command order. If a name does not start with a slash, `h5dump` begins searching for the specified object starting at the root group.

  If an object is hard linked with multiple names, `h5dump` displays the content of the object in the first occurrence. Only the link information is displayed in later occurrences.

  `h5dump` assigns a name for any unnamed datatype in the form of `#`oid1`:`oid2, where oid1 and oid2 are the object identifiers assigned by the library. The unnamed types are displayed within the root group.

  Datatypes are displayed with standard type names. For example, if a dataset is created with `H5T_NATIVE_INT` type and the standard type name for integer on that machine is `H5T_STD_I32BE`, `h5dump` displays `H5T_STD_I32BE` as the type of the dataset.

  `h5dump` can also dump a subset of a dataset. This feature operates in much the same way as hyperslabs in HDF5; the parameters specified on the command line are passed to the function `H5Sselect_hyperslab` and the resulting selection is displayed.

  The `h5dump` output is described in detail in the DDL for HDF5, the Data Description Language document.

  Note: It is not permissible to specify multiple attributes, datasets, datatypes, groups, or soft links with one flag. For example, one may not issue the command
  WRONG: `h5dump -a /attr1 /attr2 foo.h5` to display both `/attr1` and `/attr2`. One must issue the following command:
  CORRECT: `h5dump -a /attr1 -a /attr2 foo.h5`

  One byte integer type data is displayed in decimal by default. When displayed in ASCII, a non-printable code is displayed in 3 octal digits preceeded by a back-slash unless there is a C language escape sequence for it. For example, CR and LF are printed as \r and \n. Though the NUL code is represented as \0 in C, it is printed as \000 to avoid ambiguity as illustrated in the following 1 byte char data (since this is not a string, embedded NUL is possible).

              141 142 143 000 060 061 062 012
                a   b   c  \0   0   1   2  \n

  h5dump prints them as "abc\000012\n". But if h5dump prints NUL as \0, the output is "abc\0012\n" which is ambiguous.

  Using file drivers:
  It is possible to select the file driver with which to open an HDF5 file by using the `--filedriver` (or `-f`) command-line option. Valid values for the `--filedriver` option are `sec2`, `family`, `split`, and `multi`. If the file driver flag is not specified, then the file will be opened with each driver in turn, and in the order specified above, until one driver succeeds in opening the file.

  Special file naming restrictions apply when using `h5dump` with either the `split` or the `multi` driver.

  To dump a split file, `h5dump` requires that the metadata and raw data filenames end with `-m.h5` and `-r.h5`, respectively, and that the entire virtual HDF5 file, or the logical HDF5 file, be referred to on the command line by the common portion of the filename preceding the `-m` and `-r`.

  For example, assume that a split HDF5 file has its metadata in a file named `splitfile-m.h5` and its raw data in a file named `splitfile-r.h5`. The following command would dump the contents of this logical HDF5 file:
  `h5dump --filedriver="split" splitfile`

  Note that the above split filename restrictions are specific to `h5dump`; HDF5 applications do not necessarily have the same limitations.

  To dump a multi file, `h5dump` requires that the metadata and raw data filenames end with a subset of the following:
  `` `-s.h5` for userblock, superblock, and driver information block data
  `` `-b.h5` for B-tree node information
  `` `-r.h5` for dataset raw data
  `` `-g.h5` for global heap data
  `` `-l.h5` for local heap data (object names)
  `` `-o.h5` for object headers
  The entire virtual HDF5 file must also be referred to on the command line by the common portion of the filename preceding those special tags.

  For example, assume that a multi HDF5 file has its userblock, superblock, and driver information block data in a file named `multifile-s.h5`, its B-tree node information in a file named `multifile-b.h5`, its raw data in a file named `multifile-r.h5`, its global heap data in a file named `multifile-g.h5`, et cetera. The following command would dump the contents of this logical HDF5 file:
  `h5dump --filedriver="multi" multifile`

  Note that the above multi filename restrictions are specific to `h5dump`; HDF5 applications do not necessarily have the same limitations.

  To dump a family file, `h5dump` requires that the logical file’s name on the command line include the `printf(3c)`-style integer format specifier that specifies the format of the family file member numbers. For example, if an HDF5 family of files consists of the files `family_000.h5`, `family_001.h5`, `family_002.h5`, and `family_003.h5`, the logical HDF5 file would be specified on the command line as `family_%3d.h5`.

  The following command would dump the contents of this logical HDF5 file:
  `h5dump --filedriver="family" family_%3d.h5`

XML Output:
  With the `--xml` option, `h5dump` generates XML output. This output contains a complete description of the file, marked up in XML. The XML conforms to the HDF5 Document Type Definition (DTD) available at “HDF5 XML Software.”

  The XML output is suitable for use with other tools, including the HDF5 Java Products.

Options and Parameters:

  `-h` or `--help` | Print a usage message and exit.
  `-V` or `--version` | Print version number and exit.
  Formatting options:
  `-e` or `--escape` | Escape non-printing characters.
  `-r` or `--string` | Print 1-byte integer datasets as ASCII.
  `-y` or `--noindex` | Do not print array indices with data.
  `-m T` or `--format=T` | Set the floating point output format. T is a string defining the floating point format, e.g., `'%.3f'`.
  `-q Q` or `--sort_by=Q` | Sort groups and attributes by the specified index type, Q. Valid values of Q are as follows: `name` Alpha-numeric index by name (Default) `creation_order` Index by creation order
  `-z Z` or `--sort_order=Z` | Sort groups and attributes in the specified order, Z. Valid values of Z are as follows: `ascending` Sort in ascending order (Default) `descending` Sort in descending order
  `--enable-error-stack` | Prints messages from the HDF5 error stack as they occur. Injects error stack information, which is normally suppressed, directly into the output stream. This will disrupt normal `h5dump` output but is a useful diagnostic tool when data is not being correctly dumped. Consider the case when an `h5dump` call produces this message:
          dump error: unable to print data
  `h5dump` can be called again with ‘`--enable-error-stack`’ plus the original options to reveal error stack messages.
  `--no-compact-subset` | Enables recognition of the left square bracket ( `[` ) as a character in a dataset name. This option must disable compact subsetting, which is described at the end of this “Options and Parameters” section.
  `-w N` or `--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.
  File options:
  `-n` or `--contents` | Print a list of the file contents and exit.
  `-n 1` or `--contents=1` | The optional value `1` (one) on the `-n, --contents` option adds attributes to the output.
  `-B` or `--superblock` | Print the content of the superblock.
  `-H` or `--header` | Print the header only; no data is displayed.
  `-f D` or `--filedriver=D` | Specify which driver to open the file with.
  `-o F` or `--output=F` | Output raw data into file F. The files specified for the `-o` and `-O` options must be different files. The output from these options must not be comingled. To suppress the raw data display, use this option with no filename, as in either of the following examples. This has the effect of sending the output to a NULL file: `-o` `--output=`
  `-b B` or `--binary=B` | Output dataset to a binary file using the datatype specified by `B`. `B` must have one of the following values: `LE` Little-endian `BE` Big-endian `MEMORY` Memory datatype `FILE` File datatype Recommended usage is with the `-d` and `-o` options.
  `-O F` or `--ddl=F` | Output DDL text into file F. The files specified for the `-o` and `-O` options must be different files. The output from these options must not be comingled. `h5import` can use the files output by the `-o` and `-O` when importing HDF5 data. See “Using `h5dump` to create input for `h5import`.” To suppress the DDL display, use this option with no filename, as in either of the following examples. This has the effect of sending the output to a NULL file: `-O` `--ddl=`
  Object options:
  `-a P` or `--attribute=P` | Print the specified attribute.
  `-d P` or `--dataset=P` | Print the specified dataset.
  `-g P` or `--group=P` | Print the specified group and all members.
  `-l P` or `--soft-link=P` | Print the value(s) of the specified soft link.
  `-t P` or `--datatype=P` | Print the specified named datatype.
  `-A` or `--onlyattr` | Print the header and value of attributes; data of datasets is not displayed.
  `-A 0` or `--onlyattr=0` | The optional value `0` (zero) on the `-A, --onlyattr` option prints everything except attributes.
  `-N P` or `--any-path=P` | Print any attribute, dataset, datatype, group, or link whose path matches P. P may match either the absolute path or any portion of the path.
  Object property options:
  `-i` or `--object-ids` | Print the object ids.
  `-p` or `--properties` `` | Print information regarding dataset properties, including filters, storage layout, fill value, and allocation time. The filter output lists any filters used with a dataset, including the type of filter, its name, and any filter parameters. The storage layout output specifies the dataset layout (chunked, compact, or contiguous), the size in bytes of the dataset on disk, and, if a compression filter is associated with the dataset, the compression ratio. The compression ratio is computed as (uncompressed size)/(compressed size). The fill value output includes the fill value datatype and value. The allocation time output displays the allocation time as specified with `H5Pset_alloc_time`.
  `-M L` or `--packedbits=L` | Print packed bits as unsigned integers, using 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. length is the number of bits in the mask.
  `-R` or `--region` | Print dataset pointed by region references.
  XML options:
  `-x` or `--xml` | Output XML using XML schema (default) instead of DDL.
  `-u` or `--use-dtd` | Output XML using XML DTD instead of DDL.
  `-D U` or `--xml-dtd=U` | In XML output, refer to the DTD or schema at U instead of the default schema/DTD.
  `-X S` or `--xml-ns=S` | In XML output, (XML Schema) use qualified names in the XML: ":": no namespace, default: "hdf5:"
  Subsetting options and compact subsetting:
  | Subsetting is available by using the following options with the dataset option, `-d` or `--dataset`. Subsetting is accomplished by selecting a hyperslab from the data, so the options mirror those for performing a hyperslab selection. At least one of the `START`, `COUNT`, `STRIDE`, or `BLOCK` options is mandatory if you do subsetting; the remainder are optional, with default values as follows: • `STRIDE`, `COUNT`, and `BLOCK` default to `1` in each dimension. • `START` defaults to `0` in each dimension.
  `-s START` or `--start=START` | Offset of start of subsetting selection. Default: 0 in all dimensions, specifying the beginning of the dataset. Each of START, STRIDE, COUNT, and BLOCK must be a comma-separated list of integers with one integer for each dimension of the dataset.
  `-S STRIDE` or `--stride=STRIDE` | Hyperslab stride. Default: 1 in all dimensions.
  `-c COUNT` or `--count=COUNT` | Number of blocks to include in the selection. Default: 1 in all dimensions.
  `-k BLOCK` or `--block=BLOCK` | Size of block in hyperslab. Default: 1 in all dimensions. Compact subsetting: Subsetting parameters can also be expressed in a convenient compact form, as follows: `--dataset="/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: `--dataset="/foo/mydataset[START;;COUNT]"` `--dataset="/foo/mydataset[START]"` Each of START, STRIDE, COUNT, and BLOCK must be a comma-separated list of integers with one integer for each dimension of the dataset. When not specified, default parameter values are used: zeros ( `0` ) for START and ones ( `1` ) for STRIDE, COUNT, and BLOCK.
  Option Argument Conventions:
  `--` | Two dashes followed by whitespace. Indicates that the following argument is not an option. For example, this structure can be used to dump a file called `-f`:
          h5dump -- -f
  This option is necessary only when the name of the file to be examined starts with a dash (`-`), which could confuse the tool’s command-line parser.
  Option parameters appearing above are defined as follows:
  D | File driver to use in opening the file Valid values are `sec2`, `family`, `split`, and `multi`. Without the file driver option, the file will be opened with each driver in turn, and in the order specified immediately above, until one driver succeeds in opening the file.
  P | Path to the object For most options, this must be the absolute path from the root group to the object. With the `-N`, `--any-path` option, this may be either the absolute path or a partial path.
  F | A filename
  N | An integer greater than 1
  START, STRIDE, `` COUNT, and BLOCK | Comma-separated lists of integers Each of these option parameters must be a list of integers with one integer for each dimension of the dataspace being queried.
  U | A URI (as defined in [IETF RFC 2396], updated by [IETF RFC 2732]) that refers to the DTD to be used to validate the XML
  B | The form of binary output: `MEMORY` for a memory type `FILE` for the file type `LE` or `BE` for pre-existing little- or big-endian types
  Files parameter:
  `files` | File or files to be examined; one or more files may be listed. The file name may include a `printf(3C)` integer format such as `%05d` to open a file family. On Unix, Linux, and Mac OS X systems, multiple files can be examined through the use of Unix-style wildcards. For example, assume that we are working with the files `FileA.h5`, `FileB.h5`, `FileC.h5`, and `FileAB.h5`: `File[AB].h5` will pick up any file that begins with `File`, followed by any one of the characters contained in the square brackets, and ending with `.h5`. In this case, `File[AB].h5` will pick up the files `FileA.h5` and `FileB.h5`. `File?.h5` will pick up all files whose names are `File`, followed by exactly 1 character (any character), followed by `.h5`. In this case, `File?.h5` will pick up the files `FileA.h5` and `FileB.h5`, and `FileC.h5`. `File*.h5` will pick up all files whose names begin with `File` and end with `.h5`. In this case, `File*.h5` will pick up all four files. The wildcard capability is not currently available on Windows systems.

Exit Status:

  0 | Succeeded.
  > 0 | An error occurred.

Examples:
  1. Dump the group `/GroupFoo/GroupBar` in the file `quux.h5`:
     `h5dump -g /GroupFoo/GroupBar quux.h5`
  2. Dump the dataset `Fnord`, which is in the group `/GroupFoo/GroupBar` in the file `quux.h5`:
     `h5dump -d /GroupFoo/GroupBar/Fnord quux.h5`
  3. Dump the attribute `metadata` of the dataset `Fnord`, which is in the group `/GroupFoo/GroupBar` in the file `quux.h5`:
     `h5dump -a /GroupFoo/GroupBar/Fnord/metadata quux.h5`
  4. Dump the attribute `metadata` which is an attribute of the root group in the file `quux.h5`:
     `h5dump -a /metadata quux.h5`
  5. Produce an XML listing of the file `bobo.h5`, saving the listing in the file `bobo.h5.xml`:
     `h5dump --xml bobo.h5 > bobo.h5.xml`
  6. Dump a subset of the dataset `/GroupFoo/databar/` in the file `quux.h5`:
     `h5dump -d /GroupFoo/databar --start="1,1" --stride="2,3"
     --count="3,19" --block="1,1" quux.h5`
  7. The same example, using the short form to specify the subsetting parameters:
     `h5dump -d "/GroupFoo/databar[1,1;2,3;3,19;1,1]" quux.h5`
  8. Dump a binary copy of the dataset `/GroupD/FreshData/` in the file `quux.h5`, with data written in little-endian form, to the output file `FreshDataD.bin`:
     `h5dump -d "/GroupD/FreshData" -b LE
     -o "FreshDataD.bin" quux.h5`
  9. Display two sets of packed bits (bits 0-1 and bits 4-6) in the dataset `/dset` of the file `quux.h5`:
     `h5dump -d /dset -M 0,1,4,3 quux.h5`
  10. Dump the dataset `/GroupFoo/GroupBar/Fnord` to the file `quux.h5` and output the DDL into the file `ddl.txt` and the raw data into the file `data.txt`:
      `h5dump -d /GroupFoo/GroupBar/Fnord --ddl=ddl.txt -y
      -o data.txt quux.h5`
  11. Dump the dataset `/GroupFoo/GroupBar/Fnord` to the file `quux.h5`, suppress the DDL output, and output the raw data into the file `data.txt`:
      `h5dump -d /GroupFoo/GroupBar/Fnord --ddl= -y
      -o data.txt quux.h5`

Current Status:
  The current version of `h5dump` displays the following information:
  - Group
    - group attribute (see Attribute)
    - group member
  - Dataset
    - dataset attribute (see Attribute)
    - dataset type (see Datatype)
    - dataset space (see Dataspace)
    - dataset data
  - Attribute
    - attribute type (see Datatype)
    - attribute space (see Dataspace)
    - attribute data
  - Datatype
    - integer type
      - H5T_STD_I8BE, H5T_STD_I8LE, H5T_STD_I16BE, ...
      - packed bits display
      - integer types only
      - limited to first 8 bits
      - applied globally to all integer values, including inside compound types
    - bitfield type
    - floating point type
      - H5T_IEEE_F32BE, H5T_IEEE_F32LE, H5T_IEEE_F64BE, ...
    - string type
    - compound type
      - named, unnamed and transient compound type
      - integer, floating or string type member
    - opaque types
    - reference type
      - object references
      - data regions
    - enum type
    - variable-length datatypes
      - atomic types only
      - scalar or single dimensional array of variable-length types supported
  - Dataspace
    - scalar and simple space
  - Soft link
  - Hard link
  - Loop detection

See Also:

  HDF5 Data Description Language syntax at DDL for HDF5 HDF5 XML Schema at http://www.hdfgroup.org/HDF5/XML/schema/HDF5-File.xsd HDF5 XML information at http://www.hdfgroup.org/HDF5/XML/

History:

  Release | Change
  1.8.12 | Optional value of `0` (zero) for the `-A, --onlyattr` option added in this release. Option added in this release: `-N P` or `--any-path=P`
  1.8.11 | Option added in this release: `-O F` or `--ddl=F` This option can be used to suppress the DDL output. This option, combined with the `'--output=F'` (or `'-o F'`) option will generate files that can be used as input to `h5import`. `h5dump` updated in this release to display the compression ratio for user-defined filters. In `h5dump` output, `UNKNOWN_FILTER` has been changed to `USER_DEFINED_FILTER`.
  1.8.9 | Option added in this release: `--no-compact-subset` `h5dump` output has been updated for this release to improve compliance with the HDF5 DDL specification and to improve readablilty. This output is now fully compliant with the HDF5 DDL specification, but these changes may affect some user scripts: Whitespace has been modified. Display errors, such as misplaced brackets, have been fixed. When printing superblock content, user block content is now properly displayed within the superblock.
  1.8.7 | Option added in this release: `--enable-error-stack` Tool updated in this release to correctly display reference type: `H5T_REFERENCE {H5T_STD_REF_OBJ}` for object references `H5T_REFERENCE {H5T_STD_REF_DSETREG}` for dataset region references
  1.8.5 | Bitfield display fixed in this release. Option added in this release for packed bits data display: `-M` or `--packedbits` option
  1.8.4 | Option added in this release for region reference display: `-R` or `--region` option
  1.8.1 | Compression ratio added to output of `-p` or `--properties` option in this release.
  1.8.0 | Options added in this release: `-q` or `--sort_by` `-z` or `--sort_order`
  1.6.5 | Options added in this release: `-n` or `--contents` `-e` or `--escape` `-y` or `--noindex` `-p` or `--properties` `-b` or `--binary`