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.
15 {

16 __label__ fail_fapl, fail_file;

17 hid_t fapl, file, aspace, attr;

18

19 if ((fapl = H5Pcreate(H5P_FILE_ACCESS)) < 0) {

20 ret_val = EXIT_FAILURE;

21 goto fail_fapl;

22 }

23 #if H5_VERSION_GE(1, 10, 0)

24 if (H5Pset_libver_bounds(fapl, H5F_LIBVER_V18, H5F_LIBVER_V18) < 0) {

25 #elif H5_VERSION_GE(1, 8, 0)

26 if (H5Pset_libver_bounds(fapl, H5F_LIBVER_LATEST, H5F_LIBVER_LATEST) < 0) {

27 #else

28 #error Only HDF5 1.8.x and later supported.

29 #endif

30 ret_val = EXIT_FAILURE;

31 goto fail_file;

32 }

33 if ((file = H5Fcreate("set_libver_bounds.h5", H5F_ACC_TRUNC, H5P_DEFAULT, fapl)) < 0) {

34 ret_val = EXIT_FAILURE;

35 goto fail_file;

36 }

37

38 H5Fclose(file);

39 fail_file:

40 H5Pclose(fapl);

41 fail_fapl:;

42 }

H5F_LIBVER_V18
@ H5F_LIBVER_V18
Definition: H5Fpublic.h:187

H5F_LIBVER_LATEST
#define H5F_LIBVER_LATEST
Definition: H5Fpublic.h:195

H5F_ACC_TRUNC
#define H5F_ACC_TRUNC
Definition: H5Fpublic.h:50

hid_t
int64_t hid_t
Definition: H5Ipublic.h:60

H5P_FILE_ACCESS
#define H5P_FILE_ACCESS
Definition: H5Ppublic.h:52

H5P_DEFAULT
#define H5P_DEFAULT
Definition: H5Ppublic.h:102

H5Pset_libver_bounds
herr_t H5Pset_libver_bounds(hid_t plist_id, H5F_libver_t low, H5F_libver_t high)
Controls the range of library release versions used when creating objects in a file.

H5Fclose
herr_t H5Fclose(hid_t file_id)
Terminates access to an HDF5 file.

H5Fcreate
hid_t H5Fcreate(const char *filename, unsigned flags, hid_t fcpl_id, hid_t fapl_id)
Creates an HDF5 file.

H5Pclose
herr_t H5Pclose(hid_t plist_id)
Terminates access to a property list.

H5Pcreate
hid_t H5Pcreate(hid_t cls_id)
Creates a new property list as an instance of a property list class.

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.