diff options
author | Gerd Heber <gheber@hdfgroup.org> | 2020-11-10 20:57:54 (GMT) |
---|---|---|
committer | GitHub <noreply@github.com> | 2020-11-10 20:57:54 (GMT) |
commit | c0c0b6b47ffaebd158da055d04b9e9f88d8730ef (patch) | |
tree | 8d60ea50a86559873d0cdac9b1828ea90779e898 | |
parent | 9cc9107dfa34b4f28a6ed4d80ebf7e7182fe6809 (diff) | |
parent | 29b8231f92fb6b8da5e79e9f702135dec9819d07 (diff) | |
download | hdf5-c0c0b6b47ffaebd158da055d04b9e9f88d8730ef.zip hdf5-c0c0b6b47ffaebd158da055d04b9e9f88d8730ef.tar.gz hdf5-c0c0b6b47ffaebd158da055d04b9e9f88d8730ef.tar.bz2 |
Merge pull request #78 from gheber/develop
This is the first installment of Doxygen-based documentation for the H5F module.
-rw-r--r-- | doxygen/Doxyfile.in | 4 | ||||
-rw-r--r-- | doxygen/dox/H5Oget_info_by_name.dox | 18 | ||||
-rw-r--r-- | doxygen/dox/api-compat-macros.dox | 899 | ||||
-rw-r--r-- | doxygen/dox/mainpage.dox | 4 | ||||
-rw-r--r-- | src/H5Fmodule.h | 13 | ||||
-rw-r--r-- | src/H5Fpublic.h | 1314 | ||||
-rw-r--r-- | src/H5public.h | 6 |
7 files changed, 2143 insertions, 115 deletions
diff --git a/doxygen/Doxyfile.in b/doxygen/Doxyfile.in index 22a16e9..711fa7a 100644 --- a/doxygen/Doxyfile.in +++ b/doxygen/Doxyfile.in @@ -263,6 +263,8 @@ TAB_SIZE = 4 ALIASES = +@INCLUDE = @DOXYGEN_INCLUDE_ALIASES@ + # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources # only. Doxygen will then generate output that is more tailored for C. For # instance, some of the names that are used will be different. The list of all @@ -2146,7 +2148,7 @@ SEARCH_INCLUDES = YES # preprocessor. # This tag requires that the tag SEARCH_INCLUDES is set to YES. -INCLUDE_PATH = @DOXYGEN_INCLUDE_ALIASES@ +INCLUDE_PATH = # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard # patterns (like *.h and *.hpp) to filter out the header-files in the diff --git a/doxygen/dox/H5Oget_info_by_name.dox b/doxygen/dox/H5Oget_info_by_name.dox index 3276c5a..b1b9540 100644 --- a/doxygen/dox/H5Oget_info_by_name.dox +++ b/doxygen/dox/H5Oget_info_by_name.dox @@ -12,9 +12,9 @@ * document closely. * * In HDF5 versions 1.12 and after, #H5Oget_info_by_name is mapped to - * \ref H5Oget_info_by_name3(). In version 1.10 #H5Oget_info_by_name is - * identical to \ref H5Oget_info_by_name1(). - * + * \ref H5Oget_info_by_name3(). In version 1.10 #H5Oget_info_by_name is + * identical to \ref H5Oget_info_by_name1(). + * * Specific compile-time compatibility flags and the resulting * mappings are as follows: * @@ -66,27 +66,27 @@ * </tr> * <tr> * <td></td> - * <td>This change was added to restore the broken API compatibility + * <td>This change was added to restore the broken API compatibility * introduced in HDF5-1.10.3.</td> * </tr> * <tr> * <td>1.10.3</td> - * <td>The function \ref H5Oget_info_by_name() was renamed + * <td>The function \ref H5Oget_info_by_name() was renamed * to \ref H5Oget_info_by_name1.</td> * </tr> * <tr> * <td></td> - * <td>The macro #H5Oget_info_by_name was renamed to + * <td>The macro #H5Oget_info_by_name was renamed to * \ref H5Oget_info_by_name1().</td> * </tr> * <tr> * <td></td> - * <td>The macro #H5Oget_info_by_name and the function \ref H5Oget_info_name2() + * <td>The macro #H5Oget_info_by_name and the function \ref H5Oget_info_by_name2() * were introduced in this release.</td> * </tr> * <tr> * <td>1.8.8</td> - * <td>Fortran 2003 subroutine and \ref h5o_info_t derived + * <td>Fortran 2003 subroutine and \ref H5O_info_t derived * type introduced in this release.</td> * </tr> * <tr> @@ -95,5 +95,5 @@ * </tr> * </table> * - * + * */ diff --git a/doxygen/dox/api-compat-macros.dox b/doxygen/dox/api-compat-macros.dox new file mode 100644 index 0000000..6b85ccb --- /dev/null +++ b/doxygen/dox/api-compat-macros.dox @@ -0,0 +1,899 @@ +/** \page api-compat-macros API Compatibility Macros + \tableofcontents + + \section audience 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. + + \section compat-issues 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. + + \section summary 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 \Emph{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: + <ul> + <li>Source code is not available - only binaries are available; updating the + application is not feasible.</li> + <li>Source code is available, but there are no resources to update it.</li> + <li>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.</li> + <li>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.</li> + </ul> + + \section using 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, e.g., '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, e.g., '1') + at the end of the original function name. + + For example, consider the function \Code{H5Lvisit} in HDF5 release 1.10 + as compared with 1.12: + + <table> + <tr> + <th>Original function name and signature in 1.10.0</th> + <td colspan="1"> + \Code{herr_t H5Lvisit(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate_t op, void *op_data)} + </td> + </tr> + <tr> + <th>Updated function and signature, introduced in release 1.12.0</th> + <td colspan="1"> + \Code{herr_t H5Lvisit2(hid_t group_id, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate2_t op, void *op_data)} + </td> + </tr> + <tr><th>Original function and signature, renamed in release 1.12.0</th> + <td colspan="1"> + \Code{herr_t H5Lvisit1(hid_t group_id, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate1_t op, void *op_data)} + </td> + </tr> + <tr><th>API compatibility macro, introduced in release 1.12.0</th> + <td colspan="1"> + \Code{H5Lvisit} + <p>The macro, \Code{H5Lvisit}, will be mapped to either \Code{H5Lvisit1} or + \Code{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 + \Code{H5Lvisit} compatibility macro should match the number and type of the + function the macros will be mapped to (\Code{H5Lvisit1} or \Code{H5Lvisit2}). + </p> + <p>The function names ending in '1' or '2' are referred to as \Emph{versioned names}, + and the corresponding functions are referred to as \Emph{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. + </p> + </td> + </tr> + </table> + + \section options 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 + \Emph{compatibility macro mapping options}, is considered in the following sequence: + + <table border="0" style="width: 100.0%;"> + <tr> + <td valign="top" width="50%"> + <ol> + <li>What compatibility macro configuration option was used to build the HDF5 library? + We refer to this selection as the \Emph{library mapping}.</li> + <li>Was a compatibility macro global compile-time option specified when the application + was built? We refer to this (optional) selection as the \Emph{application mapping}. + If an application mapping exists, it overrides the library mapping. + \Emph{(See adjacent notes.)}</li> + <li>Were any compatibility macro function-level compile-time options specified when the + application was built? We refer to these (optional) selections as \Emph{function mappings}. + If function mappings exist, they override library and application mappings for the + relevant API compatibility macros. \Emph{(See adjacent notes.)}</li> + </ol> + </td> + <td valign="top" width="50%"> + <table border="1" cellpadding="10" style="width: 100.0%;"> + <tr><td> + \Bold{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. + </td> + </tr> + </table> + </td> + </tr> + </table> + + \subsection lib-options Library Mapping Options + When the HDF5 library is built, \Code{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. + + <div align="center">Table 1: Library Mapping Options + <table border="1" cellpadding="3"> + <tr> + <th>\Code{configure} flag</th> + <th>Macros map to release <br/> (versioned function; \Code{H5Lvisit} shown)</th> + <th>Deprecated functions available? <br/> (\Code{H5Lvisit1})</th> + </tr> + <tr align="center"> + <td>\Code{--with-default-api-version=v112} <br/> (the default in 1.12)</td> + <td>1.12.x (\Code{H5Lvisit2})</td> + <td>yes</td> + </tr> + <tr align="center"> + <td align="left">\Code{--with-default-api-version=v110}</td> + <td>1.10.x (\Code{H5Lvisit1})</td> + <td>yes</td> + </tr> + <tr align="center"> + <td align="left">\Code{--with-default-api-version=v18}</td> + <td>1.8.x (\Code{H5Lvisit1})</td> + <td>yes</td> + </tr> + <tr align="center"> + <td align="left">\Code{--with-default-api-version=v16}</td> + <td>1.6.x (\Code{H5Lvisit1})</td> + <td>yes</td> + </tr> + <tr align="center"> + <td align="left">\Code{--disable-deprecated-symbols}</td> + <td>1.12.x (\Code{H5Lvisit2})</td> + <td>no</td> + </tr> + </table> + </div> + Refer to the file \Code{libhdf5.settings} in the directory where the HDF5 library is + installed to determine the \Code{configure} flags used to build the library. In particular, + look for the two lines shown here under \Emph{Features}: + + \Code{Default API mapping: v112} + + \Code{With deprecated public symbols: yes} + + \subsection app-options Application Mapping Options + When an application using HDF5 APIs is built and linked with the HDF5 library, + compile-time options to \Code{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 \Code{--disable-deprecated-symbols} flag, then + the deprecated functions will not be available, regardless of the application mapping options. + + <div align="center">Table 2: Application Mapping Options + <table border="1" cellpadding="3"> + <tr> + <th>\Code{h5cc} option</th> + <th>Macros map to release <br/>(versioned function; \Code{H5Lvisit} shown)</th> + <th>Deprecated functions available? <br/>(\Code{H5Lvisit1})</th> + </tr> + <tr align="center"> + <td align="left">\Code{-DH5_USE_112_API} <br/> \Emph{(Default behavior if no option specified.)}</td> + <td>1.12.x (\Code{HLvisit2})</td> + <td>yes* <br/> \Emph{*if available in library}</td> + </tr> + <tr align="center"> + <td align="left">\Code{-DH5_USE_110_API}</td> + <td>1.10.x (\Code{HLvisit1})</td> + <td>yes* <br/> \Emph{*if available in library}</td> + </tr> + <tr align="center"> + <td align="left">\Code{-DH5_USE_18_API}</td> + <td>1.8.x (\Code{H5Lvisit1})</td> + <td>yes* <br/> \Emph{*if available in library}</td> + </tr> + <tr align="center"> + <td align="left">\Code{-DH5_USE_16_API}</td> + <td>1.6.x (\Code{H5Lvisit1})</td> + <td>yes* <br/> \Emph{*if available in library}</td> + </tr> + <tr align="center"> + <td align="left">\Code{-DH5_NO_DEPRECATED_SYMBOLS}</td> + <td>1.10.x (\Code{H5Lvisit1})</td> + <td>no</td> + </tr> + </table> + </div> + + \subsection fun-options 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 \Code{--disable-deprecated-symbols} + flag, or \Code{-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 + "\Code{_vers}" which is mapped by number to a specific function or + struct: + <table> + <tr> + <th>Macro</th> + <th>Function Mapping</th> + <th>Mapped to function or struct</th> + </tr> + <tr><td>\Code{H5xxx}</td> + <td>\Code{H5xxx_vers=1}</td> + <td>\Code{H5xxx1}</td> + </tr> + <tr> + <td> </td> + <td>\Code{H5xxx_vers=2}</td> + <td>\Code{H5xxx2}</td> + </tr> + </table> + + For example, in version 1.10 the \Code{H5Rreference} macro can be mapped to + either \Code{H5Rreference1} or \Code{H5Rreference2}. When used, the value of + the \Code{H5Rreference_vers} compile-time version flag determines which + function will be called: + + <ul> + <li>When \Code{H5Rreference_vers} is set to \Code{1}, the macro \Code{H5Rreference} + will be mapped to \Code{H5Rreference1}. <br/> + \Code{H5cc ... -DH5Rreference_vers=1 ...}</li> + <li>When \Code{H5Rdereference_vers} is set to \Code{2}, the macro \Code{H5Rdereference} + will be mapped to \Code{H5Rdereference2}. <br/> + \Code{h5cc ... -DH5Rreference_vers=2 ...}</li> + <li>When \Code{H5Rreference_vers} is not set, the macro \Code{H5Rreference} will be + mapped to either \Code{H5Rreference1} or \Code{H5Rreference2}, based on the + application mapping, if one was specified, or on the library mapping. <br/> + \Code{h5cc ... }</li> + </ul> + + \warning 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. \Emph{In 1.12, mappings of structures + are used by the H5L and H5O function mappings.}\n\n + For example, an application \Code{application.c} only calls \Code{H5Lvisit}, + \Code{H5Ovisit}, and \Code{H5Oget_info_by_name}. To compile this application + with 1.10 APIs in 1.12 with the function specific mappings, then not only must + \Code{H5Lvisit_vers}, \Code{H5Ovisit_vers}, and \Code{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: + \code{.sh} + 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= -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 application.c + \endcode + + \subsubsection fun-options-112 Function Mapping Options in Releases 1.12.x + <table> + <tr> + <th style="text-align: left;">Macro <br/> (\Code{H5xxx})</th> + <th>Default function used if no macro specified + <ul><li>Function/struct mapping:\Code{H5xxx_vers=N}</li></ul> + </th> + <th>Function used if specifying 1.10 + <ul><li>Function/struct mapping: \Code{H5xxx_vers=1}</li></ul> + </th> + </tr> + <tr> + <td>H5Lget_info()</td> + <td>H5Lget_info2() + <ul> + <li>Function mapping:\Code{H5Lget_info_vers=2}</li> + <li>Struct mapping:\Code{H5L_info_t_vers=2}</li> + </ul> + </td> + <td>H5Lget_info1() + <ul> + <li>Function mapping \Code{H5Lget_info_vers=1}</li> + <li>Struct mapping: \Code{H5L_info_t_vers=1}</li> + </ul> + </td> + </tr> + <tr> + <td>H5Lget_info_by_idx()</td> + <td>H5Lget_info_by_idx2() + <ul> + <li>Function mapping: \Code{H5Lget_info_by_idx_vers=2}</li> + <li>Struct mapping: \Code{H5L_info_t_vers=2}</li> + </ul> + </td> + <td>H5Lget_info_by_idx1() + <ul> + <li>Function mapping: \Code{H5Lget_info_by_idx_vers=1}</li> + <li>Struct mapping: \Code{H5L_info_t_vers=1}</li> + </ul> + </td> + </tr> + <tr> + <td>H5Literate()</td> + <td>H5Literate2() + <ul> + <li>Function mapping: \Code{H5Literate_vers=2}</li> + <li>Struct mapping: \Code{H5L_iterate_t_vers=2}</li> + </ul> + </td> + <td>H5Literate1() + <ul> + <li>Function mapping: \Code{H5Literate_vers=1}</li> + <li>Struct mapping: \Code{H5L_iterate_t_vers=1}</li> + </ul> + </td> + </tr> + <tr> + <td>H5Literate_by_name()</td> + <td>H5Literate_by_name2() + <ul> + <li>Function mapping: \Code{H5Literate_by_name_vers=2}</li> + <li>Struct mapping: \Code{H5L_iterate_t_vers=2}</li> + </ul> + </td> + <td>H5Literate_by_name1() + <ul> + <li>Function mapping: \Code{H5Literate_by_name_vers=1}</li> + <li>Struct mapping: \Code{H5L_iterate_t_vers=1}</li> + </ul> + </td> + </tr> + <tr> + <td>H5Lvisit()</td> + <td>H5Lvisit2() + <ul> + <li>Function mapping: \Code{H5Lvisit_vers=2}</li> + <li>Struct mapping: \Code{H5L_iterate_t_vers=2}</li> + </ul> + </td> + <td>H5Lvisit1() + <ul> + <li>Function mapping: \Code{H5Lvisit_vers=1}</li> + <li>Struct mapping: \Code{H5L_iterate_t_vers=1}</li> + </ul> + </td> + </tr> + <tr> + <td>H5Lvisit_by_name()</td> + <td>H5Lvisit_by_name2() + <ul> + <li>Function mapping: \Code{H5Lvisit_by_name_vers=2}</li> + <li>Struct mapping: \Code{H5L_iterate_t_vers=2}</li> + </ul> + </td> + <td>H5Lvisit_by_name1() + <ul> + <li>Function mapping: \Code{H5Lvisit_by_name_vers=1}</li> + <li>Struct mapping: \Code{H5L_iterate_t_vers=1}</li> + </ul> + </td> + </tr> + <tr> + <td>H5Oget_info()</td> + <td>H5Oget_info3() + <ul> + <li>Function mapping: \Code{H5Oget_info_vers=3}</li> + <li>Struct mapping: \Code{H5O_info_t_vers=2}</li> + </ul> + </td> + <td>H5Oget_info1() + <ul> + <li>Function mapping: \Code{H5Oget_info_vers=1}</li> + <li>Struct mapping: \Code{H5O_info_t_vers=1}</li> + </ul> + </td> + </tr> + <tr> + <td>H5Oget_info_by_idx()</td> + <td>H5Oget_info_by_idx3() + <ul><li>Function mapping: \Code{H5Oget_info_by_idx_vers=3}</li> + <li>Struct mapping: \Code{H5O_info_t_vers=2}</li> + </ul> + </td> + <td>H5Oget_info_by_idx1() + <ul> + <li>Function mapping: \Code{H5Oget_info_by_idx_vers=1}</li> + <li>Struct mapping: \Code{H5O_info_t_vers=1}</li> + </ul> + </td> + </tr> + <tr> + <td>H5Oget_info_by_name()</td> + <td>H5Oget_info_by_name3() + <ul> + <li>Function mapping: \Code{H5O_get_info_by_name_vers=3}</li> + <li>Struct mapping: \Code{H5O_info_t_vers=2}</li> + </ul> + </td> + <td>H5Oget_info_by_name1() + <ul> + <li>Function mapping: \Code{H5O_get_info_by_name_vers=1}</li> + <li>Struct mapping: \Code{H5O_info_t_vers=1}</li> + </ul> + </td> + </tr> + <tr> + <td>H5Ovisit()</td> + <td>H5Ovisit3() + <ul> + <li>Function mapping: \Code{H5Ovisit_vers=3}</li> + <li>Struct mapping: \Code{H5O_iterate_t_vers=2}</li> + </ul> + </td> + <td>H5Ovisit1() + <ul><li>Function mapping: \Code{H5Ovisit_vers=1}</li> + <li>Struct mapping: \Code{H5O_iterate_t_vers=1}</li> + </ul> + </td> + </tr> + <tr> + <td>H5Ovisit_by_name()</td> + <td>H5Ovisit_by_name3() + <ul> + <li>Function mapping: \Code{H5Ovisit_by_name_vers=3}</li> + <li>Struct mapping: \Code{H5O_iterate_t_vers=2}</li> + </ul> + </td> + <td>H5Ovisit_by_name1() + <ul> + <li>Function mapping: \Code{H5Ovisit_by_name_vers=1}</li> + <li>Struct mapping: \Code{H5O_iterate_t_vers=1}</li> + </ul> + </td> + </tr> + <tr> + <td>H5Pencode()</td> + <td>H5Pencode2() + <ul> + <li>Function mapping: \Code{H5Pencode_vers=2}</li> + </ul> + </td> + <td>H5Pencode1() + <ul> + <li>Function mapping: \Code{H5Pencode_vers=1}</li> + </ul> + </td> + </tr> + <tr> + <td>H5Sencode()</td> + <td>H5Sencode2() + <ul> + <li>Function mapping: \Code{H5Sencode_vers=2}</li> + </ul> + </td> + <td>H5Sencode1() + <ul> + <li>Function mapping: \Code{H5Sencode_vers=1}</li> + </ul> + </td> + </tr> + </table> + + \subsubsection fun-options-110 Function Mapping Options in Releases 1.10.x + <table> + <tr> + <th>Macro</th> + <th>Default function used <br/> <sub>(if no macro specified)</sub></th> + <th>Introduced in</th> + <th>\Code{h5cc} version flag and value</th> + <th>Mapped to function or struct</th> + </tr> + <tr> + <td rowspan="2">H5Rdereference()</td> + <td rowspan="2">H5Rdereference2()</td> + <td rowspan="2">HDF5-1.10.0</td> + <td>\Code{-DH5Rdereference_vers=1}</td> + <td>H5Rdereference1()</td> + </tr> + <tr> + <td>\Code{-DH5Rdereference_vers=2}</td> + <td>H5Rdereference2()</td> + </tr> + <tr> + <td rowspan="2">H5Fget_info()</td> + <td rowspan="2">H5Fget_info2()</td> + <td rowspan="2">HDF5-1.10.0</td> + <td>\Code{-DH5Fget_info_vers=1}</td> + <td>H5Fget_info1() with struct \ref H5F_info1_t</td> + </tr> + <tr> + <td>\Code{-DH5Fget_info_vers=2}</td> + <td>H5Fget_info2() with struct \ref H5F_info2_t</td> + </tr> + <tr> + <td rowspan="2">H5Oget_info()</td> + <td rowspan="2">H5Oget_info1()</td> + <td rowspan="2">HDF5-1.10.3</td> + <td>\Code{-DH5Oget_info_vers=1}</td> + <td>H5Oget_info1()</td> + </tr> + <tr> + <td>\Code{-DH5Oget_info_vers=2}</td> + <td>H5Oget_info2()</td> + </tr> + <tr> + <td rowspan="2">H5Oget_info_by_idx()</td> + <td rowspan="2">H5Oget_info_by_idx1()</td> + <td rowspan="2">HDF5-1.10.3</td> + <td>\Code{-DH5Oget_info_by_idx_vers=1}</td> + <td>H5Oget_info_by_idx1()</td> + </tr> + <tr> + <td>\Code{-DH5Oget_info_by_idx_vers=2}</td> + <td>H5Oget_info_by_idx2()</td> + </tr> + <tr> + <td rowspan="2">H5Oget_info_by_name()</td> + <td rowspan="2">H5Oget_info_by_name1()</td> + <td rowspan="2">HDF5-1.10.3</td> + <td>\Code{-DH5Oget_info_by_name_vers=1}</td> + <td>H5Oget_info_by_name1()</td> + </tr> + <tr> + <td>\Code{-DH5Oget_info_by_name_vers=2}</td> + <td>H5Oget_info_by_name2()</td> + </tr> + <tr> + <td rowspan="2">H5Ovisit()</td> + <td rowspan="2">H5Ovisit1()</td> + <td rowspan="2">HDF5-1.10.3</td> + <td>\Code{-DH5Ovisit_vers=1}</td> + <td>H5Ovisit1()</td> + </tr> + <tr> + <td>\Code{-DH5Ovisit_vers=2}</td> + <td>H5Ovisit2()</td> + </tr> + <tr> + <td rowspan="2">H5Ovisit_by_name()</td> + <td rowspan="2">H5Ovisit_by_name1()</td> + <td rowspan="2">HDF5-1.10.3</td> + <td>\Code{-DH5Ovisit_by_name_vers=1}</td> + <td>H5Ovisit_by_name1()</td> + </tr> + <tr> + <td>\Code{-DH5Ovisit_by_name_vers=2}</td> + <td>H5Ovisit_by_name2()</td> + </tr> + </table> + + \subsubsection fun-options-18 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. + + <div align="center">Table 5: Function Mapping Options in Releases 1.8.x + <table border="1" cellpadding="3" style="width: 90.0%;"> + <tr> + <th>Macro</th> + <th><code>h5cc</code> version flag and value</th> + <th>Mapped to function <br/> or struct</th> + </tr> + <tr> + <td rowspan="2">H5Acreate()</td> + <td>\Code{DH5Acreate_vers=1}</td> + <td>H5Acreate1()</td> + </tr> + <tr> + <td>\Code{DH5Acreate_vers=2}</td> + <td>H5Acreate2()</td> + </tr> + <tr> + <td rowspan="2">H5Aiterate()</td> + <td>\Code{DH5Aiterate_vers=1}</td> + <td>H5Aiterate1() <br/> with struct \ref H5A_operator1_t</td> + </tr> + <tr> + <td>\Code{DH5Aiterate_vers=2}</td> + <td>H5Aiterate2() <br/> with struct \ref H5A_operator2_t</td> + </tr> + <tr> + <td rowspan="2">H5Dcreate()</td> + <td>\Code{DH5Dcreate_vers=1}</td> + <td>H5Dcreate1()</td> + </tr> + <tr> + <td>\Code{DH5Dcreate_vers=2}</td> + <td>H5Dcreate2()</td> + </tr> + <tr><td rowspan="2">H5Dopen()</td> + <td>\Code{DH5Dopen_vers=1}</td> + <td>H5Dopen1()</td> + </tr> + <tr> + <td>\Code{DH5Dopen_vers=2}</td> + <td>H5Dopen2()</td> + </tr> + <tr> + <td rowspan="2">H5Eclear()</td> + <td>\Code{DH5Eclear_vers=1}</td> + <td>H5Eclear1()</td> + </tr> + <tr> + <td>\Code{DH5Eclear_vers=2}</td> + <td>H5Eclear2()</td> + </tr> + <tr> + <td rowspan="2">H5Eprint()</td> + <td>\Code{DH5Eprint_vers=1}</td> + <td>H5Eprint1()</td> + </tr> + <tr> + <td>\Code{DH5Eprint_vers=2}</td> + <td>H5Eprint2()</td> + </tr> + <tr> + <td rowspan="2">H5Epush()</td> + <td>\Code{DH5Epush_vers=1}</td> + <td>H5Epush1()</td> + </tr> + <tr> + <td>\Code{DH5Epush_vers=2}</td> + <td>H5Epush2()</td> + </tr> + <tr> + <td rowspan="2">H5Eset_auto()</td> + <td>\Code{DH5Eset_auto_vers=1}</td> + <td>H5Eset_auto1()</td> + </tr> + <tr> + <td>\Code{DH5Eset_auto_vers=2}</td> + <td>H5Eset_auto2()</td> + </tr> + <tr> + <td rowspan="2">H5Eget_auto()</td> + <td>\Code{DH5Eget_auto_vers=1}</td> + <td>H5Eget_auto1()</td> + </tr> + <tr> + <td>\Code{DH5Eget_auto_vers=2}</td> + <td>H5Eget_auto2()</td> + </tr> + <tr> + <td rowspan="2">\ref H5E_auto_t <br/> struct for H5Eset_auto() <br/> and H5Eget_auto()</td> + <td>\Code{DH5E_auto_t_vers=1}</td> + <td>\ref H5E_auto1_t</td> + </tr> + <tr> + <td>\Code{DH5E_auto_t_vers=2}</td> + <td>\ref H5E_auto2_t</td> + </tr> + <tr> + <td rowspan="2">H5Ewalk()</td> + <td>\Code{DH5Ewalk_vers=1}</td> + <td>H5Ewalk1() <br/> with callback \ref H5E_walk1_t <br/> and struct \ref H5E_error1_t</td> + </tr> + <tr> + <td>\Code{DH5Ewalk_vers=2}</td> + <td>H5Ewalk2() <br/> with callback \ref H5E_walk2_t <br/> and struct \ref H5E_error2_t</td> + </tr> + <tr> + <td rowspan="2">H5Gcreate()</td> + <td>\Code{DH5Gcreate_vers=1}</td> + <td>H5Gcreate1()</td> + </tr> + <tr> + <td>\Code{DH5Gcreate_vers=2}</td> + <td>H5Gcreate2()</td> + </tr> + <tr> + <td rowspan="2">H5Gopen()</td> + <td>\Code{DH5Gopen_vers=1}</td> + <td>H5Gopen1()</td> + </tr> + <tr> + <td>\Code{DH5Gopen_vers=2}</td> + <td>H5Gopen2()</td> + </tr> + <tr> + <td rowspan="2">H5Pget_filter()</td> + <td>\Code{DH5Pget_filter_vers=1}</td> + <td>H5Pget_filter1()</td> + </tr> + <tr> + <td>\Code{DH5Pget_filter_vers=2}</td> + <td>H5Pget_filter2()</td> + </tr> + <tr> + <td rowspan="2">H5Pget_filter_by_id()</td> + <td>\Code{DH5Pget_filter_by_id_vers=1}</td> + <td>H5Pget_filter_by_id1()</td> + </tr> + <tr> + <td>\Code{DH5Pget_filter_by_id_vers=2}</td> + <td>H5Pget_filter_by_id2()</td> + </tr> + <tr> + <td rowspan="2">H5Pinsert()</td> + <td>\Code{DH5Pinsert_vers=1}</td> + <td>H5Pinsert1()</td> + </tr> + <tr> + <td>\Code{DH5Pinsert_vers=2}</td> + <td>H5Pinsert2()</td> + </tr> + <tr> + <td rowspan="2">H5Pregister()</td> + <td>\Code{DH5Pregister_vers=1}</td> + <td>H5Pregister1()</td> + </tr> + <tr> + <td>\Code{DH5Pregister_vers=2}</td> + <td>H5Pregister2()</td> + </tr> + <tr> + <td rowspan="2">H5Rget_obj_type()</td> + <td>\Code{DH5Rget_obj_typevers=1}</td> + <td>H5Rget_obj_type1()</td> + </tr> + <tr> + <td>\Code{DH5Rget_obj_type_vers=2}</td> + <td>H5Rget_obj_type2()</td> + </tr> + <tr> + <td rowspan="2">H5Tarray_create()</td> + <td>\Code{DH5Tarray_create_vers=1}</td> + <td>H5Tarray_create1()</td> + </tr> + <tr> + <td>\Code{DH5Tarray_create_vers=2}</td> + <td>H5Tarray_create2()</td> + </tr> + <tr> + <td rowspan="2">H5Tcommit()</td> + <td>\Code{DH5Tcommit_vers=1}</td> + <td>H5Tcommit1()</td> + </tr> + <tr> + <td>\Code{DH5Tcommit_vers=2}</td> + <td>H5Tcommit2()</td> + </tr> + <tr> + <td rowspan="2">H5Tget_array_dims()</td> + <td>\Code{DH5Tget_array_dims_vers=1}</td> + <td>H5Tget_array_dims1()</td> + </tr> + <tr> + <td>\Code{DH5Tget_array_dims_vers=2}</td> + <td>H5Tget_array_dims2()</td> + </tr> + <tr> + <td rowspan="2">H5Topen()</td> + <td>\Code{DH5Topen_vers=1}</td> + <td>H5Topen1()</td> + </tr> + <tr> + <td>\Code{DH5Topen_vers=2}</td> + <td>H5Topen2()</td> + </tr> + <tr> + <td rowspan="2">\ref H5Z_class_t struct for H5Zregister()</td> + <td>\Code{DH5Z_class_t_vers=1}</td> + <td>\ref H5Z_class1_t</td> + </tr> + <tr> + <td>\Code{DH5Z_class_t_vers=2}</td> + <td>\ref H5Z_class2_t</td> + </tr> + </table> + </div> + + \subsubsection further Further Information + It is possible to specify multiple function mappings for a single application build: + \code{.sh} + h5cc ... -DH5Rdereference_vers=1 -DH5Fget_info_vers=2 ... + \endcode + As a result of the function and struct mappings in this compile example, all + occurrences of the macro \Code{H5Rdereference} will be mapped to \Code{H5Rdereference1} + and all occurrences of the macro \Code{H5Fget_info} will be mapped to \Code{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 \Code{--disable-deprecated-symbols} option, version 1 of the underlying functions + would not be available, and the example above that defined \Code{H5Rdereference_vers=1} + would not be supported. + + The function mappings do not negate any available functions. If \Code{H5Rdereference1} + is available in the installed version of the HDF5 library, and the application was not + compiled with the \Code{-DH5_NO_DEPRECATED_SYMBOLS} flag, the function \Code{H5Rdereference1} + will remain available to the application through its versioned name. Similarly, + \Code{H5Rdereference2} will remain available to the application as \Code{H5Rdereference2}. + The function mapping version flag \Code{H5Rdereference_vers} only controls the mapping of + the API compatibility macro \Code{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. + + \section macros 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 \Code{H5_NO_DEPRECATED_SYMBOLS}, by always + using the '1' version of versioned functions and types. For example, \Code{H5Dopen1} + will always be interpreted in exactly the same manner by any version of the library + since 1.6.8. + + \section use-case 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: + <ol> + <li>Build the HDF5 library without specifying any library mapping \Code{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.</li> + <li>Compile the application with the \Code{-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.</li> + <li>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 + \Code{-DH5Rdereference_vers=2} version flag setting to remap the \Code{H5Rdereference} + macro to \Code{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 \Code{H5Rdereference}, + should continue to be used in the code, to allow for possible re-mappings to later + versioned functions in a future release.</li> + <li>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.</li> + <li>Finally, compile the application with the application mapping + \Code{-DH5_NO_DEPRECATED_SYMBOLS}, and address any failures to complete + the application migration process.</li> + </ol> + + */
\ No newline at end of file diff --git a/doxygen/dox/mainpage.dox b/doxygen/dox/mainpage.dox index f1949e4..83fc323 100644 --- a/doxygen/dox/mainpage.dox +++ b/doxygen/dox/mainpage.dox @@ -11,7 +11,7 @@ * * <ul> * <li>\ref PDT "Predefined Datatypes"</li> - * <li><a href="https://portal.hdfgroup.org/display/HDF5/API+Compatibility+Macros">API Compatibility Macros</a></li> + * <li>\ref api-compat-macros "API Compatibility Macros"</li> * <li><a href="https://hdf5.wiki/">HDF5 Wiki</a></li> * </ul> * @@ -33,4 +33,4 @@ * opportunity to close any temporary data structures that were set up when the * routine was called. The C++ application should save some state as the * routine is started so that any problem that occurs might be diagnosed. - */ + */
\ No newline at end of file diff --git a/src/H5Fmodule.h b/src/H5Fmodule.h index 953b4da..d57926f 100644 --- a/src/H5Fmodule.h +++ b/src/H5Fmodule.h @@ -29,4 +29,17 @@ #define H5_MY_PKG_ERR H5E_FILE #define H5_MY_PKG_INIT YES +/** + * \defgroup H5F H5F + * \brief File Interface + * \todo Describe concisely what the functions in this module are about. + * + * \defgroup MDC Metadata Cache + * \ingroup H5F + * \defgroup PH5F Parallel + * \ingroup H5F + * \defgroup SWMR Single Writer Multiple Readers + * \ingroup H5F + */ + #endif /* _H5Fmodule_H */ diff --git a/src/H5Fpublic.h b/src/H5Fpublic.h index b84cff6..be8eced 100644 --- a/src/H5Fpublic.h +++ b/src/H5Fpublic.h @@ -47,24 +47,20 @@ * We're assuming that these constants are used rather early in the hdf5 * session. */ -#define H5F_ACC_RDONLY (H5CHECK H5OPEN 0x0000u) /*absence of rdwr => rd-only */ -#define H5F_ACC_RDWR (H5CHECK H5OPEN 0x0001u) /*open for read and write */ -#define H5F_ACC_TRUNC (H5CHECK H5OPEN 0x0002u) /*overwrite existing files */ -#define H5F_ACC_EXCL (H5CHECK H5OPEN 0x0004u) /*fail if file already exists*/ +#define H5F_ACC_RDONLY (H5CHECK H5OPEN 0x0000u) /**< absence of rdwr => rd-only */ +#define H5F_ACC_RDWR (H5CHECK H5OPEN 0x0001u) /**< open for read and write */ +#define H5F_ACC_TRUNC (H5CHECK H5OPEN 0x0002u) /**< overwrite existing files */ +#define H5F_ACC_EXCL (H5CHECK H5OPEN 0x0004u) /**< fail if file already exists*/ /* NOTE: 0x0008u was H5F_ACC_DEBUG, now deprecated */ -#define H5F_ACC_CREAT (H5CHECK H5OPEN 0x0010u) /*create non-existing files */ +#define H5F_ACC_CREAT (H5CHECK H5OPEN 0x0010u) /**< create non-existing files */ #define H5F_ACC_SWMR_WRITE \ - (H5CHECK 0x0020u) /*indicate that this file is \ - * open for writing in a \ - * single-writer/multi-reader (SWMR) \ - * scenario. Note that the \ - * process(es) opening the file \ - * for reading must open the file \ - * with RDONLY access, and use \ - * the special "SWMR_READ" access \ - * flag. */ + (H5CHECK 0x0020u) /**< indicate that this file is open for writing in a \ + single-writer/multi-reader (SWMR) scenario. \ + Note that the process(es) opening the file for reading must \ + open the file with RDONLY access, and use the special "SWMR_READ" \ + access flag. */ #define H5F_ACC_SWMR_READ \ - (H5CHECK 0x0040u) /*indicate that this file is \ + (H5CHECK 0x0040u) /**< indicate that this file is \ * open for reading in a \ * single-writer/multi-reader (SWMR) \ * scenario. Note that the \ @@ -73,19 +69,23 @@ * open the file with the RDONLY \ * flag. */ -/* Value passed to H5Pset_elink_acc_flags to cause flags to be taken from the - * parent file. */ -#define H5F_ACC_DEFAULT (H5CHECK H5OPEN 0xffffu) /*ignore setting on lapl */ +/** + * Default property list identifier + * + * \internal Value passed to H5Pset_elink_acc_flags to cause flags to be taken from the parent file. + * \internal ignore setting on lapl + */ +#define H5F_ACC_DEFAULT (H5CHECK H5OPEN 0xffffu) /* Flags for H5Fget_obj_count() & H5Fget_obj_ids() calls */ -#define H5F_OBJ_FILE (0x0001u) /* File objects */ -#define H5F_OBJ_DATASET (0x0002u) /* Dataset objects */ -#define H5F_OBJ_GROUP (0x0004u) /* Group objects */ -#define H5F_OBJ_DATATYPE (0x0008u) /* Named datatype objects */ -#define H5F_OBJ_ATTR (0x0010u) /* Attribute objects */ +#define H5F_OBJ_FILE (0x0001u) /**< File objects */ +#define H5F_OBJ_DATASET (0x0002u) /**< Dataset objects */ +#define H5F_OBJ_GROUP (0x0004u) /**< Group objects */ +#define H5F_OBJ_DATATYPE (0x0008u) /**< Named datatype objects */ +#define H5F_OBJ_ATTR (0x0010u) /**< Attribute objects */ #define H5F_OBJ_ALL (H5F_OBJ_FILE | H5F_OBJ_DATASET | H5F_OBJ_GROUP | H5F_OBJ_DATATYPE | H5F_OBJ_ATTR) -#define H5F_OBJ_LOCAL (0x0020u) /* Restrict search to objects opened through current file ID */ -/* (as opposed to objects opened through any file ID accessing this file) */ +#define H5F_OBJ_LOCAL (0x0020u) /**< Restrict search to objects opened through current file ID + (as opposed to objects opened through any file ID accessing this file) */ #define H5F_FAMILY_DEFAULT (hsize_t)0 @@ -99,128 +99,147 @@ #define H5F_MPIO_DEBUG_KEY "H5F_mpio_debug_key" #endif /* H5_HAVE_PARALLEL */ -/* The difference between a single file and a set of mounted files */ +/** + * The difference between a single file and a set of mounted files + */ typedef enum H5F_scope_t { - H5F_SCOPE_LOCAL = 0, /*specified file handle only */ - H5F_SCOPE_GLOBAL = 1 /*entire virtual file */ + H5F_SCOPE_LOCAL = 0, /**< specified file handle only */ + H5F_SCOPE_GLOBAL = 1 /**< entire virtual file */ } H5F_scope_t; -/* Unlimited file size for H5Pset_external() */ +/** + * Unlimited file size for H5Pset_external() + */ #define H5F_UNLIMITED ((hsize_t)(-1L)) -/* How does file close behave? - * H5F_CLOSE_DEFAULT - Use the degree pre-defined by underlining VFL - * H5F_CLOSE_WEAK - file closes only after all opened objects are closed - * H5F_CLOSE_SEMI - if no opened objects, file is close; otherwise, file - close fails - * H5F_CLOSE_STRONG - if there are opened objects, close them first, then - close file +/** + * How does file close behave? */ typedef enum H5F_close_degree_t { - H5F_CLOSE_DEFAULT = 0, - H5F_CLOSE_WEAK = 1, - H5F_CLOSE_SEMI = 2, - H5F_CLOSE_STRONG = 3 + H5F_CLOSE_DEFAULT = 0, /**< Use the degree pre-defined by underlining VFL */ + H5F_CLOSE_WEAK = 1, /**< File closes only after all opened objects are closed */ + H5F_CLOSE_SEMI = 2, /**< If no opened objects, file is close; otherwise, file close fails */ + H5F_CLOSE_STRONG = 3 /**< If there are opened objects, close them first, then close file */ } H5F_close_degree_t; -/* Current "global" information about file */ +/** + * Current "global" information about file + */ +//! [H5F_info2_t_snip] typedef struct H5F_info2_t { struct { - unsigned version; /* Superblock version # */ - hsize_t super_size; /* Superblock size */ - hsize_t super_ext_size; /* Superblock extension size */ + unsigned version; /**< Superblock version # */ + hsize_t super_size; /**< Superblock size */ + hsize_t super_ext_size; /**< Superblock extension size */ } super; struct { - unsigned version; /* Version # of file free space management */ - hsize_t meta_size; /* Free space manager metadata size */ - hsize_t tot_space; /* Amount of free space in the file */ + unsigned version; /**< Version # of file free space management */ + hsize_t meta_size; /**< Free space manager metadata size */ + hsize_t tot_space; /**< Amount of free space in the file */ } free; struct { - unsigned version; /* Version # of shared object header info */ - hsize_t hdr_size; /* Shared object header message header size */ - H5_ih_info_t msgs_info; /* Shared object header message index & heap size */ + unsigned version; /**< Version # of shared object header info */ + hsize_t hdr_size; /**< Shared object header message header size */ + H5_ih_info_t msgs_info; /**< Shared object header message index & heap size */ } sohm; } H5F_info2_t; +//! [H5F_info2_t_snip] -/* - * Types of allocation requests. The values larger than H5FD_MEM_DEFAULT +/** + * Types of allocation requests. The values larger than #H5FD_MEM_DEFAULT * should not change other than adding new types to the end. These numbers * might appear in files. * - * Note: please change the log VFD flavors array if you change this - * enumeration. + * \internal Please change the log VFD flavors array if you change this + * enumeration. */ typedef enum H5F_mem_t { - H5FD_MEM_NOLIST = -1, /* Data should not appear in the free list. + H5FD_MEM_NOLIST = -1, /**< Data should not appear in the free list. * Must be negative. */ - H5FD_MEM_DEFAULT = 0, /* Value not yet set. Can also be the + H5FD_MEM_DEFAULT = 0, /**< Value not yet set. Can also be the * datatype set in a larger allocation * that will be suballocated by the library. * Must be zero. */ - H5FD_MEM_SUPER = 1, /* Superblock data */ - H5FD_MEM_BTREE = 2, /* B-tree data */ - H5FD_MEM_DRAW = 3, /* Raw data (content of datasets, etc.) */ - H5FD_MEM_GHEAP = 4, /* Global heap data */ - H5FD_MEM_LHEAP = 5, /* Local heap data */ - H5FD_MEM_OHDR = 6, /* Object header data */ - - H5FD_MEM_NTYPES /* Sentinel value - must be last */ + H5FD_MEM_SUPER = 1, /**< Superblock data */ + H5FD_MEM_BTREE = 2, /**< B-tree data */ + H5FD_MEM_DRAW = 3, /**< Raw data (content of datasets, etc.) */ + H5FD_MEM_GHEAP = 4, /**< Global heap data */ + H5FD_MEM_LHEAP = 5, /**< Local heap data */ + H5FD_MEM_OHDR = 6, /**< Object header data */ + + H5FD_MEM_NTYPES /**< Sentinel value - must be last */ } H5F_mem_t; -/* Free space section information */ +/** + * Free space section information + */ +//! [H5F_sect_info_t_snip] typedef struct H5F_sect_info_t { - haddr_t addr; /* Address of free space section */ - hsize_t size; /* Size of free space section */ + haddr_t addr; /**< Address of free space section */ + hsize_t size; /**< Size of free space section */ } H5F_sect_info_t; +//! [H5F_sect_info_t_snip] -/* Library's format versions */ +/** + * Library's format versions + */ typedef enum H5F_libver_t { H5F_LIBVER_ERROR = -1, - H5F_LIBVER_EARLIEST = 0, /* Use the earliest possible format for storing objects */ - H5F_LIBVER_V18 = 1, /* Use the latest v18 format for storing objects */ - H5F_LIBVER_V110 = 2, /* Use the latest v110 format for storing objects */ - H5F_LIBVER_V112 = 3, /* Use the latest v112 format for storing objects */ - H5F_LIBVER_V114 = 4, /* Use the latest v114 format for storing objects */ + H5F_LIBVER_EARLIEST = 0, /**< Use the earliest possible format for storing objects */ + H5F_LIBVER_V18 = 1, /**< Use the latest v18 format for storing objects */ + H5F_LIBVER_V110 = 2, /**< Use the latest v110 format for storing objects */ + H5F_LIBVER_V112 = 3, /**< Use the latest v112 format for storing objects */ + H5F_LIBVER_V114 = 4, /**< Use the latest v114 format for storing objects */ H5F_LIBVER_NBOUNDS } H5F_libver_t; #define H5F_LIBVER_LATEST H5F_LIBVER_V114 -/* File space handling strategy */ +/** + * File space handling strategy + */ typedef enum H5F_fspace_strategy_t { H5F_FSPACE_STRATEGY_FSM_AGGR = - 0, /* Mechanisms: free-space managers, aggregators, and virtual file drivers */ - /* This is the library default when not set */ + 0, /**< Mechanisms: free-space managers, aggregators, and virtual file drivers + This is the library default when not set */ H5F_FSPACE_STRATEGY_PAGE = - 1, /* Mechanisms: free-space managers with embedded paged aggregation and virtual file drivers */ - H5F_FSPACE_STRATEGY_AGGR = 2, /* Mechanisms: aggregators and virtual file drivers */ - H5F_FSPACE_STRATEGY_NONE = 3, /* Mechanisms: virtual file drivers */ - H5F_FSPACE_STRATEGY_NTYPES /* must be last */ + 1, /**< Mechanisms: free-space managers with embedded paged aggregation and virtual file drivers */ + H5F_FSPACE_STRATEGY_AGGR = 2, /**< Mechanisms: aggregators and virtual file drivers */ + H5F_FSPACE_STRATEGY_NONE = 3, /**< Mechanisms: virtual file drivers */ + H5F_FSPACE_STRATEGY_NTYPES /**< Sentinel */ } H5F_fspace_strategy_t; -/* Deprecated: File space handling strategy for release 1.10.0 */ -/* They are mapped to H5F_fspace_strategy_t as defined above from release 1.10.1 onwards */ +/** + * File space handling strategy for release 1.10.0 + * + * \deprecated 1.10.1 + */ typedef enum H5F_file_space_type_t { - H5F_FILE_SPACE_DEFAULT = 0, /* Default (or current) free space strategy setting */ - H5F_FILE_SPACE_ALL_PERSIST = 1, /* Persistent free space managers, aggregators, virtual file driver */ - H5F_FILE_SPACE_ALL = 2, /* Non-persistent free space managers, aggregators, virtual file driver */ - /* This is the library default */ - H5F_FILE_SPACE_AGGR_VFD = 3, /* Aggregators, Virtual file driver */ - H5F_FILE_SPACE_VFD = 4, /* Virtual file driver */ - H5F_FILE_SPACE_NTYPES /* must be last */ + H5F_FILE_SPACE_DEFAULT = 0, /**< Default (or current) free space strategy setting */ + H5F_FILE_SPACE_ALL_PERSIST = 1, /**< Persistent free space managers, aggregators, virtual file driver */ + H5F_FILE_SPACE_ALL = 2, /**< Non-persistent free space managers, aggregators, virtual file driver + This is the library default */ + H5F_FILE_SPACE_AGGR_VFD = 3, /**< Aggregators, Virtual file driver */ + H5F_FILE_SPACE_VFD = 4, /**< Virtual file driver */ + H5F_FILE_SPACE_NTYPES /**< Sentinel */ } H5F_file_space_type_t; -/* Data structure to report the collection of read retries for metadata items with checksum */ -/* Used by public routine H5Fget_metadata_read_retry_info() */ #define H5F_NUM_METADATA_READ_RETRY_TYPES 21 + +/** + * Data structure to report the collection of read retries for metadata items with checksum as + * used by H5Fget_metadata_read_retry_info() + */ typedef struct H5F_retry_info_t { unsigned nbins; uint32_t *retries[H5F_NUM_METADATA_READ_RETRY_TYPES]; } H5F_retry_info_t; -/* Callback for H5Pset_object_flush_cb() in a file access property list */ +/** + * Callback for H5Pset_object_flush_cb() in a file access property list + */ typedef herr_t (*H5F_flush_cb_t)(hid_t object_id, void *udata); /*********************/ @@ -230,56 +249,1073 @@ typedef herr_t (*H5F_flush_cb_t)(hid_t object_id, void *udata); extern "C" { #endif +/** + * \ingroup H5F + * + * \brief Checks if a file can be opened with a given file access property + * list + * + * \param[in] container_name Name of a file + * \fapl_id + * + * \return \htri_t + * + * \details H5Fis_accessible() checks if the file specified by \p + * container_name can be opened with the file access property list + * \p fapl_id. + * + * \note The H5Fis_accessible() function enables files to be checked with a + * given file access property list, unlike H5Fis_hdf5(), which only uses + * the default file driver when opening a file. + * + * \since 1.12.0 + * + */ H5_DLL htri_t H5Fis_accessible(const char *container_name, hid_t fapl_id); -H5_DLL hid_t H5Fcreate(const char *filename, unsigned flags, hid_t create_plist, hid_t access_plist); -H5_DLL hid_t H5Fopen(const char *filename, unsigned flags, hid_t access_plist); +/** + * \example H5Fcreate.c + * After creating an HDF5 file with H5Fcreate(), we close it with + * H5Fclose(). + */ +/** + * \ingroup H5F + * + * \brief Creates an HDF5 file + * + * \param[in] filename Name of the file to create + * \param[in] flags File access flags. Allowable values are: + * - #H5F_ACC_TRUNC: Truncate file, if it already exists, + * erasing all data previously stored in the file + * - #H5F_ACC_EXCL: Fail if file already exists + * \fcpl_id + * \fapl_id + * \return \hid_t{file} + * + * \details H5Fcreate() is the primary function for creating HDF5 files; it + * creates a new HDF5 file with the specified name and property lists. + * + * The \p filename parameter specifies the name of the new file. + * + * The \p flags parameter specifies whether an existing file is to be + * overwritten. It should be set to either #H5F_ACC_TRUNC to overwrite + * an existing file or #H5F_ACC_EXCL, instructing the function to fail + * if the file already exists. + * + * New files are always created in read-write mode, so the read-write + * and read-only flags, #H5F_ACC_RDWR and #H5F_ACC_RDONLY, + * respectively, are not relevant in this function. Further note that + * a specification of #H5F_ACC_RDONLY will be ignored; the file will + * be created in read-write mode, regardless. + * + * More complex behaviors of file creation and access are controlled + * through the file creation and file access property lists, + * \p fcpl_id and \p fapl_id, respectively. The value of #H5P_DEFAULT + * for any property list value indicates that the library should use + * the default values for that appropriate property list. + * + * The return value is a file identifier for the newly-created file; + * this file identifier should be closed by calling H5Fclose() when + * it is no longer needed. + * + * \include H5Fcreate.c + * + * \note #H5F_ACC_TRUNC and #H5F_ACC_EXCL are mutually exclusive; use + * exactly one. + * + * \note An additional flag, #H5F_ACC_DEBUG, prints debug information. This + * flag can be combined with one of the above values using the bit-wise + * OR operator (\c |), but it is used only by HDF5 library developers; + * \Emph{it is neither tested nor supported for use in applications}. + * + * \attention \Bold{Special case — File creation in the case of an already-open file:} + * If a file being created is already opened, by either a previous + * H5Fopen() or H5Fcreate() call, the HDF5 library may or may not + * detect that the open file and the new file are the same physical + * file. (See H5Fopen() regarding the limitations in detecting the + * re-opening of an already-open file.)\n + * If the library detects that the file is already opened, + * H5Fcreate() will return a failure, regardless of the use of + * #H5F_ACC_TRUNC.\n + * If the library does not detect that the file is already opened + * and #H5F_ACC_TRUNC is not used, H5Fcreate() will return a failure + * because the file already exists. Note that this is correct + * behavior.\n + * But if the library does not detect that the file is already + * opened and #H5F_ACC_TRUNC is used, H5Fcreate() will truncate the + * existing file and return a valid file identifier. Such a + * truncation of a currently-opened file will almost certainly + * result in errors. While unlikely, the HDF5 library may not be + * able to detect, and thus report, such errors.\n + * Applications should avoid calling H5Fcreate() with an already + * opened file. + * + * \since 1.0.0 + * + * \see H5Fopen(), H5Fclose() + * + */ +H5_DLL hid_t H5Fcreate(const char *filename, unsigned flags, hid_t fcpl_id, hid_t fapl_id); +/** + * \ingroup H5F + * + * \brief Opens an existing HDF5 file + * + * \param[in] filename Name of the file to be opened + * \param[in] flags File access flags. Allowable values are: + * - #H5F_ACC_RDWR: Allows read and write access to file + * - #H5F_ACC_RDONLY: Allows read-only access to file + * - #H5F_ACC_RDWR \c | #H5F_ACC_SWMR_WRITE: Indicates that + * the file is open for writing in a + * single-writer/multi-writer (SWMR) scenario. + * - #H5F_ACC_RDONLY \c | #H5F_ACC_SWMR_READ: Indicates + * that the file is open for reading in a + * single-writer/multi-reader (SWMR) scenario. + * - An additional flag, #H5F_ACC_DEBUG, prints debug + * information. This flag can be combined with one of the + * above values using the bit-wise OR operator (\c |), but + * it is used only by HDF5 library developers; + * \Emph{it is neither tested nor supported} for use in + * applications. + * \fapl_id + * \return \hid_t{file} + * + * \details H5Fopen() is the primary function for accessing existing HDF5 files. + * This function opens the named file in the specified access mode and + * with the specified access property list. + * + * Note that H5Fopen() does not create a file if it does not already + * exist; see H5Fcreate(). + * + * The \p filename parameter specifies the name of the file to be + * opened. + * + * The \p fapl_id parameter specifies the file access property list. + * Use of #H5P_DEFAULT specifies that default I/O access properties + * are to be used. + * + * The \p flags parameter specifies whether the file will be opened in + * read-write or read-only mode, #H5F_ACC_RDWR or #H5F_ACC_RDONLY, + * respectively. More complex behaviors of file access are controlled + * through the file-access property list. + * + * The return value is a file identifier for the open file; this file + * identifier should be closed by calling H5Fclose() when it is no + * longer needed. + * + * \note #H5F_ACC_RDWR and #H5F_ACC_RDONLY are mutually exclusive; use + * exactly one. + * + * \attention \Bold{Special cases — Multiple opens:} A file can often be opened + * with a new H5Fopen() call without closing an already-open + * identifier established in a previous H5Fopen() or H5Fcreate() + * call. Each such H5Fopen() call will return a unique identifier + * and the file can be accessed through any of these identifiers as + * long as the identifier remains valid. In such multiply-opened + * cases, the open calls must use the same flags argument and the + * file access property lists must use the same file close degree + * property setting (see the external link discussion below and + * H5Pset_fclose_degree()).\n + * In some cases, such as files on a local Unix file system, the + * HDF5 library can detect that a file is multiply opened and will + * maintain coherent access among the file identifiers.\n + * But in many other cases, such as parallel file systems or + * networked file systems, it is not always possible to detect + * multiple opens of the same physical file. In such cases, HDF5 + * will treat the file identifiers as though they are accessing + * different files and will be unable to maintain coherent access. + * Errors are likely to result in these cases. While unlikely, the + * HDF5 library may not be able to detect, and thus report, + * such errors.\n + * It is generally recommended that applications avoid multiple + * opens of the same file. + * + * \attention \Bold{Special restriction on multiple opens of a file first + * opened by means of an external link:} When an external link is + * followed, the external file is always opened with the weak file + * close degree property setting, #H5F_CLOSE_WEAK (see + * H5Lcreate_external() and H5Pset_fclose_degree()). If the file is + * reopened with H5Fopen while it remains held open from such an + * external link call, the file access property list used in the + * open call must include the file close degree setting + * #H5F_CLOSE_WEAK or the open will fail. + * + * \version 1.10.0 The #H5F_ACC_SWMR_WRITE and #H5F_ACC_SWMR_READ flags were added. + * + * \see H5Fclose() + * + */ +H5_DLL hid_t H5Fopen(const char *filename, unsigned flags, hid_t fapl_id); +/** + * \ingroup H5F + * + * \brief Returns a new identifier for a previously-opened HDF5 file + * + * \param[in] file_id Identifier of a file for which an additional identifier + * is required + * + * \return \hid_t{file} + * + * \details H5Freopen() returns a new file identifier for an already-open HDF5 + * file, as specified by \p file_id. Both identifiers share caches and + * other information. The only difference between the identifiers is + * that the new identifier is not mounted anywhere and no files are + * mounted on it. + * + * The new file identifier should be closed by calling H5Fclose() when + * it is no longer needed. + * + * \note Note that there is no circumstance under which H5Freopen() can + * actually open a closed file; the file must already be open and have an + * active \p file_id. E.g., one cannot close a file with H5Fclose() on + * \p file_id then use H5Freopen() on \p file_id to reopen it. + * + */ H5_DLL hid_t H5Freopen(hid_t file_id); +/** + * \ingroup H5F + * + * \brief Flushes all buffers associated with a file to storage + * + * \loc_id{object_id} + * \param[in] scope The scope of the flush action + * + * \return \herr_t + * + * \details H5Fflush() causes all buffers associated with a file to be + * immediately flushed to storage without removing the data from the + * cache. + * + * \p object_id can be any object associated with the file, including + * the file itself, a dataset, a group, an attribute, or a named + * datatype. + * + * \p scope specifies whether the scope of the flush action is + * global or local. Valid values are as follows: + * \scopes + * + * \attention HDF5 does not possess full control over buffering. H5Fflush() + * flushes the internal HDF5 buffers then asks the operating system + * (the OS) to flush the system buffers for the open files. After + * that, the OS is responsible for ensuring that the data is + * actually flushed to disk. + * + */ H5_DLL herr_t H5Fflush(hid_t object_id, H5F_scope_t scope); +/** + * \example H5Fclose.c + * After creating an HDF5 file with H5Fcreate(), we close it with + * H5Fclose(). + */ +/** + * \ingroup H5F + * + * \brief Terminates access to an HDF5 file + * + * \file_id + * \return \herr_t + * + * \details H5Fclose() terminates access to an HDF5 file (specified by + * \p file_id) by flushing all data to storage. + * + * If this is the last file identifier open for the file and no other + * access identifier is open (e.g., a dataset identifier, group + * identifier, or shared datatype identifier), the file will be fully + * closed and access will end. + * + * Use H5Fclose() as shown in the following example: + * \include H5Fclose.c + * + * \note \Bold{Delayed close:} Note the following deviation from the + * above-described behavior. If H5Fclose() is called for a file but one + * or more objects within the file remain open, those objects will remain + * accessible until they are individually closed. Thus, if the dataset + * \c data_sample is open when H5Fclose() is called for the file + * containing it, \c data_sample will remain open and accessible + * (including writable) until it is explicitly closed. The file will be + * automatically closed once all objects in the file have been closed.\n + * Be warned, however, that there are circumstances where it is not + * possible to delay closing a file. For example, an MPI-IO file close is + * a collective call; all of the processes that opened the file must + * close it collectively. The file cannot be closed at some time in the + * future by each process in an independent fashion. Another example is + * that an application using an AFS token-based file access privilege may + * destroy its AFS token after H5Fclose() has returned successfully. This + * would make any future access to the file, or any object within it, + * illegal.\n + * In such situations, applications must close all open objects in a file + * before calling H5Fclose. It is generally recommended to do so in all + * cases. + * + * \see H5Fopen() + * + */ H5_DLL herr_t H5Fclose(hid_t file_id); +/** + * \ingroup H5F + * + * \brief Deletes an HDF5 file + * + * \param[in] filename Name of the file to delete + * \fapl_id + * + * \return \herr_t + * + * \details H5Fdelete() deletes an HDF5 file \p filename with a file access + * property list \p fapl_id. The \p fapl_id should be configured with + * the same VOL connector or VFD that was used to open the file. + * + * This API was introduced for use with the Virtual Object Layer + * (VOL). With the VOL, HDF5 "files" can map to arbitrary storage + * schemes such as object stores and relational database tables. The + * data created by these implementations may be inconvenient for a + * user to remove without a detailed knowledge of the storage scheme. + * H5Fdelete() gives VOL connector authors the ability to add + * connector-specific delete code to their connectors so that users + * can remove these "files" without detailed knowledge of the storage + * scheme. + * + * For a VOL connector, H5Fdelete() deletes the file in a way that + * makes sense for the specified VOL connector. + * + * For the native HDF5 connector, HDF5 files will be deleted via the + * VFDs, each of which will have to be modified to delete the files it + * creates. + * + * For all implementations, H5Fdelete() will first check if the file + * is an HDF5 file via H5Fis_accessible(). This is done to ensure that + * H5Fdelete() cannot be used as an arbitrary file deletion call. + * + * \since 1.12.0 + * + */ H5_DLL herr_t H5Fdelete(const char *filename, hid_t fapl_id); +/** + * \ingroup H5F + * + * \brief Returns a file creation property list identifier + * + * \file_id + * \return \hid_t{file creation property list} + * + * \details H5Fget_create_plist() returns the file creation property list + * identifier identifying the creation properties used to create this + * file. This function is useful for duplicating properties when + * creating another file. + * + * The creation property list identifier should be released with + * H5Pclose(). + * + */ H5_DLL hid_t H5Fget_create_plist(hid_t file_id); +/** + * \ingroup H5F + * + * \brief Returns a file access property list identifier + * + * \file_id + * \return \hid_t{file access property list} + * + * \details H5Fget_access_plist() returns the file access property list + * identifier of the specified file. + * + */ H5_DLL hid_t H5Fget_access_plist(hid_t file_id); +/** + * \ingroup H5F + * + * \brief Determines the read/write or read-only status of a file + * + * \file_id + * \param[out] intent Access mode flag as originally passed with H5Fopen() + * + * \return \herr_t + * + * \details Given the identifier of an open file, \p file_id, H5Fget_intent() + * retrieves the intended access mode" flag passed with H5Fopen() when + * the file was opened. + * + * The value of the flag is returned in \p intent. Valid values are as + * follows: + * \file_access + * + * \note The function will not return an error if intent is NULL; it will + * simply do nothing. + * + * \version 1.10.0 C function enhanced to work with SWMR functionality. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Fget_intent(hid_t file_id, unsigned *intent); +/** + * \ingroup H5F + * + * \brief Retrieves a file's file number that uniquely identifies an open file + * + * \file_id + * \param[out] fileno A buffer to hold the file number + * + * \return \herr_t + * + * \details H5Fget_fileno() retrieves a file number for a file specified by the + * file identifier \p file_id and the pointer \p fnumber to the file + * number. + * + * \since 1.12.0 + * + */ H5_DLL herr_t H5Fget_fileno(hid_t file_id, unsigned long *fileno); +/** + * \ingroup H5F + * + * \brief Returns the number of open object identifiers for an open file + * + * \file_id or #H5F_OBJ_ALL for all currently-open HDF5 files + * \param[in] types Type of object for which identifiers are to be returned + * + * \return Returns the number of open objects if successful; otherwise returns + * a negative value. + * + * \details Given the identifier of an open file, file_id, and the desired + * object types, types, H5Fget_obj_count() returns the number of open + * object identifiers for the file. + * + * To retrieve a count of open identifiers for open objects in all + * HDF5 application files that are currently open, pass the value + * #H5F_OBJ_ALL in \p file_id. + * + * The types of objects to be counted are specified in types as + * follows: + * \obj_types + * + * Multiple object types can be combined with the + * logical \c OR operator (|). For example, the expression + * \c (#H5F_OBJ_DATASET|#H5F_OBJ_GROUP) would call for datasets and + * groups. + * + * \version 1.6.8, 1.8.2 C function return type changed to \c ssize_t. + * \version 1.6.5 #H5F_OBJ_LOCAL has been added as a qualifier on the types + * of objects to be counted. #H5F_OBJ_LOCAL restricts the + * search to objects opened through current file identifier. + * + */ H5_DLL ssize_t H5Fget_obj_count(hid_t file_id, unsigned types); +/** + *------------------------------------------------------------------------- + * \ingroup H5F + * + * \brief Returns a list of open object identifiers + * + * \file_id or #H5F_OBJ_ALL for all currently-open HDF5 files + * \param[in] types Type of object for which identifiers are to be returned + * \param[in] max_objs Maximum number of object identifiers to place into + * \p obj_id_list + * \param[out] obj_id_list Pointer to the returned buffer of open object + * identifiers + * + * \return Returns number of objects placed into \p obj_id_list if successful; + * otherwise returns a negative value. + * + * \details Given the file identifier \p file_id and the type of objects to be + * identified, types, H5Fget_obj_ids() returns the list of identifiers + * for all open HDF5 objects fitting the specified criteria. + * + * To retrieve identifiers for open objects in all HDF5 application + * files that are currently open, pass the value #H5F_OBJ_ALL in + * \p file_id. + * + * The types of object identifiers to be retrieved are specified in + * types using the codes listed for the same parameter in + * H5Fget_obj_count(). + * + * To retrieve a count of open objects, use the H5Fget_obj_count() + * function. This count can be used to set the \p max_objs parameter. + * + * \version 1.8.2 C function return type changed to \c ssize_t and \p + * max_objs parameter datatype changed to \c size_t. + * \version 1.6.8 C function return type changed to \c ssize_t and \p + * max_objs parameter datatype changed to \c size_t. + * \since 1.6.0 + * + */ H5_DLL ssize_t H5Fget_obj_ids(hid_t file_id, unsigned types, size_t max_objs, hid_t *obj_id_list); +/** + * \ingroup H5F + * + * \brief Returns pointer to the file handle from the virtual file driver + * + * \file_id + * \fapl_id{fapl} + * \param[out] file_handle Pointer to the file handle being used by the + * low-level virtual file driver + * + * \return \herr_t + * + * \details Given the file identifier \p file_id and the file access property + * list \p fapl_id, H5Fget_vfd_handle() returns a pointer to the file + * handle from the low-level file driver currently being used by the + * HDF5 library for file I/O. + * + * \note For most drivers, the value of \p fapl_id will be #H5P_DEFAULT. For + * the \c FAMILY or \c MULTI drivers, this value should be defined + * through the property list functions: H5Pset_family_offset() for the + * \c FAMILY driver and H5Pset_multi_type() for the \c MULTI driver + * + * \since 1.6.0 + * + */ H5_DLL herr_t H5Fget_vfd_handle(hid_t file_id, hid_t fapl, void **file_handle); +/** + * \ingroup H5F + * + * \brief Mounts an HDF5 file + * + * \loc_id{loc} + * \param[in] name Name of the group onto which the file specified by \p child + * is to be mounted + * \file_id{child} + * \param[in] plist File mount property list identifier. Pass #H5P_DEFAULT! + * + * \return \herr_t + * + * \details H5Fmount() mounts the file specified by \p child onto the object + * specified by \p loc and \p name using the mount properties \p plist + * If the object specified by \p loc is a dataset, named datatype or + * attribute, then the file will be mounted at the location where the + * attribute, dataset, or named datatype is attached. + * + * \note To date, no file mount properties have been defined in HDF5. The + * proper value to pass for \p plist is #H5P_DEFAULT, indicating the + * default file mount property list. + * + */ H5_DLL herr_t H5Fmount(hid_t loc, const char *name, hid_t child, hid_t plist); +/** + * \ingroup H5F + * + * \brief Unounts an HDF5 file + * + * \loc_id{loc} + * \param[in] name Name of the mount point + * + * \return \herr_t + * + * \details Given a mount point, H5Funmount() dissociates the mount point's + * file from the file mounted there. This function does not close + * either file. + * + * The mount point can be either the group in the parent or the root + * group of the mounted file (both groups have the same name). If the + * mount point was opened before the mount then it is the group in the + * parent; if it was opened after the mount then it is the root group + * of the child. + * + */ H5_DLL herr_t H5Funmount(hid_t loc, const char *name); +/** + * \ingroup H5F + * + * \brief Returns the amount of free space in a file (in bytes) + * + * \file_id + * + * \return Returns the amount of free space in the file if successful; + * otherwise returns a negative value. + * + * \details Given the identifier of an open file, \p file_id, + * H5Fget_freespace() returns the amount of space that is unused by + * any objects in the file. + * + * The interpretation of this number depends on the configured free space + * management strategy. For example, if the HDF5 library only tracks free + * space in a file from a file open or create until that file is closed, + * then this routine will report the free space that has been created + * during that interval. + * + * \since 1.6.1 + * + */ H5_DLL hssize_t H5Fget_freespace(hid_t file_id); +/** + * \ingroup H5F + * + * \brief Returns the size of an HDF5 file (in bytes) + * + * \file_id + * \param[out] size Size of the file, in bytes + * + * \return \herr_t + * + * \details H5Fget_filesize() returns the size of the HDF5 file specified by + * \p file_id. + * + * The returned size is that of the entire file, as opposed to only + * the HDF5 portion of the file. I.e., size includes the user block, + * if any, the HDF5 portion of the file, and any data that may have + * been appended beyond the data written through the HDF5 library. + * + * \version 1.6.3 Fortran subroutine introduced in this release. + * + * \since 1.6.3 + * + */ H5_DLL herr_t H5Fget_filesize(hid_t file_id, hsize_t *size); +/** + * \ingroup H5F + * + * \brief Retrieves the file's end-of-allocation (EOA) + * + * \file_id + * \param[out] eoa The file's EOA + * + * \return \herr_t + * + * \details H5Fget_eoa() retrieves the file's EOA and returns it in the + * parameter eoa. + * + * \since 1.10.2 + * + */ H5_DLL herr_t H5Fget_eoa(hid_t file_id, haddr_t *eoa); +/** + * \ingroup H5F + * + * \brief Sets the file' EOA to the maximum of (EOA, EOF) + increment + * + * \file_id + * \param[in] increment The number of bytes to be added to the maximum of + * (EOA, EOF) + * + * \return \herr_t + * + * \details H5Fincrement_filesize() sets the file's EOA to the maximum of (EOA, + * EOF) + \p increment. The EOA is the end-of-file address stored in + * the file's superblock while EOF is the file's actual end-of-file. + * + * \since 1.10.2 + * + */ H5_DLL herr_t H5Fincrement_filesize(hid_t file_id, hsize_t increment); +/** + * \ingroup H5F + * + * \brief Retrieves a copy of the image of an existing, open file + * + * \file_id + * \param[out] buf_ptr Pointer to the buffer into which the image of the + * HDF5 file is to be copied. If \p buf_ptr is NULL, + * no data will be copied but the function’s return value + * will still indicate the buffer size required (or a + * negative value on error). + * \param[out] buf_len Size of the supplied buffer + * + * \return ssize_t + * + * \details H5Fget_file_image() retrieves a copy of the image of an existing, + * open file. This routine can be used with files opened using the + * SEC2 (or POSIX), STDIO, and Core (or Memory) virtual file drivers + * (VFDs). + * + * If the return value of H5Fget_file_image() is a positive value, it + * will be the length in bytes of the buffer required to store the + * file image. So if the file size is unknown, it can be safely + * determined with an initial H5Fget_file_image() call with buf_ptr + * set to NULL. The file image can then be retrieved with a second + * H5Fget_file_image() call with \p buf_len set to the initial call’s + * return value. + * + * While the current file size can also be retrieved with + * H5Fget_filesize(), that call may produce a larger value than is + * needed. The value returned by H5Fget_filesize() includes the user + * block, if it exists, and any unallocated space at the end of the + * file. It is safe in all situations to get the file size with + * H5Fget_file_image() and it often produces a value that is more + * appropriate for the size of a file image buffer. + * + * \note \Bold{Recommended Reading:} This function is part of the file image + * operations feature set. It is highly recommended to study the guide + * "HDF5 File Image Operations" before using this feature set.\n See the + * "See Also" section below for links to other elements of HDF5 file + * image operations. \todo Fix the references. + * + * \attention H5Pget_file_image() will fail, returning a negative value, if the + * file is too large for the supplied buffer. + * + * \see H5LTopen_file_image(), H5Pset_file_image(), H5Pget_file_image(), + * H5Pset_file_image_callbacks(), H5Pget_file_image_callbacks() + * + * \version 1.8.13 Fortran subroutine added in this release. + * + * \since 1.8.0 + * + */ H5_DLL ssize_t H5Fget_file_image(hid_t file_id, void *buf_ptr, size_t buf_len); +/** + * \ingroup MDC + * + * \todo Finish this! + */ H5_DLL herr_t H5Fget_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr); +/** + * \ingroup MDC + * + * \todo Finish this! + */ H5_DLL herr_t H5Fset_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr); +/** + * \ingroup MDC + * + * \todo Finish this! + */ H5_DLL herr_t H5Fget_mdc_hit_rate(hid_t file_id, double *hit_rate_ptr); +/** + * \ingroup MDC + * + * \todo Finish this! + */ H5_DLL 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); +/** + * \ingroup MDC + * + * \todo Finish this! + */ H5_DLL herr_t H5Freset_mdc_hit_rate_stats(hid_t file_id); +/** + * \ingroup H5F + * + * \brief Retrieves name of file to which object belongs + * + * \obj_id + * \param[out] name Buffer for the file name + * \param[in] size Size, in bytes, of the \p name buffer + * + * \return Returns the length of the file name if successful; otherwise returns + * a negative value. + * + * \details H5Fget_name() retrieves the name of the file to which the object \p + * obj_id belongs. The object can be a file, group, dataset, + * attribute, or named datatype. + * + * Up to \p size characters of the file name are returned in \p name; + * additional characters, if any, are not returned to the user + * application. + * + * If the length of the name, which determines the required value of + * size, is unknown, a preliminary H5Fget_name() call can be made by + * setting \p name to NULL. The return value of this call will be the + * size of the file name; that value plus one (1) can then be assigned + * to size for a second H5Fget_name() call, which will retrieve the + * actual name. (The value passed in with the parameter \p size must + * be one greater than size in bytes of the actual name in order to + * accommodate the null terminator; if \p size is set to the exact + * size of the name, the last byte passed back will contain the null + * terminator and the last character will be missing from the name + * passed back to the calling application.) + * + * If an error occurs, the buffer pointed to by \p name is unchanged + * and the function returns a negative value. + * + * \since 1.6.3 + * + */ H5_DLL ssize_t H5Fget_name(hid_t obj_id, char *name, size_t size); -H5_DLL herr_t H5Fget_info2(hid_t obj_id, H5F_info2_t *finfo); +/** + * \ingroup H5F + * + * \brief Retrieves name of file to which object belongs + * + * \fgdta_obj_id + * \param[out] file_info Buffer for global file information + * + * \return \herr_t + * + * \details H5Fget_info2() returns global information for the file associated + * with the object identifier \p obj_id in the H5F_info2_t \c struct + * named \p file_info. + * + * \p obj_id is an identifier for any object in the file of interest. + * + * H5F_info2_t struct is defined in H5Fpublic.h as follows: + * \snippet this H5F_info2_t_snip + * + * The \c super sub-struct contains the following information: + * \li \c vers is the version number of the superblock. + * \li \c super_size is the size of the superblock. + * \li \c super_ext_size is the size of the superblock extension. + * + * The \c free sub-struct contains the following information: + * \li vers is the version number of the free-space manager. + * \li \c hdr_size is the size of the free-space manager header. + * \li \c tot_space is the total amount of free space in the file. + * + * The \c sohm sub-struct contains shared object header message + * information as follows: + * \li \c vers is the version number of the shared object header information. + * \li \c hdr_size is the size of the shared object header message. + * \li \c msgs_info is an H5_ih_info_t struct defined in H5public.h as + * follows: \snippet H5public.h H5_ih_info_t_snip + * \li \p index_size is the summed size of all the shared object + * header indexes. Each index might be either a B-tree or + * a list. + * \li \p heap_size is the size of the heap. + * + * + * \since 1.10.0 + * + */ +H5_DLL herr_t H5Fget_info2(hid_t obj_id, H5F_info2_t *file_info); +/** + * \ingroup SWMR + * + * \todo Finish this! + */ H5_DLL herr_t H5Fget_metadata_read_retry_info(hid_t file_id, H5F_retry_info_t *info); +/** + * \ingroup SWMR + * + * \todo Finish this! + */ H5_DLL herr_t H5Fstart_swmr_write(hid_t file_id); +/** + * \ingroup H5F + * + * \brief Retrieves free-space section information for a file + * + * \file_id + * \param[in] type The file memory allocation type + * \param[in] nsects The number of free-space sections + * \param[out] sect_info Array of instances of H5F_sect_info_t in which + * the free-space section information is to be returned + * + * \return Returns the number of free-space sections for the specified + * free-space manager in the file; otherwise returns a negative value. + * + * \details H5Fget_free_sections() retrieves free-space section information for + * the free-space manager with type that is associated with file + * \p file_id. If type is #H5FD_MEM_DEFAULT, this routine retrieves + * free-space section information for all the free-space managers in + * the file. + * + * Valid values for \p type are the following: + * \mem_types + * + * H5F_sect_info_t is defined as follows (in H5Fpublic.h): + * \snippet this H5F_sect_info_t_snip + * + * This routine retrieves free-space section information for \p nsects + * sections or at most the maximum number of sections in the specified + * free-space manager. If the number of sections is not known, a + * preliminary H5Fget_free_sections() call can be made by setting \p + * sect_info to NULL and the total number of free-space sections for + * the specified free-space manager will be returned. Users can then + * allocate space for entries in \p sect_info, each of which is + * defined as an H5F_sect_info_t \c struct. + * + * \attention \Bold{Failure Modes:} This routine will fail when the following + * is true: + * \li The library fails to retrieve the file creation property list + * associated with \p file_id. + * \li If the parameter \p sect_info is non-null, but the parameter + * \p nsects is equal to 0. + * \li The library fails to retrieve free-space section information + * for the file. + * + * \since 1.10.0 + * + */ H5_DLL ssize_t H5Fget_free_sections(hid_t file_id, H5F_mem_t type, size_t nsects, H5F_sect_info_t *sect_info /*out*/); +/** + * \ingroup H5F + * + * \brief Clears the external link open file cache + * + * \file_id + * \return \herr_t + * + * \details H5Fclear_elink_file_cache() evicts all the cached child files in + * the specified file’s external file cache, causing them to be closed + * if there is nothing else holding them open. + * + * H5Fclear_elink_file_cache() does not close the cache itself; + * subsequent external link traversals from the parent file will again + * cache the target file. See H5Pset_elink_file_cache_size() for + * information on closing the file cache. + * + * \see H5Pset_elink_file_cache_size(), H5Pget_elink_file_cache_size() + * + * \since 1.8.7 + * + */ H5_DLL herr_t H5Fclear_elink_file_cache(hid_t file_id); +/** + * \ingroup H5F + * + * \brief Enables the switch of version bounds setting for a file + * + * \file_id + * \param[in] low The earliest version of the library that will be used for + * writing objects + * \param[in] high The latest version of the library that will be used for + * writing objects + * + * \return \herr_t + * + * \details H5Fset_libver_bounds() enables the switch of version bounds setting + * for an open file associated with \p file_id. + * + * For the parameters \p low and \p high, see the description for + * H5Pset_libver_bounds(). + * + * \since 1.10.2 + * + */ H5_DLL herr_t H5Fset_libver_bounds(hid_t file_id, H5F_libver_t low, H5F_libver_t high); +/** + * \ingroup MDC + * + * \todo Finish this! + */ H5_DLL herr_t H5Fstart_mdc_logging(hid_t file_id); +/** + * \ingroup MDC + * + * \todo Finish this! + */ H5_DLL herr_t H5Fstop_mdc_logging(hid_t file_id); +/** + * \ingroup MDC + * + * \todo Finish this! + */ H5_DLL herr_t H5Fget_mdc_logging_status(hid_t file_id, /*OUT*/ hbool_t *is_enabled, /*OUT*/ hbool_t *is_currently_logging); +/** + * \ingroup SWMR + * + * \todo Finish this! + */ H5_DLL herr_t H5Fformat_convert(hid_t fid); +/** + * \ingroup H5F + * + * \brief Resets the page buffer statistics + * + * \file_id + * + * \return \herr_t + * + * \details H5Freset_page_buffering_stats() resets the page buffer statistics + * for a specified file identifier \p file_id. + * + * \since 1.10.1 + * + */ H5_DLL herr_t H5Freset_page_buffering_stats(hid_t file_id); +/** + * \ingroup H5F + * + * \brief Retrieves statistics about page access when it is enabled + * + * \file_id + * \param[out] accesses Two integer array for the number of metadata and raw + * data accesses to the page buffer + * \param[out] hits Two integer array for the number of metadata and raw data + * hits in the page buffer + * \param[out] misses Two integer array for the number of metadata and raw data + * misses in the page buffer + * \param[out] evictions Two integer array for the number of metadata and raw + * data evictions from the page buffer + * \param[out] bypasses Two integer array for the number of metadata and raw + * data accesses that bypass the page buffer + * + * \return \herr_t + * + * \details H5Fget_page_buffering_stats() retrieves page buffering statistics + * such as the number of metadata and raw data accesses (\p accesses), + * hits (\p hits), misses (\p misses), evictions (\p evictions), and + * accesses that bypass the page buffer (\p bypasses). + * + * \since 1.10.1 + * + */ H5_DLL herr_t H5Fget_page_buffering_stats(hid_t file_id, unsigned accesses[2], unsigned hits[2], unsigned misses[2], unsigned evictions[2], unsigned bypasses[2]); +/** + * \ingroup MDC + * + * \todo Finish this! + */ H5_DLL herr_t H5Fget_mdc_image_info(hid_t file_id, haddr_t *image_addr, hsize_t *image_size); +/** + * \ingroup H5F + * + * \brief Retrieves the setting for whether or not a file will create minimized + * dataset object headers + * + * \file_id + * \param[out] minimize Flag indicating whether the library will or will not + * create minimized dataset object headers + * + * \return \herr_t + * + * \details H5Fget_dset_no_attrs_hint() retrieves the no dataset attributes + * hint setting for the file specified by the file identifier \p + * file_id. This setting is used to inform the library to create + * minimized dataset object headers when \c TRUE. + * + * The setting's value is returned in the boolean pointer minimize. + * + * \since 1.10.5 + * + */ H5_DLL herr_t H5Fget_dset_no_attrs_hint(hid_t file_id, hbool_t *minimize); +/** + * \ingroup H5F + * + * \brief Sets the flag to create minimized dataset object headers + * + * \file_id + * \param[in] minimize Flag indicating whether the library will or will not + * create minimized dataset object headers + * + * \return \herr_t + * + * \details H5Fset_dset_no_attrs_hint() sets the no dataset attributes hint + * setting for the file specified by the file identifier \p file_id. + * If the boolean flag \p minimize is set to \c TRUE, then the library + * will create minimized dataset object headers in the file. + * \Bold{All} files that refer to the same file-on-disk will be + * affected by the most recent setting, regardless of the file + * identifier/handle (e.g., as returned by H5Fopen()). By setting the + * \p minimize flag to \c TRUE, the library expects that no attributes + * will be added to the dataset - attributes can be added, but they + * are appended with a continuation message, which can reduce + * performance. + * + * \attention This setting interacts with H5Pset_dset_no_attrs_hint(): if + * either is set to \c TRUE, then the created dataset's object header + * will be minimized. + * + * \since 1.10.5 + * + */ H5_DLL herr_t H5Fset_dset_no_attrs_hint(hid_t file_id, hbool_t minimize); #ifdef H5_HAVE_PARALLEL +/** + * \ingroup PH5F + * + * \todo Finish this! + */ H5_DLL herr_t H5Fset_mpi_atomicity(hid_t file_id, hbool_t flag); +/** + * \ingroup PH5F + * + * \todo Finish this! + */ H5_DLL herr_t H5Fget_mpi_atomicity(hid_t file_id, hbool_t *flag); #endif /* H5_HAVE_PARALLEL */ @@ -294,19 +1330,95 @@ H5_DLL herr_t H5Fget_mpi_atomicity(hid_t file_id, hbool_t *flag); /* Typedefs */ -/* Current "global" information about file */ +/** + * Current "global" information about file + */ +//! [H5F_info1_t_snip] typedef struct H5F_info1_t { - hsize_t super_ext_size; /* Superblock extension size */ + hsize_t super_ext_size; /**< Superblock extension size */ struct { - hsize_t hdr_size; /* Shared object header message header size */ - H5_ih_info_t msgs_info; /* Shared object header message index & heap size */ + hsize_t hdr_size; /**< Shared object header message header size */ + H5_ih_info_t msgs_info; /**< Shared object header message index & heap size */ } sohm; } H5F_info1_t; +//! [H5F_info1_t_snip] /* Function prototypes */ -H5_DLL herr_t H5Fget_info1(hid_t obj_id, H5F_info1_t *finfo); +/** + * \ingroup H5F + * + * \brief Retrieves name of file to which object belongs + * + * \fgdta_obj_id + * \param[out] file_info Buffer for global file information + * + * \return \herr_t + * + * \deprecated This function has been renamed from H5Fget_info() and is + * deprecated in favor of the macro #H5Fget_info or the function + * H5Fget_info2(). + * + * \details H5Fget_info1() returns global information for the file associated + * with the object identifier \p obj_id in the H5F_info1_t \c struct + * named \p file_info. + * + * \p obj_id is an identifier for any object in the file of interest. + * + * H5F_info1_t struct is defined in H5Fpublic.h as follows: + * \snippet this H5F_info1_t_snip + * + * \c super_ext_size is the size of the superblock extension. + * + * The \c sohm sub-struct contains shared object header message + * information as follows: + * \li \c hdr_size is the size of the shared object header message. + * \li \c msgs_info is an H5_ih_info_t struct defined in H5public.h as + * follows: \snippet H5public.h H5_ih_info_t_snip + * + * \li \p index_size is the summed size of all the shared object + * header indexes. Each index might be either a B-tree or + * a list. + * + * \version 1.10.0 C function H5Fget_info() renamed to H5Fget_info1() and + * deprecated in this release. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Fget_info1(hid_t obj_id, H5F_info1_t *file_info); +/** + * \ingroup H5F + * + * \brief Sets thelatest version of the library to be used for writing objects + * + * \file_id + * \param[in] latest_format Latest format flag + * + * \return \herr_t + * + * \deprecated When? + * + * \todo In which version was this function deprecated? + * + */ H5_DLL herr_t H5Fset_latest_format(hid_t file_id, hbool_t latest_format); -H5_DLL htri_t H5Fis_hdf5(const char *filename); +/** + * \ingroup H5F + * + * \brief Determines whether a file is in the HDF5 format + * + * \param[in] file_name File name + * + * \return \htri_t + * + * \deprecated When? + * + * \details H5Fis_hdf5() determines whether a file is in the HDF5 format. + * + * \todo In which version was this function deprecated? + * + */ +H5_DLL htri_t H5Fis_hdf5(const char *file_name); #endif /* H5_NO_DEPRECATED_SYMBOLS */ diff --git a/src/H5public.h b/src/H5public.h index 5b9a5fe..1784a11 100644 --- a/src/H5public.h +++ b/src/H5public.h @@ -333,13 +333,15 @@ typedef enum H5_index_t { H5_INDEX_N /* Number of indices defined */ } H5_index_t; -/* +/** * Storage info struct used by H5O_info_t and H5F_info_t */ +//! [H5_ih_info_t_snip] typedef struct H5_ih_info_t { - hsize_t index_size; /* btree and/or list */ + hsize_t index_size; /**< btree and/or list */ hsize_t heap_size; } H5_ih_info_t; +//! [H5_ih_info_t_snip] /* Tokens are unique and permanent identifiers that are * used to reference HDF5 objects in a container. */ |