Accessibility

Maintaining Compatibility with other HDF5 Library Versions

Problem

You want to ensure that the HDF5 files you produce or modify are accessible by all releavnt tools and applications

Solution

For HDF5 items (objects, attributes, etc.) that you would like to create in new or existing HDF5 files, ascertain the supported range of HDF5 library versions as lower and upper bounds. When creating new or opening existing HDF5 files, use a file access property list and configure the supported range via the H5Pset_libver_bounds() function.
In the example below, we restrict HDF5 item creation to the HDF5 1.8.x family of library versions.

    {
        __label__ fail_fapl, fail_file;
        hid_t fapl, file, aspace, attr;
 
        if ((fapl = H5Pcreate(H5P_FILE_ACCESS)) < 0) {
            ret_val = EXIT_FAILURE;
            goto fail_fapl;
        }
#if H5_VERSION_GE(1, 10, 0)
        if (H5Pset_libver_bounds(fapl, H5F_LIBVER_V18, H5F_LIBVER_V18) < 0) {
#elif H5_VERSION_GE(1, 8, 0)
        if (H5Pset_libver_bounds(fapl, H5F_LIBVER_LATEST, H5F_LIBVER_LATEST) < 0) {
#else
#error Only HDF5 1.8.x and later supported.
#endif
            ret_val = EXIT_FAILURE;
            goto fail_file;
        }
        if ((file = H5Fcreate("set_libver_bounds.h5", H5F_ACC_TRUNC, H5P_DEFAULT, fapl)) < 0) {
            ret_val = EXIT_FAILURE;
            goto fail_file;
        }
 
        H5Fclose(file);
fail_file:
        H5Pclose(fapl);
fail_fapl:;
    }

Discussion

See RFC Setting Bounds for Object Creation in HDF5 1.10.0 for a detailed and comprehensive account of HDF5 versioning (library, file format spec., etc.) and the H5Pset_libver_bounds() function.
The default range H5F_LIBVER_EARLIEST (low) - H5F_LIBVER_LATEST (high) offers the widest compatibility range, but may not be suitable for certain (feature-)use cases.
The HDF5 library comes with a forward- and backward-compatibility guarantee: This means that the latest version of the library can always read HDF5 files created by a version realesed earlier (backward compatibility). It also means that a given release of the library can read the contents of HDF5 files created with later versions of the library as long as the files do not contain features introduced in later versions (forward compatibility).

See Also

See the recipe Creating "Large" HDF5 Attributes for an example where we use HDF5 compatibility settings to enable the creation of large HDF5 attributes.