Last modified: 23 February 2010

Syntax:

h5fix_swapped_ids 
            old_file
            new_file

Purpose:

Fixes files with fractal heap identifier encoding errors.

Motivation:

H5fix_swapped_ids corrects a metadata corruption error that manifests as incorrect encoding of fractal heap identifiers for attributes and shared object header messages. This error occurs only in particular circumstances and causes some files created on a big-endian system to be unreadable on a little-endian system.

H5fix_swapped_ids corrects the incorrect encoding.

This error existed in HDF5 Releases 1.8.0 through 1.8.4; it was fixed in HDF5 Release 1.8.4-patch1.

Description:

h5fix_swapped_ids corrects metadata encoding errors (the encoding of the fractal heap identifiers for attributes and shared object header messages) in certain types of corrupted files.

To identify the class of potentially-corrupted files: A file might have this problem only when all of the following conditions are met:

The file was created with a version of the HDF5 library from HDF5 Release 1.8.0 (HDF5-1.8.0) through HDF5 Release 1.8.4 (HDF5-1.8.4).
(The bug was fixed in HDF5 Release 1.8.4-patch1 (HDF5-1.8.4-patch1).)
The file was created on a big-endian platform (SPARC/Solaris, POWER/AIX, etc.).
One of the following occurred:
- NetCDF-4 was used to create the file and more than 8 attributes were added to an object in the file.
- An H5Pset_libver_bounds(fapl, H5F_LIBVER_LATEST, H5F_LIBVER_LATEST) call was made and more than 8 attributes were added to an object in the file.
- Shared object header messages were enabled with H5Pset_shared_mesg_nindexes() when the file was created and messages of the type specified as being shared object header messages were stored in the file.

If all of the above conditions are satisfied, a file may have this error; a file that does not meet all of the above conditions will not be corrupted.

To determine whether a specific file is corrupted: While there is no foolproof way to detect a file with these incorrectly encoded identifiers, you can examine a suspect file with h5dump. If h5dump reports an error message similar to the following, the file is likely to contain this error:

        h5dump error: error getting attribute information.

For files created with netCDF-4, this message will generally display when dumping information about the root group. If your application is generating an error stack similar to this, it's also likely that the file has this problem:

        .
        .
        .        
        #008: ../../hdf5_v1.8/src/H5B2int.c line 1951 in H5B2_iterate_node():   \
              iterator function failed major: B-Tree node minor: Unable to list \
              node
        #009: ../../hdf5_v1.8/src/H5Adense.c line 1076 in                       \
              H5A_dense_iterate_bt2_cb(): heap op callback failed major:        \
              Attribute minor: Can't operate on object
        #010: ../../hdf5_v1.8/src/H5HF.c line 680 in H5HF_op(): can't operate   \
              on object from fractal heap major: Heap minor: Can't operate      \
              on object
        #011: ../../hdf5_v1.8/src/H5HFman.c line 462 in H5HF_man_op(): unable   \
              to operate on heap object major: Heap minor: Can't operate on     \
              object
        #012: ../../hdf5_v1.8/src/H5HFman.c line 276 in H5HF_man_op_real():     \
              fractal heap object offset too large major: Heap minor: Out of    \
              range

To correct the error: This error can be corrected with the following h5fix_swapped_ids call:

        h5fix_swapped_ids old_file new_file

h5fix_swapped_ids will read the corrupted file, old_file, and write new_file with the corrected identifiers.

The fix can be performed on either a big-endian or little-endian machine.

To acquire h5fix_swapped_ids: The tool is available in both binary and source forms at http://www.hdfgroup.org/ftp/HDF5/special_tools/.

Warning: As stated above, there is no definitive way to determine whether a specific file is corrupted. You can only determine (a) whether a file is in a class of files that is subject to this corruption and (b) whether it is probably corrupted. It is therefore critical to verify that new_file has indeed been fixed before discarding old_file.

Parameters:

old_file: The corrupted file, as input.
new_file: The corrected file, as output.

Example Usage:

The following usage generates a corrected file, new_file, from old_file, a file containing encoding errors in fractal heap identifiers for attributes and shared object header messages:

      h5fix_swapped_ids old_file new_file

History:

Release	Change
1.8.4-patch1	Tool introduced in this release.