From 14fd0db7239c82353490082ee88c2a88f2f7f83c Mon Sep 17 00:00:00 2001 From: bmribler <39579120+bmribler@users.noreply.github.com> Date: Thu, 14 Mar 2024 17:30:03 -0400 Subject: [PATCH] Add files for Release Specific Information page This is just to get the files in place. The contents are not formatted yet, hence, very untidy. --- .../Migrating+from+HDF5+1.10+to+HDF5+1.14.md | 78 + .../Migrating+from+HDF5+1.12+to+HDF5+1.14.md | 38 + .../Migrating+from+HDF5+1.8+to+HDF5+1.14.md | 63 + .../release_specifics/api_comp_macros.md | 403 ++ .../hdf5-docs/release_specifics/hdf5_1_10.md | 19 + .../hdf5-docs/release_specifics/hdf5_1_12.md | 37 + .../hdf5-docs/release_specifics/hdf5_1_8.md | 9 + .../release_specifics/new_features_1_10.md | 183 + .../release_specifics/new_features_1_12.md | 37 + .../release_specific_info.md | 22 + .../release_specifics/sw_changes_1.10.md | 1120 +++++ .../release_specifics/sw_changes_1.12.md | 224 + .../release_specifics/sw_changes_1.8.md | 4053 +++++++++++++++++ 13 files changed, 6286 insertions(+) create mode 100644 documentation/hdf5-docs/release_specifics/Migrating+from+HDF5+1.10+to+HDF5+1.14.md create mode 100644 documentation/hdf5-docs/release_specifics/Migrating+from+HDF5+1.12+to+HDF5+1.14.md create mode 100644 documentation/hdf5-docs/release_specifics/Migrating+from+HDF5+1.8+to+HDF5+1.14.md create mode 100644 documentation/hdf5-docs/release_specifics/api_comp_macros.md create mode 100644 documentation/hdf5-docs/release_specifics/hdf5_1_10.md create mode 100644 documentation/hdf5-docs/release_specifics/hdf5_1_12.md create mode 100644 documentation/hdf5-docs/release_specifics/hdf5_1_8.md create mode 100644 documentation/hdf5-docs/release_specifics/new_features_1_10.md create mode 100644 documentation/hdf5-docs/release_specifics/new_features_1_12.md create mode 100644 documentation/hdf5-docs/release_specifics/release_specific_info.md create mode 100644 documentation/hdf5-docs/release_specifics/sw_changes_1.10.md create mode 100644 documentation/hdf5-docs/release_specifics/sw_changes_1.12.md create mode 100644 documentation/hdf5-docs/release_specifics/sw_changes_1.8.md diff --git a/documentation/hdf5-docs/release_specifics/Migrating+from+HDF5+1.10+to+HDF5+1.14.md b/documentation/hdf5-docs/release_specifics/Migrating+from+HDF5+1.10+to+HDF5+1.14.md new file mode 100644 index 00000000..60b16e0f --- /dev/null +++ b/documentation/hdf5-docs/release_specifics/Migrating+from+HDF5+1.10+to+HDF5+1.14.md @@ -0,0 +1,78 @@ +--- +title: Migrating from HDF5 1.10 to HDF5 1.12 +redirect_from: + - /display/HDF5/Migrating+from+HDF5+1.10+to+HDF5+1.12.html +--- + +# Migrating from HDF5 1.10 to HDF5 1.12 + +Also see the video presentation: Moving Applications from 1.10 to 1.12 + +There were many existing functions that were modified in 1.12. Applications created with 1.10 or earlier that use these functions will encounter errors when compiled with 1.12. This page describes how to compile 1.10 and earlier applications with 1.12 without modifying an application, and provides details on the functions that changed for users who wish to update their applications: + +Compiling 1.10 and earlier applications with 1.12 +Functions that changed +For further information, see: + +New Features in 1.12 +Software Changes from release to release +API Compatibility Macros in HDF5 +Compiling 1.10 and earlier applications with 1.12 +Applications that were created with earlier HDF5 releases may not compile with 1.12 by default. The API Compatibility Macros in HDF5 allow users to work around this issue. Users can specify a compatibility macro mapping for the version of HDF5 that an application was built with. For example, a 1.10 application can be built with 1.12 using either an application or library mapping as follows: + +To compile an application built with a version of HDF5 that includes deprecated symbols (the default), make sure to pass -DH5_USE_110_API to the compiler. For example: + +Autotools: h5cc -DH5_USE_110_API (C) + +CMake: cmake -DCMAKE_C_FLAGS="-DH5_USE_110_API" (and likewise for other CMAKE__FLAGS) + +To build an HDF5 library with the 1.10 APIs specify --with-default-api-version=v110 (Autotools) or -DDEFAULT_API_VERSION:STRING=v110 (CMake). + +Autotools: +./configure --with-default-api-version=v110 + +CMake: +If using the source code packaged with CMake configuration files (CMake-hdf5-1.12.0*), edit HDF5options.cmake, and add this line: + +set(ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DDEFAULT_API_VERSION:STRING=v110") + +View the libhdf5.settings file to verify that the library was built with the 1.10 APIs: + +Default API mapping: v110 (under Features:) + +However, users will not be able to take advantage of some of the new features in 1.12 if using these compatibility mappings. + +Functions that changed +Functions were modified in HDF5 version 1.12 to support a token type used in the Virtual Object Layer (VOL) and to enable 64-bit selection encodings. These changes are described below. + +The updated versions of the functions have a number (for eg '2' or '3') at the end of the original function name. The original versions of these functions were retained and renamed to have an earlier number (for eg '1') at the end of the original function name. A macro was created with the name of the original function. Please read API Compatibility Macros in HDF5 for more details on how the function names changed in version 1.12. + +Token Type +In HDF5 1.12, a token type, H5O_token_t, replaced the address type, haddr_t, for representing locations in an HDF5 file. This change better supports the Virtual Object Layer (VOL), as the concept of an "address" does not make sense for many connectors. A token type is a more generic type that can function as both a connector and address location. + +This change affected the following functions: + + + + + +H5L_GET_INFO H5L_GET_INFO1 H5L_GET_INFO2 +H5L_GET_INFO_BY_IDX H5L_GET_INFO_BY_IDX1 H5L_GET_INFO_BY_IDX2 +H5L_ITERATE H5L_ITERATE1 H5L_ITERATE2 +H5L_ITERATE_BY_NAME H5L_ITERATE_BY_NAME1 H5L_ITERATE_BY_NAME2 +H5L_VISIT H5L_VISIT1 H5L_VISIT2 +H5L_VISIT_BY_NAME H5L_VISIT_BY_NAME1 H5L_VISIT_BY_NAME2 +H5O_GET_INFO H5O_GET_INFO1 H5O_GET_INFO3 +H5O_GET_INFO_BY_IDX H5O_GET_INFO_BY_IDX1 H5O_GET_INFO_BY_IDX3 +H5O_GET_INFO_BY_NAME H5O_GET_INFO_BY_NAME1 H5O_GET_INFO_BY_NAME3 +H5O_VISIT H5O_VISIT1 H5O_VISIT3 +H5O_VISIT_BY_NAME +H5O_VISIT_BY_NAME1 + +H5O_VISIT_BY_NAME3 +Encoding Properties +These functions were introduced in HDF5 version 1.12 as part of the H5Sencode format change to enable 64-bit selection encodings and a dataspace selection that is tied to a file. See the H5Sencode / H5Sdecode format change RFC for details. + + +H5P_ENCODE H5P_ENCODE1 H5P_ENCODE2 +H5S_ENCODE H5S_ENCODE1 H5S_ENCODE2 diff --git a/documentation/hdf5-docs/release_specifics/Migrating+from+HDF5+1.12+to+HDF5+1.14.md b/documentation/hdf5-docs/release_specifics/Migrating+from+HDF5+1.12+to+HDF5+1.14.md new file mode 100644 index 00000000..e21ea614 --- /dev/null +++ b/documentation/hdf5-docs/release_specifics/Migrating+from+HDF5+1.12+to+HDF5+1.14.md @@ -0,0 +1,38 @@ +--- +title: Migrating from HDF5 1.12 to HDF5 1.14 +redirect_from: + - /display/HDF5/Migrating+from+HDF5+1.12+to+HDF5+1.14.html +--- + +# Migrating from HDF5 1.12 to HDF5 1.14 + +## API Changes +There are new API calls that require API Compatibility Macros in HDF5 1.14.0. There are, however, two API calls which have had their signature change. + +### `H5Iregister_type()` / `H5I_free_t` +The signature of `H5Iregister_type()` did not change, but the `H5I_free_t` callback it accepts did have its signature change to add an asynchronous request parameter. There is no API compatibility macro to paper over this change. The request parameter can be ignored in the callback if you are not concerned with asynchronous operations and future IDs. A description of how the request parameter should be used will be found in the (soon to be released) HDF5 Asynchronous Programming Guide. + +  **Old:** + +  `typedef herr_t (*H5I_free_t)(void *obj);` + +  **New:** + +  `typedef herr_t (*H5I_free_t)(void *obj, void **request);` + +### `H5VLquery_optional()` +The way optional operations are handled in the virtual object layer (VOL) changed significantly in HDF5 1.14.0. To better support this, the `H5VLquery_optional()` API call now takes an output flags parameter instead of a Boolean. Since the entire 1.12 VOL API has been deprecated, no API compatibility macro exists for this API call. + +  **Old:** + +  `herr_t H5VLquery_optional(hid_t obj_id, H5VL_subclass_t subcls, int opt_type, hbool_t *supported);` + +  **New:** + +  `herr_t H5VLquery_optional(hid_t obj_id, H5VL_subclass_t subcls, int opt_type, uint64_t *flags);` + +## Virtual File Layer (VFL) Changes +The virtual file layer has changed in HDF5 1.14.0. Existing virtual file drivers (VFDs) will have to be updated to work with this version of the library. + +## Virtual Object Layer (VOL) Changes +The virtual object layer has changed significantly in HDF5 1.14.0 and the 1.12 VOL API is now considered deprecated and unsupported. Existing virtual object layer connectors shoul be updated to work with this version of the library. diff --git a/documentation/hdf5-docs/release_specifics/Migrating+from+HDF5+1.8+to+HDF5+1.14.md b/documentation/hdf5-docs/release_specifics/Migrating+from+HDF5+1.8+to+HDF5+1.14.md new file mode 100644 index 00000000..05454c3c --- /dev/null +++ b/documentation/hdf5-docs/release_specifics/Migrating+from+HDF5+1.8+to+HDF5+1.14.md @@ -0,0 +1,63 @@ +--- +title: Migrating from HDF5 1.8 to HDF5 1.10 +redirect_from: + - /display/HDF5/Migrating+from+HDF5+1.8+to+HDF5+1.10.html +--- + +# Migrating from HDF5 1.8 to HDF5 1.10 + +The HDF Group will drop support for HDF5 1.8.* releases in the summer of 2020. We strongly recommend that our users start migrating their applications as soon as possible and we ask that any problems that are encountered be reported to The HDF Group. Problems can be reported by sending email to help@hdfgroup.org, submitting a request to the Service Desk Portal, or posting to the HDF-FORUM. + +Please follow these steps for moving your HDF5 application to HDF5 1.10: + +Make sure the latest (1.1.0.5+) version of HDF5 1.10 is installed on your system. You can download the HDF5 1.10 release source code from The HDF Group Download Portal, and pre-built binaries can be obtained from the Download HDF5 page on The HDF Group web site. Follow the installation instructions. + +If on Unix, you can recompile and relink your application with HDF5 1.10, by using the h5cc script with any compiler flags needed for your application. The h5cc script can be found under the bin sub-directory of the HDF5 1.10 installation point. In cases where your software package has a more complex build system and dependencies, just make sure you point to the new HDF5 1.10.* library when rebuilding your software. + +If your application or software package has any regression test suite, run it and make sure that all tests pass. + +Contact us if you find any problems. + +If you have concerns about the files created by the rebuilt application (or software package), you may wish to consider several verification steps to assure that the files can be read by applications built with HDF5 1.8 releases. + +Use the tools you regularly work with to open, browse, and modify the files created by the rebuilt application (for example, HDFView, MATLAB, IDL, etc.). + +If you have an HDF5 1.8.* installation on your system, use h5dump from that installation to read files created by the rebuilt application. If you encounter any errors, rerun h5dump with the "--enable-error-stack” flag and report the issue. + +If you have files created by your application that were built with HDF5 1.8, use h5diff from the HDF5 1.8 installation to compare with the files created by the rebuilt application. + +If you want to learn more, please see the frequently asked questions (FAQ) below. + +FAQ +What is the difference between the HDF5 1.8 and HDF5 1.10 releases ? + +Many new features (e.g., SWMR, VDS, paged allocation, etc.) that required extensions to the HDF5 file format were added to HDF5 1.10.0. +For more information please see the Release Specific Information pages. + +Why one should (or should not) move an application to HDF5 1.10 ? +HDF5 1.8 will not be supported after the May 2020 release, i.e., there will be no more public releases of HDF5 1.8 with security patches, bug fixes, performance improvements and support for OSs and compilers. + +In addition, applications originally written for use with HDF5 Release 1.8.x can be linked against the HDF5 Release 1.10.x library, thus taking advantage of performance improvements in 1.10. Users are encouraged to move to the latest releases of HDF5 1.10 or to HDF5 1.12.0 (coming out in the summer of 2019) if they want to stay with the current HDF5 upgrades. + +If you are not planning to upgrade your system environment, and a version of HDF5 1.8.* works for you, then there is no reason to upgrade to the latest HDF5. However, if you regularly update your software to use the latest HDF5 1.8 maintenance release, then you need to plan a transition to HDF5 1.10 after the HDF5 1.8 May 2020 release. + + +Why do I need to rebuild my application with HDF5 1.10? + +The HDF5 1.10.* binaries are not ABI compatible with the HDF5 1.8.* binaries due to changes in the public header files and APIs. One has to rebuild an application with the HDF5 1.10.* library. The HDF Group tries hard to maintain ABI compatibility for minor maintenance releases, for example when moving from 1.8.21 to 1.8.22, or 1.10.5 to 1.10.6, but this is not the case when migrating from one major release to another, for example, from 1.8.21 to 1.10.5. If you want to learn more about HDF5 versioning please see HDF5 Library Release Version Numbers. + +Can I migrate my application if I still use the HDF5 1.6 APIs? + +Yes, use the -DH5_USE_16_API compiler flag. For more information see the API Compatibility Macros document. + +Will my old software read files created by an application rebuilt with HDF5 1.10? + +If the application built on HDF5 Release 1.10 avoids use of the new features and does not request use of the latest format, applications built on HDF5 Release 1.8.x will be able to read files the first application created. + +Can I use the HDF5 tools I use now to read files created with the new HDF5 1.10 features? + +Unfortunately, no. However, we provide a few tools that will help you to “downgrade” the file, so it can be opened and used with tools and applications built with the 1.8 versions of HDF5. + +If your application uses SWMR, then the h5format_convert tool can be used to “downgrade” the file to the HDF5 1.8 compatible file format without rewriting raw data. + +The h5repack tool with –l flag can be used to repack VDS source datasets into the HDF5 file using contiguous, chunked or compact storage. The tool can also be used to rewrite the file using the HDF5 1.8 format by specifying the –high=H5F_LIBVER_V18 flag. diff --git a/documentation/hdf5-docs/release_specifics/api_comp_macros.md b/documentation/hdf5-docs/release_specifics/api_comp_macros.md new file mode 100644 index 00000000..8a4dbf62 --- /dev/null +++ b/documentation/hdf5-docs/release_specifics/api_comp_macros.md @@ -0,0 +1,403 @@ +--- +title: API Compatibility Macros +redirect_from: + - display/HDF5/API+Compatibility+Macros +--- + +Audience +The target audience for this document has existing applications that use the HDF5 library, and is considering moving to the latest HDF5 release to take advantage of the latest library features and enhancements. + +Compatibility Issues +With each major release of HDF5, such as 1.12 or 1.10, certain compatibility issues must be considered when migrating applications from an earlier major release. + +This document describes the approach taken by The HDF Group to help existing users of HDF5 address compatibility issues in the HDF5 API. + +Summary and Motivation +In response to new and evolving requirements for the library and data format, several basic functions have changed since HDF5 was first released. To allow existing applications to continue to compile and run properly, all versions of these functions have been retained in the later releases of the HDF5 library. + +Given the scope of changes available with each major release of HDF5, and recognizing the potentially time-consuming task of editing all the affected calls in user applications, The HDF Group has created a set of macros that can be used to flexibly and easily map existing API calls to previous release functions. We refer to these as the API compatibility macros. + +The HDF Group generally encourages users to update applications to work with the latest HDF5 library release so that all new features and enhancements are available to them. At the same time, The HDF Group understands that, under some circumstances, updating applications may not be feasible or necessary. The API compatibility macros, described in this document, provide a bridge from old APIs to new and can be particularly helpful in situations such as these: + +Source code is not available - only binaries are available; updating the application is not feasible. +Source code is available, but there are no resources to update it. +Source code is available, as are resources to update it, but the old version works quite well so updates are not a priority. At the same time, it is desirable to take advantage of certain efficiencies in the newer HDF5 release that do not require code changes. +Source code is available, as are resources to update it, but the applications are large or complex, and must continue to run while the code updates are carried out. +Understanding and Using the Macros +As part of latest HDF5 release, several functions that existed in previous versions of the library were updated with new calling parameters and given new names. The updated versions of the functions have a number (for eg '2') at the end of the original function name. The original versions of these functions were retained and renamed to have an earlier number (for eg '1') at the end of the original function name. + +For example, consider the function H5Lvisit in HDF5 release 1.10 as compared with 1.12: + +Original function name and signature in 1.10.0 +herr_t H5Lvisit ( hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate_t op, void *op_data ) + +Updated function and signature, introduced in release 1.12.0 +herr_t H5Lvisit2 ( hid_t group_id, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate2_t op, void *op_data ) + +Original function and signature, renamed in release 1.12.0 +herr_t H5Lvisit1 ( hid_t group_id, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate1_t op, void *op_data ) + +API compatibility macro, introduced in release 1.12.0 +H5Lvisit + +The macro, H5Lvisit, will be mapped to either H5Lvisit1 or H5Lvisit2. The mapping is determined by a combination of the configuration options use to build the HDF5 library and compile-time options used to build the application. The calling parameters used with the H5Lvisit compatibility macro should match the number and type of the function the macros will be mapped to (H5Lvisit1 or H5Lvisit2). + +The function names ending in ‘1’ or ‘2’ are referred to as versioned names, and the corresponding functions are referred to as versioned functions. For new code development, The HDF Group recommends use of the compatibility macro mapped to the latest version of the function. The original version of the function should be considered deprecated and, in general, should not be used when developing new code. + +Compatibility Macro Mapping Options +To determine the mapping for a given API compatibility macro in a given application, a combination of user-controlled selections, collectively referred to as the compatibility macro mapping options, is considered in the following sequence: + +What compatibility macro configuration option was used to build the HDF5 library? We refer to this selection as the library mapping. + +Was a compatibility macro global compile-time option specified when the application was built? We refer to this (optional) selection as the application mapping. If an application mapping exists, it overrides the library mapping. (See adjacent notes.) + +Were any compatibility macro function-level compile-time options specified when the application was built? We refer to these (optional) selections as function mappings. If function mappings exist, they override library and application mappings for the relevant API compatibility macros. (See adjacent notes.) +Notes: An application mapping can map APIs to the same version or to a version older than the configured library mapping. When the application attempts to map APIs to a newer version of the API than the library was configured with, it will fail to “upgrade” the mapping (and may fail silently). +When it is necessary to “upgrade” the macro mappings from those set in the library mapping, it must be done at the per-function level, using the function-level mappings. As long as one does not try to map a function to a version that was compiled out in the library mapping, individual functions can be upgraded or downgraded freely. + + + +Library Mapping Options + +When the HDF5 library is built, configure flags can be used to control the API compatibility macro mapping behavior exhibited by the library. This behavior can be overridden by application and function mappings. One configure flag excludes deprecated functions from the HDF5 library, making them unavailable to applications linked with the library. + + + +Table 1: Library Mapping Options +--with-default-api-version=v112 + +(the default in 1.12) + +1.12.x (H5Lvisit2) yes +--with-default-api-version=v110 +1.10.x (H5Lvisit1) yes +--with-default-api-version=v18 1.8.x (H5Lvisit1) yes +--with-default-api-version=v16 1.6.x (H5Lvisit1) yes +--disable-deprecated-symbols 1.12.x (H5Lvisit2) no + + +Refer to the file libhdf5.settings in the directory where the HDF5 library is installed to determine the configure flags used to build the library. In particular, look for the two lines shown here under Features: + + Default API mapping: v112 + + With deprecated public symbols: yes + +Application Mapping Options + +When an application using HDF5 APIs is built and linked with the HDF5 library, compile-time options to h5cc can be used to control the API compatibility macro mapping behavior exhibited by the application. The application mapping overrides the behavior specified by the library mapping, and can be overridden on a function-by-function basis by the function mappings. + +If the HDF5 library was configured with the --disable-deprecated-symbols flag, then the deprecated functions will not be available, regardless of the application mapping options. + + + +Table 2: Application Mapping Options +-DH5_USE_112_API + +(Default behavior if no option specified.) + +1.12.x (HLvisit2) yes* +*if available in library +-DH5_USE_110_API 1.10.x (HLvisit1) yes* +*if available in library +-DH5_USE_18_API 1.8.x (H5Lvisit1) yes* +*if available in library +-DH5_USE_16_API 1.6.x (H5Lvisit1) yes* +*if available in library +-DH5_NO_DEPRECATED_SYMBOLS 1.10.x (H5Lvisit1) no + + +Function Mapping Options + +Function mappings are specified when the application is built. These mappings can be used to control the mapping of the API compatibility macros to underlying functions on a function-by-function basis. The function mappings override the library and application mappings discussed earlier. + +If the HDF5 library was configured with the --disable-deprecated-symbols flag, or -DH5_NO_DEPRECATED_SYMBOLS is used to compile the application, then the deprecated functions will not be available, regardless of the function mapping options. + +For every function with multiple available versions, a compile-time version flag can be defined to selectively map the function macro to the desired versioned function. The function mapping consists of the function name followed by "_vers" which is mapped by number to a specific function or struct: + +H5xxx H5xxx_vers=1 H5xxx1 + H5xxx_vers=2 H5xxx2 + + +For example, in version 1.10 the H5Rreference macro can be mapped to either H5Rreference1 or H5Rreference2. When used, the value of the H5Rreference_vers compile-time version flag determines which function will be called: + +When H5Rreference_vers is set to 1, the macro H5Rreference will be mapped to H5Rreference1. + h5cc ... -DH5Rreference_vers=1 ... + + +When H5Rdereference_vers is set to 2, the macro H5Rdereference will be mapped to H5Rdereference2. + h5cc ... -DH5Rreference_vers=2 ... + + +When H5Rreference_vers is not set, the macro H5Rreference will be mapped to either H5Rreference1 or H5Rreference2, based on the application mapping, if one was specified, or on the library mapping. + h5cc ... +Please be aware that some function mappings use mapped structures, as well. If compiling an application with a function mapping that uses a mapped structure, you must include each function and mapped structure plus EVERY function that uses the mapped structure, whether or not that function is used in the application. In 1.12, mappings of structures are used by the H5L and H5O function mappings. + +For example, the application h5ex_g_iterate.c (found on the Examples by API page under "Groups") only calls H5Lvisit , H5Ovisit , and H5Oget_info_by_name . To compile this application with 1.10 APIs in 1.12 with the function specific mappings, then not only must H5Lvisit_vers, H5Ovisit_vers, and H5Oget_info_by_name_vers be specified on the command line, but the mapped structures and every function that uses the mapped structures must be included, as well. The full compile line is shown below: + +h5cc -DH5Lvisit_vers=1 -DH5Ovisit_vers=1 -DH5Oget_info_by_name_vers=1 -DH5Lvisit_by_name_vers=1 -DH5Literate_vers=1 -DH5Literate_by_name_vers=1 -DH5O_info_t_vers=1 -DH5L_info_t_vers=1 -DH5L_iterate_t_vers=1 -DH5Lget_info_by_idx_vers=1 -DH5Lget_info_vers=1 h5ex_g_visit.c + +Function Mapping Options in Releases 1.12.x + + + + + +H5L_GET_INFO +H5L_GET_INFO2 + +Function mapping: H5Lget_info_vers=2 +Struct mapping: H5L_info_t_vers=2 +H5L_GET_INFO1 + +Function mapping H5Lget_info_vers=1 +Struct mapping: H5L_info_t_vers=1 +H5L_GET_INFO_BY_IDX +H5L_GET_INFO_BY_IDX2 + +Function mapping: H5Lget_info_by_idx_vers=2 +Struct mapping: H5L_info_t_vers=2 +H5L_GET_INFO_BY_IDX1 + +Function mapping: H5Lget_info_by_idx_vers=1 +Struct mapping: H5L_info_t_vers=1 +H5L_ITERATE +H5L_ITERATE2 + +Function mapping: H5Literate_vers=2 +Struct mapping: H5L_iterate_t_vers=2 +H5L_ITERATE1 + +Function mapping: H5Literate_vers=1 +Struct mapping: H5L_iterate_t_vers=1 +H5L_ITERATE_BY_NAME +H5L_ITERATE_BY_NAME2 + +Function mapping: H5Literate_by_name_vers=2 +Struct mapping: H5L_iterate_t_vers=2 +H5L_ITERATE_BY_NAME1 + +Function mapping: H5Literate_by_name_vers=1 +Struct mapping: H5L_iterate_t_vers=1 +H5L_VISIT +H5L_VISIT2 + +Function mapping: H5Lvisit_vers=2 +Struct mapping: H5L_iterate_t_vers=2 +H5L_VISIT1 + +Function mapping: H5Lvisit_vers=1 +Struct mapping: H5L_iterate_t_vers=1 +H5L_VISIT_BY_NAME +H5L_VISIT_BY_NAME2 + +Function mapping: H5Lvisit_by_name_vers=2 +Struct mapping: H5L_iterate_t_vers=2 +H5L_VISIT_BY_NAME1 + +Function mapping: H5Lvisit_by_name_vers=1 +Struct mapping: H5L_iterate_t_vers=1 +H5O_GET_INFO +H5O_GET_INFO3 + +Function mapping: H5Oget_info_vers=3 +Struct mapping: H5O_info_t_vers=2 +H5O_GET_INFO1 + +Function mapping: H5Oget_info_vers=1 +Struct mapping: H5O_info_t_vers=1 +H5O_GET_INFO_BY_IDX +H5O_GET_INFO_BY_IDX3 + +Function mapping: H5Oget_info_by_idx_vers=3 +Struct mapping: H5O_info_t_vers=2 +H5O_GET_INFO_BY_IDX1 + +Function mapping: H5Oget_info_by_idx_vers=1 +Struct mapping: H5O_info_t_vers=1 +H5O_GET_INFO_BY_NAME +H5O_GET_INFO_BY_NAME3 + +Function mapping: H5O_get_info_by_name_vers=3 +Struct mapping: H5O_info_t_vers=2 +H5O_GET_INFO_BY_NAME1 + +Function mapping: H5O_get_info_by_name_vers=1 +Struct mapping: H5O_info_t_vers=1 +H5O_VISIT +H5O_VISIT3 + +Function mapping: H5Ovisit_vers=3 +Struct mapping: H5O_iterate_t_vers=2 +H5O_VISIT1 + +Function mapping: H5Ovisit_vers=1 +Struct mapping: H5O_iterate_t_vers=1 +H5O_VISIT_BY_NAME +H5O_VISIT_BY_NAME3 + +Function mapping: H5Ovisit_by_name_vers=3 +Struct mapping: H5O_iterate_t_vers=2 +H5O_VISIT_BY_NAME1 + +Function mapping: H5Ovisit_by_name_vers=1 +Struct mapping: H5O_iterate_t_vers=1 +H5P_ENCODE +H5P_ENCODE2 + +Function mapping: H5Pencode_vers=2 +H5P_ENCODE1 + +Function mapping: H5Pencode_vers=1 +H5S_ENCODE +H5S_ENCODE2 + +Function mapping: H5Sencode_vers=2 +H5S_ENCODE1 + +Function mapping: H5Sencode_vers=1 +Function Mapping Options in Releases 1.10.x + +The versioned H5Oget_info functions (H5Oget_info1 and H5Oget_info2) were added in 1.10.3, and H5Oget_info was replaced by a macro to invoke H5Oget_info1 or H5Oget_info2. However, this broke compatibility and caused problems for users because there was no longer a function H5Oget_info. In 1.10.4 and subsequent 1.10.x versions the macro was removed, H5Oget_info1 was deprecated, and H5Oget_info was resurrected as a function. H5Oget_info2 remained as a function, but is not a versioned alternative to the original H5Oget_info. The same is true for H5Oget_info_by name, H5Oget_info_by_idx, H5Ovisit, and H5Ovisit_by_name. The version 2 functions were added to improve performance. + +The unversioned originals and version 2 of those functions exist in 1.10 because having released them in 1.10.3, it would break compatibility to remove them, so the original and version 2 functions remained in the source but without any macro to map to one or the other. Therefore, version 2 functions are available, but only when invoked directly. + +In 1.12 there is a version 3 of all 5 functions which uses version 2 H5Oinfo2_t or H5Oiterate2_t structures. Both versions 1 and 2 are deprecated and macros replace the unversioned functions, mapping to version 1 for 18 and 110 default apis and to version 3 for 112 default api. Version 2 is available, but will only be invoked if invoked directly. + + + +Macro +Default function used + +(if no macro specified) + +Introduced in + +h5cc version flag and value Mapped to function or struct +H5Rdereference + +H5Rdereference2 HDF5-1.10.0 -DH5Rdereference_vers=1 H5Rdereference1 +-DH5Rdereference_vers=2 H5Rdereference2 +H5Fget_info + +H5Fget_info2 HDF5-1.10.0 -DH5Fget_info_vers=1 H5Fget_info1 with struct H5F_info1_t +-DH5Fget_info_vers=2 H5Fget_info2 with struct H5F_info2_t +H5Oget_info + +H5Oget_info1 HDF5-1.10.3 -DH5Oget_info_vers=1 H5Oget_info1 +-DH5Oget_info_vers=2 H5Oget_info2 +H5Oget_info_by_idx + +H5Oget_info_by_idx1 HDF5-1.10.3 -DH5Oget_info_by_idx_vers=1 H5Oget_info_by_idx1 +-DH5Oget_info_by_idx_vers=2 H5Oget_info_by_idx2 +H5Oget_info_by_name H5Oget_info_by_name1 HDF5-1.10.3 -DH5Oget_info_by_name_vers=1 H5Oget_info_by_name1 +-DH5Oget_info_by_name_vers=2 H5Oget_info_by_name2 +H5Ovisit H5Ovisit1 HDF5-1.10.3 -DH5Ovisit_vers=1 H5Ovisit1 +-DH5Ovisit_vers=2 +H5Ovisit2 + +H5Ovisit_by_name H5Ovisit_by_name1 HDF5-1.10.3 -DH5Ovisit_by_name_vers=1 H5Ovisit_by_name1 +-DH5Ovisit_by_name_vers=2 H5Ovisit_by_name2 +Function Mapping Options in Releases 1.8.x + +At release 1.8.0, the API compatibility macros, function mapping compile-time version flags and values, and corresponding versioned functions listed in the following table were introduced. If the application being compiled to run with any 1.10.x release was written to use any 1.6.x release of HDF5, you must also consider these macros and mapping options. + + + +Table 5: Function Mapping Options in Releases 1.8.x +Macro h5cc version flag and value Mapped to function +or struct +H5Acreate -DH5Acreate_vers=1 H5Acreate1 +-DH5Acreate_vers=2 H5Acreate2 +H5Aiterate -DH5Aiterate_vers=1 H5Aiterate1 +with struct H5A_operator1_t +-DH5Aiterate_vers=2 H5Aiterate2 +with struct H5A_operator2_t +H5Dcreate -DH5Dcreate_vers=1 H5Dcreate1 +-DH5Dcreate_vers=2 H5Dcreate2 +H5Dopen -DH5Dopen_vers=1 H5Dopen1 +-DH5Dopen_vers=2 H5Dopen2 +H5Eclear -DH5Eclear_vers=1 H5Eclear1 +-DH5Eclear_vers=2 H5Eclear2 +H5Eprint -DH5Eprint_vers=1 H5Eprint1 +-DH5Eprint_vers=2 H5Eprint2 +H5Epush -DH5Epush_vers=1 H5Epush1 +-DH5Epush_vers=2 H5Epush2 +H5Eset_auto -DH5Eset_auto_vers=1 H5Eset_auto1 +-DH5Eset_auto_vers=2 H5Eset_auto2 +H5Eget_auto -DH5Eget_auto_vers=1 H5Eget_auto1 +-DH5Eget_auto_vers=2 H5Eget_auto2 +H5E_auto_t +Struct for H5Eset_auto +and H5Eget_auto -DH5E_auto_t_vers=1 H5E_auto1_t +-DH5E_auto_t_vers=2 H5E_auto2_t +H5Ewalk -DH5Ewalk_vers=1 H5Ewalk1 +with callback H5E_walk1_t +and struct H5E_error1_t +-DH5Ewalk_vers=2 H5Ewalk2 +with callback H5E_walk2_t +and struct H5E_error2_t +H5Gcreate -DH5Gcreate_vers=1 H5Gcreate1 +-DH5Gcreate_vers=2 H5Gcreate2 +H5Gopen -DH5Gopen_vers=1 H5Gopen1 +-DH5Gopen_vers=2 H5Gopen2 +H5Pget_filter -DH5Pget_filter_vers=1 H5Pget_filter1 +-DH5Pget_filter_vers=2 H5Pget_filter2 +H5Pget_filter_by_id -DH5Pget_filter_by_id_vers=1 H5Pget_filter_by_id1 +-DH5Pget_filter_by_id_vers=2 H5Pget_filter_by_id2 +H5Pinsert -DH5Pinsert_vers=1 H5Pinsert1 +-DH5Pinsert_vers=2 H5Pinsert2 +H5Pregister -DH5Pregister_vers=1 H5Pregister1 +-DH5Pregister_vers=2 H5Pregister2 +H5Rget_obj_type -DH5Rget_obj_typevers=1 H5Rget_obj_type1 +-DH5Rget_obj_type_vers=2 H5Rget_obj_type2 +H5Tarray_create -DH5Tarray_create_vers=1 H5Tarray_create1 +-DH5Tarray_create_vers=2 H5Tarray_create2 +H5Tcommit -DH5Tcommit_vers=1 H5Tcommit1 +-DH5Tcommit_vers=2 H5Tcommit2 +H5Tget_array_dims -DH5Tget_array_dims_vers=1 H5Tget_array_dims1 +-DH5Tget_array_dims_vers=2 H5Tget_array_dims2 +H5Topen -DH5Topen_vers=1 H5Topen1 +-DH5Topen_vers=2 H5Topen2 +H5Z_class_t Struct for H5Zregister -DH5Z_class_t_vers=1 H5Z_class1_t +-DH5Z_class_t_vers=2 H5Z_class2_t + + +Further Information + +See the HDF5 Reference Manual for complete descriptions of all API compatibility macros and versioned functions shown. + +It is possible to specify multiple function mappings for a single application build: + +h5cc ... -DH5Rdereference_vers=1 -DH5Fget_info_vers=2 ...As a result of the function and struct mappings in this compile example, all occurrences of the macro H5Rdereference will be mapped to H5Rdereference1 and all occurrences of the macro H5Fget_info will be mapped to H5Fget_info2 for the application being built. + +The function and struct mappings can be used to guarantee that a given API compatibility macro will be mapped to the desired underlying function or struct version regardless of the library or application mappings. In cases where an application may benefit greatly from features offered by some of the later APIs, or must continue to use some earlier API versions for compatibility reasons, this fine-grained control may be very important. + +As noted earlier, the function mappings can only reference versioned functions that are included in the HDF5 library, as determined by the configure flag used to build the library. For example, if the HDF5 library being linked with the application was built with the --disable-deprecated-symbols option, version 1 of the underlying functions would not be available, and the example above that defined H5Rdereference_vers=1 would not be supported. + +The function mappings do not negate any available functions. If H5Rdereference1 is available in the installed version of the HDF5 library, and the application was not compiled with the -DH5_NO_DEPRECATED_SYMBOLS flag, the function H5Rdereference1 will remain available to the application through its versioned name. Similarly, H5Rdereference2 will remain available to the application as H5Rdereference2. The function mapping version flag H5Rdereference_vers only controls the mapping of the API compatibility macro H5Rdereference to one of the two available functions. + +This can be especially useful in any case where the programmer does not have direct control over global macro definitions, such as when writing code meant to be copied to multiple applications or when writing code in a header file. + +Compatibility Macros in HDF5 1.6.8 and Later +A series of similar compatibility macros were introduced into the release 1.6 series of the library, starting with release 1.6.8. These macros simply alias the ‘1’ version functions, callbacks, and typedefs listed above to their original non-numbered names. + +These macros were strictly a forward-looking feature at that time; they were not necessary for compatibility in 1.6.x. These macros were created at that time to enable writing code that could be used with any version of the library after 1.6.8 and any library compilation options except H5_NO_DEPRECATED_SYMBOLS, by always using the ‘1’ version of versioned functions and types. For example, H5Dopen1 will always be interpreted in exactly the same manner by any version of the library since 1.6.8. + +Common Use Case +A common scenario where the API compatibility macros may be helpful is the migration of an existing application to a new HDF5 release An incremental migration plan is outlined here: + +Build the HDF5 library without specifying any library mapping configure flag. In this default mode, the 1.6.x, 1.8.x, and 1.10.x versions of the underlying functions are available, and the API compatibility macros will be mapped to the current HDF5 versioned functions. + + +Compile the application with the -DH5_USE_NN_API application mapping option if it was written for use with an earlier HDF5 library. Because the application mapping overrides the library mapping, the macros will all be mapped to the earlier versions of the functions. + + +Remap one API compatibility macro at a time (or sets of macros), to use the current HDF5 versions. At each stage, use the function mappings to map the macros being worked on to the current versions. For example, use the -DH5Rdereference_vers=2 version flag setting to remap the H5Rdereference macro to H5Rdereference2, the 1.10.x version. +During this step, the application code will need to be modified to change the calling parameters used with the API compatibility macros to match the number and type of the 1.10.x versioned functions. The macro name, for example H5Rdereference, should continue to be used in the code, to allow for possible re-mappings to later versioned functions in a future release. + + + +After all macros have been migrated to the latest versioned functions in step 3, compile the application without any application or function mappings. This build uses the library mappings set in step 1, and maps API compatibility macros to the latest versions. + + +Finally, compile the application with the application mapping -DH5_NO_DEPRECATED_SYMBOLS, and address any failures to complete the application migration process. \ No newline at end of file diff --git a/documentation/hdf5-docs/release_specifics/hdf5_1_10.md b/documentation/hdf5-docs/release_specifics/hdf5_1_10.md new file mode 100644 index 00000000..bfb12c4f --- /dev/null +++ b/documentation/hdf5-docs/release_specifics/hdf5_1_10.md @@ -0,0 +1,19 @@ +--- +title: HDF5 1.10 +redirect_from: + - display/HDF5/HDF5+1.12+Release +--- + +Migrating from HDF5 1.8 to HDF5 1.10 + +New Features in HDF5 Release 1.10: + + Additional New APIs + Chunk Query Functionality (RFC) + Minimum Object Headers (RFC) + Parallel Library Change (RFC) + Read Proc0 and Bcast (RFC) +Setting Bounds for Object Creation in HDF5-1.10.0 - RFC +Software Changes from Release to Release for HDF5-1.10 + +API Compatibility Reports for 1.10 \ No newline at end of file diff --git a/documentation/hdf5-docs/release_specifics/hdf5_1_12.md b/documentation/hdf5-docs/release_specifics/hdf5_1_12.md new file mode 100644 index 00000000..106ec3de --- /dev/null +++ b/documentation/hdf5-docs/release_specifics/hdf5_1_12.md @@ -0,0 +1,37 @@ +--- +title: New Features in HDF5 1.12 +redirect_from: + - display/HDF5/New+Features+in+HDF5+Release+1.12 +--- + +This release includes changes in the HDF5 storage format. PLEASE NOTE that HDF5-1.10 and earlier releases cannot read files created with the new features described below that are marked with a *. + +HDF5 1.12 introduces several new features in the HDF5 library: + +Virtual Object Layer (VOL) * +Hyperslab Performance Improvement +Update to References * +Update to Selections +Virtual Object Layer (VOL) (RFC) * +See the Virtual Object Layer page for more information. + +The Virtual Object Layer (VOL) is an abstraction layer within the HDF5 library that enables different methods for accessing data and objects that conform to the HDF5 data model. The VOL intercepts all HDF5 API calls that potentially modify data on disk and forwards those calls to a plugin "object driver". The data on disk can be a different format than the HDF5 format. + + + +The plugins can actually store the objects in variety of ways. A plugin could, for example, have objects be distributed remotely over different platforms, provide a raw mapping of the model to the file system, or even store the data in other file formats (like native netCDF or HDF4 format). The user still gets the same data model where access is done to a single HDF5 “container”; however the plugin object driver translates from what the user sees to how the data is actually stored. Having this abstraction layer maintains the object model of HDF5 and allows better usage of new object storage file systems that are targeted for Exascale systems. + +Hyperslab Performance Improvements +In 1.12.0 the hyperslab selection code was optimized to achieve better performance. In general, performance improved by an order of a magnitude. In the case of reading a regular selection from a 20 GB dataset into a one dimensional array, performance improved by a factor of 6000. If you are interested in the benchmark we ran, please see issue HDFFV-10930 by logging into jira.hdfgroup.org with your hdfgroup.org login. + +Update to References (RFC) * +See the Update to References page for details on the changes in HDF5-1.12. + +HDF5 references were extended to support attributes, as well as object and dataset selections that reside in another HDF5 file. In order to support these features several functions were introduced: + +Create (H5R_CREATE*) functions were added for each reference type: object, dataset region and attribute. +A function was added to release a reference (H5R_DESTROY). This is required because a region reference no longer modifies the original file. +Functions were added to query references (H5R_GET*). +Other functions were added to simplify or clarify the API. +Update to Selections +Several new H5S APIs were introduced to allow a user to more flexibly operate on two hyperslab selections. See Update to Selections for more details. \ No newline at end of file diff --git a/documentation/hdf5-docs/release_specifics/hdf5_1_8.md b/documentation/hdf5-docs/release_specifics/hdf5_1_8.md new file mode 100644 index 00000000..733fa557 --- /dev/null +++ b/documentation/hdf5-docs/release_specifics/hdf5_1_8.md @@ -0,0 +1,9 @@ +--- +title: HDF5 1.8 +redirect_from: + - display/HDF5/HDF5+1.8+Release +--- + +New Features in HDF5 Release 1.8 + +Software Changes from Release to Release for HDF5-1.8 \ No newline at end of file diff --git a/documentation/hdf5-docs/release_specifics/new_features_1_10.md b/documentation/hdf5-docs/release_specifics/new_features_1_10.md new file mode 100644 index 00000000..fec82124 --- /dev/null +++ b/documentation/hdf5-docs/release_specifics/new_features_1_10.md @@ -0,0 +1,183 @@ +--- +title: New Features in HDF5 1.10 +redirect_from: + - display/HDF5/New+Features+in+HDF5+Release+1.10 +--- + +HDF5 1.10 introduces several new features in the HDF5 library. These new features were added in the first three releases of HDF5-1.10. For a brief description of each new feature see: + +New Features Introduced in HDF5 1.10.8 +New Features Introduced in HDF5 1.10.7 +New Features introduced in HDF5 1.10.6 +New Features introduced in HDF5 1.10.5 +New Features Introduced in HDF5 1.10.2 +New Features Introduced in HDF5 1.10.1 +New Features Introduced in HDF5 1.10.0 +This release includes changes in the HDF5 storage format. For detailed information on the changes, see: Changes to the File Format Specification + +PLEASE NOTE that HDF5-1.8 cannot read files created with the new features described below that are marked with *. + +These changes come into play when one or more of the new features is used or when an application calls for use of the latest storage format (H5P_SET_LIBVER_BOUNDS). See the RFC for more details. + +Due to the requirements of some of the new features, the format of a 1.10.x HDF5 file is likely to be different from that of a 1.8.x HDF5 file. This means that tools and applications built to read 1.10.x files will be able to read a 1.8.x file, but tools built to read 1.8.x files may not be able to read a 1.10.x file. + +If an application built on HDF5 Release 1.10 avoids use of the new features and does not request use of the latest format, applications built on HDF5 Release 1.8.x will be able to read files the first application created. In addition, applications originally written for use with HDF5 Release 1.8.x can be linked against a suitably configured HDF5 Release 1.10.x library, thus taking advantage of performance improvements in 1.10. + + New Features Introduced in HDF5 1.10.8 +The following important new features and changes were introduced in HDF5-1.10.8. For complete details see the Release Notes and the Software Changes from Release to Release page. + +New Features Introduced in HDF5 1.10.7 +The following important new features and changes were introduced in HDF5-1.10.7. For complete details see the Release Notes and the Software Changes from Release to Release page. + +Addition of AEC (open source SZip) Compression Library +HDF5 now supports building with the AEC library as a replacement library for SZip. + +Addition of the Splitter and Mirror VFDs +Two VFDs were added in this release: + +The Splitter VFD maintains separate R/W and W/O channels for ”concurrent” file writes to two files using a single HDF5 file handle. +The Mirror VFD uses TCP/IP sockets to perform write-only (W/O) file I/O on a remote machine. +Improvements to Performance +Performance has continued to improve in this release. Please see the images under Compatibility and Performance Issues on the Software Changes from Release to Release page. + +Addition of Hyperslab Selection Functions +Several hyperslab selection routines introduced in HDF5-1.12 were ported to 1.10. See the Software Changes from Release to Release page for details. + +New Features Introduced in HDF5 1.10.6 +The following important new features and changes were introduced in HDF5-1.10.6. For complete details see the Release Notes and the Software Changes from Release to Release page: + +Improvements to the CMake Support +Several improvements were added to the CMake support, including: + +Support was added for VS 2019 on Windows (with CMake 3.15). +Support was added for MinGW using a toolchain file on Linux (C only). +Virtual File Drivers - S3 and HDFS +Two Virtual File Drivers (VFDs) have been introduced in 1.10.6: + +The S3 VFD enables access to an HDF5 file via the Amazon Simple Storage Service (Amazon S3). +The HDFS VFD enables access to an HDF5 file with the Hadoop Distributed File System (HDFS). +See the Virtual File Drivers - S3 and HDFS page for more information. + +Improvement to Performance +Performance was improved when creating a large number of small datasets. + +New Features Introduced in HDF5 1.10.5 +The following important new features were added in HDF5-1.10.5. Please see the release announcement and Software Changes from Release to Release page for more details regarding these features: + +Minimized Dataset Object Headers (RFC) +The ability to minimize dataset object headers was added to reduce the file bloat caused by extra space in the dataset object header. The file bloat can occur when creating many, very small datasets. See the Release Notes for more details regarding this issue. + +The following APIs were introduced to support this feature: + +H5F_GET_DSET_NO_ATTRS_HINT + +Retrieves the setting for determining whether the specified file does or does not create minimized dataset object headers + +H5F_SET_DSET_NO_ATTRS_HINT + +Sets the flag to create minimized dataset object headers + +H5P_GET_DSET_NO_ATTRS_HINT + +Retrieves the setting for determining whether the specified DCPL does or does not create minimized dataset object headers + +H5P_SET_DSET_NO_ATTRS_HINT + +Sets the flag to create minimized dataset object headers + +Parallel Library Change (RFC) +A change was added to the default behavior in parallel when reading the same dataset in its entirety (i.e. H5S_ALL dataset selection) which is being read by all the processes collectively. The dataset must be contiguous, less than 2GB, and of an atomic datatype. The new behavior in the HDF5 library uses an MPI_Bcast to pass the data read from the disk by the root process to the remaining processes in the MPI communicator associated with the HDF5 file. + +A CFD application was used to benchmark CGNS with: + +compact storage +read-proc0-and-bcast +These results were reported by Greg Sjaardema from Sandia National Laboratories. + + + +Series 1 is the read-proc0-and-bcast solution +Series 2 is a single MPI_Bcast +Series 3 uses multiple MPI_Bcast totaling 2 MiB total data 64 bytes at a time (IIRC) +Series 4 is unmodified CGNS develop +Compact is using compact storage +Compact 192 is also using compact storage +Compact 384 is also using compact storage +The last 3 “compact” curves are just three different batch jobs on 192, 384, and 552 nodes (with 36 core/node). The Series 2 and 3 curves are not related to the CGNS benchmark, but give a qualitative indication on the scaling behavior of MPI_Bcast. Both read-proc0-and-bcast and compact storage follow MPI_Bcast’s trend, which makes sense since both methods rely on MPI_Bcast. (See the RFC for better resolution.) + +OpenMPI Support +Support for OpenMPI was added. For known problems and issues please see OpenMPI Build Issues. To better support OpenMPI, all MPI-1 API calls were replaced by MPI-2 equivalents. + +Chunk Query Functions (RFC) +New functions were added to find locations, sizes and filters applied to chunks of a dataset. This functionality is useful for applications that need to read chunks directly from the file, bypassing the HDF5 library. + +H5D_GET_CHUNK_INFO Retrieves information about a chunk specified by the chunk index +H5D_GET_CHUNK_INFO_BY_COORD Retrieves information about a chunk specified by its coordinates +H5D_GET_NUM_CHUNKS Retrieves number of chunks that have nonempty intersection with a specified selection + +New Features Introduced in HDF5 1.10.2 +Several important features and changes were added to HDF5 1.10.2. See the release announcement and blog for complete details. Following are the major new features: + +Forward Compatibility for HDF5 1.8-based Applications Accessing Files Created by HDF5 1.10.2 ( RFC ) +In HDF5 1.8.0, the H5P_SET_LIBVER_BOUNDS function was introduced for specifying the earliest ("low") and latest ("high") versions of the library to use when writing objects. With HDF5 1.10.2, new values for "low" and "high" were introduced: H5F_LIBVER_18 and H5F_LIBVER_LATEST is now mapped to H5F_LIBVER_V110. See the H5P_SET_LIBVER_BOUNDS function for details. + +Performance Optimizations for HDF5 Parallel Applications +Optimizations were introduced to parallel HDF5 for improving the performance of open, close and flush operations at scale. + +Using Compression with HDF5 Parallel Applications +HDF5 parallel applications can now write data using compression (and other filters such as the Fletcher32 checksum filter). + + + +New Features Introduced in HDF5 1.10.1 +Metadata Cache Image ( RFC ) » Fine-tuning the Metadata Cache * +HDF5 metadata is typically small, and scattered throughout the HDF5 file. This can affect performance, particularly on large HPC systems. The Metadata Cache Image feature can improve performance by writing the metadata cache in a single block on file close, and then populating the cache with the contents of this block on file open, thus avoiding the many small I/O operations that would otherwise be required on file open and close. + +Metadata Cache Evict on Close » Fine-tuning the Metadata Cache +The HDF5 library's metadata cache is fairly conservative about holding on to HDF5 object metadata (object headers, chunk index structures, etc.), which can cause the cache size to grow, resulting in memory pressure on an application or system. The "evict on close" property will cause all metadata for an object to be evicted from the cache as long as metadata is not referenced from any other open object. + +Paged Aggregation ( RFC ) » File Space Management * +The current HDF5 file space allocation accumulates small pieces of metadata and raw data in aggregator blocks which are not page aligned and vary widely in sizes. The paged aggregation feature was implemented to provide efficient paged access of these small pieces of metadata and raw data. + +Page Buffering ( RFC ) +Small and random I/O accesses on parallel file systems result in poor performance for applications. Page buffering in conjunction with paged aggregation can improve performance by giving an application control of minimizing HDF5 I/O requests to a specific granularity and alignment. + + + +New Features Introduced in HDF5 1.10.0 +SWMR * +Data acquisition and computer modeling systems often need to analyze and visualize data while it is being written. It is not unusual, for example, for an application to produce results in the middle of a run that suggest some basic parameters be changed, sensors be adjusted, or the run be scrapped entirely. + +To enable users to check on such systems, we have been developing a concurrent read/write file access pattern we call SWMR (pronounced swimmer). SWMR is short for single-writer/multiple-reader. SWMR functionality allows a writer process to add data to a file while multiple reader processes read from the file. + +Fine-tuning the Metadata Cache +The orderly operation of the metadata cache is crucial to SWMR functioning. A number of APIs have been developed to handle the requests from writer and reader processes and to give applications the control of the metadata cache they might need. However, the metadata cache APIs can be used when SWMR is not being used; so, these functions are described separately. + +Collective Metadata I/O +Calls for HDF5 metadata can result in many small reads and writes. On metadata reads, collective metadata I/O can improve performance by allowing the library to perform optimizations when reading the metadata, by having one rank read the data and broadcasting it to all other ranks. + +Collective metadata I/O improves metadata write performance through the construction of an MPI derived datatype that is then written collectively in a single call. + +File Space Management * +Usage patterns when working with an HDF5 file sometimes result in wasted space within the file. This can also impair access times when working with the resulting files. The new file space management feature provides strategies for managing space in a file to improve performance in both of these arenas. + +Virtual Datasets (VDS) * +With a growing amount of data in HDF5, the need has emerged to access data stored across multiple HDF5 files using standard HDF5 objects, such as groups and datasets, without rewriting or rearranging the data. The new virtual dataset (VDS) feature enables an application to draw on multiple datasets and files to create virtual datasets without moving or rewriting any data. + +Partial Edge Chunk Options * +New options for the storage and filtering of partial edge chunks in a dataset provide a tool for tuning I/O speed and file size in cases where the dataset size may not be a multiple of the chunk size. + +Additional New APIs +In addition to the features described above, several additional new functions, a new struct, and new macros have been introduced or newly versioned in this release. + +Changes to the File Format Specification +The file format of the HDF5 library has been changed to support the new features in HDF5-1.10. + +See the HDF5 File Format Specification for complete details on the changes. This specification describes how the bytes in an HDF5 file are organized on the storage media where the file is kept. In other words, when a file is written to disk, the file will be written according to the information described in this file. The following sections have been added or changed: + +Another version of the superblock was added. +Additional B-tree types were added to the version 2 B-trees. +The global heap block for virtual datasets was added. +The Data Layout Message was changed: the name was changed, and version 4 of the data layout message was added for the virtual type. +Additional types of indexes were added for dataset chunks. +HDF5-1.8 cannot read files created with the new features described on this page that are marked with *. \ No newline at end of file diff --git a/documentation/hdf5-docs/release_specifics/new_features_1_12.md b/documentation/hdf5-docs/release_specifics/new_features_1_12.md new file mode 100644 index 00000000..106ec3de --- /dev/null +++ b/documentation/hdf5-docs/release_specifics/new_features_1_12.md @@ -0,0 +1,37 @@ +--- +title: New Features in HDF5 1.12 +redirect_from: + - display/HDF5/New+Features+in+HDF5+Release+1.12 +--- + +This release includes changes in the HDF5 storage format. PLEASE NOTE that HDF5-1.10 and earlier releases cannot read files created with the new features described below that are marked with a *. + +HDF5 1.12 introduces several new features in the HDF5 library: + +Virtual Object Layer (VOL) * +Hyperslab Performance Improvement +Update to References * +Update to Selections +Virtual Object Layer (VOL) (RFC) * +See the Virtual Object Layer page for more information. + +The Virtual Object Layer (VOL) is an abstraction layer within the HDF5 library that enables different methods for accessing data and objects that conform to the HDF5 data model. The VOL intercepts all HDF5 API calls that potentially modify data on disk and forwards those calls to a plugin "object driver". The data on disk can be a different format than the HDF5 format. + + + +The plugins can actually store the objects in variety of ways. A plugin could, for example, have objects be distributed remotely over different platforms, provide a raw mapping of the model to the file system, or even store the data in other file formats (like native netCDF or HDF4 format). The user still gets the same data model where access is done to a single HDF5 “container”; however the plugin object driver translates from what the user sees to how the data is actually stored. Having this abstraction layer maintains the object model of HDF5 and allows better usage of new object storage file systems that are targeted for Exascale systems. + +Hyperslab Performance Improvements +In 1.12.0 the hyperslab selection code was optimized to achieve better performance. In general, performance improved by an order of a magnitude. In the case of reading a regular selection from a 20 GB dataset into a one dimensional array, performance improved by a factor of 6000. If you are interested in the benchmark we ran, please see issue HDFFV-10930 by logging into jira.hdfgroup.org with your hdfgroup.org login. + +Update to References (RFC) * +See the Update to References page for details on the changes in HDF5-1.12. + +HDF5 references were extended to support attributes, as well as object and dataset selections that reside in another HDF5 file. In order to support these features several functions were introduced: + +Create (H5R_CREATE*) functions were added for each reference type: object, dataset region and attribute. +A function was added to release a reference (H5R_DESTROY). This is required because a region reference no longer modifies the original file. +Functions were added to query references (H5R_GET*). +Other functions were added to simplify or clarify the API. +Update to Selections +Several new H5S APIs were introduced to allow a user to more flexibly operate on two hyperslab selections. See Update to Selections for more details. \ No newline at end of file diff --git a/documentation/hdf5-docs/release_specifics/release_specific_info.md b/documentation/hdf5-docs/release_specifics/release_specific_info.md new file mode 100644 index 00000000..5ada39da --- /dev/null +++ b/documentation/hdf5-docs/release_specifics/release_specific_info.md @@ -0,0 +1,22 @@ +--- +title: Release Specific Information +redirect_from: + - display/HDF5/Release+Specific+Information +--- + +### [HDF5 1.12]() +* [New Features]() +* [Software Changes from Release to Release]() +* [Migrating from HDF5 1.10 to HDF5 1.12]() + +### [HDF5 1.10]() +* [New Features]() +* [Why should I care about the HDF5-1.10.2 release? (blog)]() +* [Software Changes from Release to Release]() +* [Migrating from HDF5 1.8 to HDF5 1.10]() + +### [HDF5 1.8]() +* [New Features]() +* [Software Changes from Release to Release]() + +### [API compatibility Macros in HDF5]() diff --git a/documentation/hdf5-docs/release_specifics/sw_changes_1.10.md b/documentation/hdf5-docs/release_specifics/sw_changes_1.10.md new file mode 100644 index 00000000..364bad5e --- /dev/null +++ b/documentation/hdf5-docs/release_specifics/sw_changes_1.10.md @@ -0,0 +1,1120 @@ +--- +title: HDF5 1.10 +redirect_from: + - display/HDF5/HDF5+1.10+Release +--- + +For a description of the major new features that were introduced, please see New Features in HDF5 Release 1.10.) + +This page provides information on the changes that a maintenance developer needs to be aware of between successive releases of HDF5, such as: + +New or changed features or tools +Syntax and behavioral changes in the existing application programming interface (the API) +Certain types of changes in configuration or build processes +Note that bug fixes and performance enhancements in the C library are automatically picked up by the C++, Fortran, and Java libraries. + +The following information is included below. + +Compatiblity and Performance Issues +Release 1.10.9 versus 1.10.8 +Release 1.10.8 versus 1.10.7 +Release 1.10.7 versus 1.10.6 +Release 1.10.6 versus 1.10.5 +Release 1.10.5 versus 1.10.4, 1.10.3, and 1.10.2 + +Release 1.10.4 versus Release 1.10.3 +Release 1.10.3 versus Release 1.10.2 +Release 1.10.2 versus Release 1.10.1 + +Release 1.10.1 versus Release 1.10.0 (and 1.10.0-patch1) + +Release 1.10.0 of March 2016 versus Release 1.8.16 + +Compatibility and Performance Issues +Not all HDF5-1.10 releases are compatible. Users should NOT be using 1.10 releases prior to HDF5-1.10.3. See the compatibility matrix below for details on compatibility between 1.10 releases: + +1.10.5+ Yes Yes No No No No +1.10.4 Yes Yes No No No No +1.10.3 Yes Yes No No No No +1.10.2 No No No No No No +The following images show how performance has changed from release to release. + + + + + + + +The release notes also list changes made to the library, but these notes tend to be more at a more detail-oriented level. The release notes may include new features, bugs fixed, supported configuration features, platforms on which the library has been tested, and known problems. The release note files are listed below and can be found at the top level of the HDF5 source code tree in the release_docs directory. + +Release Notes + +Technical notes regarding the current release of the HDF5 library (RELEASE.txt in the source code) + +HISTORY-1_10.txt + +Release information for all HDF5-1.10 releases + +HISTORY-1_8_0-1_10_0.txt + +Development history between the HDF5-1.8.0 and HDF5-1.10.0 releases + +HISTORY-1_8.txt + +Release information for HDF5-1.8.0 through HDF5-1.8.21 releases + +HISTORY-1_0-1_8_0_rc3.txt + + +Technical notes starting with HDF5-1.0.0 and ending with HDF5-1.8.0-rc3 (the state of the code prior to the HDF5-1.8.0 release) + +Release 1.10.9 versus 1.10.8 +New and Changed Functions, Classes, Subroutines, Wrappers, and Macros +In the Java Wrapper + +One Java wrapper was added: + +H5.H5export_dataset + +Compatibility Notes and Reports +See the API compatibility report for the HDF5 library between 1.10.8 and 1.10.9 for information regarding compatibility with the previous release. The API Compatibility Report page includes all 1.10 compatibility reports. + +Release 1.10.8 versus 1.10.7 +New and Changed Functions, Classes, Subroutines, Wrappers, and Macros +In the C++ Wrapper + +One C++ wrapper was added: +DataSet::operator= + +Compatibility Notes and Reports +See the API compatibility report for the HDF5 library between 1.10.7 and 1.10.8 for information regarding compatibility with the previous release. The API Compatibility Report page includes all 1.10 compatibility reports. + +Release 1.10.7 versus 1.10.6 +New and Changed Functions, Classes, Subroutines, Wrappers, and Macros +In the C Interface (main library) + +The following are new C functions in this release: + +H5P_GET_FAPL_SPLITTER +Retrieves information for a splitter file access property list +H5P_SET_FAPL_SPLITTER Sets the file access property list to use the splitter driver +H5P_GET_FILE_LOCKING Gets the file locking property values +H5P_SET_FILE_LOCKING Sets the file locking property values +H5_GET_ALLOC_STATS +Gets the memory allocation statistics for the library +H5_GET_FREE_LIST_SIZES Gets the current size of the free lists used to manage memory +H5S_COMBINE_HYPERSLAB Performs an operation on a hyperslab and an existing selection and returns the resulting selection +H5S_COMBINE_SELECT Combines two hyperslab selections with an operation, returning a dataspace with the resulting selection +H5S_MODIFY_SELECT Refines a hyperslab selection with an operation using a second hyperslab to modify it +H5S_SELECT_ADJUST Adjusts a selection by subtracting an offset +H5S_SELECT_COPY Copies a selection from one dataspace to another +H5S_SELECT_INTERSECT_BLOCK Checks if current selection intersects with a block +H5S_SELECT_PROJECT_INTERSECTION Projects the intersection of two source selections to a destination selection +H5S_SELECT_SHAPE_SAME +Checks if two selections are the same shape + + + +In the C++ Wrapper + +The following C++ wrappers were added: + +FileAccPropList::getFileLocking See H5P_GET_FILE_LOCKING for details +FileAccPropList::setFileLocking See H5P_SET_FILE_LOCKING for details +Compatibility Notes and Reports +See the API compatibility report for the HDF5 library between 1.10.6 and 1.10.7 for information regarding compatibility with the previous release. The API Compatibility Report page includes all 1.10 compatibility reports. + +Release 1.10.6 versus 1.10.5 +New and Changed Functions, Classes, Subroutines, Wrappers, and Macros +In the C Interface (main library) + +The following are new C functions in this release: + +H5P_GET_FAPL_HDFS Gets the information of the given Read-Only HDFS virtual file driver +H5P_GET_FAPL_ROS3 Gets the information of the given Read-Only S3 virtual file driver +H5P_SET_FAPL_HDFS Sets up Read-Only HDFS virtual file driver +H5P_SET_FAPL_ROS3 Sets up Read-Only S3 virtual file driver + + +In the C++ Wrapper + +The following C++ wrapper was added: + +LinkCreatPropList::getCreateIntermediateGroup ( ) const +See H5P_GET_CREATE_INTERMEDIATE_GROUP +LinkCreatPropList::setCreateIntermediateGroup ( bool crt_intmd_group ) const +See H5P_SET_CREATE_INTERMEDIATE_GROUP +Compatibility Notes and Reports +See the API Compatibility Report for information regarding compatibility with previous releases. + +Release 1.10.5 versus 1.10.4, 1.10.3, and 1.10.2 +New and Changed Functions, Classes, Subroutines, Wrappers, and Macros +In the C Interface (main library) + +The following are new C functions in this release: + +H5D_GET_CHUNK_INFO Retrieves information about a chunk specified by the chunk index +H5D_GET_CHUNK_INFO_BY_COORD Retrieves information about a chunk specified by its coordinates +H5D_GET_NUM_CHUNKS Retrieves number of chunks that have nonempty intersection with a specified selection +H5F_GET_DSET_NO_ATTRS_HINT + +Retrieves the setting for determining whether the specified file does or does not create minimized dataset object headers + +H5F_SET_DSET_NO_ATTRS_HINT + +Sets the flag to create minimized dataset object headers + +H5P_GET_DSET_NO_ATTRS_HINT + +Retrieves the setting for determining whether the specified DCPL does or does not create minimized dataset object headers + +H5P_SET_DSET_NO_ATTRS_HINT + +Sets the flag to create minimized dataset object headers + + + +The following changed in this release: + +H5O_GET_INFO, H5O_GET_INFO_BY_NAME, H5O_GET_INFO_BY_IDX, H5O_VISIT, H5O_VISIT_BY_NAME + +In 1.10.3 the original functions were versioned to H5Oget_info*1 and H5Ovisit*1 and the macros H5Oget_info* and H5Ovisit* were created. This broke the API compatibility for a maintenance release. In HDF5-1.10.5, the macros introduced in HDF5-1.10.3 were removed. The H5Oget_info*1 and H5Ovisit*1 APIs were copied to H5Oget_Info* and H5Ovisit*. As an example, H5Oget_info and H5Oget_info1 are identical in this release. + + + +In the C++ Wrapper + +The following C++ wrapper was added: + +H5Object::visit() +Wrapper for the C API H5O_VISIT2. Recursively visit elements reachable from an HDF5 object and perform a common set of operations across all of those elements. See H5O_VISIT2 for more information on this function. + + + +In the Fortran Wrapper + +The following Fortran wrappers were added or changed: + +h5fget_dset_no_attrs_hint_f + +h5fset_dset_no_attrs_hint_f + +h5pget_dset_no_attrs_hint_f + +h5pset_dset_no_attrs_hint_f + +Wrappers for the dataset object header minimization calls. See H5F_GET_DSET_NO_ATTRS_HINT, H5F_SET_DSET_NO_ATTRS_HINT, H5P_GET_DSET_NO_ATTRS_HINT, and H5P_SET_DSET_NO_ATTRS_HINT. +h5ovisit_f + +h5oget_info_by_name_f + +h5oget_info + +h5oget_info_by_idx + +h5ovisit_by_name_f + +Added new Fortran 'fields' optional parameter. See H5O_VISIT2, H5O_GET_INFO_BY_NAME2, H5O_GET_INFO2, H5O_GET_INFO_BY_IDX2, and H5O_VISIT_BY_NAME2. + + + +The following Fortran utility function was added: + +h5gmtime converts (C) 'time_t' structure to Fortran DATE AND TIME storage format + + +A new Fortran derived type was added: + +c_h5o_info_t +This is interoperable with C's h5o_info_t. This is needed for callback functions which pass C's h5o_info_t data type definition. + +See the Fortran signature for H5O_GET_INFO2. + + + +In the Java wrapper + +The following Java wrappers were added or changed: + +H5Fset_libver_bounds See the C API H5F_SET_LIBVER_BOUNDS for information on this function +H5Fget_dset_no_attrs_hint + +H5Fset_dset_no_attrs_hint + +H5Pget_dset_no_attrs_hint + +H5Pset_dset_no_attrs_hint + +Wrappers for the dataset object header minimization calls See H5F_GET_DSET_NO_ATTRS_HINT, H5F_SET_DSET_NO_ATTRS_HINT, H5P_GET_DSET_NO_ATTRS_HINT, and H5P_SET_DSET_NO_ATTRS_HINT for more information on these APIs. +Compatibility Notes and Reports +See these API Compatibility Reports for 1.10 for information regarding compatibility with previous releases. Reports are available comparing HDF5-1.10.5 vs 1.10.2, HDF5-1.10.5 vs 1.10.3, and HDF5-1.10.5 vs 1.10.4. + + + +Release 1.10.4 versus Release 1.10.3 +See the API compatibility Report for information regarding compatibility with previous releases + + + +Release 1.10.3 versus Release 1.10.2 +New and Changed Functions, Classes, Subroutines, Wrappers, and Macros +In the C Interface (main library) + +The following are new C functions in this release: + +H5D_READ_CHUNK Moved from HDF5 High Level Optimizations library to core library +H5D_WRITE_CHUNK Moved from HDF5 High Level Optimizations library to core library +H5O_GET_INFO + +H5O_GET_INFO1 + +H5O_GET_INFO2 + +The function H5O_GET_INFO was moved to H5O_GET_INFO1, and the macro H5O_GET_INFO was created that can be mapped to either H5O_GET_INFO1 or H5O_GET_INFO2. For HDF5-1.10 and earlier releases, H5O_GET_INFO is mapped to H5O_GET_INFO1 by default. +H5O_GET_INFO_BY_IDX + +H5O_GET_INFO_BY_IDX1 + +H5O_GET_INFO_BY_IDX2 + +The function H5O_GET_INFO_BY_IDX was moved to H5O_GET_INFO_BY_IDX1, and the macro H5O_GET_INFO_BY_IDX was created that can be mapped to either H5O_GET_INFO_BY_IDX1 or H5O_GET_INFO_BY_IDX2. For HDF5-1.10 and earlier releases, H5O_GET_INFO_BY_IDX is mapped to H5O_GET_INFO_BY_IDX1 by default. +H5O_GET_INFO_BY_NAME + +H5O_GET_INFO_BY_NAME1 + +H5O_GET_INFO_BY_NAME2 + +The function H5O_GET_INFO_BY_NAME was moved to H5O_GET_INFO_BY_NAME1, and the macro H5O_GET_INFO_BY_NAME was created that can be mapped to either H5O_GET_INFO_BY_NAME1 or H5O_GET_INFO_BY_NAME2. For HDF5-1.10 and earlier releases, H5O_GET_INFO_BY_NAME is mapped to H5O_GET_INFO_BY_NAME1 by default. +H5O_VISIT + +H5O_VISIT1 + +H5O_VISIT2 + +The function H5O_VISIT was moved to H5O_VISIT1, and the macro H5O_VISIT was created that can be mapped to either H5O_VISIT1 or H5O_VISIT2. For HDF5-1.10 and earlier releases, H5O_VISIT is mapped to H5O_VISIT1 by default. +H5O_VISIT_BY_NAME + +H5O_VISIT_BY_NAME1 + +H5O_VISIT_BY_NAME2 + +The function H5O_VISIT_BY_NAME was moved to H5O_VISIT_BY_NAME1, and the macro H5O_VISIT_BY_NAME was created that can be mapped to either H5O_VISIT_BY_NAME1 or H5O_VISIT_BY_NAME2. For HDF5-1.10 and earlier releases, H5O_VISIT_BY_NAME is mapped to H5O_VISIT_BY_NAME1 by default. + + +In the C High Level Interface + +The following C functions were deprecated in this release: + +H5DO_READ_CHUNK Deprecated, moved to H5D_READ_CHUNK +H5DO_WRITE_CHUNK Deprecated, moved to H5D_WRITE_CHUNK + + +In the C++ Wrapper + +Several C++ wrappers were added or modified to provide additional support. See the API Compatibility Report for details. + +Compatibility Notes and Report +See the API Compatibility Report for information regarding compatibility with previous releases. + +Release 1.10.2 versus Release 1.10.1 +This section lists interface-level changes and other user-visible changes in behavior in the transition from HDF5 Release 1.10.1 to Release 1.10.2. + +New and Changed Functions, Classes, Subroutines, Wrappers, and Macros +In the C Interface (main library) + +The following are new C functions in this release: + +H5D_GET_CHUNK_STORAGE_SIZE Returns storage amount allocated within a file for a raw data chunk in a dataset +H5F_GET_EOA Retrieves the file’s EOA +H5F_INCREMENT_FILESIZE +Sets the file’s EOA to the maximum of (EOA, EOF) + increment + +H5F_SET_LIBVER_BOUNDS Enables the switch of version bounds setting for a file +H5FDdriver_query Queries a VFL driver for its feature flags when a file is not available (not documented in Reference Manual) +H5P_GET_VIRTUAL_PREFIX Retrieves prefix applied to VDS source file paths +H5P_SET_VIRTUAL_PREFIX Sets prefix to be applied to VDS source file paths + + +The following C functions changed in this release: + +H5P_SET_LIBVER_BOUNDS HDF5-1.10 was added to the range of versions +H5P_SET_VIRTUAL A change was made to the method of searching for VDS source files +H5PL* The parameters for many of the H5PL APIs were renamed + + +In the C High Level Interface + +The following new C function was added to this release: + +H5DO_READ_CHUNK Reads a raw data chunk directly from a dataset in a file + + +In the C++ Wrapper + +The following C++ wrappers were added: + +H5Lcreate_soft +Creates a soft link from link_name to target_name + +H5Lcreate_hard +Creates a hard link from new_name to curr_name + +H5Lcopy +Copy an object from a group of file + +H5Lmove +Rename an object in a group or file + +H5Ldelete +Removes the specified link from this location + +H5Tencode +Creates a binary object description of this datatype + +H5Tdecode +Returns the decoded type from the binary object description + +H5Lget_info +Returns the information of the named link + + + +These were also added: + +Class LinkCreatPropList for link create property list + +Overloaded functions H5Location::createGroup to take a link creation property list + +See the API Compatibility report for complete details. + + + +In the Java Wrapper + +The following Java wrappers were added: + +H5Pset_evict_on_close +Controls the library's behavior of evicting metadata associated with a closed object +H5Pget_evict_on_close +Retrieves the file access property list setting that determines whether an HDF5 object will be evicted from the library's metadata cache when closed +H5Pset_chunk_opts +Sets the edge chunk option in a dataset creation property list +H5Pget_chunk_opts +Retrieves the edge chunk option setting from a dataset creation property list + +H5Pset_efile_prefix +Sets the external dataset storage file prefix in the dataset access property list + +H5Pget_efile_prefix +Retrieves the prefix for external raw data storage files as set in the dataset access property list + +H5Pset_virtual_prefix +Sets prefix to be applied to VDS source file paths + +H5Pget_virtual_prefix +Retrieves prefix applied to VDS source file paths + +See the Release.txt file for details. + +Tools +New options were added to the h5clear utility: + +--filesize Print the file’s EOA and EOF +--increment=C +Set the file’s EOA to the maximum of (EOA, EOF) + C for the file + +C is >= 0; C is optional and will default to 1M when not set + + + +A new option was added to h5diff: + +--enable-error-stack Enable the error stack +Compatibility Notes and Report +See API Compatibility Reports for 1.10 for information regarding compatibility with previous releases. + +Release 1.10.1 versus Release 1.10.0 (and 1.10.0-patch1) +This section lists interface-level changes and other user-visible changes in behavior in the transition from HDF5 Release 1.10.0 (and HDF5-1.10.0-patch1) to Release 1.10.1. + +New Features +Several new features are introduced in HDF5 Release 1.10.1. + +Metadata Cache Image + +Metadata Cache Evict on Close + +Paged Aggregation + +Page Buffering + +New Features, including associated C Functions +The following features are described and documented in New Features in HDF5 Release 1.10. Each new feature in 1.10.1 is listed below along with the associated C functions: + +Metadata Cache Image: + + +H5Pget_mdc_image_config + +Retrieves the metadata cache image configuration values for a file access property list. + +H5Pset_mdc_image_config + +Sets the metadata cache image option for a file access property list. + +H5Fget_mdc_image_info + +Gets information about a metadata cache image if it exists. + +Metadata Cache Evict on Close: + + +H5Pget_evict_on_close + +Retrieves the property list setting that determines whether an HDF5 object will be evicted from the library's metadata cache when it is closed. + +H5Pset_evict_on_close + +Controls the library's behavior of evicting metadata associated with a closed object. + +Paged Aggregation: + + +H5Pget_file_space_page_size + +Retrieves the file space page size for a file creation property list. + +H5Pset_file_space_page_size + +Sets the file space page size (used with paged aggregation) for a file creation property list. + +H5Pget_file_space_strategy + +Retrieves the file space handling strategy for a file creation property list. + +H5Pset_file_space_strategy + +Sets the file space allocation strategy for a file creation property list. + +Page Buffering: + + +H5Pget_page_buffer_size + +Retrieves the maximum size for the page buffer and the minimum percentage for metadata and raw data pages. + +H5Pset_page_buffer_size + +Sets the maximum size for the page buffer and the minimum percentage for metadata and raw data pages. + +H5Fget_page_buffering_stats + +Retrieves statistics about page access when it is enabled. + +H5Freset_page_buffering_stats + +Resets the page buffer statistics. + +New and Changed Functions, Classes, Subroutines, Wrappers, and Macros +In the C Interface (main library) + +The following new C functions were added: + +H5PLappend + +H5PLget + +H5PLinsert + +H5PLprepend + +H5PLremove + +H5PLreplace + +H5PLsize + + +In the C++ Wrapper + +New member functions were added to provide const versions. For example, these methods, + +ArrayType::getArrayDims ( hsize_t* dims ) const + +ArrayType::getArrayNDims ( ) const + + + +replace these: + +ArrayType::getArrayDims ( hsize_t* dims ) + +ArrayType::getArrayNDims ( ) + +Several functions were moved to other classes. For example, this method, + +H5Location::openDataSet ( char const* name ) const + +replaces: + +CommonFG::openDataSet ( char const* name ) const + + + +PLEASE review the Compatibility report below for complete information on the C++ changes in this release. + +Compatibility Report +Compatibility report for Release 1.10.1 versus Release 1.10.0-patch1 + +See API Compatibility Reports for 1.10 for information regarding compatibility with previous releases. + +Release 1.10.0 of March 2016 versus Release 1.8.16 +This section lists interface-level changes and other user-visible changes in behavior in the transition from HDF5 Release 1.8.16 to Release 1.10.0. + +Changed Type +hid_t + +Changed from a 32-bit to a 64-bit value. + +hid_t is the type is used for all HDF5 identifiers. This change, which is necessary to accomodate the capacities of modern computing systems, therefore affects all HDF5 applications. If an application has been using HDF5’s hid_t the type, recompilation will normally be sufficient to take advantage of HDF5 Release 1.10.0. If an application uses an integer type instead of HDF5’s hid_t type, those identifiers must be changed to a 64-bit type when the application is ported to the 1.10.x series. + +New Features and Feature Sets +Several new features are introduced in HDF5 Release 1.10.0. + +Single-Writer / Multiple-Reader or SWMR + +Collective Metadata I/O + +Fine-tuning the metadata cache + +File Space Management + +Virtual Datasets or VDS + + + +Partial Edge Chunk Options + +Relative Pathnames for External Links + +Property List Encoding and Decoding + + + +More substantial lists follow, including new and modified C functions and Fortran subroutines. + +New Features, including associated C Functions and Fortran Wrappers +The following features are described and documented in New Features in HDF5 Release 1.10.0. On this page, we list each feature and its associated C functions and Fortran wrappers. + +Single-writer / Multiple-reader, commonly called SWMR: + + +H5Fstart_swmr_write + +Enables SWMR writing mode for a file. + +H5DOappend + +Appends data to a dataset along a specified dimension. +(This is a high-level API.) + +H5Pget_append_flush + +Retrieves the values of the append property that is set up in the dataset access property list. + +H5Pset_append_flush + +Sets two actions to perform when the size of a dataset’s dimension being appended reaches a specified boundary. + +H5Pget_object_flush_cb + +Retrieves the object flush property values from the file access property list. + +H5Pset_object_flush_cb + +Sets a callback function to invoke when an object flush occurs in the file. + +H5Odisable_mdc_flushes + +Prevents metadata entries for an HDF5 object from being flushed from the metadata cache to storage. + +H5Oenable_mdc_flushes + +Returns the cache entries associated with an HDF5 object to the default metadata flush and eviction algorithm. + +H5Oare_mdc_flushes_disabled + + + +Determines if an HDF5 object (dataset, group, committed datatype) has had flushes of metadata entries disabled. + +H5Fdisable_mdc_flushes + +Globally prevents dirty metadata entries from being flushed from the metadata cache to storage. + +H5Fenable_mdc_flushes + +Returns a file’s metadata cache to the standard eviction and flushing algorithm. + +H5Fare_mdc_flushes_disabled + + + +Determines if flushes have been globally disabled for a file’s metadata cache. + +H5Fget_mdc_flush_disabled_obj_ids + + + +Returns a list of all object identifiers for which flushes have been disabled in a file’s metadata cache. + + +Command-line Tools: + +h5watch + +Allows users to output new records appended to a dataset under SWMR access as it grows. The functionality is similar to the Unix user command tail with the follow option, which outputs appended data as the file grows. + +h5format_convert + +This tool allows users to convert the indexing type of a chunked dataset made with a 1.10.x version of the HDF5 Library when the latest file format is used to the 1.8.x version 1 B-tree indexing type. For example, datasets created using SWMR access, can be converted to be accessed by the HDF5 1.18 library and tools. The tool does not rewrite raw data, but it does rewrite HDF5 metadata. + +Collective Metadata I/O: + + +H5Pset_coll_metadata_write +h5pset_coll_metadata_write_f + +Establishes I/O mode property setting, collective or independent, for metadata writes. + +H5Pget_coll_metadata_write +h5pget_coll_metadata_write_f + +Retrieves I/O mode property setting for metadata writes. + +H5Pset_all_coll_metadata_ops +h5pset_all_coll_metadata_ops_f + +Establishes I/O mode, collective or independent, for metadata read operations. + +H5Pget_all_coll_metadata_ops +h5pget_all_coll_metadata_ops_f + +Retrieves I/O mode for metadata read operations. + + + +Fine-tuning the Metadata Cache: + + +H5Fget_metadata_read_retries_info + + + +Retrieves the collection of read retries for metadata items with checksum. + +H5Pget_metadata_read_attempts + + + +Retrieves the number of read attempts from a file access property list. + +H5Pset_metadata_read_attempts + + + +Sets the number of read attempts in a file access property list. + +H5Dflush + +Causes all buffers associated with a dataset to be immediately written to disk without removing the data from the cache. + +H5Drefresh + +Causes all buffers associated with a dataset to be cleared and immediately re-loaded with updated contents from disk storage. + +H5Gflush + +Causes all buffers associated with a group to be immediately flushed to disk without removing the data from the cache. + +H5Grefresh + +Causes all buffers associated with a group to be cleared and immediately re-loaded with updated contents from disk storage. + +H5Oflush + +Causes all buffers associated with an object to be immediately flushed to disk without removing the data from the cache. + +H5Orefresh + +Causes all buffers associated with an object to be cleared and immediately re-loaded with updated contents from disk storage. + +H5Tflush + +Causes all buffers associated with a committed datatype to be immediately flushed to disk without removing the data from the cache. + +H5Trefresh + +Causes all buffers associated with a committed datatype to be cleared and immediately re-loaded with updated contents from disk storage. + +H5Fget_intent + +Determines the read/write or read-only status of a file. + + +Logging APIs: + +H5Pset_mdc_log_options + +Sets metadata cache logging options. + +H5Pget_mdc_log_options + +Gets metadata cache logging options. + +H5Fstart_mdc_logging + +Starts logging metadata cache events if logging was previously enabled. + +H5Fstop_mdc_logging + +Stops logging metadata cache events if logging was previously enabled and is currently ongoing. + +H5Pget_mdc_logging_status + + + +Gets the current metadata cache logging status. + +File Space Management: + + +H5Fget_free_sections + + + +Retrieves free-space section information for a file. + +H5Fget_freespace + + + +Returns the amount of free space in a file. + +H5Fget_info2 + + + +Returns global information for a file. + +H5Pset_file_space + + + +Sets the file space management strategy and/or the free-space section threshold for an HDF5 file. + +H5Pget_file_space + + + +Retrieves the file space management strategy and/or the free-space section threshold for an HDF5 file. + + + + +The following tool has been modified to preserve or modify file freepace information appropriately when processing files employing the VDS feature: + +h5repack + +Repacks HDF5 files with various options, including the ability to change the applied filters. This version of h5repack understands the file free space feature and handles the file and metadata appropriately. + +Virtual Dataset or VDS: + + +H5Pset_virtual +h5pset_virtual_f + +Sets the mapping between virtual and source datasets. + +H5Pget_virtual_count +h5pget_virtual_count_f + +Retrieves the number of mappings for the virtual dataset. + +H5Pget_virtual_vspace +h5pget_virtual_vspace_f + +Retrieves a dataspace identifier for the selection within the virtual dataset used in the mapping. + +H5Pget_virtual_srcspace +h5pget_virtual_srcspace_f + +Retrieves a dataspace identifier for the selection within the source dataset used in the mapping. + +H5Pget_virtual_dsetname +h5pget_virtual_dsetname_f + +Retrieves the name of a source dataset used in the mapping. + +H5Pget_virtual_filename +h5pget_virtual_filename_f + +Retrieves the filename of a source dataset used in the mapping. + +H5Pset_virtual_printf_gap +h5pset_virtual_printf_gap_f + +Sets maximum number of missing source files and/or datasets with printf-style names when getting the extent of an unlimited virtual dataset. + +H5Pget_virtual_printf_gap +h5pget_virtual_printf_gap_f + +Returns maximum number of missing source files and/or datasets with printf-style names when getting the extent for an unlimited virtual dataset. + +H5Pset_virtual_view +h5pset_virtual_view_f + +Sets the view of the virtual dataset to include or exclude missing mapped elements. + +H5Pget_virtual_view +h5pget_virtual_view_f + +Retrieves the view of a virtual dataset. + + +Supporting Functions: + +H5Sis_regular_hyperslab +h5sis_regular_hyperslab_f + +Determines whether a hyperslab selection is regular. + +H5Sget_regular_hyperslab +h5sget_regular_hyperslab_f + +Retrieves a regular hyperslab selection. + + +Modified Functions: +The following pre-exising functions have been modified to understand virtual datasets. + +H5Pset_layout +h5pset_layout_f + +Specifies the layout to be used for a dataset. +Virtual dataset, H5D_VIRTUAL, has been added to the list of layouts available through this function. + +H5Pget_layout +h5pget_layout_f + +Retrieves the layout in use for a dataset. +Virtual dataset, H5D_VIRTUAL, has been added to the list of layouts. + +Partial Edge Chunks: + + +H5Pset_chunk_opts + +Sets a partial edge chunk option in a dataset access property list. + +H5Pget_chunk_opts + +Retrieves partial edge chunk option setting from a dataset access property list. + +Relative Pathnames for External Links: + + +H5Pset_elink_prefix + +These functions enable the user to specify the locations of external files. +(These functions are not yet documented.) + +H5Pget_elink_prefix + +Property List Encoding and Decoding: + + +H5Pencode + +H5Pdecode + +Additional New Functions: + + +The following new functions appear in HDF5 Release 1.10.0 but are not yet documented: + + + H5Dformat_convert + H5Dget_chunk_index_type + + H5FDlock + H5FDunlock + + H5Fformat_convert + + H5LDget_dset_dims + H5LDget_dset_elmts + H5LDget_dset_type_size +New and Changed Elements of the Packet Table (H5PT) High-level API +In the C Interface + +Replacement functions: + +H5PTcreate + +Takes a property list identifier to provide flexibility on creation properties. + +H5PTcreate_fl has been removed. + +H5PTfree_vlen_buff + +Replaces H5PTfree_vlen_readbuff. + +New functions: + +Two accessor functions have been added. + +H5PTget_dataset + +Returns the identifier of the dataset associated a packet table. + +H5PTget_type + +Returns the identifier of the datatype used by a packet table. + +H5PTis_varlen + +Determines whether a type is variable-length. + +In the C++ Interface + +Overloaded constructor + +An overloaded constructor has been added. + +FL_PacketTable + +Takes a property list identifier to provide flexibility on creation properties.>/dd> + +H5PTfree_vlen_buff + +Replaces H5PTfree_vlen_readbuff. + +Accessor wrappers + +Two accessor wrappers are added to class PacketTable. + +PacketTable::GetDataset() + +Returns the identifier of the dataset associated a packet table. + +PacketTable::GetDatatype() + +Returns the identifier of the datatype used by a packet table. + +Other wrappers + +PacketTable::FreeBuff() + +Replaces VL_PacketTable::FreeReadBuff(). + +PacketTable::IsVariableLength() + +Replaces VL_PacketTable::IsVariableLength(). + +Overloaded functions: + +Where a member functions has a char* as an argument, an overloaded functions has been added to provide the const char* argument. + +The existing version will be deprecated in a future release. + +Java Interface Changes +Integration into Main HDF5 Library + +The Java HDF5 JNI library has been integrated into the HDF5 repository. + +Configure option: + +--enable-java + +CMake option: + +HDF5_BUILD_JAVA:BOOL=ON + +Prior to the 1.10.x series, the HDF5 Java tools were built from an independent repository and were not as fully integrated with HDF5. were built from an independent repository and were not as fully integrated with HDF5. + +Package Hierarchy Change + +The package hierarchy has changed to hdf.hdflib.hdf5. + +Prior to the 1.10.x series, the hierarchy was ncsa.hdf.hdflib.hdf5. + +New Java APIs + +A number of new APIs have been added in the Java interface, including APIs for the VDS and SWMR features. + +Functions with Changed Behavior +H5Lexists + +The behavior of this function has changed in this release. When testing the pathname / (a slash representing the root of an HDF5 file) H5Lexists now returns successfully with the value 1 (one). See the entry in the HDF5 Reference Manual for H5Lexists for more information. + +API Compatibility +See API Compatibility Macros in HDF5 for details on the following. + +New API Compatibility Flag + +A new v18 flag was added enabling the building of HDF5 such that the default API is compatible with the HDF5 Release 1.8.x API: + --with-default-api-version=v18 + +New versioned functions and associated compatibility macros + +Two functions and a struct have been converted to a versioned form in this release. Compatibility macros have been created for each. + +H5Fget_info + +The original function is renamed to H5Fget_info1 and deprecated. + +A new version of the function, H5Fget_info2, is introduced. + +The compatiblity macro H5Fget_info is introduced. + +H5F_info_t + +This is the struct used by the H5Fget_info functions and macro. + +The original struct is renamed to H5F_info1_t and deprecated. + +A new version of the struct, H5F_info2_t, is introduced. + +The compatiblity macro H5F_info_t is introduced. + +H5Rdereference + +The original function is renamed to H5Rdereference1 and deprecated. + +A new version of the function, H5Rdereference2, is introduced. + +The compatiblity macro H5Rdereference is introduced. + +Autotools Configuration and Large File Support +Autotools configuration has been extensively reworked and autotool’s handling of large file support has been overhauled in this release. + +See the following sections in RELEASE.txt: + +“Autotools Configuration Has Been Extensively Reworked” +“LFS Changes” +RELEASE.txt is found in the release_docs/ subdirectory at the root level of the HDF5 code distribution. + +Compatibility Report and Comments +Compatibility report for Release 1.10.0 versus Release 1.8.16 + + See API Compatibility Reports for 1.10 for information regarding compatibility with previous releases. + +Comments regarding the report + +In the C interface, the hid_t change from 32-bit to 64-bit was made in order to address a performance problem that arose when the library “ran out” of valid object identifiers to issue and thus needed to employ an expensive algorithm to find previously issued identifiers that could be re-issued. This problem is avoided by switching the size of the hid_t type to 64-bit integers instead of 32-bit integers in order to make the pool of available integers significantly larger. (H5E_major_t and H5E_minor_t are aliased to hid_t which is why they changed size as well). (An alternate solution to this problem was applied in release HDF5 1.8.5 but this is the cleaner/preferred solution and had to wait until 1.10.0 to be included). + +hbool_t will now be defined as a _Bool type when configure determines that it’s available. + +Public structs that have members of type hid_t or hbool_t are affected by the above changes accordingly. + +The H5Fget_info function was renamed due to the introduction of a newer version of the function which returns additional information. The H5Rdereference function was renamed due to the introduction of a newer version of the function which allows a data access property list to be passed in. Both changes are accompanied with compatibility macros, so while existing code will need to be recompiled in order to use the newer library version, these functions do not need to be changed in application code using them provided that the HDF5 API compatibility macros are configured appropriately. \ No newline at end of file diff --git a/documentation/hdf5-docs/release_specifics/sw_changes_1.12.md b/documentation/hdf5-docs/release_specifics/sw_changes_1.12.md new file mode 100644 index 00000000..773e270f --- /dev/null +++ b/documentation/hdf5-docs/release_specifics/sw_changes_1.12.md @@ -0,0 +1,224 @@ +For a description of the major new features that were introduced, please see New Features in HDF5 Release 1.12. + +This page provides information on the changes that a maintenance developer needs to be aware of between successive releases of HDF5, such as: + +New or changed features or tools +Syntax and behavioral changes in the existing application programming interface (the API) +Certain types of changes in configuration or build processes +Note that bug fixes and performance enhancements in the C library are automatically picked up by the C++, Fortran, and Java libraries. + +The following information is included below. + +Release 1.12.2 versus Release 1.12.1 +Release 1.12.1 versus Release 1.12.0 +Release 1.12.0 versus Release 1.10.6 +The release notes also list changes made to the library, but these notes tend to be more at a more detail-oriented level. The release notes may include new features, bugs fixed, supported configuration features, platforms on which the library has been tested, and known problems. The release note files are listed below and can be found at the top level of the HDF5 source code tree in the release_docs directory. + +Release Notes + +Technical notes regarding the current release of the HDF5 library (RELEASE.txt in the source code) + +HISTORY-1_12.txt + +Release information for HDF5-1.12.0 through 1.12.1 + +HISTORY-1_10_0-1_12_0.txt + +Development history between the HDF5-1.10.0 and HDF5-1.12.0 releases + +HISTORY-1_10.txt + +Release information for all HDF5-1.10 releases + +HISTORY-1_8_0-1_10_0.txt + +Development history between the HDF5-1.8.0 and HDF5-1.10.0 releases + +HISTORY-1_8.txt + +Release information for HDF5-1.8.0 through 1.8.21 + +HISTORY-1_0-1_8_0_rc3.txt + +Technical notes starting with HDF5-1.0.0 and ending with HDF5-1.8.0-rc3 (the state of the code prior to the HDF5-1.8.0 release) + +Release 1.12.2 versus Release 1.12.1 +This section lists interface-level changes and other user-visible changes in behavior in the transition from HDF5 Release 1.12.1 to Release 1.12.2. + +New and Changed Functions, Classes, Subroutines, Wrappers, and Macros +In the C Interface (main library) and the High-level Interface + +The following are new C functions in this release: + +H5DSwith_new_ref Determines if new references are used with dimension scales +H5LTget_attribute_ullong Reads an unsigned long long attribute +H5LTset_attribute_ullong Create an unsigned long long attribute +H5VLobject_is_native Determines whether an object ID represents a native VOL connector object +See API Compatibility Reports for 1.12.2 for complete details. + +Release 1.12.1 versus Release 1.12.0 +This section lists interface-level changes and other user-visible changes in behavior in the transition from HDF5 Release 1.12.0 to Release 1.12.1. + +New and Changed Functions, Classes, Subroutines, Wrappers, and Macros +In the C Interface (main library) + +The following are new C functions in this release: + +H5P_GET_FAPL_SPLITTER +Retrieves information for a splitter file access property list +H5P_SET_FAPL_SPLITTER Sets the file access property list to use the splitter driver +H5P_GET_FILE_LOCKING Gets the file locking property values +H5P_SET_FILE_LOCKING Sets the file locking property values +H5_GET_ALLOC_STATS +Gets the memory allocation statistics for the library +H5_GET_FREE_LIST_SIZES Gets the current size of the free lists used to manage memory +H5S_SEL_ITER_RESET Resets a dataspace selection iterator back to an initial state +H5VL_QUERY_OPTIONAL Determines whether a VOL connector supports a particular optional callback operation + + +In the C++ Wrapper + +The following C++ wrappers were added: + +DataSet::operator= +Operator= for DataSet class + +FileAccPropList::getFileLocking +See H5P_GET_FILE_LOCKING for details + +FileAccPropList::setFileLocking +See H5P_SET_FILE_LOCKING for details + +See the API Compatibility report for complete details. + +Compatibility Notes and Report +See API Compatibility Reports for 1.12 for information regarding compatibility with previous releases. + +Release 1.12.0 versus Release 1.10.6 +This section lists interface-level changes and other user-visible changes in behavior in the transition from HDF5 Release 1.10.6 to Release 1.12.0. + +New Features +For a description of the major new features that were introduced, please see New Features in HDF5 Release 1.12. + +New and Changed Functions, Classes, Subroutines, Wrappers, and Macros +In the C/Fortran Interface (main library) + +Folllowing are the new or changed APIs introduced in HDF5-1.12.0. Those introduced with a new feature list the specific new feature that they were added for. + +H5F_DELETE N Deletes an HDF5 file +H5F_GET_FILENO Y Retrieves a file's file number that uniquely identifies the open file +H5F_IS_ACCESSIBLE Y Determines if a file can be opened with a given fapl + +H5I_ITERATE N Calls a callback for each member of the identifier type specified + +H5L_GET_INFO, H5L_GET_INFO1, H5L_GET_INFO2 Y (no change) +The function H5L_GET_INFO was moved to H5L_GET_INFO1, and H5L_GET_INFO2 was introduced. The macro H5L_GET_INFO was created that can be mapped to either H5L_GET_INFO1 or H5L_GET_INFO2. For HDF5-1.12, H5L_GET_INFO is mapped to H5L_GET_INFO2 by default. In earlier releases, H5L_GET_INFO is mapped to H5L_GET_INFO1. + +H5L_GET_INFO_BY_IDX, H5L_GET_INFO_BY_IDX1, H5L_GET_INFO_BY_IDX2 Y (no change) The function H5L_GET_INFO_BY_IDX was moved to H5L_GET_INFO_BY_IDX1, and H5L_GET_INFO_BY_IDX2 was introduced. The macro H5L_GET_INFO_BY_IDX was created that can be mapped to either H5L_GET_INFO_BY_IDX1 or H5L_GET_INFO_BY_IDX2. For HDF5-1.12, H5L_GET_INFO_BY_IDX is mapped to H5L_GET_INFO_BY_IDX2 by default. In earlier releases, H5L_GET_INFO_BY_IDX is mapped to H5L_GET_INFO_BY_IDX1. +H5L_ITERATE, H5L_ITERATE1, H5L_ITERATE2 Y (no change) The function H5L_ITERATE was moved to H5L_ITERATE1, and H5L_ITERATE2 was introduced. The macro H5L_ITERATE was created that can be mapped to either H5L_ITERATE1 or H5L_ITERATE2. For HDF5-1.12, H5L_ITERATE is mapped to H5L_ITERATE2 by default. In earlier releases, H5L_ITERATE is mapped to H5L_ITERATE1. +H5L_ITERATE_BY_NAME, H5L_ITERATE_BY_NAME1, H5L_ITERATE_BY_NAME2 Y (no change) The function H5L_ITERATE_BY_NAME was moved to H5L_ITERATE_BY_NAME1, and H5L_ITERATE_BY_NAME2 was introduced. The macro H5L_ITERATE_BY_NAME was created that can be mapped to either H5L_ITERATE_BY_NAME1 or H5L_ITERATE_BY_NAME2. For HDF5-1.12, H5L_ITERATE_BY_NAME is mapped to H5L_ITERATE_BY_NAME2 by default. In earlier releases, H5L_ITERATE_BY_NAME is mapped to H5L_ITERATE_BY_NAME1. +H5L_VISIT, H5L_VISIT1, H5L_VISIT2 N The function H5L_VISIT was moved to H5L_VISIT1, and H5L_VISIT2 was introduced. The macro H5L_VISIT was created that can be mapped to either H5L_VISIT1 or H5L_VISIT2. For HDF5-1.12, H5L_VISIT is mapped to H5L_VISIT2 by default. In earlier releases, H5L_VISIT is mapped to H5L_VISIT1. +H5L_VISIT_BY_NAME, H5L_VISIT_BY_NAME1, H5L_VISIT_BY_NAME2 N The function H5L_VISIT_BY_NAME was moved to H5L_VISIT_BY_NAME1, and H5L_VISIT_BY_NAME2 was introduced. The macro H5L_VISIT_BY_NAME was created that can be mapped to either H5L_VISIT_BY_NAME1 or H5L_VISIT_BY_NAME2. For HDF5-1.12, H5L_VISIT_BY_NAME is mapped to H5L_VISIT_BY_NAME2 by default. In earlier releases, H5L_VISIT_BY_NAME is mapped to H5L_VISIT_BY_NAME1. + +H5O_GET_INFO, H5O_GET_INFO3 N/A The function H5O_GET_INFO was replaced by the macro H5O_GET_INFO and the function H5O_GET_INFO3 was added. +H5O_GET_INFO_BY_IDX, H5O_GET_INFO_BY_IDX3 N/A The function H5O_GET_INFO_BY_IDX was replaced by the macro H5O_GET_INFO_BY_IDX. The function H5O_GET_INFO_BY_IDX3 was added. +H5O_GET_INFO_BY_NAME, H5O_GET_INFO_BY_NAME3 N/A The function H5O_GET_INFO_BY_NAME was replaced by the macro H5O_GET_INFO_BY_NAME. The function H5O_GET_INFO_BY_NAME3 was added. +H5O_GET_NATIVE_INFO N Retrieves the native file format information about an object +H5O_GET_NATIVE_INFO_BY_IDX N Retrieves native file format information about an object according to the order of an index +H5O_GET_NATIVE_INFO_BY_NAME N Retrieves native file format information about an object given its name +H5O_OPEN_BY_TOKEN Y Opens an object in an HDF5 file using its VOL independent token +H5O_TOKEN_CMP Y Compares two VOL connector object tokens +H5O_TOKEN_FROM_STR N Deserializes a string into a connector object token +H5O_TOKEN_TO_STR N Serializes a connector's object token into a string +H5O_VISIT, H5O_VISIT3 N/A The function H5O_VISIT was replaced by the macro H5O_VISIT and the function H5O_VISIT3 was added +H5O_VISIT_BY_NAME, H5O_VISIT_BY_NAME3 N/A The function H5O_VISIT_BY_NAME was replaced by the macro H5O_VISIT_BY_NAME, and the function H5O_VISIT_BY_NAME3 was added. + +H5P_ENCODE, H5P_ENCODE1, H5P_ENCODE2 + +N +Encodes properties on a property list into a buffer + +The previous function was renamed to H5P_ENCODE1 and deprecated, and the macro H5P_ENCODE was introduced. + +H5P_GET_VOL_ID Y Returns the identifier of the current VOL connector +H5P_GET_VOL_INFO N Returns a copy of the VOL information for a connector +H5P_SET_VOL Y Set the file VOL connector for a file access property list + +H5R_COPY N Copies an existing reference +H5R_CREATE_ATTR N Creates an attribute reference +H5R_CREATE_OBJECT N Creates an object reference +H5R_CREATE_REGION N Creates a region reference +H5R_DESTROY N Closes a reference +H5R_EQUAL N Determines whether two references are equal +H5R_GET_ATTR_NAME N Retrieves the attribute name for a referenced object +H5R_GET_FILE_NAME N Retrieves the file name for a referenced object +H5R_GET_OBJ_NAME N Retrieves the object name for a referenced object +H5R_GET_OBJ_TYPE3 N Retrieves the type of object that an object reference points to +H5R_GET_TYPE N Retrieves the type of reference +H5R_OPEN_ATTR N Opens the referenced HDF5 attribute +H5R_OPEN_OBJECT N Opens the referenced HDF5 object +H5R_OPEN_REGION N Sets up a dataspace and selection as specified by a region reference + +H5S_COMBINE_HYPERSLAB N Performs an operation on a hyperslab and an existing selection and returns the resulting selection +H5S_COMBINE_SELECT N +Combines two hyperslab selections with an operation, returning a dataspace with the resulting selection + +H5S_ENCODE, H5S_ENCODE1, H5S_ENCODE2 + +N/A +Encodes a dataspace object description into a binary buffer + +The function H5S_ENCODE was renamed to H5S_ENCODE1 and deprecated in this release. The macro H5S_ENCODE and the function H5S_ENCODE2 were introduced in this release. + +H5S_MODIFY_SELECT N +Refines a hyperslab selection with an operation using a second hyperslab to modify it + +H5S_SEL_ITER_CLOSE +N + +Closes a dataspace selection iterator + +H5S_SEL_ITER_CREATE N Creates a dataspace selection iterator for a dataspace's selection +H5S_SEL_ITER_GET_SEQ_LIST N Retrieves a list of offset / length sequences for the elements in an iterator +H5S_SELECT_ADJUST N Adjusts a selection by subtracting an offset +H5S_SELECT_COPY N Copies a selection from one dataspace to another +H5S_SELECT_INTERSECT_BLOCK N Checks if current selection intersects with a block +H5S_SELECT_PROJECT_INTERSECTION N Projects the intersection of two source selections to a destination selection +H5S_SELECT_SHAPE_SAME N +Checks if two selections are the same shape + + +H5T_RECLAIM N Frees the buffers allocated for storing variable-length data in memory + +H5VL_CLOSE Y Closes a VOL connector identifier +H5VL_GET_CONNECTOR_ID Y Retrieves the VOL connector identifier for a given object identifier +H5VL_GET_CONNECTOR_ID_BY_NAME Y Retrieves the identifier for a registered VOL connector name +H5VL_GET_CONNECTOR_ID_BY_VALUE Y Retrieves the identifier for a registered VOL connector value +H5VL_GET_CONNECTOR_NAME Y Retrieves the connector name for the VOL associated with the object or file identifier +H5VL_IS_CONNECTOR_REGISTERED_BY_NAME Y Tests whether a VOL class has been registered or not for a connector name +H5VL_IS_CONNECTOR_REGISTERED_BY_VALUE Y Tests whether a VOL class has been registered or not for a connector value +H5VL_REGISTER_CONNECTOR N Registers a new VOL connector +H5VL_REGISTER_CONNECTOR_BY_NAME Y Registers a new VOL connector by name +H5VL_REGISTER_CONNECTOR_BY_VALUE Y Registers a new VOL connector by connector value +H5VL_UNREGISTER_CONNECTOR Y Removes a VOL connector identifier from the library + + +In the C++ Wrapper + +H5File::getFileNum See H5F_GET_FILENO +H5File::isAccessible See H5F_IS_ACCESSIBLE +LinkCreatPropList::getCreateIntermediateGroup See H5P_GET_CREATE_INTERMEDIATE_GROUP +LinkCreatPropList::setCreateIntermediateGroup See H5P_SET_CREATE_INTERMEDIATE_GROUP +H5Location::getLinkInfo See H5L_GET_INFO +H5Location::getNativeObjinfo See H5O_GET_NATIVE_INFO +H5Location::getObjinfo +See H5O_GET_INFO +H5Object::visit See H5O_VISIT + + +API Compatibility +See API Compatibility Macros in HDF5 for details on using HDF5 version 1.12 with previous releases. + +Compatibility report for Release 1.12.0 versus Release 1.10.6 + + \ No newline at end of file diff --git a/documentation/hdf5-docs/release_specifics/sw_changes_1.8.md b/documentation/hdf5-docs/release_specifics/sw_changes_1.8.md new file mode 100644 index 00000000..c3cf875f --- /dev/null +++ b/documentation/hdf5-docs/release_specifics/sw_changes_1.8.md @@ -0,0 +1,4053 @@ +--- +title: HDF5 1.8 +redirect_from: + - display/HDF5/HDF5+1.8+Release +--- + +This document is designed to help developers maintain HDF5-based applications as they are used with successive releases of HDF5. To that end, this document lists the changes at each release that a maintenance developer needs to be aware of: + +New or changed features or tools +Syntax and behavioral changes in the existing application programming interface (the API) +Certain types of changes in configuration or build processes +Bugfixes and performance enhancements in the C library are automatically picked up by the C++ and Fortran libraries. The Java library will pick up the same bugfixes and enhancements at its next subsequent release as it is always built with the latest released version of the C library. + +The release notes also list changes made to the library, but these notes tend to be more at a more detail oriented level. The release notes may include new features, bugs fixed, supported configuration features, platforms on which the library has been tested, and known problems. The release note files are listed below and can be found at the top level of the HDF5 source code tree in the release_docs directory of the distributed HDF5 source code. + +RELEASE.txt + +Technical notes regarding the current release of the HDF5 library + +HISTORY-1_8.txt + +Technical notes for previous 1.8 releases of the HDF5 library by release + +HISTORY-1_0-1_8_0_rc3.txt + + +Technical notes for releases prior to the 1.8.0 release of the HDF5 library by release + +Are you porting an existing application from HDF5 Release 1.6.x to HDF5 Release 1.8.x? +If you are porting an existing application from any HDF5 version in the Release 1.6.x series to any version in the Release 1.8.x series, refer to “What's New in HDF5 1.8.0”. This document, with the documents linked in its introduction, provides a guide to the changes introduced in the transition from the 1.6.x series to HDF5 Release 1.8.0 and discussions of various compatibility issues. + +Release 1.8.23 of February 2023 versus Release 1.8.22 +This section lists interface-level changes and other user-visible changes in behavior in the transition from HDF5 Release 1.8.22 to Release 1.8.23. + +New and Changed Functions, Classes, Subroutines, Wrappers, and Macros +In the C Interface (main library) + +None. + +In the C High Level Interface + +None. + +In the C++ Wrapper + +None. + +Compatibility Notes and Report and Comments +The interface compatibility report provides a full list of the changed symbols. + +Release 1.8.22 of February 2021 versus Release 1.8.21 +This section lists interface-level changes and other user-visible changes in behavior in the transition from HDF5 Release 1.8.21 to Release 1.8.22. + +New and Changed Functions, Classes, Subroutines, Wrappers, and Macros +In the C Interface (main library) + +The following are new C functions in this release: + +H5P_GET_FAPL_HDFS Gets the information of the given Read-Only HDFS virtual file driver +H5P_GET_FAPL_ROS3 Gets the information of the given Read-Only S3 virtual file driver +H5P_SET_FAPL_HDFS Sets up Read-Only HDFS virtual file driver +H5P_SET_FAPL_ROS3 Sets up Read-Only S3 virtual file driver +In the C High Level Interface + +None. + +In the C++ Wrapper + +None. + +Compatibility Notes and Report and Comments +The interface compatibility report provides a full list of the changed symbols. + +Release 1.8.21 of May 2018 versus Release 1.8.20 +This section lists interface-level changes and other user-visible changes in behavior in the transition from HDF5 Release 1.8.20 to Release 1.8.21. + +New and Changed Functions, Classes, Subroutines, Wrappers, and Macros +In the C Interface (main library) + +None. + +In the C High Level Interface + +None. + +In the C++ Wrapper + +Many changes were made to improve the C++ API model. Please review the RELEASE.txt file or the compatibility report below for complete information on the C++ changes in this release. + +Compatibility Notes and Report and Comments +The interface compatibility report provides a full list of the changed symbols. + +Release 1.8.20 of November 2017 versus Release 1.8.19 +This section lists interface-level changes and other user-visible changes in behavior in the transition from HDF5 Release 1.8.19 to Release 1.8.20. + +New and Changed Functions, Classes, Subroutines, Wrappers, and Macros +In the C Interface (main library) + +None. + +In the C High Level Interface + +None. + +In the C++ Wrapper + +Many changes were made to improve the C++ API model. Please review the RELEASE.txt file or the compatibility report below for complete information on the C++ changes in this release. + +Compatibility Notes and Report and Comments +Compatibility report for Release 1.8.20 versus Release 1.8.19 + +The following interface compatibility report provides a full list of the changed symbols: + +API compatibility report for the HDF5 Library between 1.8.19 and 1.8.20 versions on x86_64 + +Release 1.8.19 of June 2017 versus Release 1.8.18 +This section lists interface-level changes and other user-visible changes in behavior in the transition from HDF5 Release 1.8.18 to Release 1.8.19. + +New and Changed Functions, Classes, Subroutines, Wrappers, and Macros +In the C Interface (main library) + +The following new C functions were added: + +H5Dget_chunk_storage_size + +H5PLappend + +H5PLget + +H5PLinsert + +H5PLprepend + +H5PLremove + +H5PLreplace + +H5PLsize + + +In the C High Level Interface + +The following new C function was added: + +H5DOread_chunk + + +In the C++ Wrapper + +Many changes were made to improve the C++ API model. Please review the RELEASE.txt file or Compatibility report below for complete information on the C++ changes in this release. + +Compatibility Notes and Report and Comments +Compatibility report for Release 1.8.19 versus Release 1.8.18 + +The following interface compatibility report provides a full list of the changed symbols: + +API compatibility report for the HDF5 Library between 1.8.18 and 1.8.19 versions on x86_64 + +Release 1.8.18 of November 2016 versus Release 1.8.17 +This section lists interface-level changes and other user-visible changes in behavior in the transition from HDF5 Release 1.8.17 to Release 1.8.18. + +New and Changed Functions, Classes, Subroutines, Wrappers, and Macros +In the C Interface (main library) + +None. + +In the C++ Interface (main library wrappers) + +The macro H5_NO_NAMESPACE was deprecated. + + + +New member functions added to provide const versions: + +DSetCreatPropList::allFiltersAvail() const + +DSetCreatPropList::getAllocTime () const + +DSetCreatPropList::getFillTime () const + +DSetCreatPropList::isFillValueDefined () const + +DSetCreatPropList::setAllocTime (H5D_alloc_time_t alloc_time) const + +DSetCreatPropList::setFillTime (H5D_fill_time_t fill_time) const + +DSetMemXferPropList::getEDCCheck () const + +DSetMemXferPropList::getHyperVectorSize () const + +DSetMemXferPropList::getSmallDataBlockSize () const + +DSetMemXferPropList::setEDCCheck (H5Z_EDC_t check) const + +DSetMemXferPropList::setHyperVectorSize (size_t vector_size) const + +DSetMemXferPropList::setSmallDataBlockSize (hsize_t size) const + +FileAccPropList::getFcloseDegree () const + +FileAccPropList::setFcloseDegree (H5F_close_degree_t degree) const + + + +The following member functions were removed: + +ArrayType::getArrayDims (hsize_t* dims) + +ArrayType::getArrayNDims () + +DataType::commit (H5Location& loc, char const* name) + +DataType::commit (H5Location& loc, std::string const& name) + +DSetCreatPropList::allFiltersAvail () + +DSetCreatPropList::getAllocTime () + +DSetCreatPropList::getFillTime () + +DSetCreatPropList::isFillValueDefined () + +DSetCreatPropList::setAllocTime (H5D_alloc_time_t alloc_time) + +DSetCreatPropList::setFillTime (H5D_fill_time_t fill_time) + +DSetMemXferPropList::getEDCCheck () + +DSetMemXferPropList::getHyperVectorSize () + +DSetMemXferPropList::getSmallDataBlockSize () + +DSetMemXferPropList::setEDCCheck (H5Z_EDC_t check) + +DSetMemXferPropList::setHyperVectorSize (size_t vector_size) + +DSetMemXferPropList::setSmallDataBlockSize (hsize_t size) + +FileAccPropList::getFcloseDegree () + +FileAccPropList::setFcloseDegree (H5F_close_degree_t degree) + +H5Location::H5Location [in-charge] (hid_t const loc_id) + +H5Location::H5Location [not-in-charge] (hid_t const loc_id) + +H5Object::H5Object [in-charge] (hid_t const object_id) + +H5Object::H5Object [not-in-charge] (hid_t const object_id) + +CommonFG::mount (char const* name, H5File& child, PropList& plist) const + +DataSet::getVlenBufSize (DataType& type, DataSpace& space) const + +DataType::commit (H5Location& loc, char const* name) + +DataType::commit (H5Location& loc, std::string const& name) + +Compatibility Notes and Report and Comments +Compatibility report for Release 1.8.18 versus Release 1.8.17 + +The following interface compatibility report provides a full list of the changed symbols: + +API compatibility report for the HDF5 Library between 1.8.17 and 1.8.18 versions on x86_64 + + + + +Release 1.8.17 of May 2016 versus Release 1.8.16 +This section lists interface-level changes and other user-visible changes in behavior in the transition from HDF5 Release 1.8.16 to Release 1.8.17. + +New and Changed Functions, Classes, Subroutines, Wrappers, and Macros +In the C Interface (main library) + +The following new C functions and environment variable enable setting a relative path for raw data files associated with datasets using external storage: + +Functions: + +H5Pset_efile_prefix +H5Pget_efile_prefix + + +Environment variable: + +HDF5_EXTFILE_PREFIX + +In the C High-Level Interface + +The following new functions have been added in the Packet Table (H5PT) high-level interface: + +H5PTcreate +H5PTget_dataset +H5PTget_type + +H5PTcreate replaces H5PTcreate_fl, which is deprecated and may be removed in a future release. + +The following functions were previously removed from the library distribution but are once again publicly available. + +Reinstated in its original form: + +H5PTis_varlen + +An updated form of H5PTfree_vlen_readbuff reinstated as: + +H5PTfree_vlen_buff + +In the C++ Interface (main library wrappers) + +New member function added in DSetCreatPropList: + +DSetCreatPropList::setNbit() was added to set up N-bit compression for a dataset. + +New overloaded const member functions added in ArrayType: + +The following functions were added to provide const versions; the non-const versions have been marked deprecated. + + + ArrayType::getArrayNDims() const + ArrayType::getArrayDims() const + +The datamembers ArrayType::rank and ArrayType::dimensions have been removed. This is an implementation detail and should not affect applications. + +In the C++ High-Level Interface + +New constructor added in FL_PacketTable: + +An overloaded constructor has been added to FL_PacketTable. The function now takes a property list identifier to provide flexibility on creation properties such as compression. + + + FL_PacketTable(hid_t fileID, const char* name, hid_t dtypeID, + hsize_t chunkSize = 0, hid_t plistID = H5P_DEFAULT) + +New member functions added in PacketTable: + +Two accessor wrappers were added to class PacketTable. + +PacketTable::GetDataset() returns the identifier of the dataset associated with the packet table. + +PacketTable::GetDatatype() returns the identifier of the datatype that the packet table uses. + +New member functions added with a char* argument: + +Overloaded functions have been added to provide a const char* argument. The existing versions of these functions will be deprecated in future releases. + +This also removes the following warning: + + + deprecated conversion from string constant to "char*" [-Wwrite-strings] + +Ifdef blocks removed: + +The #ifdef VLPT_REMOVED blocks have been removed from the packet table library source code except for the following functions: + +VL_PacketTable::IsVariableLength() was moved to PacketTable. + +VL_PacketTable::FreeReadBuff() is now PacketTable::FreeBuff(). + +Compatibility Notes and Report +Changed shared library interface version numbers (soname) + +For HDF5 Release 1.8.17, the shared object version numbers have changed as follows. + +Library + +Release +1.8.16 + +Release +1.8.17 + +Reason for Change + +HDF5 C Library + +10.1.0 + +10.2.0 + +Added APIs + +HDF5 High-level C Library + +10.0.2 + +10.1.0 + +Added APIs + +C++ Library + +11.0.0 + +12.0.0 + +Changes in existing APIs + +High-level C++ Library + +11.0.0 + +11.1.0 + +Added APIs + +All others + +10.0.2 + +10.0.3 + +Code changes that did not result in interface changes + +Compatibility report for Release 1.8.17 versus Release 1.8.16 + +The following interface compatibility report provides a full list of the changed symbols: + +API compatibility report for the HDF5 Library between 1.8.16 and 1.8.17 versions on x86 + +Release 1.8.16 of November 2015 versus Release 1.8.15 +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: + +“Dynamic Plugins in HDF5” in Advanced Topics in HDF5 +“H5PL: Plugin Interface” in the HDF5 Reference Manual +H5PLset_loading_state +H5PLget_loading_state +The following new C function has been added: + +This function reports whether the linked version of the HDF5 Library was built with the thread-safety feature enabled. + +H5is_library_threadsafe +The following flag has been removed: + +H5F_ACC_DEBUG flag for H5Fopen/create + +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. + +H5Fopen +In the C++ Interface + +The following features have been added: + +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‐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: + +API compatibility report for the HDF5 Library between 1.8.15 and 1.8.16 versions on x86 + + + +Release 1.8.15 of May 2015 versus Release 1.8.14 +This section lists interface-level changes and other user-visible changes in behavior in the transition from HDF5 Release 1.8.14 to Release 1.8.15. + +New and Changed Functions, Classes, Subroutines, Wrappers, and Macros +In the C Interface (main library) + +The following new C functions have been added: + +Memory allocation functions that use the library’s allocator. + +H5allocate_memory +H5resize_memory +The following functions enable programmatic control of the loading of dynamic plugin filters in user applications: + +H5PLset_loading_state +H5PLget_loading_state +For preliminary documentation, see “New HDF5 APIs Provide Programmatic Control of Dynamic Plugins.” +Final documentation is anticipated in July 2015. +In the C++ Interface + +The following features have been added: + +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: + + + void setLibverBounds(H5F_libver_t libver_low, H5F_libver_t libver_high) const; + + void getLibverBounds(H5F_libver_t& libver_low, H5F_libver_t& libver_high) const; + +New wrappers to retrieve the version of an object header +The following wrappers have been added to class H5::CommonFG to retrieve the object header version of an object in a file or group, given the object’s name. + + + unsigned childObjVersion(const char* objname) const; + + unsigned childObjVersion(const H5std_string& objname) const; + +A new DataType constructor +A new DataType constructor takes a PredType object and invokes H5Tcopy to generate another datatype identifier from a predefined datatype. + +The following features have been changed: + +Combined H5File::getObjCount overloaded methods +The following methods: + + + ssize_t getObjCount(unsigned types) const; + + ssize_t getObjCount() const; + +have been combined into the following: + + + ssize_t getObjCount(unsigned types = H5F_OBJ_ALL) const; + +Deprecated constructors +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: + + + (const hid_t h5_id); + + (const & original); + +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. + +In the Fortran Interface + +The following Fortran 2003 API has been added: + +h5tenum_insert_f + +Operation of the new Fortran 2003 version of this API is more consistent with the operation of the C API than was the Fortran 90 version. + +Users are strongly encouraged to use the Fortran 2003 API. + +Several global variables have been added in the Fortran API. These global variables are equivalent in definition to the comparable C definitions: + + +H5G_UDLINK_F +H5G_SAME_LOC_F +H5O_TYPE_UNKNOWN_F +H5O_TYPE_GROUP_F +H5O_TYPE_DATASET_F +H5O_NAMED_DATATYPE_F +H5O_TYPE_NTYPES_F +For parallel applications + +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(). + +Compatibility Report and Comments +Compatibility report for Release 1.8.15 versus Release 1.8.14 + +API compatibility report for the HDF5 Library between 1.8.14 and 1.8.15 versions on x86 + +Changed shared library interface version number (soname) + +In the C++ interface, two overloaded methods have been combined into a single method and one constructor has been deprecated. + +Due to these changes, the shared library interface version number (soname) has been increased. For a full list of the changed symbols, see the interface compatibility report linked immediately above. + +Release 1.8.14 of November 2014 versus Release 1.8.13 +This section lists interface-level changes and other user-visible changes in behavior in the transition from HDF5 Release 1.8.13 to Release 1.8.14. + +New and Changed Functions, Classes, Subroutines, Wrappers, and Macros +In the main library C Interface + +No new C functions have been added. + +The behavior of the following C function has been changed: + +The function H5Pset_core_write_tracking has been modified to enforce the limitation that the value of the page_size parameter cannot equal 0 (zero): + +H5Pset_core_write_tracking +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: + +H5Dcreate +In the high-level library C Interface + +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): + + + H5FD_CORE H5FD_MULTI + H5FD_FAMILY H5FD_SEC2 + H5FD_LOG H5FD_STDIO + H5FD_MPIO +Other internal int types have been changed to hid_t, but this change is expected to be transparent to the user. + +Compatibility Report and Comments +Compatibility report for Release 1.8.14 versus Release 1.8.13 + +API compatibility report for the HDF5 Library between 1.8.13 and 1.8.14 versions on x86 + +Changed shared library interface version number (soname) + +To increase the maintainability of HDF5, an architectural change has been made that required renaming several public symbols in H5Ppublic.h. + +Due to these changes, the shared library interface version number (soname) has been increased. For a full list of the changed symbols, see the interface compatibility report linked immediately above. + + + +Release 1.8.13 of May 2014 versus Release 1.8.12 +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_tracking +H5Pget_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). +H5Zfilter_avail +This function has been updated to correctly identify dynamically loaded filters. If a filter is not found among registered filters, the function now checks for dynamically loaded filters. +In the C++ Interface + +The following new features have been added: + +Wrappers to the class H5Object to get an object’s name: + + + ssize_t getObjName(char *obj_name, size_t buf_size = 0) + ssize_t getObjName(H5std_string& obj_name, size_t len = 0) + H5std_string getObjName() +Wrappers to the class H5CommonFG to get a child object’s type from a group or file: + + + H5O_type_t childObjType(const H5std_string& objname) + H5O_type_t childObjType(const char* objname) + H5O_type_t childObjType(hsize_t index, + H5_index_t index_type=H5_INDEX_NAME, + H5_iter_order_t order=H5_ITER_INC, const char* objname=".") +Wrappers to the class DSetMemXferPropList for setting or getting a transform property list: + + + DSetMemXferPropList(const char* expression); + void setDataTransform(const char* expression) + void setDataTransform(const H5std_string& expression) + ssize_t getDataTransform(char* exp, size_t buf_size=0) + H5std_string getDataTransform() +Wrapper to CompType for setting the size of a compound datatype: + + + void setSize(size_t size) +Overloaded functions to provide prototypes that declare constant arguments const: + + + DataSet::fillMemBuf + DataSet::getVlenBufSize + DataSpace::extentCopy + DataType::commit + FileAccPropList::setSplit + H5File::getVFDHandle +Additional overload to the class H5Location to get a comment as a char*: + + + ssize_t getComment(const char* name, size_t buf_size, char* comment) +Additional overloads to the class Attribute to get an attribute’s name for convenience: + + + ssize_t getName(char* attr_name, size_t buf_size=0) + ssize_t getName(H5std_string& attr_name, size_t buf_size=0) +In the Fortran Interface + +The following new Fortran subroutines have been added: + +Fortran2003 subroutines: + +h5pset_file_image_f +h5pget_file_image_f + + + +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. + +This change affects only Windows environments. + +Also see “Build and Configuration” below. + +Command-line Tools with Changed Behavior +h5repack + +h5repack has been updated to correctly handle dynamically loaded filters. + +Build and Configuration +Thread safety + +When configuring a thread-safe HDF5 Library with --enable-threadsafe, it is no longer necessary to specify --with-pthreads if the Pthreads library is in a standard location. + +Removed Functions and Wrappers +The MPI-POSIX driver has been removed. The following C functions and the corresponding Fortran subroutines and C++ wrappers therefore are no longer included in the HDF5 distribution: + +H5Pset_fapl_mpiposix +H5Pget_fapl_mpiposix +Applications performing parallel I/O should use the MPI-IO driver, H5Pset_fapl_mpio. + +Release 1.8.12 of November 2013 versus Release 1.8.11 +This section lists interface-level changes and other user-visible changes in behavior in the transition from HDF5 Release 1.8.11 to Release 1.8.12. + +New and Changed Functions, Classes, Subroutines, Wrappers, and Macros +In the C Interface (main library) + +The following C functions have been modified: + +H5Zunregister now checks for open objects using a filter before allowing the filter to be unregistered. +H5Dscatter and H5Dgather signatures have changed slightly. +The src_buff parameter type is now 'const void *' (previously: 'void *'). +In the C++ Interface + +The following new C++ class has been added: + +H5::H5Location + +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: + +createAttribute() +openAttribute() +attrExists() +renameAttr() +removeAttr() +flush() +getFileName() +getNumAttrs() + + + +getObjType() +iterateAttrs() +setComment() +getComment() +removeComment() +reference() +dereference() +getRegion() + +The following wrappers for C functions have been added: + +H5Location::getRefObjType + +Corresponding C function: H5Rget_obj_type2 + +Retrieves the type of the object that an object reference points to. + +H5Location::attrExists + +Corresponding C function: H5Aexist + +Determines whether a given attribute exists. + +H5Location::setComment + +Two overloaded versions of H5Location::setComment have been added to take "." in lieue of the name of the object. + +In the classes DataSet, DataType, and Group, the following constructors have changed as follows: + +These constructors + DataSet(H5Object& obj, const void* ref, H5R_type_t ref_type = H5R_OBJECT); + DataSet(H5File& h5file, const void* ref, H5R_type_t ref_type = H5R_OBJECT); + DataSet(Attribute& attr, const void* ref, H5R_type_t ref_type = H5R_OBJECT); +have changed to + DataSet(const H5Location& loc, const void* ref, H5R_type_t ref_type = H5R_OBJECT); + DataSet(const Attribute& attr, const void* ref, H5R_type_t ref_type = H5R_OBJECT); +These constructors + DataType(H5Object& obj, const void* ref, H5R_type_t ref_type = H5R_OBJECT); + DataType(H5File& h5file, const void* ref, H5R_type_t ref_type = H5R_OBJECT); + DataType(Attribute& attr, const void* ref, H5R_type_t ref_type = H5R_OBJECT); +have changed to + DataType(const H5Location& loc, const void* ref, H5R_type_t ref_type = H5R_OBJECT); + DataType(const Attribute& attr, const void* ref, H5R_type_t ref_type = H5R_OBJECT); + +These constructors + Group(H5Object& obj, const void* ref, H5R_type_t ref_type = H5R_OBJECT); + Group(H5File& h5file, const void* ref, H5R_type_t ref_type = H5R_OBJECT); + Group(Attribute& attr, const void* ref, H5R_type_t ref_type = H5R_OBJECT); +have changed to + Group(const H5Location& loc, const void* ref, H5R_type_t ref_type = H5R_OBJECT); + Group(const Attribute& attr, const void* ref, H5R_type_t ref_type = H5R_OBJECT); +New Command-line Tool Options and Option Parameters +h5dump + +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. + + +h5repack + +The h5repack option -f, --filter has a new parameter, UD, to enable the use of user-defined filters: + -f UD= + --filter=UD= + + +h5stat + +h5stat has three new options for setting print thresholds: + For attributes: + -aN + --attribute=N + + For links in a group: + -lN + --links=N + + For dimension sizes: + -mN + --dims=N + +Build and Configuration +CMake and Autotools configuration + +A new configuration option can be used to change the default plugin path: + + + +Autotools configure option + + + +--with-default-plugindir=location + + + +cmake option + + + +-DH5_DEFAULT_PLUGINDIR:PATH=location + +CMake configuration + +CMake builds of HDF5 now create *.so.{lt_version} files with the same version as configure. + +Autotools configure flag + +The configure flag FFLAGS has been renamed to FCFLAGS. + +Compile Scripts with Changed Behavior +h5cc and h5pcc + +h5c++ + +h5fc and h5pfc + +These compile scripts have been modified to change the default behavior to link to shared libraries in environments where HDF5 has been configured with --disable-static. + +Command-line Tools with Changed Behavior +h5dump + +h5dump output now displays + USER_DEFINED_FILTER +where it previously displayed UNKNOWN_FILTER. + + +h5dump now correctly exports subsetted data to a file using the -o, --output option. + +Release 1.8.11 of May 2013 versus Release 1.8.10 +This section lists interface-level changes and other user-visible changes in behavior in the transition from HDF5 Release 1.8.10 to Release 1.8.11. + +New and Changed Functions and Subroutines +The following new high-level C function has been added: + +H5DOwrite_chunk +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. + +H5DOwrite_chunk is the first function in HDF5’s new high-level “HDF5 Optimized Functions” library. + +The following new C functions have been added: + +H5Dscatter +H5Dgather +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. + +See “HDF5 Dynamically Loaded Filters” (PDF only) for further information. + +New Command-line Tool Option +h5dump and h5import + +h5dump has a new option to output the DDL structure of a file or object: + -O + --ddl= +[‘-O’ above is ‘dash-uppercase-o’.] + +h5import can now take the output of + h5dump -O -o +directly as input files. +See “Using h5dump to create input for h5import” in the h5import reference manual entry. + +New Configuration and Build Tool +cmakehdf5 + +This new build command script is similar to buildhdf5 and is available in the bin/ directory of the distributed source code. + +For HDF5, the CMake minimum is now 2.8.10. + +Function, Subroutines, and Feature with Changed Syntax or Behavior +The return value of the following high-level C function has changed: + +H5DSget_scale_name +This function has been changed to not include the NULL terminator in the returned size of of the dimension scale name (bug fix). + +In the Fortran subroutines + +h5pset_external_f and +h5pget_external_f +the type of the offset parameter has changed to INTEGER(KIND=OFF_T) to support 8-byte integers, matching the C type definition of off_t. + +The HDF5 Library now supports data conversion from enumeration to integer and floating-point numeric datatypes. + +Command-line Tools with Changed Behavior +h5diff + +When comparing two files or objects, h5diff now recognizes a unique extra attribute attached to an object as a difference and returns with an exit code of 1. + +Previously, h5diff did not recognize the extra attribute as a difference. + +h5ls + +The content of the h5ls --help output has been revised. + +h5dump + +h5dump has been updated to display the compression ratio for user-defined filters. + +In h5dump output, UNKNOWN_FILTER has been changed to USER_DEFINED_FILTER. + +Removed Functions and Wrappers +The following C functions and the corresponding C++ wrappers have been removed: + +H5Pset_dxpl_multi +H5Pget_dxpl_multi + +H5::DSetMemXferPropList:setMulti +H5::DSetMemXferPropList:getMulti +Release 1.8.10 of November 2012 versus Release 1.8.9 +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. + +Changed Command-line Tool +h5import has been updated to accept an input file created by h5dump. + +Release 1.8.9 of May 2012 versus Release 1.8.8 +This section lists interface-level changes and other user-visible changes in behavior in the transition from HDF5 Release 1.8.8 to Release 1.8.9. + +New and Changed Functions +A new high level C function and Fortran subroutine were added to HDF5 Lite (H5LT) to determine whether an HDF5 path is correct and resolves to a valid HDF5 object: + +H5LTpath_valid +h5ltpath_valid_f + + +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: + +H5LTopen_file_image +H5Fget_file_image + + + + +H5Pset_file_image +H5Pget_file_image + + +H5Pset_file_image_callbacks +H5Pget_file_image_callbacks +For the callbacks, struct, and ENUM, see H5Pset_file_image_callbacks. + +Use of this feature is described in “HDF5 File Image Operations” (PDF). + + +The following functions were modified or added to the HDF5 Library to allow an application to control the operation of copying committed datatypes with H5Ocopy: + +Function with changed interface: + +H5Pset_copy_object +New flag for use with H5Pset_copy_object: + +H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG +Function with changed behavior: + +H5Ocopy +This function’s behavior is changed, but only with the use of the new flag, H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG. +New functions and callback function: + +H5Pset_mcdt_search_cb +H5Pget_mcdt_search_cb +H5O_mcdt_search_cb_t + + +H5Padd_merge_committed_dtype_path +H5Pfree_merge_committed_dtype_paths +Use of this capability is described in “Copying Committed Datatypes with H5Ocopy” (PDF). + + +The following C functions and Fortran subroutines were added to provide a mechanism to ensure sequential consistency in parallel environments using MPI I/O: + +H5Fset_mpi_atomicity +H5Fget_mpi_atomicity + + +h5fset_mpi_atomicity_f +h5fget_mpi_atomicity_f +Use of this capability is described in “Enabling a Strict Consistency Semantics Model in Parallel HDF5” (PDF). + + +The following function was added at Release 1.8.5 but was not documented at that time. It is mentioned here for those who may have missed its introduction: + +H5Oexists_by_name +New Fortran Subroutines +The following Fortran subroutines have been added in this release: + +h5ltpath_valid_f +h5ocopy_f +h5fset_mpi_atomicity_f +h5fget_mpi_atomicity_f +Where a subroutine is part of a new HDF5 feature, that feature is described above. + +Fortran Subroutine with Changed Behavior +The content of the buffer returned by the following Fortran subroutine has changed as noted: + +h5ltget_attribute_string_f +If the returned buffer requires padding, h5ltget_attribute_string_f now employs space padding; this buffer was previously returned with a C NULL terminator. +Command-line Utilities with New Options and/or Changed Behavior +h5repack has one new option and improved performance under certain circumstances: + +‐Mn, ‐‐metadata_block_size=n +Sets the metadata block size in the output file. + +Performance is improved when repacking large chunked datasets (for example, when dataset size exceeds 128 MB). + + +h5stat has one new option: + +‐S, ‐‐summary +Displays a summary of file space usage for a file. + + +h5dump has one new option, a new capability, and updated output: + +‐‐no-compact-subset +Disables compact subsetting to allow the left-hand square bracket character ( [ ) in a dataset name. + +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. +Release 1.8.8 of November 2011 versus Release 1.8.7 +This section lists interface-level changes and other user-visible changes in behavior in the transition from HDF5 Release 1.8.7 to Release 1.8.8. + +New C Functions +Two new parallel I/O functions enable an application to query whether or how a collective I/O operation actually completed: + +H5Pget_mpio_actual_chunk_opt_mode +H5Pget_mpio_actual_io_mode +Updated Fortran Interface, including Fortran 2003 Features +The HDF5 Fortran interface has been extended and upgraded to Fortran 2003 for this release. + +See “Configure and Build Changes” below for the configure options to use when building HDF5 with Fortran 2003 enabled. + +Features enabled in this upgrade are described in New Features in the HDF5 Fortran Library: Adding Support for the Fortran 2003 Standard (PDF only). In general, the links below are to technical descriptions (reference manual entries, for example) of specific interfaces. + +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: + +h5dvlen_reclaim_f +h5eset_auto_f +h5literate_by_name_f +h5literate_f +h5ovisit_f +h5oget_info_by_name_f +h5tconvert_f +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: + +h5pget_f +h5pget_fill_value_f +h5pinsert_f +h5pregister_f +h5pset_f +h5pset_fill_value_f +h5rcreate_f +h5rdereference_f +h5rget_name_f +h5rget_object_type_f +Subroutines with support for the derived type C_PTR and a changed signature in Fortran 2003 environments: + +h5aread_f +h5awrite_f +h5dread_f +h5dwrite_f +Subroutine with additional optional parameters in Fortran 2003 environments: + +h5pcreate_class_f +New and updated Fortran 90 subroutines +New Fortran 90 subroutines: + +h5pset_nbit_f +h5pset_scaleoffset_f +Updated Fortran 90 subroutines: + +h5open_f +h5close_f * +h5check_version_f +h5get_libversion_f +h5garbage_collect_f +h5dont_atexit_f +* h5close_f has been modified in this release to close only the HDF5 Fortran Library interface; it no longer closes the underlying HDF5 Library. + +New Fortran utility functions and derived types +New Fortran utility functions: + +h5offsetof Available only in Fortran 2003 environments. +h5kind_to_type Available in either Fortran environment. +New Fortran derived types in Fortran 2003 environments: + +hvl_t Described in New Features. +h5o_info_t See h5ovisit_f. +New high level Fortran interface +New Fortran subroutines in the HDF5 Dimension Scale high-level interface, H5DS: + +h5dsset_scale_f +h5dsattach_scale_f +h5dsdetach_scale_f +h5dsis_attached_f +h5dsis_scale_f +h5dsset_label_f +h5dsget_label_f +h5dsget_scale_name_f +h5dsget_num_scales_f +These subtroutines are available in both Fortran 90 and Fortran 2003 environments. + +C Functions with Changed Capability +H5Tcreate now supports fixed-length and variable-length string types. + +Driver Changes on Windows Systems +Changed behavior: + +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). + +h5diff, when comparing a file to itself, now reports no differences. + +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. + + + + + +Release 1.8.7 of May 2011 versus Release 1.8.6 +This section lists interface-level changes and other user-visible changes in behavior in the transition from HDF5 Release 1.8.6 to Release 1.8.7. + +New C Functions and Macros +Three new functions enable the caching of files opened through external links. This cache can improve the performance of external links in heavy use cases: + +H5Pset_elink_file_cache_size +H5Pget_elink_file_cache_size +H5Fclear_elink_file_cache + +Two new macros enable compile-time inclusion or exclusion of code depending on the version of the HDF5 Library against which an application is to be linked: + +H5_VERSION_GE +H5_VERSION_LE +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: + +H5Screate_simple +H5Sset_extent_simple +H5Pset_external +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. + +H5Pset_fapl_log + +HDF5 now blocks committing a datatype that cannot hold any data. This currently includes compound datatypes with no fields and enumerated datatypes with no members. + +H5Tcommit1 +H5Tcommit2 +H5Tcommit_anon +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. + + + +h5ltmake_dataset_f +h5ltmake_dataset_int_f +h5ltmake_dataset_float_f +h5ltmake_dataset_double_f + + +h5ltread_dataset_f +h5ltread_dataset_int_f +h5ltread_dataset_float_f +h5ltread_dataset_double_f + +h5tbget_field_info_f has a new maxlen_out parameter. This parameter is optional. + +Command-line Utilities with New Options +h5diff has a new verbose with levels option to display additional attribute information: + +-vn, --verbose=n + +h5dump has one new option to enable reporting of the HDF5 Library’s error stack: + +--enable-error-stack +Command-line Utility with Changed Option Name +h5ls has one changed option name: + +--enable-error-stack replaces --error. +The --error option is deprecated but remains available. + +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. + +h5diff --use-system-epsilon now employs the formula '|a - b|' instead of '|a - b| / b'. + +h5copy now accepts the same file as the source and target file; this enables object copying within a file. + +h5dump now displays reference types as described in DDL in BNF for HDF5: + + + +H5T_REFERENCE {H5T_STD_REF_OBJ} + +Object reference + + + +H5T_REFERENCE {H5T_STD_REF_DSETREG} + +Dataset region reference + +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. + +Release 1.8.6 versus Release 1.8.5, February 2011 +This section lists interface-level changes and other user-visible changes in behavior in the transition from HDF5 Release 1.8.5 to Release 1.8.6. + +C Functions with Additional Capability +H5Tset_order and H5Tget_order can now be used with all datatypes. See the related note regarding H5T_ORDER_MIXED immediately below. + +ENUM with New Member +H5T_order_t, an ENUM used to set or indicate datatype endianness, includes a new member: + + H5T_ORDER_MIXED + +The function H5Tget_order returns this value when called on a compound datatype whose members are not all of the same endianness. + +Command-line Utilities with New Options +h5diff has one new option: + +--exclude-path + + +h5ls and h5diff have two new options: + +--follow-symlinks +--no-dangling-links +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. + +h5repack can now convert a dataset to compact layout. + +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. + +The new order of arguments for these scripts is as follows: + + + $CLINKER + $H5BLD_CPPFLAGS + $CPPFLAGS + $H5BLD_CFLAGS + $CFLAGS + $LDFLAGS + $clibpath + $link_objs + $LIBS + $link_args + $shared_link + +Thread Safety on Windows +This release adds support for thread safety on Windows using the Windows threads library. See the file RELEASE.txt in the distributed HDF5 source code (hdf5/release_docs/RELEASE.txt) for details. + +Parallel HDF5 +The Parallel HDF5 build process has changed to use mpiexec instead of mpirun. + +Release 1.8.5 versus Release 1.8.4, June 2010 +This section lists interface-level changes and other user-visible changes in behavior in the transition from HDF5 Release 1.8.4 to Release 1.8.5. + +New C Function +The following function was added to the HDF5 Library at this release, but was not documented at that time: + +H5Oexists_by_name +(This note added in November 2011, shortly following Release 1.8.8.) + +C Functions with Additional Capability +The following functions have been modified to accommodate filters set on a group creation property list: + +H5Pall_filters_avail +H5Pget_filter1 +H5Pget_filter2 +H5Pget_filter_by_id1 +H5Pget_filter_by_id2 +H5Pget_nfilters + + + +H5Pmodify_filter +H5Premove_filter +H5Pset_deflate +H5Pset_filter +H5Pset_fletcher32 + +Related to H5Zregister, the calling protocol for the can_apply and set_local callback functions has been extended to accommodate the use of filters on group creation property lists. + +New C++ Member Function and Overloaded Member Functions +The following C++ member function is new in this release: + +DataSet::getInMemDataSize + + + +To simplify getting a dataset’s data size in memory. + + + +The overloaded forms of the following C++ member functions are new in this release: + +CommonFG::getObjnameByIdx + + + +Overloaded to take char* for name. + +CommonFG::getObjTypeByIdx + + + +Overloaded to return type name as a char*. + +Command-line Utility with New Options +h5diff has two new options: + +--follow-links +--no-dangling-links + + +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_F + H5L_TYPE_SOFT_F + H5L_TYPE_EXTERNAL_F + H5L_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. + +Release 1.8.4 versus Release 1.8.3, November 2009 +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.) + +h5lget_info_by_idx_f +h5lget_info_by_idx_f (loc_id, group_name, index_field, order, n, & + link_type, f_corder_valid, corder, cset, address, val_size, & + hdferr, lapl_id) + +The parameters link_type, address, and val_size have been added; the parameter data_size has been removed. + +Tools with Changed Interface or Behavior +h5diff has one new option: + +--use-system-epsilon + +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. + +Release 1.8.3 versus Release 1.8.2, May 2009 +This section lists API-level changes and changes in behavior in the transition from HDF5 Release 1.8.2 to Release 1.8.3. + +New Functions +C functions: + +The following C functions are new for this release and are documented in the HDF5 Reference Manual. + + + +H5Pset_elink_cb + + + +herr_t H5Pset_elink_cb( hid_t lapl_id, H5L_elink_traverse_t func, void *op_data ) +See entry. + + + +H5Pget_elink_cb + + + +herr_t H5Pget_elink_cb( hid_t lapl_id, H5L_elink_traverse_t *func, void **op_data ) +See entry. + + + +H5Pset_elink_acc_flags + + + +herr_t H5Pset_elink_acc_flags( hid_t lapl_id, unsigned flags ) +See entry. + + + +H5Pget_elink_acc_flags + + + +herr_t H5Pget_elink_acc_flags( hid_t lapl_id, unsigned *flags ) +See entry. + + + +H5Pset_chunk_cache + + + +herr_t H5Pset_chunk_cache( hid_t dapl_id, size_t rdcc_nslots, size_t rdcc_nbytes, double rdcc_w0 ) +See entry. + + + +H5Pget_chunk_cache + + + +herr_t H5Pget_chunk_cache( hid_t dapl_id, size_t *rdcc_nslots, size_t *rdcc_nbytes, double *rdcc_w0 ) +See entry. + + + +H5Dget_access_plist + + + +hid_t H5Dget_access_plist( hid_t dset_id ) +See entry. + + + +H5Iis_valid + + + +htri_t H5Iis_valid( hid_t id ) +See entry. + +Fortran Subroutines: + +The following subroutines are new in this release: + +h5dget_access_plist_f +h5iis_valid_f +h5pset_chunk_cache +h5pget_chunk_cache + +Function with Changed Behavior +H5set_free_list_limits + +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 +h5diff + +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.) + +This tool has two new options: + + -c, --compare Lists objects that are not comparable. + + -N, --nan Avoids NaNs detection. + +h5dump + +h5dump now correctly specifies an XML DTD or a schema URL. + +h5dump binary output now defaults to NATIVE. + +The new -b, --binary option can be used to specify alternate binary formats. + +h5repack + +When a user does not specify a chunk size, h5repack now defines the default chunk size to be the same same as the size of the hyperslab used to read the chunks. + +Release 1.8.2 versus Release 1.8.1, November 2008 +This section lists API-level changes and changes in behavior in the transition from HDF5 Release 1.8.1 to Release 1.8.2. + +New Functions +C functions: + +The following C functions are new for this release and are documented in the HDF5 Reference Manual. + + + +H5Pset_elink_fapl + + + +herr_t H5Pset_elink_fapl( hid_t lapl_id, hid_tfapl_id ) +See entry. + + + +H5Pget_elink_fapl + + + +hid_t H5Pget_elink_fapl( hid_t lapl_id ) +See entry. + +Fortran Subroutine: + +The following subroutine is new in this release: + H5Tget_native_type_f + +New C++ Wrappers +The following functions were added as wrappers for the C function H5Rdereference to replace the incorrect IdComponent::dereference(): + + + void H5Object::dereference(H5Object& obj, void* ref, + H5R_type_t ref_type=H5R_OBJECT) + void H5Object::dereference(H5File& h5file, void* ref, + H5R_type_t ref_type=H5R_OBJECT) + void H5Object::dereference(Attribute& obj, void* ref, + H5R_type_t ref_type=H5R_OBJECT) + +The following constructors were added to create the associated objects by way of dereference: + + + DataSet(H5Object& obj, void* ref, H5R_type_t ref_type=H5R_OBJECT) + DataSet(H5File& file, void* ref, H5R_type_t ref_type=H5R_OBJECT) + DataSet(Attribute& attr, void* ref, H5R_type_t ref_type=H5R_OBJECT) + Group(H5Object& obj, void* ref, H5R_type_t ref_type=H5R_OBJECT) + Group(H5File& obj, void* ref, H5R_type_t ref_type=H5R_OBJECT) + Group(Attribute& attr, void* ref, H5R_type_t ref_type=H5R_OBJECT) + DataType(H5Object& obj, void* ref, H5R_type_t ref_type=H5R_OBJECT) + DataType(H5File& file, void* ref, H5R_type_t ref_type=H5R_OBJECT) + DataType(Attribute& attr, void* ref, H5R_type_t ref_type=H5R_OBJECT) + +Functions with Changed Syntax +The following function syntaxes have changed; the affected return values and parameter are noted as underscored red text. + +C functions: + +H5Fget_obj_count + +ssize_t H5Fget_obj_count( hid_t file_id, unsigned int types ) + +H5Fget_obj_ids + +ssize_t H5Fget_obj_ids( hid_t file_id, unsigned int types, + size_t max_objs, hid_t *obj_id_list ) + +Changed Fortran Subroutines +The optional parameter mounted has been added to the following subroutines: + + +h5gget_info_f +h5gget_info_by_idx_f +h5gget_info_by_name_f +Changed Data Structure +H5G_info_t + +A mounted filed has been added to the H5G_info_t struct. + +Tools with Changed Interface or Behavior +h5diff + +h5diff now returns 1 if the files differ in structure, i.e., if the file graphs differ by any object. + +The tool’s error return code has been changed to 2. + +h5repack and h5diff + +The standard command-line syntax of both tools has been changed to parallel that of h5dump. The new syntax of each is as follows: + + h5repack [OPTIONS] file1 file2 + + h5diff [OPTIONS] file1 file2 [object1 [object2]] + +In each case, the old syntax remains available (though undocumented) to avoid breaking existing scripts. + +h5repack + +The following new options control the addition of user block data to an existing HDF5 file: + +-u U +--ublock=U + + + +Specifies the name of the file containing the user block data to be added. + + +-b B +--block=B + + + + +Specifies the size of the block to be added. + +The following new options set parameters governing the tool’s use of H5Pset_alignment: + +-t T +--threshold=T + + + +Specifies the threshold value for H5Pset_alignment. + + +-a A +--alignment=A + + + + +Specifies the alignment value for H5Pset_alignment. + +h5repack now supports multiple instances of the '-f' or '--filter' option, allowing the use of multiple I/O filters with an object. + +With no change in the command-line syntax, h5repack now retains an existing userblock when repacking an HDF5 file. + +h5import + +The floating point format flag TEXTFPE, for scientific notation, has been deprecated. The flag TEXTFP, which accepts scientific notation, should be used instead. + +h5import now imports string data with the STR keyword in the INPUT-CLASS configuration field. + +h5dump and h5ls + +These tools now traverse external links when performing recursive traversals. + +h5dump + +Binary output now defaults to NATIVE with the '-b' option, optionally accepting NATIVE, FILE, BE, and LE. + +The new '-m T' or '--format T' option enables a user-defined formatting string for printing floating-point numbers. + +With no change in the command-line syntax, h5dump now prints a compression ratio when compression filters are in use. + +Deprecated Functions +The following functions are deprecated as of this release: + + H5Pset_preserve + H5Pget_preserve +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. + + + +Release 1.8.1 versus Release 1.8.0 +HDF5 Release 1.8.1 is a minor release with several bugfixes and optimizations and limited new features. + +The most significant new feature is an expanded set of Fortran90 APIs, enabling essentially all new C library features of Release 1.8.0. + +New Functions and Tools +C functions: + +There are no new C functions for Release 1.8.1. + +Fortran subroutines: + +The following Fortran subroutines are new for Release 1.8.1 and are documented in the HDF5 Reference Manual. + +H5A + + +h5acreate_f +h5acreate_by_name_f +h5adelete_by_idx_f +h5adelete_by_name_f +h5aexists_f +h5aexists_by_name_f +h5aget_create_plist_f +h5aget_info_f +h5aget_info_by_idx_f + + + + +h5aget_info_by_name_f +h5aget_name_by_idx_f +h5aget_storage_size_f +h5aopen_f +h5aopen_by_idx_f +h5aopen_by_name_f +h5arename_f +h5arename_by_name_f + +H5D + + +h5dcreate_anon_f +h5dcreate_f + + + + +h5dopen_f +h5dset_extent_f + +H5G + + +h5gcreate_anon_f +h5gcreate_f +h5gget_create_plist_f +h5gget_info_f + + + + +h5gget_info_by_idx_f +h5gget_info_by_name_f +h5gopen_f + +H5L + + +h5lcopy_f +h5lcreate_external_f +h5lcreate_hard_f +h5lcreate_soft_f +h5ldelete_f +h5ldelete_by_idx_f + + + + +h5lexists_f +h5lget_info_f +h5lget_info_by_idx_f +h5lget_name_by_idx_f +h5lmove_f + +H5O + + +h5olink_f + + + + +h5oopen_f + +H5P + + +h5pget_attr_creation_order_f +h5pget_attr_phase_change_f +h5pget_char_encoding_f +h5pget_copy_object_f +h5pget_create_inter_group_f +h5pget_data_transform_f +h5pget_elink_prefix_f +h5pget_est_link_info_f +h5pget_fapl_direct_f +h5pget_link_creation_order_f +h5pget_link_phase_change_f +h5pget_local_heap_size_hint_f +h5pget_nlinks_f +h5pget_obj_track_times_f +h5pget_shared_mesg_index_f +h5pget_shared_mesg_nindexes_f + + + + +h5pset_attr_creation_order_f +h5pset_attr_phase_change_f +h5pset_char_encoding_f +h5pset_copy_object_f +h5pset_create_inter_group_f +h5pset_data_transform_f +h5pset_elink_prefix_f +h5pset_est_link_info_f +h5pset_fapl_direct_f +h5pset_libver_bounds_f +h5pset_link_creation_order_f +h5pset_link_phase_change_f +h5pset_local_heap_size_hint_f +h5pset_obj_track_times_f +h5pset_nbit_f +h5pset_nlinks_f +h5pset_scaleoffset_f + +H5R + + +h5rget_name_f + + + + + +H5S + + +h5sdecode_f +h5sencode_f + + + + +h5sextent_equal_f + +H5T + + +h5tcommit_anon_f +h5tcommit_f +h5tcommitted_f +h5tcompiler_conv_f + + + + +h5tdecode_f +h5tencode_f +h5tget_create_plist_f +h5topen_f + +C++ wrappers: + +There are no new C++ wrappers for Release 1.8.1. + +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. + +IdComponent::dereference was incorrect; it was changed from: + void IdComponent::dereference(IdComponent& obj, void* ref) +to: + void H5Object::dereference(H5File& h5file, void* ref) + void H5Object::dereference(H5Object& obj, void* ref) +Tools with changed syntax: + +The command-line syntax of h5repack was changed in Release 1.8.0 to the following: + h5repack [OPTIONS] in_file out_file +Since this would be imcompatible with existing user scripts, the original syntax has be re-enabled in this release: + h5repack -i in_file -o out_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 '-d min_indexed_links' or '--indexed=min_indexed_links'. In Release 1.8.1, the '-i' form has been changed to '-d' as follows: + -d min_indexed_links +or + --indexed=min_indexed_links +The command-line syntax of h5diff was changed in Release 1.8.0 to the following: + h5diff [OPTIONS] file1 file2 [object1 [object2 ] ] +Tools with new options: + +h5dump +-m T or --format T Sets format of floating point output + +Changed Behavior or Output +Changed library behavior: + +A 4GB limit on the size of dataset chunks is now properly enforced when a dataset is created. + +The HDF5 Library now works more effectively with external links. Some valid external links that previously failed will now be properly recognized. See H5Lcreate_external. + +C functions with changed behavior: + +The behavior of H5Lcreate_external has changed as described immediately above. + +Tools with changed behavior and changed output: + +The h5dump -p option now prints the compression ratio if a compression filter is associated with a dataset. + +h5dump now supports external links, displaying the target objects (datasets, groups, and named datatypes). + +Tools with changed output: + +Changed Library Configuration +The following configuration flag is new with this release: + +--disable-sharedlib-rpath + +Removed Patch Requirement +The patch that was required for Cygwin with HDF5 Release 1.8.0 has been rolled into this release and no longer needs to be applied by the user. + + + +Release 1.8.0 versus Release 1.6.x +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 + +H5Acreate1 +H5Acreate2 + +Renamed from H5Acreate +New + +H5Aiterate + +H5Aiterate1 +H5Aiterate2 + +Renamed from H5Aiterate +New + +H5Dcreate + +H5Dcreate1 +H5Dcreate2 + +Renamed from H5Dcreate +New + +H5Dopen + +H5Dopen1 +H5Dopen2 + +Renamed from H5Dopen +New + +H5Eclear + +H5Eclear1 +H5Eclear2 + +Renamed from H5Eclear +New + +H5Eget_auto + +H5Eget_auto1 +H5Eget_auto2 + +Renamed from H5Eget_auto +New + +H5Eprint + +H5Eprint1 +H5Eprint2 + +Renamed from H5Eprint +New + +H5Epush + +H5Epush1 +H5Epush2 + +Renamed from H5Epush +New + +H5Eset_auto + +H5Eset_auto1 +H5Eset_auto2 + +Renamed from H5Eset_auto +New + +H5Ewalk + +H5Ewalk1 +H5Ewalk2 + +Renamed from H5Ewalk +New + +H5Gcreate + +H5Gcreate1 +H5Gcreate2 + +Renamed from H5Gcreate +New + +H5Gopen + +H5Gopen1 +H5Gopen2 + +Renamed from H5Gopen +New + +H5Pget_filter + +H5Pget_filter1 +H5Pget_filter2 + +Renamed from H5Pget_filter +New + +H5Pget_filter_by_id + +H5Pget_filter_by_id1 +H5Pget_filter_by_id2 + +Renamed from H5Pget_filter_by_id +New + +H5Pinsert + +H5Pinsert1 +H5Pinsert2 + +Renamed from H5Pinsert +New + +H5Pregister + +H5Pregister1 +H5Pregister2 + +Renamed from H5Pregister +New + +H5Rget_obj_type + +H5Rget_obj_type1 +H5Rget_obj_type2 + +Renamed from H5Rget_obj_type +New + +H5Tarray_create + +H5Tarray_create1 +H5Tarray_create2 + +Renamed from H5Tarray_create +New + +H5Tcommit + +H5Tcommit1 +H5Tcommit2 + +Renamed from H5Tcommit +New + +H5Tget_array_dims + +H5Tget_array_dims1 +H5Tget_array_dims2 + +Renamed from H5Tget_array_dims +New + +H5Topen + +H5Topen1 +H5Topen2 + +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. + +Recursive iteration + + + +H5Lvisit + +herr_t H5Lvisit( hid_t group_id, H5_index_t index_type, H5_iter_order_t order, H5L_iterate_t op, void *op_data ) +See entry. + +H5Lvisit_by_name + +herr_t H5Lvisit_by_name( hid_t loc_id, const char *group_name, H5_index_t index_type, H5_iter_order_t order, H5L_iterate_t op, void *op_data, hid_t lapl_id ) +See entry. + +H5Ovisit + +herr_t H5Ovisit( hid_t group_id, H5_index_t index_type, H5_iter_order_t order, H5O_iterate_t op, void *op_data ) +See entry. + +H5Ovisit_by_name + +herr_t H5Ovisit_by_name( hid_t loc_id, const char *object_name, H5_index_t index_type, H5_iter_order_t order, H5O_iterate_t op, void *op_data, hid_t lapl_id ) +See entry. + +“Format bounds” property +Release-to-release format compatibility + + + +H5Pset_libver_bounds + +herr_t H5Pset_libver_bounds( hid_t fapl_id, H5F_libver_t low, H5F_libver_t high ) +See entry. + +H5Pget_libver_bounds + +herr_t H5Pget_libver_bounds( hid_t fapl_id, H5F_libver_t *low, H5F_libver_t *high ) +See entry. + +Configurable compact-or-indexed +groups (compact and large groups) + + + +H5Pset_link_phase_change + +herr_t H5Pset_link_phase_change( hid_t gcpl_id, unsigned max_compact, unsigned min_dense ) +See entry. + +H5Pget_link_phase_change + +herr_t H5Pget_link_phase_change( hid_t gcpl_id, unsigned *max_compact, unsigned *min_dense ) +See entry. + +H5Pset_est_link_info + +herr_t H5Pset_est_link_info( hid_t gcpl_id, unsigned est_num_entries, unsigned est_name_len ) +See entry. + +H5Pget_est_link_info + +herr_t H5Pget_est_link_info( hid_t gcpl_id, unsigned *est_num_entries, unsigned *est_name_len ) +See entry. + +H5Pset_nlinks + +herr_t H5Pset_nlinks( hid_t lapl_id, size_t nlinks ) +See entry. + +H5Pget_nlinks + +herr_t H5Pget_nlinks( hid_t lapl_id, size_t *nlinks ) +See entry. + +User-defined links + + + +H5Lcreate_ud + +herr_t H5Lcreate_ud( hid_t link_loc_id, const char *link_name, H5L_type_t link_type, const char *udata, size_t udata_size, hid_t lcpl_id, hid_t lapl_id ) +See entry. + +H5Lregister + +herr_t H5Lregister( const H5L_class_t * link_class ) +See entry. + +H5Lunregister + +herr_t H5Lunregister( H5L_type_t link_cls_id ) +See entry. + +H5Oincr_refcount + +herr_t H5Oincr_refcount( hid_t object_id ) +See entry. + +H5Odecr_refcount + +herr_t H5Odecr_refcount( hid_t object_id ) +See entry. + +External links + + + +H5Lcreate_external + +herr_t H5Lcreate_external( const char *file_name, const char *object_name, hid_t link_loc_id, const char *link_name, hid_t lcpl_id, hid_t lapl_id ) +See entry. + +H5Lunpack_elink_val + +herr_t H5Lunpack_elink_val( char *ext_linkval, size_t link_size, const char **filename, const char **obj_path ) +See entry. + +H5Pset_elink_prefix + +herr_t H5Pset_elink_prefix( hid_t lapl_id, const char *prefix ) +See entry. + +H5Pget_elink_prefix + +herr_t H5Pget_elink_prefix( hid_t lapl_id, const char **prefix ) +See entry. + +Link creation order +tracking and indexing + + + +H5Pset_link_creation_order + +herr_t H5Pset_link_creation_order( hid_t ocpl_id, unsigned *crt_order_flags ) +See entry. + +H5Pget_link_creation_order + +herr_t H5Pget_link_creation_order( hid_t ocpl_id, unsigned *crt_order_flags ) +See entry. + +H5Gget_create_plist + +hid_t H5Gget_create_plist( hid_t group_id ) +See entry. + +H5Gget_info_by_idx + +herr_t H5Gget_info_by_idx( hid_t loc_id, const char *group_name, H5_index_t index_type, H5_iter_order_t order, hsize_t n, H5G_info_t *group_info, hid_t lapl_id ) +See entry. + +H5Tget_create_plist + +hid_t H5Tget_create_plist( hid_t dtype_id ) +See entry. + +Link API (H5L), an all-new interface +(includes user-defined and external links) + + + +H5Lcopy + +herr_t H5Lcopy( hid_t src_loc_id, const char *src_name, hid_t dest_loc_id, const char *dest_name, hid_t lcpl_id hid_t lapl_id ) +See entry. + +H5Lcreate_external + +herr_t H5Lcreate_external( const char *file_name, const char *object_name, hid_t link_loc_id, const char *link_name, hid_t lcpl_id, hid_t lapl_id ) +See entry. + +H5Lcreate_hard + +herr_t H5Lcreate_hard( hid_t obj_loc_id, const char *obj_name, hid_t link_loc_id, const char *link_name, hid_t lcpl_id, hid_t lapl_id ) +See entry. + +H5Lcreate_soft + +herr_t H5Lcreate_soft( const char *target_path, hid_t link_loc_id, const char *link_name, hid_t lcpl_id, hid_t lapl_id ) +See entry. + +H5Lcreate_ud + +herr_t H5Lcreate_ud( hid_t link_loc_id, const char *link_name, H5L_type_t link_type, const char *udata, size_t udata_size, hid_t lcpl_id, hid_t lapl_id ) +See entry. + +H5Ldelete + +herr_t H5Ldelete( hid_t loc_id, const char *name, hid_t lapl_id ) +See entry. + +H5Ldelete_by_idx + +herr_t H5Ldelete_by_idx( hid_t loc_id, const char *group_name, H5_index_t index_field, H5_iter_order_t order, hsize_t n, hid_t lapl_id ) +See entry. + +H5Lexists + +htri_t H5Lexists( hid_t loc_id, const char *name, hid_t lapl_id ) +See entry. + +H5Lget_info + +herr_t H5Lget_info( hid_t link_loc_id, const char *link_name, H5L_info_t *link_buff, hid_t lapl_id ) +See entry. + +H5Lget_info_by_idx + +herr_t H5Lget_info_by_idx( hid_t loc_id, const char *group_name, H5_index_t index_field, H5_iter_order_t order, hsize_t n, H5L_info_t *link_val, hid_t lapl_id ) +See entry. + +H5Lget_name_by_idx + +ssize_t H5Lget_name_by_idx( hid_t loc_id, const char *group_name, H5_index_t index_field, H5_iter_order_t order, hsize_t n, char *name, size_t size, hid_t lapl_id ) +See entry. + +H5Lget_val + +herr_t H5Lget_val( hid_t link_loc_id, const char *link_name, void *linkval_buff, size_t size, hid_t lapl_id ) +See entry. + +H5Lget_val_by_idx + +ssize_t H5Lget_val_by_idx( hid_t loc_id, const char *group_name, H5_index_t index_field, H5_iter_order_t order, hsize_t n, char *value_buf, size_t size, hid_t lapl_id ) +See entry. + +H5Lis_registered + +htri_t H5Lis_registered( H5L_type_t link_cls_id ) +See entry. + +H5Literate + +herr_t H5Literate( hid_t loc_id, H5_index_t index_type, H5_iter_order_t order, hsize_t *idx, H5L_iterate_t op, void *op_data ) +See entry. + +H5Literate_by_name + +herr_t H5Literate( hid_t loc_id, const char *group_name, H5_index_t index_type, H5_iter_order_t order, hsize_t *idx, H5L_iterate_t op, void *op_data, hid_t *lapl_id ) +See entry. + +H5Lmove + +herr_t H5Lmove( hid_t src_loc_id, const char *src_name, hid_t dest_loc_id, const char *dest_name, hid_t lcpl, hid_t lapl ) +See entry. + +H5Lregister + +herr_t H5Lregister( const H5L_class_t * link_class ) +See entry. + +H5Lunpack_elink_val + +herr_t H5Lunpack_elink_val( char *ext_linkval, size_t link_size, const char **filename, const char **obj_path ) +See entry. + +H5Lunregister + +herr_t H5Lunregister( H5L_type_t link_cls_id ) +See entry. + +H5Lvisit + +herr_t H5Lvisit( hid_t group_id, H5_index_t index_type, H5_iter_order_t order, H5L_iterate_t op, void *op_data ) +See entry. + +H5Lvisit_by_name + +herr_t H5Lvisit_by_name( hid_t loc_id, const char *group_name, H5_index_t index_type, H5_iter_order_t order, H5L_iterate_t op, void *op_data, hid_t lapl_id ) +See entry. + +Enhanced attribute handling + + + +H5Acreate2 + +hid_t H5Acreate2( hid_t loc_id, const char *obj_name, const char *attr_name, hid_t type_id, hid_t space_id, hid_t acpl_id, hid_t aapl_id, hid_t lapl_id ) +See entry. + +H5Adelete_by_idx + +herr_t H5Adelete_by_idx( hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t lapl_id ) +See entry. + +H5Adelete_by_name + +herr_t H5Adelete_by_name( hid_t loc_id, const char *obj_name, const char *attr_name, hid_t lapl_id ) +See entry. + +H5Aget_info + +herr_t H5Aget_info( hid_t attr_id, H5A_info_t *ainfo ) +See entry. + +H5Aget_info_by_idx + +herr_t H5Aget_info_by_idx( hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5A_info_t *ainfo, hid_t lapl_id ) +See entry. + +H5Aget_info_by_name + +herr_t H5Aget_info_by_name( hid_t loc_id, const char *obj_name, const char *attr_name, H5A_info_t *ainfo, hid_t lapl_id ) +See entry. + +H5Aget_name_by_idx + +ssize_t H5Aget_name_by_idx( hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, char *name, size_t size, hid_t lapl_id ) +See entry. + +H5Aget_storage_size + +hsize_t H5Aget_storage_size( hid_t attr_id ) +See entry. + +H5Aiterate2 + +herr_t H5Aiterate2( hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order, hsize_t *n, H5A_operator2_t op, void *op_data ) +See entry. + +H5Aiterate_by_name + +herr_t H5Aiterate_by_name( hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t *n, H5A_operator2_t op, void *op_data, hid_t lapd_id ) +See entry. + +H5Aopen + +herr_t H5Aopen( hid_t loc_id, const char *obj_name, const char *attr_name, hid_t aapl_id, hid_t lapl_id ) +See entry. + +H5Aopen_by_idx + +herr_t H5Aopen_by_idx( hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t aapl_id, hid_t lapl_id ) +See entry. + +H5Arename_by_name + +herr_t H5Arename_by_name( hid_t loc_id, const char *obj_name, const char *old_attr_name, const char *new_attr_name, hid_t lapl_id ) +See entry. + +Managing large numbers of attributes + + + +H5Pset_attr_phase_change + +herr_t H5Pset_attr_phase_change( hid_t ocpl_id, unsigned max_compact, unsigned min_dense ) +See entry. + +H5Pget_attr_phase_change + +herr_t H5Pget_attr_phase_change( hid_t ocpl_id, unsigned *max_compact, unsigned *min_dense ) +See entry. + +Attribute creation order +tracking and indexing + + + +H5Pset_attr_creation_order + +herr_t H5Pset_attr_creation_order( hid_t ocpl_id, unsigned crt_order_flags ) +See entry. + +H5Pget_attr_creation_order + +herr_t H5Pget_attr_creation_order( hid_t ocpl_id, unsigned *crt_order_flags ) +See entry. + +H5Aget_create_plist + +hid_t H5Aget_create_plist( hid_t attr_id ) +See entry. + +Shared object header messages (SOHM) + + + +H5Pset_shared_mesg_index + +herr_t H5Pset_shared_mesg_index( hid_t fcpl_id, unsigned index_num, unsigned mesg_type_flags, unsigned min_mesg_size ) +See entry. + +H5Pset_shared_mesg_nindexes + +herr_t H5Pset_shared_mesg_nindexes( hid_t plist_id, unsigned nindexes ) +See entry. + +H5Pset_shared_mesg_phase_change + +herr_t H5Pset_shared_mesg_phase_change( hid_t fcpl_id, unsigned max_list, unsigned min_btree ) +See entry. + +H5Pget_shared_mesg_index + +herr_t H5Pget_shared_mesg_index( hid_t fcpl_id, unsigned index_num, unsigned *mesg_type_flags, unsigned *min_mesg_size ) +See entry. + +H5Pget_shared_mesg_nindexes + +herr_t H5Pget_shared_mesg_nindexes( hid_t fcpl_id, unsigned *nindexes ) +See entry. + +H5Pget_shared_mesg_phase_change + +herr_t H5Pget_shared_mesg_phase_change( hid_t fcpl_id, unsigned *max_list, unsigned *min_btree ) +See entry. + +Enhanced local heap size +management (group meta data) + + + +H5Pset_local_heap_size_hint + +herr_t H5Pset_local_heap_size_hint( hid_t gcpl_id, size_t *size_hint ) +See entry. + +H5Pget_local_heap_size_hint + +herr_t H5Pget_local_heap_size_hint( hid_t gcpl_id, size_t size_hint ) +See entry. + +UNICODE support + + + +H5Pset_char_encoding + +herr_t H5Pset_char_encoding( hid_t plist_id, H5T_cset_t encoding ) +See entry. + +H5Pget_char_encoding + +herr_t H5Pget_char_encoding( hid_t plist_id, H5T_cset_t encoding ) +See entry. + +Object API (H5O), all new + + + +H5Oclose + +herr_t H5Oclose( hid_t object_id ) +See entry. + +H5Ocopy + +herr_t H5Ocopy( hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, const char *dst_name, hid_t ocp_plist_id, hid_t lcpl_id ) +See entry. + +H5Odecr_refcount + +herr_t H5Odecr_refcount( hid_t object_id ) +See entry. + +H5Oget_comment + +ssize_t H5Oget_comment( hid_t object_id, char *comment, size_t bufsize ) +See entry. + +H5Oget_comment_by_name + +ssize_t H5Oget_comment_by_name( hid_t loc_id, const char *name, char *comment, size_t bufsize, hid_t lapl_id ) +See entry. + +H5Oget_info + +herr_t H5Oget_info( hid_t object_id, H5O_info_t *obj_info ) +See entry. + +H5Oget_info_by_idx + +herr_t H5Oget_info_by_idx( hid_t loc_id, const char *group_name, H5_index_t index_field, H5_iter_order_t order, hsize_t n, H5O_info_t *obj_info, hid_t lapl_id ) +See entry. + +H5Oget_info_by_name + +herr_t H5Oget_info_by_name( hid_t loc_id, const char *object_name, H5O_info_t *object_info, hid_t lapl_id ) +See entry. + +H5Oincr_refcount + +herr_t H5Oincr_refcount( hid_t object_id ) +See entry. + +H5Olink + +herr_t H5Olink( hid_t obj_id, hid_t new_loc_id, const char *new_link_name, hid_t lcpl, hid_t lapl ) +See entry. + +H5Oopen + +hid_t H5Oopen( hid_t loc_id, const char *name, hid_t lapl_id ) +See entry. + +H5Oopen_by_addr + +hid_t H5Oopen_by_addr( hid_t loc_id, haddr_t addr ) +See entry. + +H5Oopen_by_idx + +herr_t H5Oopen_by_idx( hid_t loc_id, const char *group_name, H5_index_t index_field, H5_iter_order_t order, hsize_t n, hid_t lapl_id ) +See entry. + +H5Oset_comment + +herr_t H5Oset_comment( hid_t object_id, const char *comment ) +See entry. + +H5Oset_comment_by_name + +herr_t H5Oset_comment_by_name( hid_t loc_id, const char *name, const char *comment, hid_t lapl_id ) +See entry. + +H5Ovisit + +herr_t H5Ovisit( hid_t group_id, H5_index_t index_type, H5_iter_order_t order, H5O_iterate_t op, void *op_data ) +See entry. + +H5Ovisit_by_name + +herr_t H5Ovisit_by_name( hid_t loc_id, const char *object_name, H5_index_t index_type, H5_iter_order_t order, H5O_iterate_t op, void *op_data, hid_t lapl_id ) +See entry. + +Object creation or copying with +“create intermediate groups” property + + + +H5Pset_create_intermediate_group + +herr_t H5Pset_create_intermediate_group( hid_t gcpl_id, unsigned crt_intermed_group ) +See entry. + +H5Pget_create_intermediate_group + +herr_t H5Pget_create_intermediate_group( hid_t gcpl_id, unsigned *crt_intermed_group ) +See entry. + +Object copy properties + + + +H5Ocopy + +herr_t H5Ocopy( hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, const char *dst_name, hid_t ocp_plist_id, hid_t lcpl_id ) +See entry. + +H5Pset_copy_object + +herr_t H5Pset_copy_object( hid_t cplist_id, unsigned copy_options ) +See entry. + +H5Pget_copy_object + +herr_t H5Pget_copy_object( hid_t cplist_id, unsigned *copy_options ) +See entry. + +Improved object and file +information retrieval + + + +H5Aget_info + +herr_t H5Aget_info( hid_t attr_id, H5A_info_t *ainfo ) +See entry. + +H5Aget_info_by_name + +herr_t H5Aget_info_by_name( hid_t loc_id, const char *obj_name, const char *attr_name, H5A_info_t *ainfo, hid_t lapl_id ) +See entry. + +H5Aget_info_by_idx + +herr_t H5Aget_info_by_idx( hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5A_info_t *ainfo, hid_t lapl_id ) +See entry. + +H5Fget_info + +herr_t H5Fget_info( hid_t obj_id, H5F_info_t *bh_info ) +See entry. + +H5Gget_info + +herr_t H5Gget_info( hid_t group_id, H5G_info_t group_info ) +See entry. + +H5Gget_info_by_name + +herr_t H5Gget_info_by_name( hid_t loc_id, const char *group_name, H5G_info_t group_info, hid_t lapl_id ) +See entry. + +H5Gget_info_by_idx + +herr_t H5Gget_info_by_idx( hid_t loc_id, const char *group_name, H5_index_t index_type, H5_iter_order_t order, hsize_t n, H5G_info_t group_info, hid_t lapl_id ) +See entry. + +H5Lget_info + +herr_t H5Lget_info( hid_t link_loc_id, const char *link_name, H5L_info_t *link_buff, hid_t lapl_id ) +See entry. + +H5Lget_info_by_idx + +herr_t H5Lget_info_by_idx( hid_t loc_id, const char *group_name, H5_index_t index_field, H5_iter_order_t order, hsize_t n, H5L_info_t *link_val, hid_t lapl_id ) +See entry. + +H5Oget_info + +herr_t H5Oget_info( hid_t object_id, H5O_info_t *obj_info ) +See entry. + +H5Oget_info_by_name + +herr_t H5Oget_info_by_name( hid_t loc_id, const char *object_name, H5O_info_t *object_info, hid_t lapl_id ) +See entry. + +H5Oget_info_by_idx + +herr_t H5Oget_info_by_idx( hid_t loc_id, const char *group_name, H5_index_t index_field, H5_iter_order_t order, hsize_t n, H5O_info_t *obj_info, hid_t lapl_id ) +See entry. + +Name of referenced object + + + +H5Rget_name + +ssize_t H5Rget_name( hid_t loc_id, H5R_type_t ref_type, void *ref, char *name, size_t size ) +See entry. + +Anonymous object creation + + + +H5Dcreate_anon + +hid_t H5Dcreate_anon( hid_t loc_id, hid_t type_id, hid_t space_id, hid_t dcpl_id, hid_t dapl_id ) +See entry. + +H5Gcreate_anon + +hid_t H5Gcreate_anon(hid_t loc_id, const char * name, hid_t gcpl_id, hid_t gapl_id) +See entry. + +H5Tcommit_anon + +herr_t H5Tcommit_anon( hid_t loc_id, hid_t type_id, hid_t tcpl_id, hid_t tapl_id ) +See entry. + +H5Lcreate_hard + +herr_t H5Lcreate_hard( hid_t obj_loc_id, const char *obj_name, hid_t link_loc_id, const char *link_name, hid_t lcpl, hid_t lapl ) +See entry. + +New-style object creation and open +functions (includes anonymous +object creation) + + + +H5Dcreate_anon + +hid_t H5Dcreate_anon( hid_t loc_id, hid_t type_id, hid_t space_id, hid_t dcpl_id, hid_t dapl_id ) +See entry. + +H5Dcreate2 + +hid_t H5Dcreate2( hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t lcpl_id, hid_t dcpl_id, hid_t dapl_id ) +See entry. + +H5Dopen2 + +hid_t H5Dopen2( hid_t loc_id, const char *name, hid_t dapl_id ) +See entry. + +H5Gcreate_anon + +hid_t H5Gcreate_anon(hid_t loc_id, const char * name, hid_t gcpl_id, hid_t gapl_id) +See entry. + +H5Gcreate2 + +hid_t H5Gcreate2( hid_t loc_id, const char *name, hid_t lcpl_id, hid_t gcpl_id, hid_t gapl_id ) +See entry. + +H5Gopen2 + +hid_t H5Gopen2( hid_t loc_id, const char * name, hid_t gapl_id ) +See entry. + +H5Tcommit_anon + +herr_t H5Tcommit_anon( hid_t loc_id, hid_t type_id, hid_t tcpl_id, hid_t tapl_id ) +See entry. + +H5Tcommit2 + +herr_t H5Tcommit2( hid_t loc_id, const char *name, hid_t type_id, hid_t lcpl_id, hid_t tcpl_id, hid_t tapl_id ) +See entry. + +H5Topen2 + +hid_t H5Topen2( hid_t loc_id, const char * name, hid_t tapl_id ) +See entry. + +User-defined identifiers + + + +H5Iregister + +hid_t H5Iregister(H5I_type_t type, void *object) +See entry. + +H5Iregister_type + +H5I_type_t H5Iregister_type(size_t hash_size, unsigned reserved, H5I_free_t free_func) +See entry. + +H5Idestroy_type + +herr_t H5Idestroy_type(H5I_type_t type) +See entry. + +H5Iinc_type_ref + +int H5Iinc_type_ref(H5I_type_t type) +See entry. + +H5Idec_type_ref + +int H5Idec_type_ref(H5I_type_t type) +See entry. + +H5Iget_type_ref + +int H5Iget_type_ref(H5I_type_t type) +See entry. + +Other identifier API (H5I) enhancements + + + +H5Iclear_type + +herr_t H5Iclear_type(H5I_type_t type, hbool_t force) +See entry. + +H5Inmembers + +int H5Inmembers(H5I_type_t type, hsize_t *num_members) +See entry. + +H5Iobject_verify + +void * H5Iobject_verify(hid_t id, H5I_type_t id_type) +See entry. + +H5Iremove_verify + +void * H5Iremove_verify(hid_t id, H5I_type_t id_type) +See entry. + +H5Isearch + +void * H5Isearch(H5I_type_t type, H5I_search_func_t func, void *key) +See entry. + +H5Itype_exists + +htri_t H5Itype_exists(H5I_type_t type) +See entry. + +Compression filters: N-bit +and scale-offset + + + +H5Pset_nbit + +herr_t H5Pset_nbit( hid_t plist_id ) +See entry. + +H5Pset_scaleoffset + +herr_t H5Pset_scaleoffset( hid_t plist_id, H5Z_SO_scale_type_t scale_type, int scale_factor ) +See entry. + +User-defined datatype conversion +callback functions + + + +H5Pget_type_conv_cb + +herr_t H5Pget_type_conv_cb( hid_t plist, H5T_conv_except_func_t *func, void **op_data ) +See entry. + +H5Pset_type_conv_cb + +herr_t H5Pset_type_conv_cb( hid_t plist, H5T_conv_except_func_t func, void *op_data ) +See entry. + +Datatype compiler conversion check + + + +H5Tcompiler_conv + +htri_t H5Tcompiler_conv( hid_t src_id, hid_t dst_id ) +See entry. + +Dataset array size reduction + + + +H5Dset_extent + +herr_t H5Dset_extent( hid_t dset_id, const hsize_t *size ) +See entry. + +Dataspace equivalence + + + +H5Sextent_equal + +herr_t H5Sextent_equal( hid_t sid1, hid_t sid2 ) +See entry. + +Direct I/O, bypassing system cache + + + +H5Pset_fapl_direct + +herr_t H5Pset_fapl_direct( hid_t fapl_id, size_t alignment, size_t block_size, size_t cbuf_size ) +See entry. + +H5Pget_fapl_direct + +herr_t H5Pget_fapl_direct( hid_t fapl_id, size_t *alignment, size_t *block_size, size_t *cbuf_size ) +See entry. + +Parallel I/O optimization +(collective chunk I/O) + + + +H5Pset_dxpl_mpio_chunk_opt + +herr_t H5Pset_dxpl_mpio_chunk_opt(hid_t dxpl_id, H5FD_mpio_chunk_opt_t opt_mode) +See entry. + +H5Pset_dxpl_mpio_chunk_opt_num + +herr_t H5Pset_dxpl_mpio_chunk_opt_num(hid_t dxpl_id, unsigned num_chunk_per_proc) +See entry. + +H5Pset_dxpl_mpio_chunk_opt_ratio + +herr_t H5Pset_dxpl_mpio_chunk_opt_ratio(hid_t dxpl_id, unsigned percent_num_proc_per_chunk) +See entry. + +H5Pset_dxpl_mpio_collective_opt + +herr_t H5Pset_dxpl_mpio_collective_opt( hid_t dxpl_id, H5FD_mpio_collective_opt_t opt_mode ) +See entry. + +Enhanced error handling (H5E) + + + +H5Eauto_is_v2 + +herr_t H5Eauto_is_v2( hid_t estack_id, unsigned *is_stack ) +See entry. + +H5Eclear2 + +herr_t H5Eclear2( hid_t estack_id ) +See entry. + +H5Eclose_msg + +herr_t H5Eclose_msg (hid_t mesg_id) +See entry. + +H5Eclose_stack + +herr_t H5Eclose_stack(hid_t estack_id) +See entry. + +H5Ecreate_msg + +hid_t H5Ecreate_msg(hid_t class, H5E_type_t msg_type, const char* mesg) +See entry. + +H5Eget_auto2 + +herr_t H5Eget_auto2(hid_t estack_id, H5E_auto2_t * func, void **client_data) +See entry. + +H5Eget_class_name + +ssize_t H5Eget_class_name(hid_t class_id, char* name, size_t size) +See entry. + +H5Eget_current_stack + +hid_t H5Eget_current_stack(void) +See entry. + +H5Eget_msg + +ssize_t H5Eget_msg(hid_t mesg_id, H5E_type_t* mesg_type, char* mesg, size_t size) +See entry. + +H5Eget_num + +ssize_t H5Eget_num(hid_t estack_id) +See entry. + +H5Epop + +herr_t H5Epop(hid_t estack_id, size_t count) +See entry. + +H5Eprint2 + +herr_t H5Eprint2(hid_t estack_id, FILE * stream) +See entry. + +H5Epush2 + +herr_t H5Epush2(hid_t estack_id, const char *file, const char *func, unsigned line, hid_t class_id, hid_t major_id, hid_t minor_id, const char *msg, ...) +See entry. + +H5Eregister_class + +hid_t H5Eregister_class(const char* cls_name, const char* lib_name, const char* version) +See entry. + +H5Eset_auto2 + +herr_t H5Eset_auto2(hid_t estack_id, H5E_auto2_t func, void *client_data) +See entry. + +H5Eset_current_stack + +herr_t H5Eset_current_stack(hid_t estack_id) +See entry. + +H5Eunregister_class + +herr_t H5Eunregister_class(hid_t class_id) +See entry. + +H5Ewalk2 + +herr_t H5Ewalk2(hid_t estack_id, H5E_direction_t direction, H5E_walk2_t func, void * client_data) +See entry. + +Meta data cache management + + + +H5Fget_mdc_config + +herr_t H5Fget_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr) +See entry. + +H5Fget_mdc_hit_rate + +herr_t H5Fget_mdc_hit_rate(hid_t file_id, double *hit_rate_ptr) +See entry. + +H5Fget_mdc_size + +herr_t H5Fget_mdc_size(hid_t file_id, size_t *max_size_ptr, size_t *min_clean_size_ptr, size_t *cur_size_ptr, int *cur_num_entries_ptr) +See entry. + +H5Freset_mdc_hit_rate_stats + +herr_t H5Freset_mdc_hit_rate_stats(hid_t file_id) +See entry. + +H5Fset_mdc_config + +herr_t H5Fset_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr) +See entry. + +H5Pset_mdc_config + +herr_t H5Pset_mdc_config(hid_t plist_id, H5AC_cache_config_t * config_ptr) +See entry. + +H5Pget_mdc_config + +herr_t H5Pget_mdc_config(hid_t plist_id, H5AC_cache_config_t * config_ptr) +See entry. + +File read/write status + + + +H5Fget_intent + +herr_t H5Fget_intent( hid_t file_id, unsigned *intent ) +See entry. + +Arithmetic data transform on I/O + + + +H5Pget_data_transform + +herr_t H5Pget_data_transform( hid_t plist_id, char* expression, size_t size) +See entry. + +H5Pset_data_transform + +herr_t H5Pset_data_transform( hid_t plist, const char* expression ) +See entry. + +Dataspace and datatype serial conversion + + + +H5Sdecode + +hid_t H5Sdecode( const void *buf ) +See entry. + +H5Sencode + +herr_t H5Sencode( hid_t obj_id, void *buf, size_t *nalloc ) +See entry. + +H5Tdecode + +hid_t H5Tdecode( const void *buf ) +See entry. + +H5Tencode + +herr_t H5Tencode( hid_t obj_id, void *buf, size_t *nalloc ) +See entry. + +Enhanced filter management + + + +H5Pget_filter2 + +herr_t H5Pget_filter2( hid_t plist_id, unsigned idx, unsigned int *flags, size_t *cd_nelmts, unsigned cd_values[], size_t namelen, char name[], unsigned *filter_config) +See entry. + +H5Pget_filter_by_id2 + +hid_t H5Pget_filter_by_id2( hid_t plist_id, H5Z_filter_t filter_id, unsigned int *flags, size_t *cd_nelmts, unsigned int cd_values[], size_t namelen, char name[], unsigned int *filter_config) +See entry. + +Comparison of properties + + + +H5Pinsert2 + +hid_t H5Pinsert2( hid_t plid, const char *name, size_t size, void *value, H5P_prp_set_func_t set, H5P_prp_get_func_t get, H5P_prp_delete_func_t delete, H5P_prp_copy_func_t copy, H5P_prp_compare_func_t compare, H5P_prp_close_func_t close) +See entry. + +H5Pregister2 + +herr_t H5Pregister2( hid_t class, const char * name, size_t size, void * default, H5P_prp_create_func_t create, H5P_prp_set_func_t set, H5P_prp_get_func_t get, H5P_prp_delete_func_t delete, H5P_prp_copy_func_t copy, H5P_prp_compare_func_t compare, H5P_prp_close_func_t close) +See entry. + +Two-way conversion between datatype +and text description of datatype + + + +H5LTtext_to_dtype + +hid_t H5LTtext_to_datatype( const char *text, H5LT_lang_t lang_type) +See entry. + +H5LTdtype_to_text + +herr_t H5LTdtype_to_text( hid_t datatype, char *str, H5LT_lang_t lang_type, size_t *len) +See entry. + +Fortran subroutines: + +New Fortran subroutines in the main library are not yet included for Release 1.8.0-beta. + +See below for Fortran routines for High-Level HDF5 APIs. + +C++ wrappers: + +There no new C++ wrappers for Release 1.8.0-beta. + +High Level C APIs: + +H5LT: The following functions have been added to the HDF5 Lite (H5LT) API: + +H5LTtext_to_dtype + +hid_t H5LTtext_to_datatype( const char *text, H5LT_lang_t lang_type) +See entry. + +H5LTdtype_to_text + +herr_t H5LTdtype_to_text( hid_t datatype, char *str, H5LT_lang_t lang_type, size_t *len) +See entry. + +H5LTset_attribute_long_long + +herr_t H5LTset_attribute_long_long( hid_t loc_id, const char *obj_name, const char *attr_name, const long_long *data, size_t *size) +See entry. + +H5LTget_attribute_long_long + +herr_t H5LTget_attribute_long_long( hid_t loc_id, const char *obj_name, const char *attr_name, long_long *data) +See entry. + +Two high-level C APIs are distributed for the first time with this release: + + +H5PT, the HDF5 Packet Table interface +H5DS, the HDF5 Dimension Scale interface +Full documentation for these interfaces can be accessed directly from the High Level APIs overview page. + +The new functions included in the packet table (H5PT) high-level APIs are as follows: + +H5PTcreate_fl + +hid_t H5PTcreate_fl( hid_t loc_id, const char * dset_name, hid_t dtype_id, hsize_t chunk_size ) + +H5PTcreate_vl + +hid_t H5PTcreate_vl( hid_t loc_id, const char *dset_name, hsize_t chunk_size ) + +H5PTopen + +hid_t H5PTopen( hid_t loc_id, const char *dset_name ) + +H5PTclose + +herr_t H5PTclose( hid_t table_id ) + +H5PTappend + +herr_t H5PTappend( hid_t table_id, hsize_t nrecords, const void *data) + +H5PTcreate_index + +herr_t H5PTcreate_index( hid_t table_id) + +H5PTset_index + +herr_t H5PTset_index( hid_t table_id, hsize_t pt_index) + +H5PTread_packets + +herr_t H5PTread_packets( hid_t table_id, hsize_t start, hsize_t nrecords, void *data) + +H5PTget_next + +herr_t H5PTget_next( hid_t table_id, hsize_t nrecords, void *data) + +H5PTget_num_packets + +herr_t H5PTget_num_packets( hid_t table_id, hsize_t * nrecords) + +H5PTis_valid + +herr_t H5PTis_valid( hid_t table_id) + +H5PTis_varlen + +herr_t H5PTis_varlen( hid_t table_id) + +H5PTfree_vlen_readbuff + +herr_t H5PTfree_vlen_readbuff( hid_t table_id, hsize_t bufflen, void * buff) + + + + +The new functions included in the dimension scale (H5DS) high-level APIs are as follows: + +H5DSset_scale + +herr_t H5DSmake_scale(hid_t dsid, char *dimname) + +H5DSattach_scale + +herr_t H5DSattach_scale(hid_t did, hid_t dsid, unsigned int idx) + +H5DSdetach_scale + +herr_t H5DSdetach_scale(hid_t did, hid_t dsid, unsigned int idx) + +H5DSis_attached + +htri_t H5DSis_attached(hid_t did, hid_t dsid, unsigned int idx) + +H5DSis_scale + +htri_t H5DSis_scale(hid_t did) + +H5DSiterate_scales + +herr_t H5DSiterate_scales(hid_t did, unsigned dim, int *idx, H5DS_iterate_t visitor, void *visitor_data) + +H5DSset_label + +herr_t H5DSset_label(hid_t did, unsigned int idx, const char *label) + +H5DSget_label + +ssize_t H5DSget_label(hid_t did, unsigned int idx, char *label, size_t size) + +H5DSget_scale_name + +hssize_t H5DSget_scale_name(hid_t did, char name, size_t *size) + +H5DSget_num_scales + +int H5DSget_num_scales(hid_t did, unsigned int idx) + +High Level Fortan90 APIs: + +Fortran90 subroutines are now available for the following high-level APIs: + H5LT: HDF5 Lite + H5IM: HDF5 Image + H5TB: HDF5 Table + +Tools: + +h5stat + +Deprecated and Deleted Functions +The following functions, subroutines and wrappers have been removed in this release: + +C functions: + + + +H5Pset_fapl_gass +H5Pget_fapl_gass + + + + +HDF5 no longer provides GASS support. + +H5Pset_fapl_srb +H5Pget_fapl_srb + + + + + +HDF5 no longer provides SRB support. +SRB functionality is now supported through the mechanism described in SRB — The DICE Storage Resource Broker. + +H5Pset_fapl_stream +H5Pget_fapl_stream + + + + +The stream virtual file driver (H5FD_STREAM) has been removed from the HDF5 distribution. The functionality was last available from http://hdf5-addons.origo.ethz.ch/. + +H5Tset_overflow +H5Tget_overflow + + + +These two functions are replaced by H5Pget_type_conv_cb and H5Pset_type_conv_cb. + +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_NBIT + H5Z_FILTER_SCALEOFFSET + + +H5Pget_filter + +Two new filter identifiers are available as the return value: + H5Z_FILTER_NBIT + H5Z_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_F + H5Z_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_t n) + +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: + version + encoder_present + decoder_present +The struct is now defined as follows: + + + typedef struct H5Z_class_t { + int version; + H5Z_filter_t filter_id; + unsigned encoder_present + unsigned decoder_present + const char *comment; + H5Z_can_apply_func_t can_apply_func; + H5Z_set_local_func_t set_local_func; + H5Z_func_t filter_func; + } H5Z_class_t; +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_GROUP + H5G_DATASET + H5G_TYPE + H5G_LINK + + +H5I_type_t — Identifier types + +The following symbols have been added to this ENUM: + H5I_UNINT + H5I_ERROR_CLASS + H5I_ERROR_MSG + H5I_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_NBIT + H5Z_FILTER_SCALEOFFSET + + +New Datatypes +The following OpenVMS-specific floating point datatypes are new with this release: + +H5T_VAX_F32 + +H5T_VAX_F64 + +New Property Lists +The following property lists are new with this release: + +H5P_DATASET_ACCESS + +H5P_GROUP_CREATE + +H5P_GROUP_ACCESS + +H5P_DATATYPE_CREATE + +H5P_DATATYPE_ACCESS + +H5P_ATTRIBUTE_CREATE + +Changed Library Configuration +The following configuration features have changed as follows. + +New with this release: + --disable-dependency-tracking + + --enable-hdf5v1_6 + + --enable-dconv-exception + --disable-dconv-exception + --enable-dconv-accuracy + --disable-dconv-accuracy + + --program-prefix=PREFIX + --program-prefix=SUFFIX + --program-transform-name=PROGRAM + + --enable-maintainer-mode + + --disable-dependency-tracking + --enable-dependency-tracking + + --enable-codestack + + --enable-direct-vfd + + --with-tags[=TAGS] + +New with this release, but expected to be useful only to those working inside the HDF5 Library or working very closely with HDF5 developers: + --enable-build-all + --enable-metadata-trace-file + +New with this release, but not actively supported: + --enable-fphdf5 + +Changed in this release: + --enable-shared[=PKGS] + --enable-static[=PKGS] + --enable-fast-install[=PKGS] + +Removed in this release: + --enable-hdf5v1_4 + --enable-funcstack + --with-ssl=LIB + --with-gass=DIR + --with-srb=DIR +The environment variables FC and FCFLAGS replace F9X and F9XFLAGS, respectively, which are deprecated in this release. + +Additional new “influential environment variables” in this release include the following: + CXX + CXXFLAGS + CXXCPP + F77 + FFLAGS + + \ No newline at end of file