HDF5 Software Changes from Release to Release
for HDF5 Releases 1.8.x

This document covers HDF5 releases in the HDF5 Release 1.8.x
series prior to the current release.
For each release, we list new features and changes in
the existing HDF5 feature set,
the HDF5 application programming interface (API), and
the command-line tools distributed with the HDF5 Library.
The intent is to note changes that application developers must be
aware of when maintaining applications or libraries
that must work with progressively newer versions of HDF5.

This section lists interface-level changes and
other user-visible changes in behavior
in the transition from HDF5 Release 1.8.15 to Release 1.8.16.

New and Changed Functions, Classes, Subroutines, Wrappers,
and Macros

In the C Interface (main library)

New HDF5 Plugin Interface (H5PL)

A new HDF5 Plugin Interface (H5PL), enabling
programmatic control of dynamically loaded plugins,
was introduced at HDF5 Release 1.8.15.
This interface was only partially documented at that time,
but more complete documentation is now available:

The flag H5F_ACC_DEBUG was used to provide
extra debugging information for HDF Library developers.
This flag and the underlying functionality have been
removed from the library due to disuse.
The symbol remains defined since it was visible in
H5Fpublic.h, but it has been set to
zero (0) and has no effect anywhere
in the library.

New class H5::ObjCreatPropList
for the object creation property list class

The new class H5::ObjCreatPropList
is derived from H5::PropList and
is a baseclass of H5::DSetCreatPropList.
Additional property list classes will be added to
the library in future releases and some of those will
be derived from H5::ObjCreatPropList.

New wrappers for the C functions
H5P[s/g]et_attr_phase_change and
H5P[s/g]et_attr_creation_order

The following wrappers were added to the class
H5::ObjCreatPropList
for the respective C functions:

C Function

C++ Wrapper

H5Pset_attr_phase_change

H5::ObjCreatPropList::setAttrPhaseChange

H5Pget_attr_phase_change

H5::ObjCreatPropList::getAttrPhaseChange

H5Pset_attr_creation_order

H5::ObjCreatPropList::setAttrCrtOrder

H5Pget_attr_creation_order

H5::ObjCreatPropList::getAttrCrtOrder

Library Configuration

Use of thread-safety with the HDF5 High-level Library
has been declared unsupported in the build tools:
Autotools and CMake.

The global lock used by the thread-safety mechanism
is not raised to the high-level library level,
making it possible that the library state could change
if a context switch were to occur in a high-level library
call. Because of this, the combination of thread-safety
and the high-level library is officially unsupported by
The HDF Group.

Though this combination has never been supported in HDF5,
this was not enforced by the build systems.
With this release, the combination has been explicitly
flagged as unsupported in Autotools and CMake,
the build systems used with HDF5.

The new unsupported declaration will cause an Autotools
configure step to fail if --enable-threadsafe
and --enable-hl are combined unless
additional options are specified (see below).
Since the high-level library is built by default,
this means that these extra configuration options will
need to be used any time --enable-threadsafe
is selected.

To use Autotools to build an application with
--enable-threadsafe,
use one of the following approaches:

Use --disable-hl to disable the
high-level library.
(Recommended)

Use --enable-unsupported to build the
high-level library with the thread-safety feature.

To use CMake to build an application with
HDF5_ENABLE_THREADSAFE=ON,
use one of the following approaches:

Use HDF5_BUILD_HL_LIB=OFF
to disable the high-level library.
(Recommended)

Use HDF5_ALLOW_UNSUPPORTED=ON
to build the high-level library with the
thread-safety feature.

Since this combination is unsupported, applications
using it must be carefully tested for potential
thread-safety failures.

Compatibility Notes and Report

Decoupled shared object version numbers
(soname)

Shared object version numbers, soname,
for HDF5 wrapper libraries,
such as the C++ and Fortran libraries,
have been decoupled from the shared object version
number for the HDF5 library.
In this and future releases, each library’s
soname will be maintained on an
individual basis according to the interface changes
specific to each wrapper library.

Changed shared library interface version
numbers (soname)

For HDF5 Release 1.8.16, the shared object version numbers
have changed as follows.

Library

Release 1.8.15

Release 1.8.16

Reason for Change

HDF5 Library

10.0.1

10.1.0

Added APIs

C++ Library

10.0.1

11.0.0

Changes in existing APIs

High&dash;level C++ Library

10.0.1

11.0.0

Changes in existing APIs

All others

10.0.1

10.0.2

Code changes that did not result in interface changes

Compatibility report for Release 1.8.16 versus
Release 1.8.15

The following interface compatibility report
provides a full list of the changed symbols:

New wrappers for the C functions
H5Pset_libver_bounds and
H5Pget_libver_bounds

The following wrappers have been added to class
H5::FileAccPropList.
The first sets the bounds on versions of the HDF5 Library
format to be used when creating or writing objects;
the second retrieves the current settings:

The following two constructors of the classes
AbstractDs,
IdComponent,
H5Location,
and H5Object
are no longer appropriate after the data member
id was moved from IdComponent
to the sub-classes in previous releases:

The copy constructors have been no-ops and are removed
in this HDF5 Release 1.8.15.
The other constructors will be removed in
HDF5 Release 1.10 and are expected to be removed
from HDF5 Release 1.8.17 if their removal causes
no problems.

A fix for issues encountered upon calling
MPI_Finalize without having closed everything
in an HDF5 file

An attribute destroy callback has been attached
to MPI_COMM_SELF that shuts down the
HDF5 Library when MPI_COMM_SELF
is destroyed, that is, on MPI_Finalize.
This should fix several issues that users see when they
forget to close HDF5 objects before calling
MPI_Finalize().

The following performance optimization has been implemented
in the Parallel HDF5 library:

The algoritm for writing chunk fill values for new datasets
has been optimized to write out all chunk fill values
collectively in a single MPI-IO call. This was previously
done independently by rank 0 (zero) one block at a time.
This optimization should produce a significant performance
improvement when creating chunked datasets in parallel,
most notably when chunk dimensions are relatively small.
This optimization will be evident in use of the following
function:

High-level HDF5 interfaces now ensure that strings are
null-terminated and will not overflow a buffer.

In several high-level functions, the type from the file
was previously re-used as the memory type and
no check is made to ensure that a string was actually
null-terminated.

All high-level functions now
check for NULL pointers;
verify that a received a string is null-terminated; and
verify that the string will not overflow the buffer.
The minimum length of the buffers is now used in
strncmp to avoid overflow.

In the main library C++ Interface

No new C++ methods have been added.

The following changes have been made in the C++ interface:

Changed defaults

Default value of class member id:
The data member id in several classes
that represent HDF5 objects are now initialized
to H5I_INVALID_ID.

Default value of a PropList
member id:
The data member id in class
PropList is now initialized
to H5P_DEFAULT.

In HDF5 Release 1.8.13 and earlier,
the above were initialized to 0 (zero).

Changed file access flags

The flag H5F_ACC_CREAT
has been removed from the C++ interface.

In the main library Fortran Interface

No new Fortran subroutines have been added.

Changed Fortran INTEGER parameter types:

Types of the following Fortran parameter constants
have been changed from INTEGER to
INTEGER(HID_T):

This section lists interface-level changes and
other user-visible changes in behavior
in the transition from HDF5 Release 1.8.12 to Release 1.8.13.

New and Changed Functions, Classes, Subroutines, Wrappers,
and Macros

In the C Interface (main library)

The following new C functions have been added:

To free memory allocated by HDF5 function calls:

H5free_memory
This function should be used to free memory that has
been allocated by HDF5 API calls such as
H5Tget_member_name and
H5Pget_class_name.

The primary value for this call is on Windows systems,
where it is common for application code and the
HDF5 Library to be using different C run-time
libraries (CRT). Using this new call ensures that the
same CRT handles both the allocation and free.

This function can also be useful in any case where
the library uses a different memory manager than the
application, such as when a debug memory manager is
in use or when the HDF5 Library is wrapped for use
in a managed language like Python or Java.

New configuration property for the CORE driver:

H5Pset_core_write_trackingH5Pget_core_write_tracking
With this property, the CORE driver,
H5Pset_fapl_core,
can be configured to track dirty regions in the file and
write out only the changed regions on flush or close
operations.
Additionally, a page aggregation size
can be set that will aggregate small writes into
larger writes. For example,
setting a 1 mebibyte (1 MiB) page aggregation size
will logically partition the the in-memory file
into 1 MiB pages that will be written out
in their entirety if even a single byte is dirtied.

The following C functions have been modified:

H5Rget_name
If the name parameter is passed as
NULL, then the size
parameter is ignored and the function returns the size
of the buffer required to read the name
(not including the NULL terminator).

h5fget_file_image_f
(Added in Release 1.8.11, but not documented at that time.)

The following Fortran subroutine has been changed:

h5pset_chunk_cache_f
The values of the constants
H5D_CHUNK_CACHE_NSLOTS_DFLT_F and
H5D_CHUNK_CACHE_NBYTES_DFLT_F
have been changed to
INTEGER(KIND=size_t).

Other New Features

Parallel I/O support:

Parallel I/O support has been enhanced to allow collective I/O
on point selections.

Thread safety (Windows only)

The thread-safe HDF5 library no longer leaks thread-local
storage resources on Windows with Win32 threads.
This cleanup can only be performed when the library
is built as a shared library, so a
thread-safe HDF5 static library with Win32 threads
is no longer supported.

The class H5::H5Location has been added
as a base class of H5File and
H5Object. It represents the location
concept in the C library, where an identifier of an
HDF5 object or an HDF5 file being passed in as a
loc_id parameter.

The following member functions and their
overloaded versions have been moved from
various subclasses into the base class
H5Location:

New Command-line Tool Options and Option Parameters

h5dump has a new option for identifying
objects by a full or partial path:
-NP --any-path=P

The h5dump attributes-only option,
-A or --only-attr,
now accepts an optional parameter value
of 0 (zero):
-A 0 --only-attr=0
Specifying this value has the effect of reversing
the role of the option to display everything
except attributes.

New and Changed Functions and Subroutines

This function writes a data chunk directly into a file,
bypassing hyperslab selection, data conversion, and
the filter pipeline.
The user must be careful with the function and
clearly understand the I/O process of the library.
See “Direct
Chunk Write” for additional information.

These functions scatter data to and gather data from
a selection within a memory buffer.

The following new Fortran subroutines have been added:

Fortran90 subroutines:

h5odecr_refcount_f

h5oexists_by_name_f

h5oget_comment_f

h5oget_comment_by_name_f

h5oincr_refcount_f

h5oopen_by_idx_f

h5oset_comment_f

h5oset_comment_by_name_f

h5oclose_f was introduced in
HDF5 Release 1.8.8 but remained undocumented
until this release.

Fortran2003 subroutines:

h5oget_info_f

h5oget_info_by_idx_f

h5ovisit_by_name_f

New Feature: Dynamically Loaded Filters

HDF5 now detects and dynamically loads external filters,
reducing the need for an application to register custom filters
or for a developer building on HDF5 to compile a custom filter
into a customized HDF5 distribution.

This section lists interface-level changes and
other user-visible changes in behavior
in the transition from HDF5 Release 1.8.9 to Release 1.8.10.

New and Changed Functions and Subroutines

The following new C function has been added:

H5Pget_mpio_no_collective_cause

The following new Fortran subroutine has been added:

h5pget_mpio_actual_io_mode_f

The syntax of the following high-level C function has changed:

H5TBAget_fill
This function’s return type has been changed to
h5tri_t.
A return value of
1 indicates that a fill value is present,
0 indicates that no fill value is present,
and a negative value indicates an error.
(The former return type was herr_t.)

Note that H5TBAget_fill
and a companion function H5TBAget_title,
both in the HDF5 Table (H5TB) high-level API,
are undocumented.
These functions will be added to the
HDF5 Reference Manual
shortly after HDF5 Release 1.8.10.

New and Changed Functions

The new file image operations feature consists of the
following functions and their associated callbacks,
struct, and ENUM.
This feature enables an application to load a file
into memory (as a file image) and to operate on that
file image without the overhead of disk I/O.
This feature provides the following functions:

The files parameter now accommodates
wildcards. With this change, h5dump
command-line options can be applied across multiple
files without listing the files individually.

h5dump output has been updated for
this release to improve compliance with the
HDF5 DDL specification
and to improve readablilty.
This output is now fully compliant with the
HDF5 DDL specification, but these changes may affect
some user scripts:

Whitespace has been modified.

Display errors, such as misplaced brackets,
have been fixed.

When printing superblock content,
user block content is now properly displayed within
the superblock.

Terminology:
If the Fortran compiler in use is Fortran 2003 compliant
and the installed HDF5 Library was configured using both the
--enable-fortran and
--enable-fortran2003 flags,
the resulting HDF5 Fortran Library is referred to below as a
Fortran 2003 environment.
Without either of the Fortran 2003 compliant compiler
or the --enable-fortran2003 flag, the resulting
HDF5 Fortran Library is referred to below as a
Fortran 90 environment.

New Fortran 2003-only subroutines
New subroutines available only in Fortran 2003 environments:

Subroutines with Fortran 90 versions and
extended features in Fortran 2003 environments
Subroutines in this section have extended support in
Fortran 2003 environments, but are new or unchanged in
Fortran 90 environments.

All existing Fortran 90 subroutines, including those
not mentioned below, are available in both Fortran 90
and Fortran 2003 environments.

Subroutines with support for the derived type
C_PTR in Fortran 2003 environments:

C Functions with Changed Capability

Driver Changes on Windows Systems

HDF5’s
Windows
driver
has been modified in this release to be a wrapper of the
POSIX-compliant
SEC2 driver.
This change should be transparent to all user applications.

New default driver:

As of this release, the default driver
on Windows systems is changed to SEC2;
it had previously been the Windows driver.

If you wish to use the Windows driver in an application,
it remains fully available.
In such cases, the driver must be set explicitly with a
H5Pset_fapl_windows call.

Command-line Utilities with Changed Behavior

h5jam
now checks the file that is to be inserted into the user block
and does not allow the insertion if it is an HDF5 file.
This is necessary because an HDF5 file in the user block
will make the original HDF5 portion of the file inaccessable.

h5diff
with the --delta option reports two NaN
values as equal regardless of the type of NaN
(as described in the reference manual entry).

Configure and Build Changes

configure now uses the same flags and symbols
in its tests as are used to build the library.

To build HDF5 with the Fortran 2003 interfaces requires the use of
two configure options:
--enable-fortran
--enable-fortran2003
Note that building the Fortran 2003 interfaces requires
a Fortran 2003-capable compiler and that
--enable-fortran2003 cannot be used alone.

The --enable-h5dump-packed-bits configure option
has been removed. The code that this option enabled is now
always compiled into h5dump.

When building on Linux systems, the HDF5 Library now links
with the bsd_compat library.

Parallel Library and Configuration Changes

The parallel HDF5 library now always compiles code to
take advantage of MPI functionalities that allow for the use
of complex derived datatypes during IO and that allow for
collective IO when one or more processes do not contribute
to the operation.

This was previously conditionally compiled into the library
and controlled by configure via the
hdf5_cv_mpi_special_collective_io_works and
hdf5_cv_mpi_complex_derived_datatype_works
cache values.
These values were preset in the config/*
files based on the compiler and/or system or could be set
on the configure line.
Support for these cache values has been removed and
they no longer have an effect on the compilation of the use
of these MPI functionalities.

C Functions with Changed Capability

HDF5 now allows the size of any dataspace dimension to be
0 (zero). This was previously allowed
only if the maximum size of the dimension was unlimited.
Though their signatures have not changed, the range of valid
parameter values is affected for the following functions:

Note that no data can be written to a dataset in which
the size of any dimension is set to zero.

In the logging file driver,
implementation of the following flags has been completed:
H5FD_LOG_TIME_OPEN,
H5FD_LOG_TIME_READ,
H5FD_LOG_TIME_WRITE, and
H5FD_LOG_TIME_SEEK
Two new flags have been added:
H5FD_LOG_NUM_TRUNCATE and
H5FD_LOG_TIME_STAT.

HDF5 has long blocked creating a dataset or attribute
with such a datatype.

Fortran Subroutines with Changed Capability

Several
h5ltmake_dataset*_f
and
h5ltread_dataset*_f
subroutines have been modified to allow them to
create or read arrays of up to seven dimensions.
They had previously been limited to three dimensions.

Command-line Utility with Changed Option Name

Command-line Utilities with Changed Behavior

Attribute comparison with
h5diff
has been corrected to compare all attributes with common names
when comparing objects.
Previously, h5diff compared attributes correctly
only when two objects had the same number of attributes
and all attribute names were identical; if there was either a
value or name difference between two attributes,
subsequent attributes were not compared.

Configure and Build Changes

Configure now generates Makefiles that build in
silent make mode by default.
In this mode, compile and link lines are significantly
simplified for clarity. You can opt out of this default
with either of the following approaches:

Use the --disable-silent-rules flag at
configure time to override the default and view actual
compile and link lines during the build.

Use the make command with the V=1
option to run a verbose make.

The new configure option --enable-unsupported
can be used to stop configure from preventing the
use of unsupported configure option combinations.
For example, use of this option enables building HDF5 with the
unsupported and untested configurations of
C++ in a parallel environment or
Fortran with a threadsafe library.

WARNING:
Use
--enable-unsupported
at your own risk!
This option may result in a library that does not compile
or does not run as expected.

Parallel HDF5

mpicc and mpif90 are now the default
C and Fortran compilers on Linux systems when
--enable-parallel is specified but no
$CC or $FC is defined.

Command-line Utilities with New Options

Command-line Utilities with Changed Behavior

h5diff
now compares member objects and groups recursively when
two files or groups are specified to be compared.

h5ls
now displays object and attribute names exactly as stored in
the file rather than interpreting them for output.
For example, if an attribute is named \ttemp
in the file, h5ls will output that name as
\ttemp rather than converting the leading
\t to a tab.

Compiler Script Arguments and Environment Variables

h5cc,
h5fc,
h5c++,
h5pcc,
and
h5pfc
arguments have been expanded
to enable the user to add compiler and linker flags
that will take precedence over the flags from the HDF5 build.

The arguments CPPFLAGS, CFLAGS,
LDFLAGS, and LIBS have been
duplicated with the prefix H5BLD_
to put the flags and paths from the HDF5 build in the
correct places and to allow the script user to add entries in
CPPFLAGS, CFLAGS,
LDFLAGS, and LIBS that will take
precedence over those from the HDF5 build.
Changes to these entries can be made
persistent by editing CFLAGSBASE,
CPPFLAGSBASE, LDFLAGSBASE, and
LIBSBASE near the top of the script.
If the change is to be temporary, the user can set
HDF5_CFLAGS, HDF5_CPPFLAGS,
HDF5_LDFLAGS, or HDF5_LIBS
in the environment.

Command-line Utility with New Options

Fortran Subroutines with Changed Interface

The link type parameter values associated with the
following Fortran subroutines have changed in this release:

h5lget_info_f

h5lget_info_by_idx_f

Valid values for the parameter link_type
have changed to the following:
H5L_TYPE_HARD_FH5L_TYPE_SOFT_FH5L_TYPE_EXTERNAL_FH5L_TYPE_ERROR_F
These values previously began with the string
'H5L_LINK_'.

CMake

This release includes an adaptation enabling HDF5 builds
with CMake.
This early-stage adaptation is distributed to provide an
opportunity for early access and experimentation;
the CMake-related files should not be viewed as final
and may change before the next release.

While the initial development effort has been focussed on
Microsoft Windows platforms, the HDF5 Library has been
successfully built with CMake on Linux and Mac OS X.

See the file CMake.txt in the distributed
HDF5 source code (hdf5/release_docs/CMake.txt)
for details.

This section lists interface-level changes and
other user-visible changes in behavior
in the transition from HDF5 Release 1.8.3 to Release 1.8.4.

Embedded HDF5 Library Settings Information

Library settings are now embedded in an HDF5 executable
so that an “orphaned” executable can be queried
(via the Unix strings command, for example) to display the
library settings used to build it.
The embedded settings information is the same as that
normally found in the libhdf5.settings file.

This capability may be disabled with the use of the
--disable-embedded-libinfo flag during configure.

New Fortran Subroutine and Constant

The following Fortran subroutine is new in this release:
h5oopen_by_addr_f

The following Fortran constant, corresponding to
the C constant H5T_ORDER_NONE, has been added
in this release:
H5T_ORDER_NONE_F

New C++ Member Functions

New C++ member functions are provided to
determine a dataset’s or attribute’s
data size in memory:
size_t DataSet::getInMemDataSize() const
size_t Attribute::getInMemDataSize() const
The size in each case is in bytes.

Function with Changed Interface or Behavior

H5check_version now displays
embedded library information (see above)
if a version mismatch is detected.

The function has also been changed to suppress the
warning message entirely if
$HDF5_DISABLE_VERSION_CHECK is set to
2 or higher.

Fortran Subroutines with Changed Syntax

The following Fortran subroutines have changed syntax
in this release:

h5lget_info_f

The type of the parameter address has changed
from INTEGER to INTEGER(HADDR_T).
(This note added on 13 January 2010.)

Tools with Changed Interface or Behavior

With this option, h5diff returns a difference
if and only if the difference between two data values
exceeds the system value for epsilon
(that is, if |a-b| > epsilon).

The tool’s default behavior has also changed;
without this option, the tool now checks for strict equality.
Prior default behavior was to use an epsilon internally
defined in HDF5.

This option has no short form.

h5dump
has one new option and the behavior of another set of
options has changed:
-R or --region

With this option, h5dump prints
the data pointed to by a region reference.
Without this option, h5dump prints
only the reference.

Usage of the subsetting parameters has changed.
All of START,
STRIDE, COUNT,
and BLOCK now have default values.
If those defaults are satisfactory,
h5dump no longer requires that all four
be specifiespecified when subsetting a dataset.

Changed Library Configuration

The following configuration flag is new with this release:
--disable-embedded-libinfo
This flag disables the embedding of HDF5 Library settings
in an HDF5 executable.

Function with Changed Behavior

The HDF5 Library now dynamically creates separate
factory free lists to manage blocks of
a fixed size; these blocks were previously
managed within the blockfree lists.
Factory free lists use the same settings as specified
in H5set_free_list_limits
for block free lists.

While the API has not changed, users may see both
a performance boost and increased memory usage.

Tools with Changed Interface or Behavior

The default behavior of h5diff is now
to detect and compare NaNs.
Use the -N or --nan
option (below) to turn this behavior off and
avoid the performance penalty that NaN detection
and comparison entalis.
(NaN detection and comparison became the default in
in HDF5 Release 1.6.8.)

Deprecated Functions

The original role of these functions is now
part of the core HDF5 Library functionality.

Changed File Installation

The file libhdf5_fortran.settings is no longer
installed with the HDF5 Library;
the original content of that file is now included in
libhdf5.settings.

Changed Library Configuration

It is no longer necessary to manually set an SZIP library path in
LD_LIBRARY_PATH
when building HDF5 with shared SZIP libraries;
configure will determine the correct path
from the --with-szlib flag,
prepending it to and exporting LD_LIBRARY_PATH.

Note that if an SZIP library path is set in a user-supplied
LD_LIBRARY_PATH, in an existing script, for example,
that does not necessarily need to be changed;
configure will prepend the SZIP library path
extracted from --with-szlib
to the user-supplied LD_LIBRARY_PATH.

Functions and Tools with Changed Syntax

C functions with changed syntax:

There are no C functions
with changed syntax in Release 1.8.1.

Fortran subroutines with changed syntax:

In the following Fortran subroutines, spos is a
new parameter indicating the position of the sign bit:
h5tset_fields_f(type_id,
spos,
epos, esize, mpos, msize, hdferr)h5tget_fields_f(type_id,
spos,
epos, esize, mpos, msize, hdferr)

Changed C++ wrappers:

The class AbstractDS was moved out of
H5Object.

The class Attribute now multiply inherits from
IdComponent and AbstractDs;
the class DataSet now multiply inherits from
H5Object and AbstractDs.

In addition, data member IdComponent::id
was moved into subclasses:
Attribute, DataSet,
DataSpace, DataType, H5File,
Group, and PropList.

The command-line syntax of h5repack was changed in
Release 1.8.0 to the following:
h5repack [OPTIONS]
in_fileout_file

Since this would be imcompatible with existing user scripts,
the original syntax has be re-enabled in this release:
h5repack -iin_file-oout_file
[OPTIONS]

h5repack now understands either syntax.

An h5repack
option to set the minimum number of links in indexed format
was introduced in Release 1.8.0 as
'-dmin_indexed_links'
or '--indexed=min_indexed_links'.
In Release 1.8.1, the '-i' form has been changed
to '-d' as follows:
-dmin_indexed_linksor
--indexed=min_indexed_links

The command-line syntax of h5diff was changed in
Release 1.8.0 to the following:
h5diff [OPTIONS]
file1file2
[object1 [object2 ] ]

Removed Patch Requirement

HDF5 Release 1.8.0 is a major release with several new features
and a variety of bugfixes, optimizations, and
portability enhancements.

See the document
“What’s New in HDF5 1.8.0”
for a high-level overview of the new functionality in this release.
The following pages assume a familiarity with that overview.

This section provides details of the API-level changes that have been made
in the transition to HDF5 Release 1.8.0 from the Release 1.6.x series.

API Compatibility Macros with Associated Renamed and New Functions

Release 1.8.0 introduces API compatibility macros
designed to facilitate application migration.
These macros are intended to facilitate developer management
of a clean, step-by-step migration from an older HDF5 Library
to the new release;
they can also be used to enable older applications to use the
new library without requiring that the application be rewritten.
See API Compatibility
Macros in HDF5 for a full description.

Macros are identified in reference manual function indexes
by an italic typeface.

The new macros and the new and old functions to which they
may be mapped are as follows:

H5Acreate

H5Acreate1H5Acreate2

Renamed from H5Acreate
New

H5Aiterate

H5Aiterate1H5Aiterate2

Renamed from H5Aiterate
New

H5Dcreate

H5Dcreate1H5Dcreate2

Renamed from H5Dcreate
New

H5Dopen

H5Dopen1H5Dopen2

Renamed from H5Dopen
New

H5Eclear

H5Eclear1H5Eclear2

Renamed from H5Eclear
New

H5Eget_auto

H5Eget_auto1H5Eget_auto2

Renamed from H5Eget_auto
New

H5Eprint

H5Eprint1H5Eprint2

Renamed from H5Eprint
New

H5Epush

H5Epush1H5Epush2

Renamed from H5Epush
New

H5Eset_auto

H5Eset_auto1H5Eset_auto2

Renamed from H5Eset_auto
New

H5Ewalk

H5Ewalk1H5Ewalk2

Renamed from H5Ewalk
New

H5Gcreate

H5Gcreate1H5Gcreate2

Renamed from H5Gcreate
New

H5Gopen

H5Gopen1H5Gopen2

Renamed from H5Gopen
New

H5Pget_filter

H5Pget_filter1H5Pget_filter2

Renamed from H5Pget_filter
New

H5Pget_filter_by_id

H5Pget_filter_by_id1H5Pget_filter_by_id2

Renamed from H5Pget_filter_by_id
New

H5Pinsert

H5Pinsert1H5Pinsert2

Renamed from H5Pinsert
New

H5Pregister

H5Pregister1H5Pregister2

Renamed from H5Pregister
New

H5Rget_obj_type

H5Rget_obj_type1H5Rget_obj_type2

Renamed from H5Rget_obj_type
New

H5Tarray_create

H5Tarray_create1H5Tarray_create2

Renamed from H5Tarray_create
New

H5Tcommit

H5Tcommit1H5Tcommit2

Renamed from H5Tcommit
New

H5Tget_array_dims

H5Tget_array_dims1H5Tget_array_dims2

Renamed from H5Tget_array_dims
New

H5Topen

H5Topen1H5Topen2

Renamed from H5Topen
New

(H5Dcreate and H5Dopen added to
the above list in November 2010, prior to Release 1.8.6.)

New Functions and Tools

C functions:

The following C functions are new for Release 1.8.0 and,
unless otherwise noted, are documented in the
HDF5 Reference
Manual.

Several functions, subroutines, and wrappers
are deprecated in this HDF5 release
and may eventually be removed from the HDF5 distribution
and from the HDF5 Reference Manual.
A Release 1.6.x compatibility mode is provided
enabling these and other Release 1.6.x compatibility
features, but is available only if the HDF5 Library is
configured with the default settings or with the flag
--with-default-api-version=v16.
Release 1.8.0 also provides macros that can be mapped
selectively to 1.6.x and 1.8.0 function versions
according to the needs of a user application.
The backward compatibility mode is enabled in the
Release 1.8.0 binaries distributed by NCSA.
See API Compatibility
Macros in HDF5 for full details.

Deprecated functions are marked in the function index
at the beginning of each API section in the
HDF5 Reference Manual.

Virtual File Driver Removed

The stream virtual file driver (H5FD_STREAM)
have been removed in this release.
This affects the functions H5Pset_fapl_stream
and H5Pget_fapl_stream and
the constant H5FD_STREAM.

This virtual file driver will remain available at
http://hdf5-addons.origo.ethz.ch/.
Note that as of this writing, this transition is still
in progress; the necessary integration tools may not be
available when HDF5 Release 1.8.0 first comes out.

Functions with New or Changed Symbols or Fixed Values

Symbols and preset values associated with the following
functions, subroutines or wrappers have changed as noted.

C functions:

H5Tregister

Null is no longer a valid value for the
parameter func.

H5Pget_filter_by_id

H5Pmodify_filter

H5Premove_filter

H5Pset_filter

H5Zfilter_avail

H5Zget_filter_info

Two new filter identifiers are available for the
filter parameter:
H5Z_FILTER_NBITH5Z_FILTER_SCALEOFFSET

H5Pget_filter

Two new filter identifiers are available as the return value:
H5Z_FILTER_NBITH5Z_FILTER_SCALEOFFSET

Fortran90 subroutines:

h5pget_filter_f

h5pget_filter_by_id_f

h5pmodify_filter_f

h5premove_filter_f

h5pset_filter_f

h5zfilter_avail_f

h5zget_filter_info_f

Two new filter identifiers are available for the
filter or filter_id parameters:
H5Z_FILTER_NBIT_FH5Z_FILTER_SCALEOFFSET_F

Functions with Changed Syntax

Function syntax changes in this release are handled
through the mechanism described in
API Compatibility
Macros in HDF5.

Exceptions:

The function H5Eget_minor is not governed by the
above-mentioned macros and its return type has changed:

H5Eget_minor

char *H5Eget_minor
(H5E_minor_tn)

See entry.
An application calling H5Eget_minor from an
HDF5 Library of Release 1.8.0 or later will have to free the
memory associated with the return value to prevent a memory leak.
(This note added at Release 1.8.4, November 2009.)

In the function H5Dextend,
the size parameter signature was changed.

H5Dextend

herr_t *H5Dextend(
hid_t dataset_id,
const hsize_t size[]
)

See entry
for current information; see the
Release 1.6 entry
for the old signature.
The new function signature is generally considered equivalent
to the old signature, but some compilers require an exact match.
(This note added in February 2010, following Release 1.8.4.)

Renamed Functions

The following C functions have been renamed.
The original function names remain available under
certain circumstances;
see API Compatibility
Macros in HDF5 for full details.

Original name

New name

H5Acreate

H5Acreate1

H5Aiterate

H5Aiterate1

H5Eclear

H5Eclear1

H5Eget_auto

H5Eget_auto1

H5Eprint

H5Eprint1

H5Epush

H5Epush1

H5Eset_auto

H5Eset_auto1

H5Ewalk

H5Ewalk1

H5Gcreate

H5Gcreate1

H5Gopen

H5Gopen1

H5Pget_filter

H5Pget_filter1

H5Pget_filter_by_id

H5Pget_filter_by_id1

H5Pinsert

H5Pinsert1

H5Pregister

H5Pregister1

H5Rget_obj_type

H5Rget_obj_type1

H5Tarray_create

H5Tarray_create1

H5Tcommit

H5Tcommit1

H5Tget_array_ndims

H5Tget_array_ndims1

H5Topen

H5Topen1

Changed Library Structures

The following library structures have changed as follows:

C API:

H5FD_t

In this struct, the field fileno[2]
has changed to fileno.
The struct is otherwise unchanged.

H5Z_class_t

This struct contains three new fields:
versionencoder_presentdecoder_present
The struct is now defined as follows:

Changed ENUMs

The following enumerated datatypes used by the library
are discontinued in this release:

H5E_major_t
— Major error numbers

H5E_minor_t
— Minor error numbers

HDF5 error codes have changed from the ENUM
format used in earlier releases to an identifier format.
As ENUMs, error codes were constants
defined at compile time; as identifiers, error codes
are defined at runtime, in the same manner as HDF5
object identifiers (file, dataset, group, etc.).

Under normal circumstances, this change should be transparent
to user applications.

The following enumerated datatypes used by the library
have changed in the C and Fortran APIs as follows:

H5G_obj_t
— Object types

This ENUM has reordered as follows:
H5G_GROUPH5G_DATASETH5G_TYPEH5G_LINK

H5I_type_t
— Identifier types

The following symbols have been added
to this ENUM:
H5I_UNINTH5I_ERROR_CLASSH5I_ERROR_MSGH5I_ERROR_STACK

Another new symbol
H5I_NTYPES

replaces the old symbol
H5I_NGROUPS
While visible in the public API, H5I_NTYPES
functions as a limit value for the HDF5 Library and
is not generally used at the application level.
The same was true of H5I_NGROUPS.

H5S_class_t
— Dataspace type identifiers

The following symbol has been added:
H5S_NULL

H5T_cset_t
— Character set encoding identifiers

The following symbol has been added:
H5T_CSET_UTF8

H5Z_filter_t
— Filters identifiers

The following symbols have been added:
H5Z_FILTER_NBITH5Z_FILTER_SCALEOFFSET

New Datatypes

The following OpenVMS-specific floating point datatypes
are new with this release: