Last modified: 12 April 2011
Tool Name: h5dump
Syntax:
h5dump [OPTIONS] file
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

It is possible to select the file driver with which to open the HDF5 file by using the --filedriver (-f) command-line option. Acceptable 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.

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.

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 http://www.hdfgroup.org/DTDs/HDF5-File.dtd.

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

Options and Parameters:

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

Current Status:
The current version of h5dump displays the following information:
See Also:

History:
Release     Change
1.6.5 The following options added in this release:
   -n or --contents
   -e or --escape
   -y or --noindex
   -p or --properties
   -b or --binary
1.8.0 The following options added in this release:
   -q or --sort_by
   -z or --sort_order
1.8.1 Compression ratio added to output of -p or --properties option in this release.
1.8.4 Region reference display, -R or --region option, added in this release.
1.8.5 Bitfield display fixed in this release.
Packed Bits data display, -M or --packedbits option, added in this release.
1.8.7 The following 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