netcdf-c/libhdf5/hdf5set_format_compatibility.c

92 lines
3.5 KiB
C
Raw Normal View History

/* Copyright 2022, University Corporation for Atmospheric Research.
* See COPYRIGHT file for copying and redistribution conditions. */
/**
* @file
* @internal This function selects the best HDF5 file format options
* to create netCDF-4 files that can be read and written by older
* library versions.
*
* Format compatibility is transient, not baked in to an HDF5 file
* at creation time. Therefore the desired compatibilty options
* must be selected every time a file is opened for writing.
*
* This function should be called before every call to create a new
* netCDF-4 file, or to open an existing netCDF-4 file for writing.
* This function has no effect when opening a file for read only.
*
* This function should work correctly with all HDF5 library versions
* from 1.8.0 through 1.13.0 and beyond, with no further changes.
* This assumes that HDF5 versioning controls remain consistent
* into the future.
*
* The basic functionality is to select the traditional HDF5 v1.8
* format compatibility, whenever possible. The less desirable
* v1.6 compatibily is selected in a few strange cases when it is
* not possible to select v1.8.
*
* Files created or updated with v1.10 and higher compatibility are
* not legal netCDF-4 format, as of 2022 January. They are not
* readable by any netCDF library version linked with any HDF5 v1.8
* or older library version. However, it is possible for advanced
* or experimental software to deliberately override these default
* format settings, to create advanced format files for special
* purposes.
*
* Files created with v1.6 compatibility have superblock version 0.
* Files created with v1.8 compatibility have superblock version 2.
* Files created with v1.10 compatibility have superblock version 3,
* and are avoided by default. Et cetera.
*
* The superblock version is locked in when a file is first created.
* It is then possible to get a mix of v1.6 and v1.8 internal
* object versions, when an existing netCDF-4 file is modified by
* a different software version than the one that originally
* created the file. Mixed-object files of this nature are common
* and do not suffer any serious problems.
*
* See netcdf-c github issues #250 and #951 for more details about
* the rationale and evolution of netCDF-4 format compatibility.
*
* See HDF5 documentation for H5Pset_libver_bounds and related RFC's,
* for more details about HDF5 file object versioning.
*
* @author Dave Allured, NOAA/PSL/CIRES @date 2022 January 11
*/
#include "config.h"
#include "hdf5internal.h"
/**
* @internal Function to set HDF5 file access options for backward
* format compatibility. Call this before every call to H5Fcreate
* or H5Fopen.
*
* @param fapl_id Identifier for valid file access property list to
* be used in the next call to H5Fcreate or H5Fopen.
*
* @return ::NC_EHDFERR General failure in HDF5.
*
* @author Dave Allured, NOAA/PSL/CIRES @date 2022 January 11
*/
int
hdf5set_format_compatibility(hid_t fapl_id)
{
#if H5_VERSION_GE(1,10,2)
/* lib versions 1.10.2 and higher */
if (H5Pset_libver_bounds(fapl_id, H5F_LIBVER_V18, H5F_LIBVER_LATEST) < 0)
#else
#if H5_VERSION_GE(1,10,0)
/* lib versions 1.10.0, 1.10.1 */
if (H5Pset_libver_bounds(fapl_id, H5F_LIBVER_EARLIEST, H5F_LIBVER_LATEST) < 0)
#else
/* all HDF5 1.8 lib versions */
if (H5Pset_libver_bounds(fapl_id, H5F_LIBVER_LATEST, H5F_LIBVER_LATEST) < 0)
#endif
#endif
return NC_EHDFERR; /* failure exit */
return NC_NOERR; /* normal exit */
}