diff options
| author | Allen Byrne <50328838+byrnHDF@users.noreply.github.com> | 2022-03-31 13:23:35 (GMT) |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2022-03-31 13:23:35 (GMT) |
| commit | 9fdf9546541866f989b4f46aad6f6ac975563777 (patch) | |
| tree | e56a66816abf1a6c16c9db2874d25b1c0dbeb3e8 | |
| parent | dcdbeb7124c28f87d96bb9900f3d92e2a07bcd6b (diff) | |
| download | hdf5-9fdf9546541866f989b4f46aad6f6ac975563777.zip hdf5-9fdf9546541866f989b4f46aad6f6ac975563777.tar.gz hdf5-9fdf9546541866f989b4f46aad6f6ac975563777.tar.bz2 | |
1.8 Merge doxygen changes from develop (#1545)
* Merge doxygen changes from develop
* revert macro code change
* Format correction
91 files changed, 7030 insertions, 1505 deletions
@@ -203,25 +203,37 @@ ./doxygen/aliases ./doxygen/CMakeLists.txt ./doxygen/Doxyfile.in +./doxygen/dox/APIVersions.dox ./doxygen/dox/About.dox ./doxygen/dox/Cookbook.dox ./doxygen/dox/DDLBNF110.dox ./doxygen/dox/FileFormatSpec.dox +./doxygen/dox/FTS.dox ./doxygen/dox/GettingStarted.dox +./doxygen/dox/Glossary.dox ./doxygen/dox/H5AC_cache_config_t.dox -./doxygen/dox/H5Acreate.dox -./doxygen/dox/H5Aiterate.dox ./doxygen/dox/MetadataCachingInHDF5.dox -./doxygen/dox/OtherSpecs.dox ./doxygen/dox/Overview.dox ./doxygen/dox/ReferenceManual.dox +./doxygen/dox/RFC.dox ./doxygen/dox/Specifications.dox ./doxygen/dox/TechnicalNotes.dox ./doxygen/dox/api-compat-macros.dox +./doxygen/dox/maybe_metadata_reads.dox ./doxygen/dox/rm-template.dox +./doxygen/dox/cookbook/Accessibility.c +./doxygen/dox/cookbook/Accessibility.dox +./doxygen/dox/cookbook/Attributes.c +./doxygen/dox/cookbook/Attributes.dox +./doxygen/dox/cookbook/Files.c +./doxygen/dox/cookbook/Files.dox +./doxygen/dox/cookbook/Performance.dox +./doxygen/examples/DebuggingHDF5Applications.html ./doxygen/examples/FF-IH_FileGroup.gif ./doxygen/examples/FF-IH_FileObject.gif +./doxygen/examples/FileFormat.html ./doxygen/examples/FileFormatSpecChunkDiagram.jpg +./doxygen/examples/Filters.html ./doxygen/examples/H5Pset_metadata_read_attempts.c ./doxygen/examples/H5Pset_object_flush_cb.c ./doxygen/examples/H5.format.1.0.html @@ -230,15 +242,27 @@ ./doxygen/examples/H5.format.html ./doxygen/examples/H5A_examples.c ./doxygen/examples/H5D_examples.c +./doxygen/examples/H5E_examples.c ./doxygen/examples/H5Fclose.c ./doxygen/examples/H5Fcreate.c ./doxygen/examples/H5F_examples.c +./doxygen/examples/H5G_examples.c +./doxygen/examples/H5I_examples.c +./doxygen/examples/H5L_examples.c +./doxygen/examples/H5O_examples.c +./doxygen/examples/H5PL_examples.c ./doxygen/examples/H5Pget_metadata_read_attempts.1.c ./doxygen/examples/H5Pget_metadata_read_attempts.2.c ./doxygen/examples/H5Pget_metadata_read_attempts.3.c ./doxygen/examples/H5Pget_object_flush_cb.c +./doxygen/examples/H5P_examples.c +./doxygen/examples/H5R_examples.c +./doxygen/examples/H5S_examples.c +./doxygen/examples/H5T_examples.c +./doxygen/examples/H5Z_examples.c ./doxygen/examples/H5_examples.c ./doxygen/examples/ImageSpec.html +./doxygen/examples/IOFlow.html ./doxygen/examples/PaletteExample1.gif ./doxygen/examples/Palettes.fm.anc.gif ./doxygen/examples/TableSpec.html @@ -253,6 +277,7 @@ ./doxygen/img/FF-IH_FileGroup.gif ./doxygen/img/FF-IH_FileObject.gif ./doxygen/img/FileFormatSpecChunkDiagram.jpg +./doxygen/img/HDF5.png ./doxygen/img/HDFG-logo.png ./doxygen/img/IOFlow.gif ./doxygen/img/IOFlow2.gif diff --git a/doxygen/CMakeLists.txt b/doxygen/CMakeLists.txt index ca36ef1..920fafa 100644 --- a/doxygen/CMakeLists.txt +++ b/doxygen/CMakeLists.txt @@ -27,6 +27,7 @@ if (DOXYGEN_FOUND) set (DOXYGEN_EXTERNAL_SEARCH NO) set (DOXYGEN_SEARCHENGINE_URL) set (DOXYGEN_STRIP_FROM_PATH ${HDF5_SOURCE_DIR}) + set (DOXYGEN_STRIP_FROM_INC_PATH ${HDF5_SOURCE_DIR}) set (DOXYGEN_PREDEFINED "H5_HAVE_DIRECT H5_HAVE_LIBHDFS H5_HAVE_MAP_API H5_HAVE_PARALLEL H5_HAVE_ROS3_VFD") # This configure and individual custom targets work together diff --git a/doxygen/Doxyfile.in b/doxygen/Doxyfile.in index afc8f3a..e28c50c 100644 --- a/doxygen/Doxyfile.in +++ b/doxygen/Doxyfile.in @@ -179,7 +179,7 @@ STRIP_FROM_PATH = @DOXYGEN_STRIP_FROM_PATH@ # specify the list of include paths that are normally passed to the compiler # using the -I flag. -STRIP_FROM_INC_PATH = +STRIP_FROM_INC_PATH = @DOXYGEN_STRIP_FROM_INC_PATH@ # If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but # less readable) file names. This can be useful is your file systems doesn't diff --git a/doxygen/aliases b/doxygen/aliases index 2ca29ef..5d55720 100644 --- a/doxygen/aliases +++ b/doxygen/aliases @@ -24,7 +24,6 @@ ALIASES += htri_t="Returns zero (false), a positive (true) or a negative (failur ALIASES += api_vers_2{3}="\1() is a macro that is mapped to either \2() or \3().\n\see \ref api-compat-macros" ALIASES += api_vers_3{4}="\1() is a macro that is mapped to either \2() or \3() or \4().\n\see \ref api-compat-macros" -ALIASES += api_vers_4{5}="\1() is a macro that is mapped to either \2() or \3() or \4() or \5().\n\see \ref api-compat-macros" ALIASES += deprecation_note{1}="\deprecated Superseded by \1." @@ -48,12 +47,6 @@ ALIASES += op_data_in="\param[in] op_data User-defined callback function context ALIASES += op_data_in{1}="\param[in] \1 User-defined callback function context" ################################################################################ -# Asynchronous -################################################################################ - -ALIASES += async_variant_of{1}="Asynchronous version of \1()" - -################################################################################ # Attributes ################################################################################ @@ -128,13 +121,6 @@ ALIASES += fg_loc_id="\loc_id. The identifier may be that of a file or group." ALIASES += fg_loc_id{1}="\loc_id{\1}. The identifier may be that of a file or group." ################################################################################ -# Maps -################################################################################ - -ALIASES += map_id="\param[in] map_id Map identifier" -ALIASES += map_id{1}="\param[in] \1 Map identifier" - -################################################################################ # Property lists ################################################################################ @@ -170,12 +156,6 @@ ALIASES += lapl_id{1}="\param[in] \1 Link access property list identifier" ALIASES += lcpl_id="\param[in] lcpl_id Link creation property list identifier" ALIASES += lcpl_id{1}="\param[in] \1 Link creation property list identifier" -ALIASES += mapl_id="\param[in] mapl_id Map access property list identifier" -ALIASES += mapl_id{1}="\param[in] \1 Map access property list identifier" - -ALIASES += mcpl_id="\param[in] mcpl_id Map creation property list identifier" -ALIASES += mcpl_id{1}="\param[in] \1 Map creation property list identifier" - ALIASES += oapl_id="\param[in] oapl_id Object access property list identifier" ALIASES += oapl_id{1}="\param[in] \1 Object access property list identifier" @@ -197,9 +177,6 @@ ALIASES += tapl_id{1}="\param[in] \1 Datatype access property list identifier" ALIASES += tcpl_id="\param[in] tcpl_id Datatype creation property list identifier" ALIASES += tcpl_id{1}="\param[in] \1 Datatype creation property list identifier" -ALIASES += vipl_id="\param[in] vipl_id VOL initialization property list identifier" -ALIASES += vipl_id{1}="\param[in] \1 vipl_id VOL initialization property list identifier" - ################################################################################ # Objects ################################################################################ @@ -213,19 +190,11 @@ ALIASES += fgdta_obj_id{1}="\obj_id{\1}. The identifier may be that of a file, g ALIASES += fgdta_loc_obj_id{1}="\loc_obj_id{\1}. The identifier may be that of a file, group, dataset, named datatype, or attribute." ################################################################################ -# Asynchronous Arguments -################################################################################ - -ALIASES += app_file="\param[in] app_file For internal use only, not a visible user parameter" -ALIASES += app_func="\param[in] app_func For internal use only, not a visible user parameter" -ALIASES += app_line="\param[in] app_line For internal use only, not a visible user parameter" -ALIASES += es_id="\param[in] es_id Event set identifier" -ALIASES += es_id{1}="\param[in] \1 Event set identifier" - -################################################################################ # Others ################################################################################ +ALIASES += estack_id="\param[in] estack_id Error stack identifier" +ALIASES += estack_id{1}="\param[in] \1 Error stack identifier" ALIASES += cpp_c_api_note="\attention \Bold{C++ Developers using HDF5 C-API functions beware:}\n Several functions in this C-API take function pointers or callbacks as arguments. Examples include H5Pset_elink_cb(), H5Pset_type_conv_cb(), H5Tconvert(), and H5Ewalk2(). Application code must ensure that those callback functions return normally such to allow the HDF5 to manage its resources and maintain a consistent state. For instance, those functions must not use the C \c setjmp / \c longjmp mechanism to leave those callback functions. Within the context of C++, any exceptions thrown within the callback function must be caught, such as with a \Code{catch(…)} statement. Any exception state can be placed within the provided user data function call arguments, and may be thrown again once the calling function has returned. Exceptions raised and not handled inside the callback are not supported as it might leave the HDF5 library in an inconsistent state. Similarly, using C++20 coroutines cannot be used as callbacks, since they do not support plain return statements. If a callback function yields execution to another C++20 coroutine calling HDF5 functions as well, this may lead to undefined behavior." ALIASES += par_compr_note="\attention If you are planning to use compression with parallel HDF5, ensure that calls to H5Dwrite() occur in collective mode. In other words, all MPI ranks (in the relevant communicator) call H5Dwrite() and pass a dataset transfer property list with the MPI-IO collective option property set to #H5FD_MPIO_COLLECTIVE_IO.\n Note that data transformations are currently \Bold{not} supported when writing to datasets in parallel and with compression enabled." ALIASES += sa_metadata_ops="\sa \li H5Pget_all_coll_metadata_ops() \li H5Pget_coll_metadata_write() \li H5Pset_all_coll_metadata_ops() \li H5Pset_coll_metadata_write() \li \ref maybe_metadata_reads" @@ -242,7 +211,7 @@ ALIASES += ref_group_impls="<a href=\"https://portal.hdfgroup.org/display/HDF5/G ALIASES += ref_h5lib_relver="<a href=\"https://portal.hdfgroup.org/display/HDF5/HDF5+Library+Release+Version+Numbers\">HDF5 Library Release Version Numbers</a>" ALIASES += ref_mdc_in_hdf5="<a href=\"https://portal.hdfgroup.org/display/HDF5/Metadata+Caching+in+HDF5\">Metadata Caching in HDF5</a>" ALIASES += ref_mdc_logging="<a href=\"https://portal.hdfgroup.org/display/HDF5/H5F_START_MDC_LOGGING\">Metadata Cache Logging</a>" -ALIASES += ref_news_112="<a href=\"https://portal.hdfgroup.org/display/HDF5/New+Features+in+HDF5+Release+1.12\">New Features in HDF5 Release 1.12</a>" +ALIASES += ref_news_18="<a href=\"https://portal.hdfgroup.org/display/HDF5/New+Features+in+HDF5+Release+1.8\">New Features in HDF5 Release 1.8</a>" ALIASES += ref_h5ocopy="<a href=\"https://portal.hdfgroup.org/display/HDF5/Copying+Committed+Datatypes+with+H5Ocopy\">Copying Committed Datatypes with H5Ocopy()</a>" ALIASES += ref_sencode_fmt_change="<a href=\"https://portal.hdfgroup.org/pages/viewpage.action?pageId=58100093&preview=/58100093/58100094/encode_format_RFC.pdf\">RFC H5Secnode() / H5Sdecode() Format Change</a>" ALIASES += ref_vlen_strings="\Emph{Creating variable-length string datatypes}" @@ -253,17 +222,10 @@ ALIASES += ref_vol_doc="VOL documentation" ################################################################################ ALIASES += ref_rfc20210528="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_multi_thread.pdf\">Multi-Thread HDF5</a>" -ALIASES += ref_rfc20210219="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/selection_io_RFC_210610.pdf\">Selection I/O</a>" -ALIASES += ref_rfc20200213="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_VFD_subfiling_200424.pdf\">VFD Sub-filing</a>" -ALIASES += ref_rfc20200210="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/Onion_VFD_RFC_211122.pdf\">Onion VFD</a>" ALIASES += ref_rfc20190923="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/2019-09-23-RFC_VOL_feature_flags.pdf\">Virtual Object Layer (VOL) API Compatibility</a>" -ALIASES += ref_rfc20190715="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/var_len_data_sketch_design_190715.pdf\">Variable-Length Data in HDF5 Sketch Design</a>" ALIASES += ref_rfc20190410="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_VFD_Plugin.docx.pdf\">A Plugin Interface for HDF5 Virtual File Drivers</a>" ALIASES += ref_rfc20181231="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_Min_Obj_Headers_181231.pdf\">Dataset Object Header Size</a>" ALIASES += ref_rfc20181220="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/3.2.1_3.2.2_deliverable_181220_v4.pdf\">MS 3.2 – Addressing Scalability: Scalability of open, close, flush CASE STUDY: CGNS Hotspot analysis of CGNS cgp_open</a>" -ALIASES += ref_rfc20180830="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_Sparse_Chunks180830.pdf\">Sparse Chunks</a>" -ALIASES += ref_rfc20180829="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/mirror_VFD_RFC_2018-10-05.pdf\">H5FD_MIRROR Virtual File Driver</a>" -ALIASES += ref_rfc20180815="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/splitter_VFD_RFC_180830.pdf\">Splitter_VFD</a>" ALIASES += ref_rfc20180620="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC-Chunking%20Functions-2018-06-20-v3.docx.pdf\">Chunk query functionality in HDF5</a>" ALIASES += ref_rfc20180610="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/VFD_SWMR_RFC_200916.pdf\">VFD SWMR</a>" ALIASES += ref_rfc20180321="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC-API_Contexts-2018-03-21.docx.pdf\">API Contexts</a>" @@ -326,12 +288,8 @@ ALIASES += ref_rfc20091218="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RCF_h5d ALIASES += ref_rfc20090907="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_Tools_Lib_v2.pdf\">HDF5 Tools Library Functions</a>" ALIASES += ref_rfc20090612="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_h5diff_default_epsilon.pdf\">Default EPSILON values for comparing floating point data</a>" ALIASES += ref_rfc20081218="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_h5diff_NonComparable.pdf\">Reporting of Non-Comparable Datasets by <tt>h5diff</tt></a>" -ALIASES += ref_rfc20081205="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_elink_callback.pdf\">External Link Traversal Callback</a>" -ALIASES += ref_rfc20081030="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_chunk_cache_functions.pdf\">Setting Raw Data Chunk Cache Parameters in HDF5</a>" ALIASES += ref_rfc20080915="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/FileFreeSpacePerformance.pdf\">Performance Report for Free-space Manager</a>" ALIASES += ref_rfc20080904="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/ExternalLinkFileAccessProperty.pdf\">Setting File Access Property List for accessing External Link</a>" -ALIASES += ref_rfc20080728="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_Native_Time_Types.pdf\">Native Time Types in HDF5</a>" -ALIASES += ref_rfc20080723="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_Special_Values_in_HDF5.pdf\">Special Values in HDF5</a>" ALIASES += ref_rfc20080301="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/DynamicTransformations_RFC.pdf\">Dynamic Transformations to HDF5 Data</a>" ALIASES += ref_rfc20080209="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC-Using-SVN-branching-Feb9.pdf\">Using SVN branching to improve software development process at THG</a>" ALIASES += ref_rfc20080206="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC-HIS-REL-1.8_Feb6.pdf\">Maintaining the <tt>HISTORY.txt</tt> and <tt>RELEASE.txt</tt> files in HDF5</a>" diff --git a/doxygen/dox/APIVersions.dox b/doxygen/dox/APIVersions.dox new file mode 100644 index 0000000..3658f06 --- /dev/null +++ b/doxygen/dox/APIVersions.dox @@ -0,0 +1,173 @@ +/** + * \ingroup H5A + * \def H5Acreate + * \api_vers_2{H5Acreate,H5Acreate1,H5Acreate2} + */ + +/** + * \ingroup H5A + * \def H5Aiterate + * \api_vers_2{H5Aiterate,H5Aiterate1,H5Aiterate2} + */ + +/** + * \ingroup H5D + * \def H5Dcreate + * \api_vers_2{H5Dcreate,H5Dcreate1,H5Dcreate2} + */ + +/** + * \ingroup H5E + * \def H5Eget_auto + * \api_vers_2{H5Eget_auto,H5Eget_auto1,H5Eget_auto2} + */ + +/** + * \ingroup H5E + * \def H5Eprint + * \api_vers_2{H5Eprint,H5Eprint1,H5Eprint2} + */ + +/** + * \ingroup H5E + * \def H5Epush + * \api_vers_2{H5Epush,H5Epush1,H5Epush2} + */ + +/** + * \ingroup H5E + * \def H5Eset_auto + * \api_vers_2{H5Eset_auto,H5Eset_auto1,H5Eset_auto2} + */ + +/** + * \ingroup H5E + * \def H5Ewalk + * \api_vers_2{H5Ewalk,H5Ewalk1,H5Ewalk2} + */ + +/** + * \ingroup H5F + * \def H5Fget_info + * \api_vers_2{H5Fget_info,H5Fget_info1,H5Fget_info2} + */ + +/** + * \ingroup H5G + * \def H5Gcreate + * \api_vers_2{H5Gcreate,H5Gcreate1,H5Gcreate2} + */ + +/** + * \ingroup H5G + * \def H5Gopen + * \api_vers_2{H5Gopen,H5Gopen1,H5Gopen2} + */ + +/** + * \ingroup H5L + * \def H5Lget_info + * \api_vers_2{H5Lget_info,H5Lget_info1,H5Lget_info2} + */ + +/** + * \ingroup H5L + * \def H5Lget_info_by_idx + * \api_vers_2{H5Lget_info_by_idx,H5Lget_info_by_idx1,H5Lget_info_by_idx2} + */ + +/** + * \ingroup TRAV + * \def H5Literate + * \api_vers_2{H5Literate,H5Literate1,H5Literate2} + */ + +/** + * \ingroup TRAV + * \def H5Literate_by_name + * \api_vers_2{H5Literate_by_name,H5Literate_by_name1,H5Literate_by_name2} + */ + +/** + * \ingroup TRAV + * \def H5Lvisit + * \api_vers_2{H5Lvisit,H5Lvisit1,H5Lvisit2} + */ + +/** + * \ingroup TRAV + * \def H5Lvisit_by_name + * \api_vers_2{H5Lvisit_by_name,H5Lvisit_by_name1,H5Lvisit_by_name2} + */ + +/** + * \ingroup H5O + * \def H5Oget_info + * \api_vers_3{H5Oget_info,H5Oget_info1,H5Oget_info2,H5Oget_info3} + */ + +/** + * \ingroup H5O + * \def H5Oget_info_by_idx + * \api_vers_3{H5Oget_info_by_idx,H5Oget_info_by_idx1,H5Oget_info_by_idx2,H5Oget_info_by_idx3} + */ + +/** + * \ingroup H5O + * \def H5Oget_info_by_name + * \api_vers_3{H5Oget_info_by_name,H5Oget_info_by_name1,H5Oget_info_by_name2,H5Oget_info_by_name3} + */ + +/** + * \ingroup H5O + * \def H5Ovisit + * \api_vers_3{H5Ovisit,H5Ovisit1,H5Ovisit2,H5Ovisit3} + */ + +/** + * \ingroup H5O + * \def H5Ovisit_by_name + * \api_vers_3{H5Ovisit_by_name,H5Ovisit_by_name1,H5Ovisit_by_name2,H5Ovisit_by_name3} + */ + +/** + * \ingroup H5R + * \def H5Rdereference + * \api_vers_2{H5Rdereference,H5Rdereference1,H5Rdereference2} + */ + +/** + * \ingroup H5R + * \def H5Rget_obj_type + * \api_vers_3{H5Rget_obj_type,H5Rget_obj_type1,H5Rget_obj_type2,H5R_get_obj_type3} + */ + +/** + * \ingroup H5S + * \def H5Sencode + * \api_vers_2{H5Sencode,H5Sencode1,H5Sencode2} + */ + +/** + * \ingroup H5T + * \def H5Tcommit + * \api_vers_2{H5Tcommit,H5Tcommit1,H5Tcommit2} + */ + +/** + * \ingroup H5T + * \def H5Topen + * \api_vers_2{H5Topen,H5Topen1,H5Topen2} + */ + +/** + * \ingroup ARRAY + * \def H5Tarray_create + * \api_vers_2{H5Tarray_create,H5Tarray_create1,H5Tarray_create2} + */ + +/** + * \ingroup ARRAY + * \def H5Tget_array_dims + * \api_vers_2{H5Tget_array_dims,H5Tget_array_dims1,H5Tget_array_dims2} + */ diff --git a/doxygen/dox/About.dox b/doxygen/dox/About.dox index 777b2a6..a8b31d7 100644 --- a/doxygen/dox/About.dox +++ b/doxygen/dox/About.dox @@ -10,4 +10,118 @@ and the online version of their Not only does Eigen set a standard as a piece of software, but also as an example of <em>documentation done right</em>. +\section about_documentation Documentation about Documentation + +In this section, we describe common documentation maintenance tasks. + +\subsection plain_html Including Plain HTML Pages + +The most common use case for this is the inclusion of older documentation. +New documentation should, whenever possible, be created using Doxygen markdown! + +Use Doxygen's <a href="https://www.doxygen.nl/manual/commands.html#cmdhtmlinclude"><code>htmlinclude</code></a> +special command to include existing plain HTML pages. + +An example from this documentation set can be seen +<a href="https://github.com/HDFGroup/hdf5/blob/develop/doxygen/dox/FileFormatSpec.dox">here</a>. + +\subsection new_rm_entry Creating a New Reference Manual Entry + +Please refer to the \ref RMT for guidance on how to create a new reference manual entry. + +\subsubsection new_example Adding and Referencing API Examples + +For each HDF5 module, such as \Code{H5F}, there is an examples source file called +\Code{H5*_examples.c}. For example, the \Code{H5F} API examples are located in +<a href="https://github.com/HDFGroup/hdf5/blob/develop/doxygen/examples/H5F_examples.c"> +<code>H5F_examples.c</code></a>. Examples are code blocks marked as Doxygen +<a href="https://www.doxygen.nl/manual/commands.html#cmdsnippet">snippets</a>. +For example, the source code for the H5Fcreate() API sample is located between +the +\verbatim +//! <!-- [create] --> +... +//! <!-- [create] --> +\endverbatim +comments in +<a href="https://github.com/HDFGroup/hdf5/blob/develop/doxygen/examples/H5F_examples.c"> +<code>H5F_examples.c</code></a>. + +Add a new API example by adding a new code block enclosed between matching +snippet tags. The name of the tag is usually the function name stripped of +the module prefix. + +The inclusion of such a block of code can then be triggered via Doxygen's +<a href="https://www.doxygen.nl/manual/commands.html#cmdsnippet"><code>snippet</code></a> +special command. For example, the following markup +\verbatim +* \snippet H5F_examples.c create +\endverbatim +yields +\snippet H5F_examples.c create + +\subsubsection api_macro Adding an API Macro + +API macros are handled by the <code>api_vers_2, api_vers_3, api_vers_4</code> +custom commands. The numbers indicate the number of potential API function +mappings. For example, H5Acreate() has two potential mappings, H5Acreate1() and +H5Acreate2(). To trigger the creation of a reference manual entry for H5Acreate() +use the following markup: +\verbatim +\api_vers_2{H5Acreate,H5Acreate1,H5Acreate2} +\endverbatim +This yields: + +\api_vers_2{H5Acreate,H5Acreate1,H5Acreate2} + +\subsection custom_commands Creating Custom Commands + +See Doxygen's <a href="https://www.doxygen.nl/manual/custcmd.html">Custom Commands documentation</a> +as a general reference. + +All custom commands for this project are located in the +<a href="https://github.com/HDFGroup/hdf5/blob/develop/doxygen/aliases"><tt>aliases</tt></a> +file in the <a href="https://github.com/HDFGroup/hdf5/tree/develop/doxygen"><tt>doxygen</tt></a> +subdirectory of the <a href="https://github.com/HDFGroup/hdf5">main HDF5 repo</a>. + +The custom commands are grouped in sections. Find a suitable section for your command or +ask for help if unsure! + +\subsection new_rfc Adding a New RFC or Referencing an Existing RFC + +For ease of reference, we define custom commands for each RFC in the <tt>RFCs</tt> section +of the +<a href="https://github.com/HDFGroup/hdf5/blob/develop/doxygen/aliases"><tt>aliases</tt></a> +file. For example the custom command \Code{ref_rfc20141210} can be used to insert a +reference to "RFC: Virtual Object Layer". In other words, the markup +\verbatim +\ref_rfc20141210 +\endverbatim +yields a clickable link: + +\ref_rfc20141210 + +To add a new RFC, add a custom command for the RFC to the +<a href="https://github.com/HDFGroup/hdf5/blob/develop/doxygen/aliases"><tt>aliases</tt></a> +file. The naming convention for the custom command is \Code{ref_rfcYYYYMMDD}, +where \Code{YYYYMMDD} is the ID of the RFC. The URL is composed of the prefix +\verbatim +https://docs.hdfgroup.org/hdf5/rfc/ +\endverbatim +and the name of your RFC file, typically, a PDF file, i.e., the full URL would +be +\verbatim +https://docs.hdfgroup.org/hdf5/rfc/my_great_rfc_name.pdf +\endverbatim + +\subsection hosting How Do Updates and Changes Get Published? + +Currently, the files underlying this documentation website are stored in an +bucket on AWS S3. The top-level bucket is <pre>s3://docs.hdfgroup.org/hdf5/</pre> +There are folders for the <tt>development</tt> branch and all supported release +version. + +Talk to your friendly IT-team if you need write access, or you need someone to +push an updated version for you! + */
\ No newline at end of file diff --git a/doxygen/dox/Cookbook.dox b/doxygen/dox/Cookbook.dox index 4abc896..56523e2 100644 --- a/doxygen/dox/Cookbook.dox +++ b/doxygen/dox/Cookbook.dox @@ -2,4 +2,18 @@ Healthy, everyday recipes for every taste and budget... +\ref Files +\li \ref CB_FreeSpace +\li \ref CB_RemoveUnusedSpace +\li \ref CB_UserBlock + +\ref Attributes +\li \ref CB_LargeAttributes + +\ref Accessibility +\li \ref CB_MaintainCompat + +\ref Performance +\li \ref CB_MDCPerf + */
\ No newline at end of file diff --git a/doxygen/dox/FTS.dox b/doxygen/dox/FTS.dox new file mode 100644 index 0000000..9dae7c1 --- /dev/null +++ b/doxygen/dox/FTS.dox @@ -0,0 +1,8 @@ +/** \page FTS Full-Text Search + +\htmlonly +<script async src="https://cse.google.com/cse.js?cx=75c754173f9b90804"></script> +<div class="gcse-search"></div> +\endhtmlonly + +*/
\ No newline at end of file diff --git a/doxygen/dox/Glossary.dox b/doxygen/dox/Glossary.dox new file mode 100644 index 0000000..9ccd27d --- /dev/null +++ b/doxygen/dox/Glossary.dox @@ -0,0 +1,565 @@ +/** \page GLS Glossary + +\section GLS_A A + +<DL> + <DT>Array datatype</DT> + <DD>A family of HDF5 datatypes whose elements are arrays of a fixed rank (≤ + 32) and fixed finite extent. All array elements must be of the same HDF5 + datatype.</DD> +</DL> + +<DL> + <DT>Array variable</DT> + <DD><P>A variable that can store (logically) dense, rectilinear, multidimensional + arrays of elements of a given HDF5 datatype.</P> + <P>The combination of array rank (dimensionality) and extent is called an + array variable's shape. This includes the degenerate array shapes of a + singleton (scalar) and the empty array (null).</P> + <P>The array element datatype is sometimes referred to as the array + variable's type, which is not entirely accurate because the array variable's + type is 'array of element type' rather than 'element type'.</P> + <P>In HDF5, there are two kinds of array variables, attributes and datasets, + and the distinction is functional (i.e., how they can be used) rather than + conceptual. Attributes are commonly used for descriptive "light-weight" + HDF5 object metadata while datasets are HDF5 objects used to store + "heavy-weight" problem-sized data.</P> + </DD> +</DL> + +<DL> + <DT>Attribute</DT> + <DD><P>A named array variable that is associated with an HDF5 object, its + owner or attributee, and used to represent application domain-specific + metadata of the object. Intuitively, the set of an object's attributes can + be thought of as its key-value pair collection. Attribute names (keys) can + be arbitrary Unicode strings, but must be unique per object, i.e., an + object can have at most one attribute with a given name.</P> + <P>A scalar attribute is an attribute backed by a singleton array + variable. A null attribute is attribute backed by an empty array + variable.</P> +</DD> +</DL> + +\section GLS_B B + +<DL> + <DT>Bitfield datatype</DT> + <DD>A family of HDF5 datatypes whose elements are fixed-width bit fields.</DD> +</DL> + +\section GLS_C C + +<DL> + <DT>Chunked layout</DT> + <DD> + <P>A dataset storage layout where the dataset elements are partitioned into + fixed-size multidimensional chunks or tiles. Chunked layout is mandatory + for datasets with one or more dimensions of indefinite (infinite) extent + or where compression or other filters are applied to the dataset elements.</P> + <P>Chunked layout may improve I/O performance for certain access patterns.</P> +</DD> +</DL> + +<DL> + <DT>Committed datatype</DT> + <DD>An immutable kind of HDF5 object that is used to store an HDF5 datatype + definition, which can be referenced by multiple array variables. When linked + to an HDF5 group, a committed datatype can be located by an HDF5 path name, + and is sometimes called a named datatype.</DD> +</DL> + +<DL> + <DT>Compact layout</DT> + <DD></DD> +</DL> + +<DL> + <DT>Compound datatype</DT> + <DD> + <P>A family of HDF5 datatypes whose elements are records with named fields + of other HDF5 datatypes. Currently, on ASCII field names are supported.</P> + <P>Similar to a <CODE>struct</CODE> in C or a <CODE>COMMON</CODE> block in + Fortran.</P> +</DD> +</DL> + +<DL> + <DT>Contiguous layout</DT> + <DD>A dataset storage layout where the dataset elements are physically stored + in an HDF5 file as a contiguous block of bytes.</DD> +</DL> + +\section GLS_D D + +<DL> + <DT>Dataset</DT> + <DD> + <P>A kind of HDF5 object, a linked array variable. which can be located in + an HDF5 file through a path name. Datasets are commonly used to store + "heavy-weight" problem-sized data.</P> + <P>The HDF5 library offers a lot of features aimed at optimized dataset + access and storage, including compression and partial I/O.</P> +</DD> +</DL> + +<DL> + <DT>Dataspace</DT> + <DD>The shape of an array variable. With the exception of degenerate cases + (empty set, singleton), this is a rectilinear lattice or grid of a certain + rank (dimensionality) and extent.</DD> +</DL> + +<DL> + <DT>Datatype</DT> + <DD> + <P>An HDF5 datatype consists of an abstract data type (a set of elements) + and a bit-level representation of these elements in storage such as an HDF5 + file or memory.</P> + <P>The HDF5 library comes with a large set of predefined datatypes and + offers mechanisms for creating user-defined datatypes.</P> + <P>The ten major families or classes of HDF5 datatypes are:</P> + <UL> + <LI>Integer datatypes</LI> + <LI>Floating-point number datatypes</LI> + <LI>String datatypes</LI> + <LI>Bitfield datatypes</LI> + <LI>Opaque datatypes</LI> + <LI>Compound datatypes</LI> + <LI>Reference datatypes</LI> + <LI>Enumerated datatypes</LI> + <LI>Variable-length sequence datatypes</LI> + <LI>Array datatypes</LI> + </UL> +</DD> +</DL> + +\section GLS_E E + +<DL> + <DT>Enumeration datatype</DT> + <DD>A family of HDF5 datatypes whose elements represent named integer values + called members or enumerators. Currently, only ASCII names are supported.</DD> +</DL> + +<DL> + <DT>External layout</DT> + <DD>A form of contiguous layout where a dataset's elements are physically + stored in unformatted binary files outside the HDF5 file.</DD> +</DL> + +<DL> + <DT>External link</DT> + <DD>An HDF5 link whose destination is specified as a pair of an HDF5 file name +and an HDF5 path name in that file.</DD> +</DL> + +\section GLS_F F + +<DL> + <DT>Field</DT> + <DD>See compound datatype.</DD> +</DL> + +<DL> + <DT>File</DT> + <DD> + <OL> + <LI>A byte stream (in a storage context such as a file system or in + memory) formatted according to the HDF5 File Format Specification.</LI> + <LI>A (logical) container for HDF5 objects.</LI> + </OL> + </DD> +</DL> + +<DL> + <DT>File format</DT> + <DD></DD> +</DL> + +<DL> + <DT>Fill value</DT> + <DD></DD> +</DL> + +<DL> + <DT>Filter</DT> + <DD></DD> +</DL> + +\section GLS_G G + +<DL> + <DT>Group</DT> + <DD> + <P>A kind of HDF5 object that stores a collection of HDF5 links. Each HDF5 + file contains at least one group, it's root group.</P> + <P>Among the destinations of an HDF5 group's links may be other HDF5 groups + (including the group itself!). This ability is sometimes referred to as the + closure property of groups. It is the basis for creating hierarchical or + more general graph-like structures.</P> +</DD> +</DL> + +\section GLS_H H + +<DL> + <DT>Hard link</DT> + <DD>An HDF5 link whose destination is specified (internally) as the address of + an HDF5 object in the same HDF5 file.</DD> +</DL> + +<DL> + <DT>Hierarchy</DT> + <DD>See group.</DD> +</DL> + +<DL> + <DT>Hyperslab</DT> + <DD> + <P>A regular multidimensional pattern described by four vectors whose length + equals the rank of the pattern.</P> + <OL> + <LI><CODE>start</CODE> - the offset where the first block of the hyperslab begins</LI> + <LI><CODE>stride</CODE> - the offset between pattern blocks</LI> + <LI><CODE>count</CODE> - the number of blocks</LI> + <LI><CODE>block</CODE> - the extent of an individual pattern block</LI> + </OL> + <P>For example, the black squares on a (two-dimensional) chessboard with + origin at <CODE>(0,0)</CODE> can be represented as the union of two + hyperslabs representing the even <CODE>(0,2,4,6)</CODE> and + odd <CODE>(1,3,5,7)</CODE> rows, respectively.</P> + <IMG SRC="https://upload.wikimedia.org/wikipedia/commons/thumb/d/d7/Chessboard480.svg/176px-Chessboard480.svg.png"/> + <P>The hyperslab parameters for the even rows are: <CODE>start (0,0)</CODE>, + <CODE>stride (2,2)</CODE>, <CODE>count (4,4)</CODE>, <CODE>block + (1,1)</CODE>. Likewise the parameters for the odd rows are: <CODE>start + (1,1)</CODE>, <CODE>stride (2,2)</CODE>, <CODE>count + (4,4)</CODE>, <CODE>block (1,1)</CODE>.</P> +</DD> +</DL> + +\section GLS_I I + +<DL> + <DT>Identifier</DT> + <DD>An opaque, transient handle used by the HDF5 library to manipulate + in-memory representations of HDF5 items.</DD> +</DL> + +\section GLS_L L + +<DL> + <DT>Library</DT> + <DD></DD> +</DL> + +<DL> + <DT>Link</DT> + <DD> + <P>A named, uni-directional association between a source and a + destination. In HDF5, the source is always the HDF5 group that hosts the + link in its link collection.</P> + <P>There are several ways to specify a link's destination:</P> + <UL> + <LI>The address of an HDF5 object in the same HDF5 file; so-called hard + link.</LI> + <LI>A path name in the same or a different file; so-called soft or + external link.</LI> + <LI>User-defined</LI> + </UL> + <P>A link name can be any Unicode string that does not contain slashes + (<CODE>"/"</CODE>) or consists of a single dot character + (<CODE>"."</CODE>). A link name must be unique in a group's link + collection.</P> + </DD> +</DL> + +\section GLS_M M + +<DL> + <DT>Metadata</DT> + <DD>Data that in a given context has a descriptive or documentation function + for other data. Typically, the metadata is small compared to the data it + describes.</DD> +</DL> + +<DL> + <DT>Member</DT> + <DD> + <P>A link destination is sometimes referred to as a member of the link's + source (group). This way of speaking invites confusion: A destination (e.g., + object) can be the destination of multiple links in the same (!) or + different groups. It would then be a "member" of a given group with + multiplicity greater than one and be a member of multiple groups.</P> + <P> It is the link that is a member of the group's link collection and not + the link destination.</P> + </DD> +</DL> + +\section GLS_N N + +<DL> + <DT>Name</DT> + <DD> + <P>A Unicode string that depending on the item it names might be subject to + certain character restrictions, such as ASCII-encoded only. In HDF5, the + user might encounter the following names:</P> + <UL> + <LI>A link name</LI> + <LI>A path name</LI> + <LI>An attribute name</LI> + <LI>A field name (compound datatypes)</LI> + <LI>A constant name (enumeration datatypes)</LI> + <LI>A tag name (opaque datatypes)</LI> + <LI>A file name</LI> + </UL> + </DD> +</DL> + + +<DL> + <DT>Named datatype</DT> + <DD>See committed datatype.</DD> +</DL> + +<DL> + <DT>Null dataspace</DT> + <DD>A shape which represents the empty set. Array variables with this shape + cannot store any values.</DD> +</DL> + +\section GLS_O O + +<DL> + <DT>Object</DT> + <DD>An HDF5 group, dataset or named datatype; an HDF5 item that can be linked + to zero or more groups and decorated with zero or more HDF5 attributes.</DD> +</DL> + +<DL> + <DT>Object reference</DT> + <DD> + <OL> + <LI>A datatype for representing references to objects in a file.</LI> + <LI>A value of the object reference datatype.</LI> + </OL> + </DD> +</DL> + +<DL> + <DT>Opaque datatype</DT> + <DD>A family of HDF5 datatypes whose elements are byte sequences of a given + fixed length. An opaque datatype can be tagged with a sequence of up to 256 + ASCII characters, e.g., MIME code.</DD> +</DL> + +\section GLS_P P + +<DL> + <DT>Path name</DT> + <DD>A Unicode string that is the concatenation of link names separated by + slashes (<CODE>'/'</CODE>). In HDF5, path names are used to locate and refer + to HDF5 objects.</DD> +</DL> + +<DL> + <DT>Plugin</DT> + <DD>An HDF5 library feature or capability that can be added dynamically at + application run time rather than library compilation time. Plugins are + usually implemented as shared libraries, and their discovery and loading + behavior can be controlled programmatically or through environment + variables. + </DD> +</DL> + +<DL> + <DT>Point selection</DT> + <DD>A dataspace selection that consists of a set of points (coordinates) in + the same dataspace.</DD> +</DL> + +<DL> + <DT>Property list</DT> + <DD> + <P>An HDF5 API construct, a means of customizing the behavior of the HDF5 + library when creating, accessing or modifying HDF5 items.</P> + <P>While the default property settings are sufficient in many cases, certain + HDF5 features, such as compression, can be reasonably controlled only by the + user who has to provide the desired settings via property lists.</P> +</DD> +</DL> + +\section GLS_R R + +<DL> + <DT>Rank</DT> + <DD>The number of dimensions of a non-null dataspace.</DD> +</DL> + +<DL> + <DT>Reference</DT> + <DD> + <OL> + <LI>An HDF5 object reference</LI> + <LI>An HDF5 dataset region reference</LI> + </OL> + </DD> +</DL> + +<DL> + <DT>Reference datatype</DT> + <DD> + <OL> + <LI>An HDF5 datatype whose elements represent references to HDF5 + objects.</LI> + <LI>An HDF5 datatype whose elements represent references to regions of an + HDF5 dataset.</LI> + </OL> + </DD> +</DL> + +<DL> + <DT>Region reference</DT> + <DD>See dataset region reference.</DD> +</DL> + +<DL> + <DT>Root group</DT> + <DD> + <P>An HDF5 group that is present in all HDF5 files and that acts as the + entry or base point for all other data stored in an HDF5 file.</P> + <P>The root group is "the mother of all objects" in an HDF5 file in the + sense that all objects (and their attributes) can be discovered, + beginning at the root group, by combinations of the following + operations:</P> + <UL> + <LI>Link traversal</LI> + <LI>De-referencing of object references</LI> + </UL> + <P>This discovery is portable and robust with respect to file-internal + storage reorganization.</P> +</DD> +</DL> + +\section GLS_S S + +<DL> + <DT>Scalar dataspace</DT> + <DD>A kind of HDF5 dataspace that has the shape of a singleton, i.e., a set + containing a single element. Array variables with this shape store exactly one + element.</DD> +</DL> + +<DL> + <DT>Selection</DT> + <DD> + <OL> + <LI>A subset of points of an HDF5 dataspace. The subset might be a point + selection or a combination (union, intersection, etc.) of hyperslabs.</LI> + <LI>A subset of dataset elements associated with a dataspace selection as + described under 1.</LI> + </OL> + </DD> +</DL> + +<DL> + <DT>Serialization</DT> + <DD> + <OL> + <LI>The flattening of an N-dimensional array into a 1-dimensional + array.</LI> + <LI>The encoding of a complex data item as a linear byte stream.</LI> + </OL> + </DD> +</DL> + +<DL> + <DT>Soft link</DT> + <DD>A kind of HDF5 link in which the link destination is specified as an HDF5 + path name. The path name may or may not refer to an actual object.</DD> +</DL> + +<DL> + <DT>Storage layout</DT> + <DD>The storage arrangement for dataset elements, links in a group's link + collection, or attributes in an object's attribute collection.</DD> +</DL> + +<DL> + <DT>String datatype</DT> + <DD></DD> +</DL> + +<DL> + <DT>Super block</DT> + <DD>An HDF5 file format primitive; a block of data which contains information + required to access HDF5 files in a portable manner on multiple platforms. The + super block contains information such as version numbers, the size of offsets + and lengths, and the location of the root group.</DD> +</DL> + +<DL> + <DT>SWMR</DT> + <DD>Single Writer Multiple Reader, a file access mode in which a single + process is permitted to write data to an HDF5 file while other processes are + permitted to read data from the same file without the need of inter-process + communication or synchronization.</DD> +</DL> + +<DL> + <DT>Symbolic link</DT> + <DD>An external link or a soft link.</DD> +</DL> + +\section GLS_U U + +<DL> + <DT>User block</DT> + <DD>An HDF5 file format primitive that allows one to set aside a fixed-size + (at least 512 bytes or any power of 2 thereafter) contiguous range of bytes at + the beginning of an HDF5 file for application purposes which will be + skipped/ignored by the HDF5 library.</DD> +</DL> + +<DL> + <DT>UTF-8</DT> + <DD> + <P>A variable-length (1-4 bytes per code point) encoding of the Unicode set + of code points. This is the encoding supported by HDF5 to represent Unicode + strings.</P> + <P>The ASCII encoding is a proper subset of UTF-8.</P> +</DD> +</DL> + +\section GLS_V V + +<DL> + <DT>Variable-length (sequence) datatype</DT> + <DD>A family of HDF5 datatypes whose elements are variable-length sequences of + a given datatype.</DD> +</DL> + +<DL> + <DT>Virtual Dataset (VDS)</DT> + <DD>An HDF5 dataset with virtual storage layout. A dataset whose elements are + partially or entirely stored physically in other datasets.</DD> +</DL> + +<DL> + <DT>Virtual File Driver (VFD)</DT> + <DD></DD> +</DL> + + +<DL> + <DT>Virtual layout</DT> + <DD></DD> +</DL> + + +<DL> + <DT>Virtual Object Layer (VOL)</DT> + <DD></DD> +</DL> + +*/ diff --git a/doxygen/dox/H5AC_cache_config_t.dox b/doxygen/dox/H5AC_cache_config_t.dox index 9b9862b..3faecd5 100644 --- a/doxygen/dox/H5AC_cache_config_t.dox +++ b/doxygen/dox/H5AC_cache_config_t.dox @@ -26,7 +26,7 @@ * * \Emph{*** DEPRECATED ***} Use \Code{H5Fstart/stop} logging functions instead * - * The trace file is a debuging feature that allow the capture of + * The trace file is a debugging feature that allow the capture of * top level metadata cache requests for purposes of debugging and/or * optimization. This field should normally be set to \c FALSE, as * trace file collection imposes considerable overhead. @@ -82,7 +82,7 @@ * H5C_incr__off ) && ( decr_mode == H5C_decr__off )}). There * is no logical reason why this should be so, but it simplifies * implementation and testing, and I can't think of any reason - * why it would be desireable. If you can think of one, I'll + * why it would be desirable. If you can think of one, I'll * revisit the issue. (JM) * \endparblock * @@ -383,7 +383,7 @@ * to disk.\n * When the sync point is reached (or when there is a user generated * flush), process zero flushes sufficient entries to bring it into - * complience with its min clean size (or flushes all dirty entries in + * compliance with its min clean size (or flushes all dirty entries in * the case of a user generated flush), broad casts the list of * entries just cleaned to all the other processes, and then exits * the sync point.\n diff --git a/doxygen/dox/H5Acreate.dox b/doxygen/dox/H5Acreate.dox deleted file mode 100644 index 18d648f..0000000 --- a/doxygen/dox/H5Acreate.dox +++ /dev/null @@ -1,9 +0,0 @@ -/** - * \ingroup H5A - * \def H5Acreate() - * H5Acreate() is a macro that is mapped to either H5Acreate1() or - * H5Acreate2(). - * - * - * \todo Standardize the way we describe these macros! - */ diff --git a/doxygen/dox/H5Aiterate.dox b/doxygen/dox/H5Aiterate.dox deleted file mode 100644 index 46b9bb4..0000000 --- a/doxygen/dox/H5Aiterate.dox +++ /dev/null @@ -1,9 +0,0 @@ -/** - * \ingroup H5A - * \def H5Aiterate() - * H5Aiterate() is a macro that is mapped to either H5Aiterate1() or - * H5Aiterate2(). - * - * - * \todo Standardize the way we describe these macros! - */ diff --git a/doxygen/dox/MetadataCachingInHDF5.dox b/doxygen/dox/MetadataCachingInHDF5.dox index adaf110..b84ddea 100644 --- a/doxygen/dox/MetadataCachingInHDF5.dox +++ b/doxygen/dox/MetadataCachingInHDF5.dox @@ -668,7 +668,7 @@ reduction. With the hit rate threshold cache size decrement algorithm, the remaining fields in the section are ignored. -\subsubsection acsr Ageout Cache Size Reduction +\subsubsection dacsr Ageout Cache Size Reduction If \ref H5AC_cache_config_t.decr_mode "decr_mode" is #H5C_decr__age_out the cache size is decreased by the ageout algorithm, and the remaining fields of the diff --git a/doxygen/dox/OtherSpecs.dox b/doxygen/dox/OtherSpecs.dox deleted file mode 100644 index e53f26e..0000000 --- a/doxygen/dox/OtherSpecs.dox +++ /dev/null @@ -1,11 +0,0 @@ -/** \page IMG HDF5 Image and Palette Specification Version 1.2 - -\htmlinclude ImageSpec.html - -*/ - -/** \page TBL HDF5 Table Specification Version 1.0 - -\htmlinclude TableSpec.html - -*/ diff --git a/doxygen/dox/Overview.dox b/doxygen/dox/Overview.dox index 754722e..040769c 100644 --- a/doxygen/dox/Overview.dox +++ b/doxygen/dox/Overview.dox @@ -1,14 +1,12 @@ /** \mainpage notitle -This is the documentation set for HDF5. You can -<a href="hdf5-doc.tgz">download</a> it as a tgz archive for offline reading. - -This is the documention set for HDF5 in terms of specifications and software -developed and maintained by <a href="https://www.hdfgroup.org/">The HDF -Group</a>. It is impractical to document the entire HDF5 ecosystem in one place, -and you should also consult the documentation sets of the many outstanding -community projects. +This is the documentation set for HDF5. +It includes specifications and documentation +of software and tools developed and maintained by +<a href="https://www.hdfgroup.org/">The HDF Group</a>. It is impractical to document +the entire HDF5 ecosystem in one place, and you should also consult the documentation +sets of the many outstanding community projects. For a first contact with HDF5, the best place is to have a look at the \link GettingStarted getting started \endlink page that shows you how to write and @@ -19,12 +17,28 @@ technical documentation consists to varying degrees of information related to <em>tasks</em>, <em>concepts</em>, or <em>reference</em> material. As its title suggests, the \link RM Reference Manual \endlink is 100% reference material, while the \link Cookbook \endlink is focused on tasks. The different guide-type -documents cover a mix of tasks, concepts, and reference, to help a certain +documents cover a mix of tasks, concepts, and reference, to help a specific <em>audience</em> succeed. -Finally, do not miss the search engine (top right-hand corner)! If you are -looking for a specific function, it'll take you there directly. If unsure, it'll -give you an idea of what's on offer and a few promising leads. +\par Versions + Version-specific documentation (see the version in the title area) can be found + here: + - HDF5 <code>develop</code> branch (this site) + - <a href="https://docs.hdfgroup.org/hdf5/v1_12/index.html">HDF5 1.12.x</a> + - <a href="https://docs.hdfgroup.org/hdf5/v1_10/index.html">HDF5 1.10.x</a> + - <a href="https://docs.hdfgroup.org/hdf5/v1_8/index.html">HDF5 1.8.x</a> + +\par Search + If you are looking for a specific function, constant, type, etc., use the + search box in the top right-hand corner!\n Otherwise, check out the + \link FTS full-text search\endlink. + +\par Offline reading + You can <a href="hdf5-doc.tgz">download</a> it as a tgz archive for offline reading. + +\par History + A snapshot (~April 2017) of the pre-Doxygen HDF5 documentation can be found + <a href="https://docs.hdfgroup.org/archive/support/HDF5/doc/index.html">here</a>. \par ToDo List There is plenty of <a href="./todo.html">unfinished business</a>. diff --git a/doxygen/dox/RFC.dox b/doxygen/dox/RFC.dox new file mode 100644 index 0000000..c16dcea --- /dev/null +++ b/doxygen/dox/RFC.dox @@ -0,0 +1,91 @@ +/** \page RFC RFCs + +<table> +<tr><th>RFC ID</th><th>Title</th><th>Comments</th></tr> +<tr> <td>2021-05-28</td> <td>\ref_rfc20210528</td> <td></td></tr> +<tr> <td>2019-09-23</td> <td>\ref_rfc20190923</td> <td></td></tr> +<tr> <td>2019-04-10</td> <td>\ref_rfc20190410</td> <td></td> </tr> +<tr> <td>2018-12-31</td> <td>\ref_rfc20181231</td> <td></td> </tr> +<tr> <td>2018-12-20</td> <td>\ref_rfc20181220</td> <td></td> </tr> +<tr> <td>2018-06-20</td> <td>\ref_rfc20180620</td> <td></td> </tr> +<tr> <td>2018-06-10</td> <td>\ref_rfc20180610</td> <td></td> </tr> +<tr> <td>2018-03-21</td> <td>\ref_rfc20180321</td> <td></td> </tr> +<tr> <td>2018-01-25</td> <td>\ref_rfc20180125</td> <td></td> </tr> +<tr> <td>2017-07-07</td> <td>\ref_rfc20170707</td> <td></td> </tr> +<tr> <td>2016-01-05</td> <td>\ref_rfc20160105</td> <td></td> </tr> +<tr> <td>2015-09-15</td> <td>\ref_rfc20150915</td> <td></td> </tr> +<tr> <td>2015-07-09</td> <td>\ref_rfc20150709</td> <td></td> </tr> +<tr> <td>2015-06-15</td> <td>\ref_rfc20150615</td> <td></td> </tr> +<tr> <td>2015-04-29</td> <td>\ref_rfc20150429</td> <td></td> </tr> +<tr> <td>2015-04-24</td> <td>\ref_rfc20150424</td> <td></td> </tr> +<tr> <td>2015-04-23</td> <td>\ref_rfc20150423</td> <td></td> </tr> +<tr> <td>2015-03-01</td> <td>\ref_rfc20150301</td> <td></td> </tr> +<tr> <td>2015-02-12</td> <td>\ref_rfc20150212</td> <td></td> </tr> +<tr> <td>2015-02-05</td> <td>\ref_rfc20150205</td> <td></td> </tr> +<tr> <td>2015-02-02</td> <td>\ref_rfc20150202</td> <td></td> </tr> +<tr> <td>2014-12-10</td> <td>\ref_rfc20141210</td> <td></td> </tr> +<tr> <td>2014-12-01</td> <td>\ref_rfc20141201</td> <td></td> </tr> +<tr> <td>2014-09-16</td> <td>\ref_rfc20140916</td> <td></td> </tr> +<tr> <td>2014-08-27</td> <td>\ref_rfc20140827</td> <td></td> </tr> +<tr> <td>2014-07-29</td> <td>\ref_rfc20140729</td> <td></td> </tr> +<tr> <td>2014-07-22</td> <td>\ref_rfc20140722</td> <td></td> </tr> +<tr> <td>2014-07-17</td> <td>\ref_rfc20140717</td> <td></td> </tr> +<tr> <td>2014-07-07</td> <td>\ref_rfc20140707</td> <td></td> </tr> +<tr> <td>2014-05-24</td> <td>\ref_rfc20140524</td> <td></td> </tr> +<tr> <td>2014-03-18</td> <td>\ref_rfc20140318</td> <td></td> </tr> +<tr> <td>2014-03-13</td> <td>\ref_rfc20140313</td> <td></td> </tr> +<tr> <td>2014-02-24</td> <td>\ref_rfc20140224</td> <td></td> </tr> +<tr> <td>2013-12-11</td> <td>\ref_rfc20131211</td> <td></td> </tr> +<tr> <td>2013-09-30</td> <td>\ref_rfc20130930</td> <td></td> </tr> +<tr> <td>2013-09-19</td> <td>\ref_rfc20130919</td> <td></td> </tr> +<tr> <td>2013-06-30</td> <td>\ref_rfc20130630</td> <td></td> </tr> +<tr> <td>2013-03-16</td> <td>\ref_rfc20130316</td> <td></td> </tr> +<tr> <td>2012-11-14</td> <td>\ref_rfc20121114</td> <td></td> </tr> +<tr> <td>2012-10-24</td> <td>\ref_rfc20121024</td> <td></td> </tr> +<tr> <td>2012-08-28</td> <td>\ref_rfc20120828</td> <td></td> </tr> +<tr> <td>2012-05-23</td> <td>\ref_rfc20120523</td> <td></td> </tr> +<tr> <td>2012-05-01</td> <td>\ref_rfc20120501</td> <td></td> </tr> +<tr> <td>2012-03-05</td> <td>\ref_rfc20120305</td> <td></td> </tr> +<tr> <td>2012-02-20</td> <td>\ref_rfc20120220</td> <td></td> </tr> +<tr> <td>2012-01-20</td> <td>\ref_rfc20120120</td> <td></td> </tr> +<tr> <td>2012-01-04</td> <td>\ref_rfc20120104</td> <td></td> </tr> +<tr> <td>2011-11-19</td> <td>\ref_rfc20111119</td> <td></td> </tr> +<tr> <td>2011-08-25</td> <td>\ref_rfc20110825</td> <td></td> </tr> +<tr> <td>2011-08-11</td> <td>\ref_rfc20110811</td> <td></td> </tr> +<tr> <td>2011-07-26</td> <td>\ref_rfc20110726</td> <td></td> </tr> +<tr> <td>2011-06-14</td> <td>\ref_rfc20110614</td> <td></td> </tr> +<tr> <td>2011-03-29</td> <td>\ref_rfc20110329</td> <td></td> </tr> +<tr> <td>2011-01-18</td> <td>\ref_rfc20110118</td> <td></td> </tr> +<tr> <td>2010-11-22</td> <td>\ref_rfc20101122</td> <td></td> </tr> +<tr> <td>2010-11-04</td> <td>\ref_rfc20101104</td> <td></td> </tr> +<tr> <td>2010-10-18</td> <td>\ref_rfc20101018</td> <td></td> </tr> +<tr> <td>2010-09-02</td> <td>\ref_rfc20100902</td> <td></td> </tr> +<tr> <td>2010-07-27</td> <td>\ref_rfc20100727</td> <td></td> </tr> +<tr> <td>2010-07-26</td> <td>\ref_rfc20100726</td> <td></td> </tr> +<tr> <td>2010-05-11</td> <td>\ref_rfc20100511</td> <td></td> </tr> +<tr> <td>2010-04-22</td> <td>\ref_rfc20100422</td> <td></td> </tr> +<tr> <td>2010-03-12</td> <td>\ref_rfc20100312</td> <td></td> </tr> +<tr> <td>2009-12-18</td> <td>\ref_rfc20091218</td> <td></td> </tr> +<tr> <td>2009-09-07</td> <td>\ref_rfc20090907</td> <td></td> </tr> +<tr> <td>2009-06-12</td> <td>\ref_rfc20090612</td> <td></td> </tr> +<tr> <td>2008-12-18</td> <td>\ref_rfc20081218</td> <td></td> </tr> +<tr> <td>2008-09-15</td> <td>\ref_rfc20080915</td> <td></td> </tr> +<tr> <td>2008-09-04</td> <td>\ref_rfc20080904</td> <td></td> </tr> +<tr> <td>2008-03-01</td> <td>\ref_rfc20080301</td> <td></td> </tr> +<tr> <td>2008-02-09</td> <td>\ref_rfc20080209</td> <td></td> </tr> +<tr> <td>2008-02-06</td> <td>\ref_rfc20080206</td> <td></td> </tr> +<tr> <td>2007-11-11</td> <td>\ref_rfc20071111</td> <td></td> </tr> +<tr> <td>2007-10-18</td> <td>\ref_rfc20071018</td> <td></td> </tr> +<tr> <td>2007-08-01</td> <td>\ref_rfc20070801</td> <td></td> </tr> +<tr> <td>2007-04-13</td> <td>\ref_rfc20070413</td> <td></td> </tr> +<tr> <td>2007-01-15</td> <td>\ref_rfc20070115</td> <td></td> </tr> +<tr> <td>2006-06-23</td> <td>\ref_rfc20060623</td> <td></td> </tr> +<tr> <td>2006-06-04</td> <td>\ref_rfc20060604</td> <td></td> </tr> +<tr> <td>2006-05-05</td> <td>\ref_rfc20060505</td> <td></td> </tr> +<tr> <td>2006-04-10</td> <td>\ref_rfc20060410</td> <td></td> </tr> +<tr> <td>2006-03-17</td> <td>\ref_rfc20060317</td> <td></td> </tr> +<tr> <td>2006-01-24</td> <td>\ref_rfc20060124</td> <td></td> </tr> +<tr> <td>2004-08-11</td> <td>\ref_rfc20040811</td> <td></td> </tr> +</table> + +*/
\ No newline at end of file diff --git a/doxygen/dox/ReferenceManual.dox b/doxygen/dox/ReferenceManual.dox index 054f4c6..53f64a7 100644 --- a/doxygen/dox/ReferenceManual.dox +++ b/doxygen/dox/ReferenceManual.dox @@ -3,35 +3,83 @@ The functions provided by the HDF5 C-API are grouped into the following \Emph{modules}: -\li \ref H5A "Attributes" — Management of HDF5 attributes (\ref H5A) -\li \ref H5D "Datasets" — Management of HDF5 datasets (\ref H5D) -\li \ref H5S "Dataspaces" — Management of HDF5 dataspaces which describe the shape of datasets and attributes (\ref H5S) -\li \ref H5T "Datatypes" — Management of datatypes which describe elements of datasets and attributes (\ref H5T) -\li \ref H5E "Error Handling" — Functions for handling HDF5 errors (\ref H5E) -\li \ref H5F "Files" — Management of HDF5 files (\ref H5F) -\li \ref H5Z "Filters" — Configuration of filters that process data during I/O operation (\ref H5Z) -\li \ref H5G "Groups" — Management of groups in HDF5 files (\ref H5G) -\li \ref H5I "Identifiers" — Management of object identifiers and object names (\ref H5I) -\li \ref H5 "Library" — General purpose library functions (\ref H5) -\li \ref H5L "Links" — Management of links in HDF5 groups (\ref H5L) -\li \ref H5O "Objects" — Management of objects in HDF5 files (\ref H5O) -\li \ref H5PL "Plugins" — Programmatic control over dynamically loaded plugins (\ref H5PL) -\li \ref H5P "Property Lists" — Management of property lists to control HDF5 library behavior (\ref H5P) -\li \ref H5R "References" — Management of references to specific objects and data regions in an HDF5 file (\ref H5R) - -\par API Versioning - See \ref api-compat-macros - -\par Deprecated Functions and Types - A list of deprecated functions and types can be found - <a href="./deprecated.html">here</a>. - -\par Etiquette - Here are a few simple rules to follow: - \li \Bold{Handle discipline:} If you acquire a handle (by creation or copy), \Emph{you own it!} (..., i.e., you have to close it.) - \li \Bold{Dynamic memory allocation:} ... - \li \Bold{Use of locations:} Identifier + name combo +<table> +<tr><th>Modules</th></tr> +<tr valign="top"> +<td> + +<table> +<tr><td style="border: none;"> +\li \ref H5A "Attributes (H5A)" +\li \ref H5D "Datasets (H5D)" +\li \ref H5S "Dataspaces (H5S)" +\li \ref H5T "Datatypes (H5T)" +\li \ref H5E "Error Handling (H5E)" +\li \ref H5F "Files (H5F)" +\li \ref H5Z "Filters (H5Z)" +\li \ref H5G "Groups (H5G)" +</td><td style="border: none;"> +\li \ref H5I "Identifiers (H5I)" +\li \ref H5 "Library General (H5)" +\li \ref H5L "Links (H5L)" +\li \ref H5O "Objects (H5O)" +\li \ref H5P "Property Lists (H5P)" +\li \ref H5PL "Dynamically-loaded Plugins (H5PL)" +\li \ref H5R "References (H5R)" +</td><td style="border: none;vertical-align: top;"> +\li \ref api-compat-macros +\li <a href="./deprecated.html">Deprecated functions</a> +\li High-level Extensions + <ul> + <li><a href="https://portal.hdfgroup.org/display/HDF5/Lite">\Bold{HDF5 Lite} (H5LT)</a></li> + <li><a href="https://portal.hdfgroup.org/display/HDF5/Images">\Bold{HDF5 Image} (H5IM)</a></li> + <li><a href="https://portal.hdfgroup.org/display/HDF5/Tables">\Bold{HDF5 Table} (H5TB)</a></li> + <li><a href="https://portal.hdfgroup.org/display/HDF5/Packet+Tables">\Bold{HDF5 Packet Table} (H5TB)</a></li> + <li><a href="https://portal.hdfgroup.org/display/HDF5/Dimension+Scales">\Bold{HDF5 Dimension Scale} (H5DS)</a></li> + </ul> +</td></tr> +<tr><td colspan="3" style="border: none;"> +\ref H5 \ref H5A \ref H5D \ref H5E \ref H5F \ref H5G \ref H5I \ref H5L +\ref H5O \ref H5P \ref H5PL \ref H5R \ref H5S \ref H5T \ref H5Z +</td></tr> +</table> + +</td></tr> +<tr><th>Mind the gap</th></tr> +<tr><td> +Follow these simple rules and stay out of trouble: + +\li \Bold{Handle discipline:} The HDF5 C-API is rife with handles or + identifiers, which you typically obtain by creating new HDF5 items, copying + items, or retrieving facets of items. \Emph{You acquire a handle, you own it!} + (Colin Powell) In other words, you are responsible for releasing the underlying + resources via the matching \Code{H5*close()} call, or deal with the consequences + of resource leakage. +\li \Bold{Closed means closed:} Do not pass identifiers that were previously + \Code{H5*close()}-d to other API functions! It will generate an error. +\li \Bold{Dynamic memory allocation:} The API contains a few functions in which the + HDF5 library dynamically allocates memory on the caller's behalf. The caller owns + this memory and eventually must free it by calling H5free_memory(). (\Bold{Not} + the `free` function \Emph{du jour}!) +\li \Bold{Be careful with that saw:} Do not modify the underlying collection when an + iteration is in progress! +\li \Bold{Use of locations:} Certain API functions, typically called \Code{H5***_by_name} + use a combination of identifiers and path names to refer to HDF5 objects. + If the identifier fully specifies the object in question, pass \Code{'.'} (a dot) + for the name! + +Break a leg! +</td> +</tr> +</table> \cpp_c_api_note +\par Don't like what you see? - You can help to improve this Reference Manual + Complete the survey linked near the top of this page!\n + We treat documentation like code: Fork the + <a href="https://github.com/HDFGroup/hdf5">HDF5 repo</a>, make changes, and create a + <a href="https://github.com/HDFGroup/hdf5/pulls">pull request</a> !\n + See the \ref RMT for general guidance. + */
\ No newline at end of file diff --git a/doxygen/dox/Specifications.dox b/doxygen/dox/Specifications.dox index bd7e849..f6fee78 100644 --- a/doxygen/dox/Specifications.dox +++ b/doxygen/dox/Specifications.dox @@ -18,4 +18,40 @@ \li <a href="https://support.hdfgroup.org/HDF5/doc/HL/H5DS_Spec.pdf"> HDF5 Dimension Scale Specification</a> -*/
\ No newline at end of file +*/ + +/** \page FMT3 HDF5 File Format Specification Version 3.0 + +\htmlinclude H5.format.html + +*/ + +/** \page FMT2 HDF5 File Format Specification Version 2.0 + +\htmlinclude H5.format.2.0.html + +*/ + +/** \page FMT11 HDF5 File Format Specification Version 1.1 + +\htmlinclude H5.format.1.1.html + +*/ + +/** \page FMT1 HDF5 File Format Specification Version 1.0 + +\htmlinclude H5.format.1.0.html + +*/ + +/** \page IMG HDF5 Image and Palette Specification Version 1.2 + +\htmlinclude ImageSpec.html + +*/ + +/** \page TBL HDF5 Table Specification Version 1.0 + +\htmlinclude TableSpec.html + +*/ diff --git a/doxygen/dox/TechnicalNotes.dox b/doxygen/dox/TechnicalNotes.dox index 2bda175..9bd2802 100644 --- a/doxygen/dox/TechnicalNotes.dox +++ b/doxygen/dox/TechnicalNotes.dox @@ -1,6 +1,10 @@ /** \page TN Technical Notes \li \link api-compat-macros API Compatibility Macros \endlink +\li \ref APPDBG "Debugging HDF5 Applications" +\li \ref FMTDISC "File Format Walkthrough" +\li \ref FILTER "Filters" +\li \ref IOFLOW "HDF5 Raw I/O Flow Notes" \li \ref TNMDC "Metadata Caching in HDF5" \li \ref MT "Thread Safe library" \li \ref VFL "Virtual File Layer" @@ -13,8 +17,32 @@ */ +/** \page IOFLOW HDF5 Raw I/O Flow Notes + +\htmlinclude IOFlow.html + +*/ + /** \page VFL HDF5 Virtual File Layer \htmlinclude VFL.html */ + +/** \page FMTDISC HDF5 File Format Discussion + +\htmlinclude FileFormat.html + +*/ + +/** \page FILTER HDF5 Filters + +\htmlinclude Filters.html + +*/ + +/** \page APPDBG Debugging HDF5 Applications + +\htmlinclude DebuggingHDF5Applications.html + +*/
\ No newline at end of file diff --git a/doxygen/dox/cookbook/Accessibility.c b/doxygen/dox/cookbook/Accessibility.c new file mode 100644 index 0000000..9f8fe55 --- /dev/null +++ b/doxygen/dox/cookbook/Accessibility.c @@ -0,0 +1,46 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <assert.h> +#include <stdio.h> +#include <stdlib.h> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [set_libver_bounds] --> + { + __label__ fail_fapl, fail_file; + hid_t fapl, file, aspace, attr; + + if ((fapl = H5Pcreate(H5P_FILE_ACCESS)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_fapl; + } +#if H5_VERSION_GE(1, 8, 0) + if (H5Pset_libver_bounds(fapl, H5F_LIBVER_LATEST, H5F_LIBVER_LATEST) < 0) { +#else +#error Only HDF5 1.8.x and later supported. +#endif + ret_val = EXIT_FAILURE; + goto fail_file; + } + if ((file = H5Fcreate("set_libver_bounds.h5", H5F_ACC_TRUNC, H5P_DEFAULT, fapl)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + + H5Fclose(file); +fail_file: + H5Pclose(fapl); +fail_fapl:; + } + //! <!-- [set_libver_bounds] --> + + assert(ret_val == EXIT_SUCCESS); + + return ret_val; +} diff --git a/doxygen/dox/cookbook/Accessibility.dox b/doxygen/dox/cookbook/Accessibility.dox new file mode 100644 index 0000000..f100283 --- /dev/null +++ b/doxygen/dox/cookbook/Accessibility.dox @@ -0,0 +1,39 @@ +/** \page Accessibility + +\section Accessibility + +\subsection CB_MaintainCompat Maintaining Compatibility with other HDF5 Library Versions + +\par Problem +You want to ensure that the HDF5 files you produce or modify are accessible by all +releavnt tools and applications + +\par Solution +For HDF5 items (objects, attributes, etc.) that you would like to +create in new or existing HDF5 files, ascertain the supported range of HDF5 +library versions as lower and upper bounds. When creating new or opening +existing HDF5 files, use a file access property list and configure the supported +range via the H5Pset_libver_bounds() function.\n +In the example below, we restrict HDF5 item creation to the HDF5 1.8.x family of +library versions. +\snippet{lineno} Accessibility.c set_libver_bounds + +\par Discussion +See RFC \ref_rfc20160105 for a detailed and comprehensive account of HDF5 +versioning (library, file format spec., etc.) and the H5Pset_libver_bounds() +function.\n +The default range #H5F_LIBVER_EARLIEST (low) - #H5F_LIBVER_LATEST (high) offers the +widest compatibility range, but may not be suitable for certain (feature-)use +cases.\n +The HDF5 library comes with a \Emph{forward-} and \Emph{backward-compatibility} +guarantee: This means that the latest version of the library can always read +HDF5 files created by a version realesed earlier (backward compatibility). +It also means that a given release of the library can read the contents of +HDF5 files created with later versions of the library as long as the files +do not contain features introduced in later versions (forward compatibility). + +\par See Also +See the recipe \ref CB_LargeAttributes for an example where we use HDF5 +compatibility settings to enable the creation of large HDF5 attributes. + +*/
\ No newline at end of file diff --git a/doxygen/dox/cookbook/Attributes.c b/doxygen/dox/cookbook/Attributes.c new file mode 100644 index 0000000..6e51cab --- /dev/null +++ b/doxygen/dox/cookbook/Attributes.c @@ -0,0 +1,59 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <assert.h> +#include <stdio.h> +#include <stdlib.h> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [large_attribute] --> + { + __label__ fail_attr, fail_aspace, fail_fapl, fail_file; + hid_t fapl, file, aspace, attr; + + if ((fapl = H5Pcreate(H5P_FILE_ACCESS)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_fapl; + } +#if H5_VERSION_GE(1, 8, 0) + if (H5Pset_libver_bounds(fapl, H5F_LIBVER_LATEST, H5F_LIBVER_LATEST) < 0) { +#else +#error Only HDF5 1.8.x and later supported. +#endif + ret_val = EXIT_FAILURE; + goto fail_file; + } + if ((file = H5Fcreate("large_attribute.h5", H5F_ACC_TRUNC, H5P_DEFAULT, fapl)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + + if ((aspace = H5Screate_simple(1, (hsize_t[]){1024 * 1024}, NULL)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_aspace; + } + if ((attr = H5Acreate(file, "4MiB", H5T_IEEE_F32LE, aspace, H5P_DEFAULT, H5P_DEFAULT)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_attr; + } + + H5Aclose(attr); +fail_attr: + H5Sclose(aspace); +fail_aspace: + H5Fclose(file); +fail_file: + H5Pclose(fapl); +fail_fapl:; + } + //! <!-- [large_attribute] --> + + assert(ret_val == EXIT_SUCCESS); + + return ret_val; +} diff --git a/doxygen/dox/cookbook/Attributes.dox b/doxygen/dox/cookbook/Attributes.dox new file mode 100644 index 0000000..68fd159 --- /dev/null +++ b/doxygen/dox/cookbook/Attributes.dox @@ -0,0 +1,38 @@ +/** \page Attributes + +\section Attributes + +\subsection CB_LargeAttributes Creating "Large" HDF5 Attributes + +\par Problem +You would like to use HDF5 attributes the size of whose values +exceeds a few dozen kilobytes + +\par Solution +A file format change in the HDF5 1.8.x family of library releases made it +possible to have attributes larger than about 64 KiB. Ensure that the lower +library version bound for new HDF5 item creation is at least 1.8.x, and create +larger attributes as usual.\n +In the example below, we create an attribute whose value occupies 4 MiB. + +\note This feature is only supported in HDF5 1.8.x+ + +\snippet{lineno} Attributes.c large_attribute + +\par Discussion +Large attributes are supported only in HDF5 versions 1.8.x and higher. +This has implications for the accessibility of your HDF5 files and +is your call.\n +Since there are no size limitations for large attributes, it might +seem tempting to mistake them for dataset stand-ins. This is not the +case, for at least two reasons: +1. Attributes decorate HDF5 objects, have their own local namespace, + and can't be link targets. +2. Attribute I/O treats the attribute value as atomic, i.e., there + is no support for partial I/O. A large attribute will always be + read or written in its entirety. + +\par See Also +See \ref CB_MaintainCompat for HDF5 compatibility implications. + + */
\ No newline at end of file diff --git a/doxygen/dox/cookbook/Files.c b/doxygen/dox/cookbook/Files.c new file mode 100644 index 0000000..1f1f4b1 --- /dev/null +++ b/doxygen/dox/cookbook/Files.c @@ -0,0 +1,71 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <assert.h> +#include <stdio.h> +#include <stdlib.h> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [free_space] --> + { + __label__ fail_fcpl, fail_fapl, fail_file; + hid_t fcpl, fapl, file; + + if ((fcpl = H5Pcreate(H5P_FILE_CREATE)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_fcpl; + } + + if ((fapl = H5Pcreate(H5P_FILE_ACCESS)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_fapl; + } + + if ((file = H5Fcreate("free_space.h5", H5F_ACC_TRUNC, fcpl, fapl)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + H5Fclose(file); + +fail_file: + H5Pclose(fapl); +fail_fapl: + H5Pclose(fcpl); +fail_fcpl:; + } + //! <!-- [free_space] --> + + //! <!-- [user_block] --> + { + __label__ fail_fcpl, fail_file; + hid_t fcpl, file; + + if ((fcpl = H5Pcreate(H5P_FILE_CREATE)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_fcpl; + } + if (H5Pset_userblock(fcpl, 8192 * 1024) < 0) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + if ((file = H5Fcreate("userblock.h5", H5F_ACC_TRUNC, fcpl, H5P_DEFAULT)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + H5Fclose(file); + +fail_file: + H5Pclose(fcpl); +fail_fcpl:; + } + //! <!-- [user_block] --> + + assert(ret_val == EXIT_SUCCESS); + + return ret_val; +} diff --git a/doxygen/dox/cookbook/Files.dox b/doxygen/dox/cookbook/Files.dox new file mode 100644 index 0000000..0b918a0 --- /dev/null +++ b/doxygen/dox/cookbook/Files.dox @@ -0,0 +1,31 @@ +/** \page Files + +\section Files + +\subsection CB_UserBlock Creating an HDF5 File User Block + +\par Problem +You would like to include certain ancillary, non-HDF5 content in an +HDF5 file such that it can be accessed without the HDF5 library. + +\par Solution +Use a file creation property list in which the user block size is set via +H5Pset_userblock(). In the example below, we create an 8 MiB user block. +\snippet{lineno} Files.c user_block + +\par Discussion +The user block begins at offset 0 and must be at least 512 bytes and a power +of 2. The HDF5 library ignores any content between the beginning of the +file and the end of the user block.\n +You can add or strip a user block to/from an existing HDF5 file with the +\Code{h5jam}/\Code{h5unjam} tool, respectively. +\warning +If you try to embed content into the user block for use by other applications, +pay close attention to how they handle space beyond the last used byte in the +user block or the user block in general. In the worst case, applications might +try to truncate the rest of the file and destroy the HDF5 portion of the file. + +\par See Also +References to related recipes + + */
\ No newline at end of file diff --git a/doxygen/dox/cookbook/Performance.dox b/doxygen/dox/cookbook/Performance.dox new file mode 100644 index 0000000..7ac3a18 --- /dev/null +++ b/doxygen/dox/cookbook/Performance.dox @@ -0,0 +1,21 @@ +/** \page Performance + +\section Performance + +\subsection CB_MDCPerf Assessing HDF5 Metadata Cache Performance + +\par Problem +You are trying to diagnose and improve the I/O performance of an application +and would like to understand if a simple metadata cache adjustment might +yield substantial performance gains + +\par Solution +The to-the-point solution, i.e., the solution w/o any background or explanation + +\par Discussion +A discussion of the fine points and variants of the solution + +\par See Also +References to related recipes + + */
\ No newline at end of file diff --git a/doxygen/dox/maybe_metadata_reads.dox b/doxygen/dox/maybe_metadata_reads.dox new file mode 100644 index 0000000..1bb53e0 --- /dev/null +++ b/doxygen/dox/maybe_metadata_reads.dox @@ -0,0 +1,50 @@ +/** + * \page maybe_metadata_reads Functions with No Access Property List Parameter that May Generate Metadata Reads + * + * \ingroup GACPL + * + * Currently there are several operations in HDF5 that can issue metadata reads + * from the metadata cache, but that take no property list. It is therefore not + * possible to set a collective requirement individually for those operations. The + * only solution with the HDF5 1.10.0 release is to set the collective requirement + * globally on H5Fopen() or H5Fcreate() for all metadata operations to be + * collective. + * + * The following is a list of those functions in the HDF5 library. This list is + * integral to the discussion in the H5Pset_all_coll_metadata_ops() entry: + * + * H5Awrite(), H5Aread(), H5Arename(), H5Aiterate2(), H5Adelete(), H5Aexists() + * + * H5Dget_space_status(), H5Dget_storage_size(), H5Dset_extent(), H5Ddebug(), + * H5Dclose(), H5Dget_create_plist(), H5Dget_space() (for virtual datasets) + * + * H5Gget_create_plist(), H5Gget_info(), H5Gclose() + * + * H5Literate(), H5Lvisit() + * + * H5Rcreate(), H5Rdereference2() (for object references), + * H5Rget_region(), H5Rget_obj_type2(), H5Rget_name() + * + * H5Ocopy(), H5Oopen_by_addr(), H5Oincr_refcount(), H5Odecr_refcount(), + * H5Oget_info(), H5Oset_comment(), H5Ovisit() + * + * H5Fis_hdf5(), H5Fflush(), H5Fclose(), H5Fget_file_image(), H5Freopen(), + * H5Fget_freespace(), H5Fget_info2(), H5Fget_free_sections(), H5Fmount(), + * H5Funmount() + * + * H5Iget_name() + * + * H5Tget_create_plist(), H5Tclose() + * + * H5Zunregister() + * + * In addition, \b most deprecated functions fall into this category. + * + * The HDF Group may address the above limitation in a future major release, but + * no decision has been made at this time. Such a change might, for example, + * include adding new versions of some or all the above functions with an extra + * property list parameter to allow an individual setting for the collective + * calling requirement. + * + * \sa_metadata_ops + */ diff --git a/doxygen/examples/DebuggingHDF5Applications.html b/doxygen/examples/DebuggingHDF5Applications.html new file mode 100644 index 0000000..3390887 --- /dev/null +++ b/doxygen/examples/DebuggingHDF5Applications.html @@ -0,0 +1,392 @@ +<html> + <head> + <title>Debugging HDF5 Applications</title> + + <h2>Introduction</h2> + + <p>The HDF5 library contains a number of debugging features to + make programmers' lives easier including the ability to print + detailed error messages, check invariant conditions, display + timings and other statistics, and trace API function calls and + return values. + + </p><dl> + <dt><b>Error Messages</b> + </dt><dd>Error messages are normally displayed automatically on the + standard error stream and include a stack trace of the library + including file names, line numbers, and function names. The + application has complete control over how error messages are + displayed and can disable the display on a permanent or + temporary basis. Refer to the documentation for the H5E error + handling package. + + <br><br> + </dd><dt><b>Invariant Conditions</b> + </dt><dd>Unless <code>NDEBUG</code> is defined during compiling, the + library will include code to verify that invariant conditions + have the expected values. When a problem is detected the + library will display the file and line number within the + library and the invariant condition that failed. A core dump + may be generated for post mortem debugging. The code to + perform these checks can be included on a per-package bases. + + <br><br> + </dd><dt><b>Timings and Statistics</b> + </dt><dd>The library can be configured to accumulate certain + statistics about things like cache performance, datatype + conversion, data space conversion, and data filters. The code + is included on a per-package basis and enabled at runtime by + an environment variable. + + <br><br> + </dd><dt><b>API Tracing</b> + </dt><dd>All API calls made by an application can be displayed and + include formal argument names and actual values and the + function return value. This code is also conditionally + included at compile time and enabled at runtime. + </dd></dl> + + <p>The statistics and tracing can be displayed on any output + stream (including streams opened by the shell) with output from + different packages even going to different streams. + + </p><h2>Error Messages</h2> + + <p>By default any API function that fails will print an error + stack to the standard error stream. + + </p><p> + </p><center> + <table border="" align="center" width="100%"> + <tbody><tr> + <td> + <p><code></code></p><pre><code> +HDF5-DIAG: Error detected in thread 0. Back trace follows. + #000: H5F.c line 1245 in H5Fopen(): unable to open file + major(04): File interface + minor(10): Unable to open file + #001: H5F.c line 846 in H5F_open(): file does not exist + major(04): File interface + minor(10): Unable to open file + </code></pre> + </td> + </tr> + </tbody></table> + </center> + + <p>The error handling package (H5E) is described + <a href="./group___h5_e.html">elsewhere</a>. + + </p><h2>Invariant Conditions</h2> + + <p>To include checks for invariant conditions the library should + be configured with <code>--disable-production</code>, the + default for versions before 1.2. The library designers have made + every attempt to handle error conditions gracefully but an + invariant condition assertion may fail in certain cases. The + output from a failure usually looks something like this: + + </p><p> + </p><center> + <table border="" align="center" width="100%"> + <tbody><tr> + <td> + <p><code></code></p><pre><code> +Assertion failed: H5.c:123: i<NELMTS(H5_debug_g) +IOT Trap, core dumped. + </code></pre> + </td> + </tr> + </tbody></table> + </center> + + <h2>Timings and Statistics</h2> + + <p>Code to accumulate statistics is included at compile time by + using the <code>--enable-debug</code> configure switch. The + switch can be followed by an equal sign and a comma-separated + list of package names or else a default list is used. + + </p><p> + </p><center> + <table border="" align="center" width="80%"> + <tbody><tr> + <th>Name</th> + <th>Default</th> + <th>Description</th> + </tr> + <tr> + <td align="center">a</td> + <td align="center">No</td> + <td>Attributes</td> + </tr> + <tr> + <td align="center">ac</td> + <td align="center">Yes</td> + <td>Meta data cache</td> + </tr> + <tr> + <td align="center">b</td> + <td align="center">Yes</td> + <td>B-Trees</td> + </tr> + <tr> + <td align="center">d</td> + <td align="center">Yes</td> + <td>Datasets</td> + </tr> + <tr> + <td align="center">e</td> + <td align="center">Yes</td> + <td>Error handling</td> + </tr> + <tr> + <td align="center">f</td> + <td align="center">Yes</td> + <td>Files</td> + </tr> + <tr> + <td align="center">g</td> + <td align="center">Yes</td> + <td>Groups</td> + </tr> + <tr> + <td align="center">hg</td> + <td align="center">Yes</td> + <td>Global heap</td> + </tr> + <tr> + <td align="center">hl</td> + <td align="center">No</td> + <td>Local heaps</td> + </tr> + <tr> + <td align="center">i</td> + <td align="center">Yes</td> + <td>Interface abstraction</td> + </tr> + <tr> + <td align="center">mf</td> + <td align="center">No</td> + <td>File memory management</td> + </tr> + <tr> + <td align="center">mm</td> + <td align="center">Yes</td> + <td>Library memory management</td> + </tr> + <tr> + <td align="center">o</td> + <td align="center">No</td> + <td>Object headers and messages</td> + </tr> + <tr> + <td align="center">p</td> + <td align="center">Yes</td> + <td>Property lists</td> + </tr> + <tr> + <td align="center">s</td> + <td align="center">Yes</td> + <td>Data spaces</td> + </tr> + <tr> + <td align="center">t</td> + <td align="center">Yes</td> + <td>Datatypes</td> + </tr> + <tr> + <td align="center">v</td> + <td align="center">Yes</td> + <td>Vectors</td> + </tr> + <tr> + <td align="center">z</td> + <td align="center">Yes</td> + <td>Raw data filters</td> + </tr> + </tbody></table> + </center> + + <p>In addition to including the code at compile time the + application must enable each package at runtime. This is done + by listing the package names in the <code>HDF5_DEBUG</code> + environment variable. That variable may also contain file + descriptor numbers (the default is `2') which control the output + for all following packages up to the next file number. The + word <code>all</code> refers to all packages. Any word my be + preceded by a minus sign to turn debugging off for the package. + + </p><p> + </p><center> + <table border="" align="center" width="100%"> + <caption align="top"><b>Sample debug specifications</b></caption> + <tbody><tr valign="top"> + <td><code>all</code></td> + <td>This causes debugging output from all packages to be + sent to the standard error stream.</td> + </tr> + <tr valign="top"> + <td><code>all -t -s</code></td> + <td>Debugging output for all packages except datatypes + and data spaces will appear on the standard error + stream.</td> + </tr> + <tr valign="top"> + <td><code>-all ac 255 t,s</code></td> + <td>This disables all debugging even if the default was to + debug something, then output from the meta data cache is + send to the standard error stream and output from data + types and spaces is sent to file descriptor 255 which + should be redirected by the shell.</td> + </tr> + </tbody></table> + </center> + + <p>The components of the <code>HDF5_DEBUG</code> value may be + separated by any non-lowercase letter. + + </p><h2>API Tracing</h2> + + <p>The HDF5 library can trace API calls by printing the + function name, the argument names and their values, and the + return value. Some people like to see lots of output during + program execution instead of using a good symbolic debugger, and + this feature is intended for their consumption. For example, + the output from <code>h5ls foo</code> after turning on tracing, + includes: + + </p><p> + </p><center> + <table border="" align="center" width="100%"> + <tbody><tr> + <td> + <code><pre> +H5Tcopy(type=184549388) = 184549419 (type); +H5Tcopy(type=184549392) = 184549424 (type); +H5Tlock(type=184549424) = SUCCEED; +H5Tcopy(type=184549393) = 184549425 (type); +H5Tlock(type=184549425) = SUCCEED; +H5Fopen(filename="foo", flags=0, access=H5P_DEFAULT) = FAIL; +HDF5-DIAG: Error detected in thread 0. Back trace follows. + #000: H5F.c line 1245 in H5Fopen(): unable to open file + major(04): File interface + minor(10): Unable to open file + #001: H5F.c line 846 in H5F_open(): file does not exist + major(04): File interface + minor(10): Unable to open file + </pre></code> + </td> + </tr> + </tbody></table> + </center> + + <p>The code that performs the tracing must be included in the + library by specifying the <code>--enable-trace</code> + configuration switch (the default for versions before 1.2). Then + the word <code>trace</code> must appear in the value of the + <code>HDF5_DEBUG</code> variable. The output will appear on the + last file descriptor before the word <code>trace</code> or two + (standard error) by default. + + </p><p> + </p><center> + <table border="" align="center" width="100%"> + <tbody><tr> + <td>To display the trace on the standard error stream: + <code><pre>$ env HDF5_DEBUG=trace a.out + </pre></code> + </td> + </tr> + <tr> + <td>To send the trace to a file: + <code><pre>$ env HDF5_DEBUG="55 trace" a.out 55>trace-output + </pre></code> + </td> + </tr> + </tbody></table> + </center> + + <h3>Performance</h3> + + <p>If the library was not configured for tracing then there is no + unnecessary overhead since all tracing code is excluded. + However, if tracing is enabled but not used there is a small + penalty. First, code size is larger because of extra + statically-declared character strings used to store argument + types and names and extra auto variable pointer in each + function. Also, execution is slower because each function sets + and tests a local variable and each API function calls the + <code>H5_trace()</code> function. + + </p><p>If tracing is enabled and turned on then the penalties from the + previous paragraph apply plus the time required to format each + line of tracing information. There is also an extra call to + H5_trace() for each API function to print the return value. + + </p><h3>Safety</h3> + + <p>The tracing mechanism is invoked for each API function before + arguments are checked for validity. If bad arguments are passed + to an API function it could result in a segmentation fault. + However, the tracing output is line-buffered so all previous + output will appear. + + </p><h3>Completeness</h3> + + <p>There are two API functions that don't participate in + tracing. They are <code>H5Eprint()</code> and + <code>H5Eprint_cb()</code> because their participation would + mess up output during automatic error reporting. + + </p><p>On the other hand, a number of API functions are called during + library initialization and they print tracing information. + + </p><h3>Implementation</h3> + + <p>For those interested in the implementation here is a + description. Each API function should have a call to one of the + <code>H5TRACE()</code> macros immediately after the + <code>FUNC_ENTER()</code> macro. The first argument is the + return type encoded as a string. The second argument is the + types of all the function arguments encoded as a string. The + remaining arguments are the function arguments. This macro was + designed to be as terse and unobtrousive as possible. + + </p><p>In order to keep the <code>H5TRACE()</code> calls synchronized + with the source code we've written a perl script which gets + called automatically just before Makefile dependencies are + calculated for the file. However, this only works when one is + using GNU make. To reinstrument the tracing explicitly, invoke + the <code>trace</code> program from the hdf5 bin directory with + the names of the source files that need to be updated. If any + file needs to be modified then a backup is created by appending + a tilde to the file name. + + </p><p> + </p><center> + <table border="" align="center" width="100%"> + <caption align="top"><b>Explicit Instrumentation</b></caption> + <tbody><tr> + <td> + <code><pre> +$ ../bin/trace *.c +H5E.c: in function `H5Ewalk_cb': +H5E.c:336: warning: trace info was not inserted + </pre></code> + </td> + </tr> + </tbody></table> + </center> + + <p>Note: The warning message is the result of a comment of the + form <code>/*NO TRACE*/</code> somewhere in the function + body. Tracing information will not be updated or inserted if + such a comment exists. + + </p><p>Error messages have the same format as a compiler so that they + can be parsed from program development environments like + Emacs. Any function which generates an error will not be + modified.</p> + +</body></html> diff --git a/doxygen/examples/FileFormat.html b/doxygen/examples/FileFormat.html new file mode 100644 index 0000000..fc35357 --- /dev/null +++ b/doxygen/examples/FileFormat.html @@ -0,0 +1,1275 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<!-- saved from url=(0072)https://gamma.hdfgroup.org/papers/HISS/030515.FileFormat/FileFormat.html --> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> + <title>HDF5 File Format Discussion</title> + + <meta name="author" content="Quincey Koziol"> +</head> + +<body text="#000000" bgcolor="#FFFFFF"> + +<style type="text/css"> +OL.loweralpha { list-style-type: lower-alpha } +OL.upperroman { list-style-type: upper-roman } +</style> + +<style type="text/css"> +TD CAPTION EM { color: red } +TD EM { color: blue } +TABLE CAPTION STRONG { font-size: larger } +</style> + +<center><h1>HDF5 File Format Discussion</h1></center> +<center><h3>Quincey Koziol<br> + koziol@ncsa.uiuc.edu<br> + May 15, 2003 +</h3></center> + +<ol class="upperroman"> + +<li><h3><u>Document's Audience:</u></h3> + +<ul> + <li>Current H5 library designers and knowledgable external developers.</li> +</ul> + +</li><li><h3><u>Background Reading:</u></h3> + +<dl> + <dt><a href="https://docs.hdfgroup.org/hdf5/develop/_s_p_e_c.html">HDF5 File Format Specification</a> + </dt><dd>This describes the current HDF5 file format. +</dd></dl> + +</li><li><h3><u>Introduction:</u></h3> + +<dl> + <dt><strong>What is this document about?</strong></dt> + <dd>This document attempts to explain the HDF5 file format + specification with a few examples and describes some potential + improvements to the format specification. + </dd> <br> +</dl> + +</li><li><h3><u>File Format Examples:</u></h3> + +<p>This section has several small programs and describes the format of a file +created with each of them. +</p> + +<p>Example program one - <em>Create an empty file</em>: +</p><pre> <code> +#include "hdf5.h" +#include <assert.h> + +int main() +{ + hid_t fid; /* File ID */ + herr_t ret; /* Generic return value */ + + /* Create the file */ + fid=H5Fcreate("example1.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); + assert(fid>=0); + + /* Close the file */ + ret=H5Fclose(fid); + assert(ret>=0); + + return(0); +} +</assert.h></code> </pre> + + <center> + <table border="" align="center" cellpadding="4" width="80%"> + <caption align="top"> + <strong>Super Block</strong> + </caption> + + <tbody><tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align="center"> + <td>\211</td> + <td>'H'</td> + <td>'D'</td> + <td>'F'</td> + </tr> + + <tr align="center"> + <td>\r</td> + <td>\n</td> + <td>\032</td> + <td>\n</td> + </tr> + + <tr align="center"> + <td>0</td> + <td>0</td> + <td>0</td> + <td>0</td> + </tr> + + <tr align="center"> + <td>0</td> + <td>8</td> + <td>8</td> + <td>0</td> + </tr> + + <tr align="center"> + <td colspan="2">4</td> + <td colspan="2">16</td> + </tr> + + <tr align="center"> + <td colspan="4">0x00000003</td> + </tr> + + <tr align="center"> + <td colspan="4">0</td> + </tr> + + <tr align="center"> + <td colspan="4"><br>0xffffffffffffffff<br><br></td> + </tr> + + <tr align="center"> + <td colspan="4">?</td> + </tr> + + <tr align="center"> + <td colspan="4"><br>0xffffffffffffffff<br><br></td> + </tr> + + <tr align="center"> + <td colspan="4"> + <table border="" width="100%"> + <tbody><tr align="center"> + <td colspan="4">0</td> + </tr> + + <tr align="center"> + <td colspan="4"><br>928<br><br></td> + </tr> + + <tr align="center"> + <td colspan="4">H5G_CACHED_STAB (1)</td> + </tr> + + <tr align="center"> + <td colspan="4">0</td> + </tr> + + <tr align="center"> + <td colspan="4"> + <table border="" width="100%"> + <tbody><tr align="center"> + <td colspan="4"><br>384<br><br></td> + </tr> + <tr align="center"> + <td colspan="4"><br>96<br><br></td> + </tr> + </tbody></table> + </td> + </tr> + </tbody></table> + </td> + </tr> + </tbody></table> + </center> +<br> +<pre> <code> +%h5debug example1.h5 + +Reading signature at address 0 (rel) +File Super Block... +File name: example1.h5 +File access flags 0x00000000 +File open reference count: 1 +Address of super block: 0 (abs) +Size of user block: 0 bytes +Super block version number: 0 +Free list version number: 0 +Root group symbol table entry version number: 0 +Shared header version number: 0 +Size of file offsets (haddr_t type): 8 bytes +Size of file lengths (hsize_t type): 8 bytes +Symbol table leaf node 1/2 rank: 4 +Symbol table internal node 1/2 rank: 16 +File consistency flags: 0x00000003 +Base address: 0 (abs) +Free list address: UNDEF (rel) +Address of driver information block: UNDEF (rel) +Root group symbol table entry: + Name offset into private heap: 0 + Object header address: 928 + Dirty: Yes + Cache info type: Symbol Table + Cached information: + B-tree address: 384 + Heap address: 96 +</code> </pre> + + + <center> + <table border="" cellpadding="4" width="80%"> + <caption align="top"> + <strong>Root Group Object Header</strong> + </caption> + + <tbody><tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align="center"> + <td colspan="1" width="25%">1</td> + <td colspan="1" width="25%">0</td> + <td colspan="2" width="50%">2</td> + </tr> + <tr align="center"> + <td colspan="4">1</td> + </tr> + <tr align="center"> + <td colspan="4">32</td> + </tr> + <tr align="center"> + <td colspan="2">0x0011</td> + <td colspan="2">16</td> + </tr> + <tr align="center"> + <td>0x01</td> + <td colspan="3">0</td> + </tr> + <tr align="center"> + <td colspan="4"> + <table border="" width="100%"> + <tbody><tr align="center"> + <td colspan="4"><br>384<br><br></td> + </tr> + <tr align="center"> + <td colspan="4"><br>96<br><br></td> + </tr> + </tbody></table> + </td> + </tr> + <tr align="center"> + <td colspan="2">0</td> + <td colspan="2">0</td> + </tr> + <tr align="center"> + <td>0x00</td> + <td colspan="3">0</td> + </tr> + </tbody></table> + </center> +<br> +<pre> <code> +%h5debug example1.h5 928 + +New address: 928 +Reading signature at address 928 (rel) +Object Header... +Dirty: 0 +Version: 1 +Header size (in bytes): 16 +Number of links: 1 +Number of messages (allocated): 2 (32) +Number of chunks (allocated): 1 (8) +Chunk 0... + Dirty: 0 + Address: 944 + Size in bytes: 32 +Message 0... + Message ID (sequence number): 0x0011 stab(0) + Shared message: No + Constant: Yes + Raw size in obj header: 16 bytes + Chunk number: 0 + Message Information: + B-tree address: 384 + Name heap address: 96 +Message 1... + Message ID (sequence number): 0x0000 null(0) + Shared message: No + Constant: No + Raw size in obj header: 0 bytes + Chunk number: 0 + Message Information: + <no info="" for="" this="" message=""> +</no></code> </pre> + + <center> + <table border="" cellpadding="4" width="80%"> + <caption align="top"> + <strong>Root Group Local Heap</strong> + </caption> + + <tbody><tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align="center"> + <td>'H'</td> + <td>'E'</td> + <td>'A'</td> + <td>'P'</td> + </tr> + + <tr align="center"> + <td colspan="4">0</td> + </tr> + + <tr align="center"> + <td colspan="4">256</td> + </tr> + + <tr align="center"> + <td colspan="4">8</td> + </tr> + + <tr align="center"> + <td colspan="4">128</td> + </tr> + </tbody></table> + </center> +<br> + +<pre> <code> +%h5debug example1.h5 96 + +New address: 96 +Reading signature at address 96 (rel) +Local Heap... +Dirty: 0 +Header size (in bytes): 32 +Address of heap data: 128 +Data bytes allocated on disk: 256 +Data bytes allocated in core: 256 +Free Blocks (offset, size): + Block #0: 8, 248 +Percent of heap used: 3.12% +Data follows (`__' indicates free region)... + 0: 00 00 00 00 00 00 00 00 __ __ __ __ __ __ __ __ ........ + 16: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 32: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 48: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 64: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 80: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 96: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 112: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 128: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 144: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 160: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 176: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 192: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 208: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 224: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 240: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + +</code> </pre> + + <center> + <table border="" cellpadding="4" width="80%"> + <caption align="top"> + <strong>Root Group B-tree</strong> + </caption> + + <tbody><tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + </tr><tr align="center"> + <td>'T'</td> + <td>'R'</td> + <td>'E'</td> + <td>'E'</td> + + </tr><tr align="center"> + <td>0</td> + <td>0</td> + <td colspan="2">0</td> + + </tr><tr align="center"> + <td colspan="4"><br>0xffffffffffffffff<br><br></td> + + </tr><tr align="center"> + <td colspan="4"><br>0xffffffffffffffff<br><br></td> + + </tr></tbody></table> + </center> +<br> +<pre> <code> +%h5debug example1.h5 384 96 + +New address: 384 +Reading signature at address 384 (rel) +Tree type ID: H5B_SNODE_ID +Size of node: 544 +Size of raw (disk) key: 8 +Dirty flag: False +Number of initial dirty children: 0 +Level: 0 +Address of left sibling: UNDEF +Address of right sibling: UNDEF +Number of children (max): 0 (32) + +</code> </pre> + +<p></p> + +<p>Example program two - <em>Create a file with a single dataset in it</em>: +</p><pre> <code> +#include "hdf5.h" +#include <assert.h> + +int main() +{ + hid_t fid; /* File ID */ + hid_t sid; /* Dataspace ID */ + hid_t did; /* Dataset ID */ + herr_t ret; /* Generic return value */ + + /* Create the file */ + fid=H5Fcreate("example2.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); + assert(fid>=0); + + /* Create a scalar dataspace for the dataset */ + sid=H5Screate(H5S_SCALAR); + assert(sid>=0); + + /* Create a trivial dataset */ + did=H5Dcreate(fid, "Dataset", H5T_NATIVE_INT, sid, H5P_DEFAULT); + assert(did>=0); + + /* Close the dataset */ + ret=H5Dclose(did); + assert(ret>=0); + + /* Close the dataspace */ + ret=H5Sclose(sid); + assert(ret>=0); + + /* Close the file */ + ret=H5Fclose(fid); + assert(ret>=0); + + return(0); +} +</assert.h></code> </pre> + + <center> + <table border="" align="center" cellpadding="4" width="80%"> + <caption align="top"> + <strong>Super Block</strong> + </caption> + + <tbody><tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align="center"> + <td>\211</td> + <td>'H'</td> + <td>'D'</td> + <td>'F'</td> + </tr> + + <tr align="center"> + <td>\r</td> + <td>\n</td> + <td>\032</td> + <td>\n</td> + </tr> + + <tr align="center"> + <td>0</td> + <td>0</td> + <td>0</td> + <td>0</td> + </tr> + + <tr align="center"> + <td>0</td> + <td>8</td> + <td>8</td> + <td>0</td> + </tr> + + <tr align="center"> + <td colspan="2">4</td> + <td colspan="2">16</td> + </tr> + + <tr align="center"> + <td colspan="4">0x00000003</td> + </tr> + + <tr align="center"> + <td colspan="4">0</td> + </tr> + + <tr align="center"> + <td colspan="4"><br>0xffffffffffffffff<br><br></td> + </tr> + + <tr align="center"> + <td colspan="4">?</td> + </tr> + + <tr align="center"> + <td colspan="4"><br>0xffffffffffffffff<br><br></td> + </tr> + + <tr align="center"> + <td colspan="4"> + <table border="" width="100%"> + <tbody><tr align="center"> + <td colspan="4">0</td> + </tr> + + <tr align="center"> + <td colspan="4"><br>928<br><br></td> + </tr> + + <tr align="center"> + <td colspan="4">H5G_CACHED_STAB (1)</td> + </tr> + + <tr align="center"> + <td colspan="4">0</td> + </tr> + + <tr align="center"> + <td colspan="4"> + <table border="" width="100%"> + <tbody><tr align="center"> + <td colspan="4"><br>384<br><br></td> + </tr> + <tr align="center"> + <td colspan="4"><br>96<br><br></td> + </tr> + </tbody></table> + </td> + </tr> + </tbody></table> + </td> + </tr> + </tbody></table> + </center> +<br> +<pre> <code> +%h5debug example2.h5 + +Reading signature at address 0 (rel) +File Super Block... +File name: example2.h5 +File access flags 0x00000000 +File open reference count: 1 +Address of super block: 0 (abs) +Size of user block: 0 bytes +Super block version number: 0 +Free list version number: 0 +Root group symbol table entry version number: 0 +Shared header version number: 0 +Size of file offsets (haddr_t type): 8 bytes +Size of file lengths (hsize_t type): 8 bytes +Symbol table leaf node 1/2 rank: 4 +Symbol table internal node 1/2 rank: 16 +File consistency flags: 0x00000003 +Base address: 0 (abs) +Free list address: UNDEF (rel) +Address of driver information block: UNDEF (rel) +Root group symbol table entry: + Name offset into private heap: 0 + Object header address: 928 + Dirty: Yes + Cache info type: Symbol Table + Cached entry information: + B-tree address: 384 + Heap address: 96 +</code> </pre> + + <center> + <table border="" cellpadding="4" width="80%"> + <caption align="top"> + <strong>Root Group Object Header</strong> + </caption> + + <tbody><tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align="center"> + <td colspan="1" width="25%">1</td> + <td colspan="1" width="25%">0</td> + <td colspan="2" width="50%">2</td> + </tr> + <tr align="center"> + <td colspan="4">1</td> + </tr> + <tr align="center"> + <td colspan="4">32</td> + </tr> + <tr align="center"> + <td colspan="2">0x0011</td> + <td colspan="2">16</td> + </tr> + <tr align="center"> + <td>0x01</td> + <td colspan="3">0</td> + </tr> + <tr align="center"> + <td colspan="4"> + <table border="" width="100%"> + <tbody><tr align="center"> + <td colspan="4"><br>384<br><br></td> + </tr> + <tr align="center"> + <td colspan="4"><br>96<br><br></td> + </tr> + </tbody></table> + </td> + </tr> + <tr align="center"> + <td colspan="2">0</td> + <td colspan="2">0</td> + </tr> + <tr align="center"> + <td>0x00</td> + <td colspan="3">0</td> + </tr> + </tbody></table> + </center> +<br> +<pre> <code> +%h5debug example2.h5 928 + +New address: 928 +Reading signature at address 928 (rel) +Object Header... +Dirty: 0 +Version: 1 +Header size (in bytes): 16 +Number of links: 1 +Number of messages (allocated): 2 (32) +Number of chunks (allocated): 1 (8) +Chunk 0... + Dirty: 0 + Address: 944 + Size in bytes: 32 +Message 0... + Message ID: 0x0011 stab(0) + Shared message: No + Constant: Yes + Raw size in obj header: 16 bytes + Chunk number: 0 + Message Information: + B-tree address: 384 + Name heap address: 96 +Message 1... + Message ID: 0x0000 null(0) + Shared message: No + Constant: No + Raw size in obj header: 0 bytes + Chunk number: 0 + Message Information: + <no info="" for="" this="" message=""> +</no></code> </pre> + + <center> + <table border="" cellpadding="4" width="80%"> + <caption align="top"> + <strong>Root Group Local Heap</strong> + </caption> + + <tbody><tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align="center"> + <td>'H'</td> + <td>'E'</td> + <td>'A'</td> + <td>'P'</td> + </tr> + + <tr align="center"> + <td colspan="4">0</td> + </tr> + + <tr align="center"> + <td colspan="4">256</td> + </tr> + + <tr align="center"> + <td colspan="4">16</td> + </tr> + + <tr align="center"> + <td colspan="4">128</td> + </tr> + </tbody></table> + </center> +<br> + +<pre> <code> +%h5debug example2.h5 96 + +New address: 96 +Reading signature at address 96 (rel) +Local Heap... +Dirty: 0 +Header size (in bytes): 32 +Address of heap data: 128 +Data bytes allocated on disk: 256 +Data bytes allocated in core: 256 +Free Blocks (offset, size): + Block #0: 16, 240 +Percent of heap used: 6.25% +Data follows (`__' indicates free region)... + 0: 00 00 00 00 00 00 00 00 44 61 74 61 73 65 74 00 ........Dataset. + 16: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 32: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 48: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 64: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 80: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 96: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 112: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 128: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 144: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 160: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 176: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 192: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 208: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 224: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 240: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ +</code> </pre> + + <center> + <table border="" cellpadding="4" width="80%"> + <caption align="top"> + <strong>Root Group B-tree</strong> + </caption> + + <tbody><tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + </tr><tr align="center"> + <td>'T'</td> + <td>'R'</td> + <td>'E'</td> + <td>'E'</td> + + </tr><tr align="center"> + <td>0</td> + <td>0</td> + <td colspan="2">1</td> + + </tr><tr align="center"> + <td colspan="4"><br>0xffffffffffffffff<br><br></td> + + </tr><tr align="center"> + <td colspan="4"><br>0xffffffffffffffff<br><br></td> + + </tr><tr align="center"> + <td colspan="4"><br>0<br><br></td> + + </tr><tr align="center"> + <td colspan="4"><br>1248<br><br></td> + + </tr><tr align="center"> + <td colspan="4"><br>8<br><br></td> + + </tr></tbody></table> + </center> +<br> +<pre> <code> +%h5debug example2.h5 384 96 + +New address: 384 +Reading signature at address 384 (rel) +Tree type ID: H5B_SNODE_ID +Size of node: 544 +Size of raw (disk) key: 8 +Dirty flag: False +Number of initial dirty children: 0 +Level: 0 +Address of left sibling: UNDEF +Address of right sibling: UNDEF +Number of children (max): 1 (32) +Child 0... + Address: 1248 + Left Key: + Heap offset: 0 + Name : + Right Key: + Heap offset: 8 + Name : Dataset +</code> </pre> + + <center> + <table border="" cellpadding="4" width="80%"> + <caption align="top"> + <strong>Root Group B-tree Symbol Table Node</strong> + </caption> + + <tbody><tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + </tr><tr align="center"> + <td>'S'</td> + <td>'N'</td> + <td>'O'</td> + <td>'D'</td> + + </tr><tr align="center"> + <td>1</td> + <td>0</td> + <td colspan="2">1</td> + + </tr><tr align="center"> + <td colspan="4"> + <table border="" width="100%"> + <tbody><tr align="center"> + <td colspan="4">8</td> + </tr> + + <tr align="center"> + <td colspan="4"><br>976<br><br></td> + </tr> + + <tr align="center"> + <td colspan="4">0</td> + </tr> + + <tr align="center"> + <td colspan="4">0</td> + </tr> + + <tr align="center"> + <td colspan="4"><br><br>0<br><br><br></td> + </tr> + </tbody></table> + </td> + + </tr></tbody></table> + </center> +<br> +<pre> <code> +%h5debug example2.h5 1248 96 + +New address: 1248 +Reading signature at address 1248 (rel) +Symbol Table Node... +Dirty: No +Size of Node (in bytes): 328 +Number of Symbols: 1 of 8 +Symbol 0: + Name: `Dataset' + Name offset into private heap: 8 + Object header address: 976 + Dirty: No + Cache info type: Nothing Cached +</code> </pre> + + <center> + <table border="" cellpadding="4" width="90%"> + <caption align="top"> + <strong>'/Dataset' Object Header</strong> + </caption> + + <tbody><tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align="center"> + <td colspan="1"><em>Version:</em> 1</td> + <td colspan="1"><em>Reserved:</em> 0</td> + <td colspan="2"><em>Number of Header Messages:</em> 6</td> + </tr> + <tr align="center"> + <td colspan="4"><em>Object Reference Count:</em> 1</td> + </tr> + <tr align="center"> + <td colspan="4"><em>Total Object Header Size:</em> 256</td> + </tr> +<!-- Fill Value Header Message --> + <tr align="center"> + <td colspan="4"> + <table border="" width="100%"> + <caption align="top" color="#80FFFF"> + <em>Fill Value Header Message</em> + </caption> + <tbody><tr align="center"> + <th width="25%"></th> + <th width="25%"></th> + <th width="25%"></th> + <th width="25%"></th> + </tr> + + <tr align="center"> + <!-- Object Header Message Type --> + <td colspan="2"><em>Message Type:</em> 0x0005</td> + <!-- Object Header Message Length --> + <td colspan="2"><em>Message Data Size:</em> 8</td> + </tr> + <tr align="center"> + <!-- Object Header Message Flags --> + <td colspan="1"><em>Flags:</em> 0x01</td> + <!-- Reserved --> + <td colspan="3"><em>Reserved:</em> 0</td> + </tr> + <tr align="center"> + <!-- Version --> + <td colspan="1"><em>Version:</em> 1</td> + <!-- Space Allocation Time --> + <td colspan="1"><em>Space Allocation Time:</em> 2 (Late)</td> + <!-- Fill Value Writing Time --> + <td colspan="1"><em>Fill Value Writing Time:</em> 0 (At allocation)</td> + <!-- Fill Value Defined --> + <td colspan="1"><em>Fill Value Defined:</em> 0 (Undefined)</td> + </tr> + <tr align="center"> + <!-- Fill Value Datatype Size --> + <td colspan="4"><em>Fill Value Datatype Size:</em> 0 (Use dataset's datatype for fill-value datatype)</td> + </tr> + </tbody></table> + </td> + </tr> +<!-- Datatype Header Message --> + <tr align="center"> + <td colspan="4"> + <table border="" width="100%"> + <caption align="top"> + <em>Datatype Header Message</em> + </caption> + <tbody><tr align="center"> + <th width="25%"></th> + <th width="25%"></th> + <th width="25%"></th> + <th width="25%"></th> + </tr> + + <tr align="center"> + <!-- Object Header Message Type --> + <td colspan="2"><em>Message Type:</em> 0x0003</td> + <!-- Object Header Message Length --> + <td colspan="2"><em>Message Data Size:</em> 16</td> + </tr> + <tr align="center"> + <!-- Object Header Message Flags --> + <td colspan="1"><em>Flags:</em> 0x01</td> + <!-- Reserved --> + <td colspan="3"><em>Reserved:</em> 0</td> + </tr> + <tr align="center"> + <!-- Type Class and Version --> + <td colspan="1"> + <table border="" width="100%"> + <tbody><tr align="center"> + <td width="50%"><em>Version:</em> 0x1</td> + <td><em>Class:</em> 0x0 (Fixed-Point)</td> + </tr> + </tbody></table> + </td> + <!-- Class Bit Field --> + <td colspan="3"><em>Fixed-Point Bit-Field:</em> 0x08 (Little-endian, No padding, Signed)</td> + </tr> + <tr align="center"> + <!-- Type Size (in bytes) --> + <td colspan="4"><em>Size:</em> 4</td> + </tr> + <tr align="center"> + <!-- Bit Offset --> + <td colspan="2"><em>Bit Offset:</em> 0</td> + <!-- Bit Precision --> + <td colspan="2"><em>Bit Precision:</em> 32</td> + </tr> + <tr align="center"> + <!-- Message alignment filler --> + <td colspan="4"><em>Message Alignment Filler:</em> -</td> + </tr> + </tbody></table> + </td> + </tr> +<!-- Dataspace Header Message --> + <tr align="center"> + <td colspan="4"> + <table border="" width="100%"> + <caption align="top"> + <em>Dataspace Header Message</em> + </caption> + <tbody><tr align="center"> + <th width="25%"></th> + <th width="25%"></th> + <th width="25%"></th> + <th width="25%"></th> + </tr> + + <tr align="center"> + <!-- Object Header Message Type --> + <td colspan="2"><em>Message Type:</em> 0x0001</td> + <!-- Object Header Message Length --> + <td colspan="2"><em>Message Data Size:</em> 8</td> + </tr> + <tr align="center"> + <!-- Object Header Message Flags --> + <td colspan="1"><em>Flags:</em> 0x00</td> + <!-- Reserved --> + <td colspan="3"><em>Reserved:</em> 0</td> + </tr> + <tr align="center"> + <!-- Version --> + <td colspan="1"><em>Version:</em> 1</td> + <!-- Rank --> + <td colspan="1"><em>Rank:</em> 0 (Scalar)</td> + <!-- Flags --> + <td colspan="1"><em>Flags:</em> 0x00 (No maximum dimensions, no permutation information)</td> + <!-- Reserved --> + <td colspan="1"><em>Reserved:</em> 0</td> + </tr> + <tr align="center"> + <!-- Reserved --> + <td colspan="4"><em>Reserved:</em> 0</td> + </tr> + </tbody></table> + </td> + </tr> +<!-- Layout Header Message --> + <tr align="center"> + <td colspan="4"> + <table border="" width="100%"> + <caption align="top"> + <em>Layout Header Message</em> + </caption> + <tbody><tr align="center"> + <th width="25%"></th> + <th width="25%"></th> + <th width="25%"></th> + <th width="25%"></th> + </tr> + + <tr align="center"> + <!-- Object Header Message Type --> + <td colspan="2"><em>Message Type:</em> 0x0008</td> + <!-- Object Header Message Length --> + <td colspan="2"><em>Message Data Size:</em> 24</td> + </tr> + <tr align="center"> + <!-- Object Header Message Flags --> + <td colspan="1"><em>Flags:</em> 0x00</td> + <!-- Reserved --> + <td colspan="3"><em>Reserved:</em> 0</td> + </tr> + <tr align="center"> + <!-- Version --> + <td colspan="1"><em>Version:</em> 1</td> + <!-- Rank --> + <td colspan="1"><em>Rank:</em> 1 (Dataspace rank+1)</td> + <!-- Class --> + <td colspan="1"><em>Class:</em> 1 (Contiguous)</td> + <!-- Reserved --> + <td colspan="1"><em>Reserved:</em> 0</td> + </tr> + <tr align="center"> + <!-- Reserved --> + <td colspan="4"><em>Reserved:</em> 0</td> + </tr> + <tr align="center"> + <!-- Address --> + <td colspan="4"><br><em>Address:</em> 0xffffffffffffffff (Undefined)<br><br></td> + </tr> + <tr align="center"> + <!-- Layout Dimensions --> + <td colspan="4"><em>Dimension 0 Size:</em> 4 (Datatype size)</td> + </tr> + <tr align="center"> + <!-- Message alignment filler --> + <td colspan="4"><em>Message Alignment Filler:</em> -</td> + </tr> + </tbody></table> + </td> + </tr> +<!-- Modification Date & Time Header Message --> + <tr align="center"> + <td colspan="4"> + <table border="" width="100%"> + <caption align="top"> + <em>Modification Date & Time Header Message</em> + </caption> + <tbody><tr align="center"> + <th width="25%"></th> + <th width="25%"></th> + <th width="25%"></th> + <th width="25%"></th> + </tr> + + <tr align="center"> + <!-- Object Header Message Type --> + <td colspan="2"><em>Message Type:</em> 0x0012</td> + <!-- Object Header Message Length --> + <td colspan="2"><em>Message Data Size:</em> 8</td> + </tr> + <tr align="center"> + <!-- Object Header Message Flags --> + <td colspan="1"><em>Flags:</em> 0x00</td> + <!-- Reserved --> + <td colspan="3"><em>Reserved:</em> 0</td> + </tr> + <tr align="center"> + <!-- Version --> + <td colspan="1"><em>Version:</em> 1</td> + <!-- Reserved --> + <td colspan="3"><em>Reserved:</em> 0</td> + </tr> + <tr align="center"> + <!-- Modification time --> + <td colspan="4"><em>Seconds Since Epoch:</em> 1052401700 (2003-05-08 08:48:20 CDT)</td> + </tr> + </tbody></table> + </td> + </tr> +<!-- Null Header Message --> + <tr align="center"> + <td colspan="4"> + <table border="" width="100%"> + <caption align="top"> + <em>Null Header Message</em> + </caption> + <tbody><tr align="center"> + <th width="25%"></th> + <th width="25%"></th> + <th width="25%"></th> + <th width="25%"></th> + </tr> + + <tr align="center"> + <td colspan="2"><em>Message Type:</em> 0x0000</td> + <td colspan="2"><em>Message Data Size:</em> 144</td> + </tr> + <tr align="center"> + <td colspan="1"><em>Flags:</em> 0x00</td> + <td colspan="3"><em>Reserved:</em> 0</td> + </tr> + </tbody></table> + </td> + </tr> + </tbody></table> + </center> +<br> +<pre> <code> +%h5debug example2.h5 976 + +New address: 976 +Reading signature at address 976 (rel) +Object Header... +Dirty: 0 +Version: 1 +Header size (in bytes): 16 +Number of links: 1 +Number of messages (allocated): 6 (32) +Number of chunks (allocated): 1 (8) +Chunk 0... + Dirty: 0 + Address: 992 + Size in bytes: 256 +Message 0... + Message ID (sequence number): 0x0005 `fill_new' (0) + Shared: No + Constant: Yes + Raw size in obj header: 8 bytes + Chunk number: 0 + Message Information: + Version: 1 + Space Allocation Time: Late + Fill Time: On Allocation + Fill Value Defined: Undefined + Size: 0 + Data type: <dataset type=""> +Message 1... + Message ID (sequence number): 0x0003 data_type(0) + Shared message: No + Constant: Yes + Raw size in obj header: 16 bytes + Chunk number: 0 + Message Information: + Type class: integer + Size: 4 bytes + Byte order: little endian + Precision: 32 bits + Offset: 0 bits + Low pad type: zero + High pad type: zero + Sign scheme: 2's comp +Message 2... + Message ID (sequence number): 0x0001 simple_dspace(0) + Shared message: No + Constant: No + Raw size in obj header: 8 bytes + Chunk number: 0 + Message Information: + Rank: 0 +Message 3... + Message ID (sequence number): 0x0008 layout(0) + Shared message: No + Constant: No + Raw size in obj header: 24 bytes + Chunk number: 0 + Message Information: + Data address: UNDEF + Number of dimensions: 1 + Size: {4} +Message 4... + Message ID (sequence number): 0x0012 mtime_new(0) + Shared message: No + Constant: No + Raw size in obj header: 8 bytes + Chunk number: 0 + Message Information: + Time: 2003-03-05 14:52:00 CST +Message 5... + Message ID (sequence number): 0x0000 null(0) + Shared message: No + Constant: No + Raw size in obj header: 144 bytes + Chunk number: 0 + Message Information: + <no info="" for="" this="" message=""> +</no></dataset></code> </pre> + +<p></p> + +</li></ol> + + + +</body></html> diff --git a/doxygen/examples/Filters.html b/doxygen/examples/Filters.html new file mode 100644 index 0000000..7054a3b --- /dev/null +++ b/doxygen/examples/Filters.html @@ -0,0 +1,450 @@ +<html> + <head> + <title>Filters</title> + <h1>Filters in HDF5</h1> + + <b>Note: Transient pipelines described in this document have not + been implemented.</b> + + <h2>Introduction</h2> + + <p>HDF5 allows chunked data to pass through user-defined filters + on the way to or from disk. The filters operate on chunks of an + <code>H5D_CHUNKED</code> dataset can be arranged in a pipeline + so output of one filter becomes the input of the next filter. + + </p><p>Each filter has a two-byte identification number (type + <code>H5Z_filter_t</code>) allocated by The HDF Group and can also be + passed application-defined integer resources to control its + behavior. Each filter also has an optional ASCII comment + string. + + </p> + <table> + <tbody><tr> + <th>Values for <code>H5Z_filter_t</code></th> + <th>Description</th> + </tr> + + <tr valign="top"> + <td><code>0-255</code></td> + <td>These values are reserved for filters predefined and + registered by the HDF5 library and of use to the general + public. They are described in a separate section + below.</td> + </tr> + + <tr valign="top"> + <td><code>256-511</code></td> + <td>Filter numbers in this range are used for testing only + and can be used temporarily by any organization. No + attempt is made to resolve numbering conflicts since all + definitions are by nature temporary.</td> + </tr> + + <tr valign="top"> + <td><code>512-65535</code></td> + <td>Reserved for future assignment. Please contact the + <a href="mailto:help@hdfgroup.org">HDF5 development team</a> + to reserve a value or range of values for + use by your filters.</td> + </tr></tbody></table> + + <h2>Defining and Querying the Filter Pipeline</h2> + + <p>Two types of filters can be applied to raw data I/O: permanent + filters and transient filters. The permanent filter pipeline is + defined when the dataset is created while the transient pipeline + is defined for each I/O operation. During an + <code>H5Dwrite()</code> the transient filters are applied first + in the order defined and then the permanent filters are applied + in the order defined. For an <code>H5Dread()</code> the + opposite order is used: permanent filters in reverse order, then + transient filters in reverse order. An <code>H5Dread()</code> + must result in the same amount of data for a chunk as the + original <code>H5Dwrite()</code>. + + </p><p>The permanent filter pipeline is defined by calling + <code>H5Pset_filter()</code> for a dataset creation property + list while the transient filter pipeline is defined by calling + that function for a dataset transfer property list. + + </p><dl> + <dt><code>herr_t H5Pset_filter (hid_t <em>plist</em>, + H5Z_filter_t <em>filter</em>, unsigned int <em>flags</em>, + size_t <em>cd_nelmts</em>, const unsigned int + <em>cd_values</em>[])</code> + </dt><dd>This function adds the specified <em>filter</em> and + corresponding properties to the end of the transient or + permanent output filter pipeline (depending on whether + <em>plist</em> is a dataset creation or dataset transfer + property list). The <em>flags</em> argument specifies certain + general properties of the filter and is documented below. The + <em>cd_values</em> is an array of <em>cd_nelmts</em> integers + which are auxiliary data for the filter. The integer values + will be stored in the dataset object header as part of the + filter information. + </dd><dt><code>int H5Pget_nfilters (hid_t <em>plist</em>)</code> + </dt><dd>This function returns the number of filters defined in the + permanent or transient filter pipeline depending on whether + <em>plist</em> is a dataset creation or dataset transfer + property list. In each pipeline the filters are numbered from + 0 through <em>N</em>-1 where <em>N</em> is the value returned + by this function. During output to the file the filters of a + pipeline are applied in increasing order (the inverse is true + for input). Zero is returned if there are no filters in the + pipeline and a negative value is returned for errors. + </dd><dt><code>H5Z_filter_t H5Pget_filter (hid_t <em>plist</em>, + int <em>filter_number</em>, unsigned int *<em>flags</em>, + size_t *<em>cd_nelmts</em>, unsigned int + *<em>cd_values</em>, size_t namelen, char name[])</code> + </dt><dd>This is the query counterpart of + <code>H5Pset_filter()</code> and returns information about a + particular filter number in a permanent or transient pipeline + depending on whether <em>plist</em> is a dataset creation or + dataset transfer property list. On input, <em>cd_nelmts</em> + indicates the number of entries in the <em>cd_values</em> + array allocated by the caller while on exit it contains the + number of values defined by the filter. The + <em>filter_number</em> should be a value between zero and + <em>N</em>-1 as described for <code>H5Pget_nfilters()</code> + and the function will return failure (a negative value) if the + filter number is out of range. If <em>name</em> is a pointer + to an array of at least <em>namelen</em> bytes then the filter + name will be copied into that array. The name will be null + terminated if the <em>namelen</em> is large enough. The + filter name returned will be the name appearing in the file or + else the name registered for the filter or else an empty string. + </dd></dl> + + <p>The flags argument to the functions above is a bit vector of + the following fields: + + </p> + <table> + <tbody><tr> + <th>Values for <em>flags</em></th> + <th>Description</th> + </tr> + + <tr valign="top"> + <td><code>H5Z_FLAG_OPTIONAL</code></td> + <td>If this bit is set then the filter is optional. If + the filter fails (see below) during an + <code>H5Dwrite()</code> operation then the filter is + just excluded from the pipeline for the chunk for which + it failed; the filter will not participate in the + pipeline during an <code>H5Dread()</code> of the chunk. + This is commonly used for compression filters: if the + compression result would be larger than the input then + the compression filter returns failure and the + uncompressed data is stored in the file. If this bit is + clear and a filter fails then the + <code>H5Dwrite()</code> or <code>H5Dread()</code> also + fails.</td> + </tr> + </tbody></table> + + <h2>Defining Filters</h2> + + <p>Each filter is bidirectional, handling both input and output to + the file, and a flag is passed to the filter to indicate the + direction. In either case the filter reads a chunk of data from + a buffer, usually performs some sort of transformation on the + data, places the result in the same or new buffer, and returns + the buffer pointer and size to the caller. If something goes + wrong the filter should return zero to indicate a failure. + + </p><p>During output, a filter that fails or isn't defined and is + marked as optional is silently excluded from the pipeline and + will not be used when reading that chunk of data. A required + filter that fails or isn't defined causes the entire output + operation to fail. During input, any filter that has not been + excluded from the pipeline during output and fails or is not + defined will cause the entire input operation to fail. + + </p><p>Filters are defined in two phases. The first phase is to + define a function to act as the filter and link the function + into the application. The second phase is to register the + function, associating the function with an + <code>H5Z_filter_t</code> identification number and a comment. + + </p><dl> + <dt><code>typedef size_t (*H5Z_func_t)(unsigned int + <em>flags</em>, size_t <em>cd_nelmts</em>, const unsigned int + <em>cd_values</em>[], size_t <em>nbytes</em>, size_t + *<em>buf_size</em>, void **<em>buf</em>)</code> + </dt><dd>The <em>flags</em>, <em>cd_nelmts</em>, and + <em>cd_values</em> are the same as for the + <code>H5Pset_filter()</code> function with the additional flag + <code>H5Z_FLAG_REVERSE</code> which is set when the filter is + called as part of the input pipeline. The input buffer is + pointed to by <em>*buf</em> and has a total size of + <em>*buf_size</em> bytes but only <em>nbytes</em> are valid + data. The filter should perform the transformation in place if + possible and return the number of valid bytes or zero for + failure. If the transformation cannot be done in place then + the filter should allocate a new buffer with + <code>malloc()</code> and assign it to <em>*buf</em>, + assigning the allocated size of that buffer to + <em>*buf_size</em>. The old buffer should be freed + by calling <code>free()</code>. + + <br><br> + </dd><dt><code>herr_t H5Zregister (H5Z_filter_t <em>filter_id</em>, + const char *<em>comment</em>, H5Z_func_t + <em>filter</em>)</code> + </dt><dd>The <em>filter</em> function is associated with a filter + number and a short ASCII comment which will be stored in the + hdf5 file if the filter is used as part of a permanent + pipeline during dataset creation. + </dd></dl> + + <h2>Predefined Filters</h2> + + <p>If <code>zlib</code> version 1.1.2 or later was found + during configuration then the library will define a filter whose + <code>H5Z_filter_t</code> number is + <code>H5Z_FILTER_DEFLATE</code>. Since this compression method + has the potential for generating compressed data which is larger + than the original, the <code>H5Z_FLAG_OPTIONAL</code> flag + should be turned on so such cases can be handled gracefully by + storing the original data instead of the compressed data. The + <em>cd_nvalues</em> should be one with <em>cd_value[0]</em> + being a compression aggression level between zero and nine, + inclusive (zero is the fastest compression while nine results in + the best compression ratio). + + </p><p>A convenience function for adding the + <code>H5Z_FILTER_DEFLATE</code> filter to a pipeline is: + + </p><dl> + <dt><code>herr_t H5Pset_deflate (hid_t <em>plist</em>, unsigned + <em>aggression</em>)</code> + </dt><dd>The deflate compression method is added to the end of the + permanent or transient filter pipeline depending on whether + <em>plist</em> is a dataset creation or dataset transfer + property list. The <em>aggression</em> is a number between + zero and nine (inclusive) to indicate the tradeoff between + speed and compression ratio (zero is fastest, nine is best + ratio). + </dd></dl> + + <p>Even if the <code>zlib</code> isn't detected during + configuration the application can define + <code>H5Z_FILTER_DEFLATE</code> as a permanent filter. If the + filter is marked as optional (as with + <code>H5Pset_deflate()</code>) then it will always fail and be + automatically removed from the pipeline. Applications that read + data will fail only if the data is actually compressed; they + won't fail if <code>H5Z_FILTER_DEFLATE</code> was part of the + permanent output pipeline but was automatically excluded because + it didn't exist when the data was written. + + </p><p><code>zlib</code> can be acquired from + <code><a href="http://www.cdrom.com/pub/infozip/zlib/"> + http://www.cdrom.com/pub/infozip/zlib/</a></code>. + + </p><h2>Example</h2> + + <p>This example shows how to define and register a simple filter + that adds a checksum capability to the data stream. + + </p><p>The function that acts as the filter always returns zero + (failure) if the <code>md5()</code> function was not detected at + configuration time (left as an exercise for the reader). + Otherwise the function is broken down to an input and output + half. The output half calculates a checksum, increases the size + of the output buffer if necessary, and appends the checksum to + the end of the buffer. The input half calculates the checksum + on the first part of the buffer and compares it to the checksum + already stored at the end of the buffer. If the two differ then + zero (failure) is returned, otherwise the buffer size is reduced + to exclude the checksum. + + </p> + <table> + <tbody><tr> + <td> + <p><code></code></p><pre><code> + size_t + md5_filter(unsigned int flags, size_t cd_nelmts, + const unsigned int cd_values[], size_t nbytes, + size_t *buf_size, void **buf) + { + #ifdef HAVE_MD5 + unsigned char cksum[16]; + + if (flags & H5Z_REVERSE) { + /* Input */ + assert(nbytes>=16); + md5(nbytes-16, *buf, cksum); + + /* Compare */ + if (memcmp(cksum, (char*)(*buf)+nbytes-16, 16)) { + return 0; /*fail*/ + } + + /* Strip off checksum */ + return nbytes-16; + + } else { + /* Output */ + md5(nbytes, *buf, cksum); + + /* Increase buffer size if necessary */ + if (nbytes+16>*buf_size) { + *buf_size = nbytes + 16; + *buf = realloc(*buf, *buf_size); + } + + /* Append checksum */ + memcpy((char*)(*buf)+nbytes, cksum, 16); + return nbytes+16; + } + #else + return 0; /*fail*/ + #endif + } + </code></pre> + </td> + </tr> + </tbody></table> + + <p>Once the filter function is defined it must be registered so + the HDF5 library knows about it. Since we're testing this + filter we choose one of the <code>H5Z_filter_t</code> numbers + from the reserved range. We'll randomly choose 305. + + </p><p> + </p> + <table> + <tbody><tr> + <td> + <p><code></code></p><pre><code> + #define FILTER_MD5 305 + herr_t status = H5Zregister(FILTER_MD5, "md5 checksum", md5_filter); + </code></pre> + </td> + </tr> + </tbody></table> + + <p>Now we can use the filter in a pipeline. We could have added + the filter to the pipeline before defining or registering the + filter as long as the filter was defined and registered by time + we tried to use it (if the filter is marked as optional then we + could have used it without defining it and the library would + have automatically removed it from the pipeline for each chunk + written before the filter was defined and registered). + + </p><p> + </p> + <table> + <tbody><tr> + <td> + <p><code></code></p><pre><code> + hid_t dcpl = H5Pcreate(H5P_DATASET_CREATE); + hsize_t chunk_size[3] = {10,10,10}; + H5Pset_chunk(dcpl, 3, chunk_size); + H5Pset_filter(dcpl, FILTER_MD5, 0, 0, NULL); + hid_t dset = H5Dcreate(file, "dset", H5T_NATIVE_DOUBLE, space, dcpl); + </code></pre> + </td> + </tr> + </tbody></table> + + <h2>6. Filter Diagnostics</h2> + + <p>If the library is compiled with debugging turned on for the H5Z + layer (usually as a result of <code>configure + --enable-debug=z</code>) then filter statistics are printed when + the application exits normally or the library is closed. The + statistics are written to the standard error stream and include + two lines for each filter that was used: one for input and one + for output. The following fields are displayed: + + </p><p> + </p> + <table> + <tbody><tr> + <th>Field Name</th> + <th>Description</th> + </tr> + + <tr valign="top"> + <td>Method</td> + <td>This is the name of the method as defined with + <code>H5Zregister()</code> with the characters + "< or ">" prepended to indicate + input or output.</td> + </tr> + + <tr valign="top"> + <td>Total</td> + <td>The total number of bytes processed by the filter + including errors. This is the maximum of the + <em>nbytes</em> argument or the return value. + </td></tr> + + <tr valign="top"> + <td>Errors</td> + <td>This field shows the number of bytes of the Total + column which can be attributed to errors.</td> + </tr> + + <tr valign="top"> + <td>User, System, Elapsed</td> + <td>These are the amount of user time, system time, and + elapsed time in seconds spent in the filter function. + Elapsed time is sensitive to system load. These times + may be zero on operating systems that don't support the + required operations.</td> + </tr> + + <tr valign="top"> + <td>Bandwidth</td> + <td>This is the filter bandwidth which is the total + number of bytes processed divided by elapsed time. + Since elapsed time is subject to system load the + bandwidth numbers cannot always be trusted. + Furthermore, the bandwidth includes bytes attributed to + errors which may significanly taint the value if the + function is able to detect errors without much + expense.</td> + </tr> + </tbody></table> + + <p> + </p> + <table> + <caption align="bottom"> + <b>Example: Filter Statistics</b> + </caption> + <tbody><tr> + <td> + <p><code></code></p><pre><code>H5Z: filter statistics accumulated ov= + er life of library: + Method Total Errors User System Elapsed Bandwidth + ------ ----- ------ ---- ------ ------- --------- + >deflate 160000 40000 0.62 0.74 1.33 117.5 kBs + <deflate 120000 0 0.11 0.00 0.12 1.000 MBs + </code></pre> + </td> + </tr> + </tbody></table> + + <hr> + + + <p><a name="fn1">Footnote 1:</a> Dataset chunks can be compressed + through the use of filters. Developers should be aware that + reading and rewriting compressed chunked data can result in holes + in an HDF5 file. In time, enough such holes can increase the + file size enough to impair application or library performance + when working with that file. See + <a href="https://support.hdfgroup.org/HDF5/doc1.6/Performance.html#Freespace"> + Freespace Management</a> + in the chapter + <a href="https://support.hdfgroup.org/HDF5/doc1.6/Performance.html"> + Performance Analysis and Issues</a>.</p> +</html> diff --git a/doxygen/examples/H5.format.1.0.html b/doxygen/examples/H5.format.1.0.html index 2d3ffbe..d2b6610 100644 --- a/doxygen/examples/H5.format.1.0.html +++ b/doxygen/examples/H5.format.1.0.html @@ -10,12 +10,12 @@ <table border=0 width=90%> <tr> <td valign=top> - <ol type=I> + <ol type="I"> <li><a href="#Intro">Introduction</a> <li><a href="#BootBlock">Disk Format Level 0 - File Signature and Super Block</a> <li><a href="#Group">Disk Format Level 1 - File Infrastructure</a> <font size=-2> - <ol type=A> + <ol type="A"> <li><a href="#Btrees">Disk Format Level 1A - B-link Trees and B-tree Nodes</a> <li><a href="#SymbolTable">Disk Format Level 1B - Group</a> <li><a href="#SymbolTableEntry">Disk Format Level 1C - Group Entry</a> @@ -26,9 +26,9 @@ </font> <li><a href="#DataObject">Disk Format Level 2 - Data Objects</a> <font size=-2> - <ol type=A> + <ol type="A"> <li><a href="#ObjectHeader">Disk Format Level 2a - Data Object Headers</a> - <ol type=1> + <ol type="1"> <li><a href="#NILMessage">Name: NIL</a> <!-- 0x0000 --> <li><a href="#SimpleDataSpace">Name: Simple Dataspace</a> <!-- 0x0001 --> <!-- @@ -41,13 +41,13 @@ </font> </ol> </td><td> </td><td valign=top> - <ol type=I> + <ol type="I" start="4"> <li><a href="#DataObject">Disk Format Level 2 - Data Objects</a> <font size=-2><i>(Continued)</i> - <ol type=A> + <ol type="A"> <li><a href="#ObjectHeader">Disk Format Level 2a - Data Object Headers</a><i>(Continued)</i> - <ol type=1> + <ol type="1" start="6"> <li><a href="#CompactDataStorageMessage">Name: Data Storage - Compact</a> <!-- 0x0006 --> <li><a href="#ExternalFileListMessage">Name: Data Storage - External Data Files</a> <!-- 0x0007 --> <li><a href="#LayoutMessage">Name: Data Storage - Layout</a> <!-- 0x0008 --> @@ -495,7 +495,7 @@ Elena> "Free-space object" <td>End of File Address</td> <td>This is the relative file address of the first byte past the end of all HDF5 data. It is used to determine whether a - file has been accidently truncated and as an address where + file has been accidentally truncated and as an address where file data allocation can occur if the free list is not used.</td> </tr> @@ -2414,7 +2414,7 @@ Elena> "Free-space object" <td><b>Normalization.</b> The value can be 0 if there is no normalization, 1 if the most significant bit of the mantissa is always set (except for 0.0), and 2 if the most - signficant bit of the mantissa is not stored but is + significant bit of the mantissa is not stored but is implied to be set. The value 3 is reserved and will not appear in this field.</td> </tr> @@ -2916,7 +2916,7 @@ Elena> "Free-space object" <p>The fill value message stores a single data point value which is returned to the application when an uninitialized data point - is read from the dataset. The fill value is interpretted with + is read from the dataset. The fill value is interpreted with the same datatype as the dataset. If no fill value message is present then a fill value of all zero is assumed. @@ -3327,7 +3327,7 @@ Elena> "Free-space object" <p> <center> - <table border align=center cellpadding=4 witdh="80%"> + <table border align=center cellpadding=4 width="80%"> <caption align=top> <b>Filter Pipeline Message</b> </caption> @@ -3386,7 +3386,7 @@ Elena> "Free-space object" <p> <center> - <table border align=center cellpadding=4 witdh="80%"> + <table border align=center cellpadding=4 width="80%"> <caption align=top> <b>Filter Pipeline Message</b> </caption> diff --git a/doxygen/examples/H5.format.1.1.html b/doxygen/examples/H5.format.1.1.html index ebbbe8e..b91ac90 100644 --- a/doxygen/examples/H5.format.1.1.html +++ b/doxygen/examples/H5.format.1.1.html @@ -36,18 +36,18 @@ TABLE.list TD { border:none; } <table border=0 width=90%> <tr> <td valign=top> - <ol type=I> + <ol type="I"> <li><a href="#Intro">Introduction</a> <li><a href="#FileMetaData">Disk Format Level 0 - File Metadata</a> <font size=-2> - <ol type=A> + <ol type="A"> <li><a href="#SuperBlock">Disk Format Level 0A - File Signature and Super Block</a> <li><a href="#DriverInfo">Disk Format Level 0B - File Driver Info</a> </ol> </font> <li><a href="#FileInfra">Disk Format Level 1 - File Infrastructure</a> <font size=-2> - <ol type=A> + <ol type="A"> <li><a href="#Btrees">Disk Format Level 1A - B-link Trees and B-tree Nodes</a> <li><a href="#SymbolTable">Disk Format Level 1B - Group</a> <li><a href="#SymbolTableEntry">Disk Format Level 1C - Group Entry</a> @@ -58,9 +58,9 @@ TABLE.list TD { border:none; } </font> <li><a href="#DataObject">Disk Format Level 2 - Data Objects</a> <font size=-2> - <ol type=A> + <ol type="A"> <li><a href="#ObjectHeader">Disk Format Level 2a - Data Object Headers</a> - <ol type=1> + <ol type="1"> <li><a href="#NILMessage">Name: NIL</a> <!-- 0x0000 --> <li><a href="#SimpleDataSpace">Name: Simple Dataspace</a> <!-- 0x0001 --> <!-- <li><a href="#DataSpaceMessage">Name: Complex Dataspace</a> --> <!-- 0x0002 --> @@ -73,13 +73,13 @@ TABLE.list TD { border:none; } </font> </ol> </td><td> </td><td valign=top> - <ol type=I start=4> + <ol type="I" start="4"> <li><a href="#DataObject">Disk Format Level 2 - Data Objects</a> <font size=-2><i>(Continued)</i> <ol type=A> <li><a href="#ObjectHeader">Disk Format Level 2a - Data Object Headers</a><i>(Continued)</i> - <ol type=1 start=6> + <ol type="1" start="7"> <!-- <li><a href="#CompactDataStorageMessage">Name: Data Storage - Compact</a> --> <!-- 0x0006 --> <li><a href="#ReservedMessage_0006">Name: Reserved - not assigned yet</a> <!-- 0x0006 --> <li><a href="#ExternalFileListMessage">Name: Data Storage - External Data Files</a> <!-- 0x0007 --> @@ -616,7 +616,7 @@ TABLE.list TD { border:none; } <td> <P>This is the absolute file address of the first byte past the end of all HDF5 data. It is used to determine whether a - file has been accidently truncated and as an address where + file has been accidentally truncated and as an address where file data allocation can occur if space from the free list is not used. </P> @@ -3184,7 +3184,7 @@ TABLE.list TD { border:none; } <td><b>Normalization.</b> The value can be 0 if there is no normalization, 1 if the most significant bit of the mantissa is always set (except for 0.0), and 2 if the most - signficant bit of the mantissa is not stored but is + significant bit of the mantissa is not stored but is implied to be set. The value 3 is reserved and will not appear in this field.</td> </tr> diff --git a/doxygen/examples/H5.format.2.0.html b/doxygen/examples/H5.format.2.0.html index 3653489..4a5fe37 100644 --- a/doxygen/examples/H5.format.2.0.html +++ b/doxygen/examples/H5.format.2.0.html @@ -821,7 +821,7 @@ II.A. Disk Format: Level 0A - Format Signature and Superblock</a></h3> <td> <p>This is the absolute file address of the first byte past the end of all HDF5 data. It is used to determine whether a - file has been accidently truncated and as an address where + file has been accidentally truncated and as an address where file data allocation can occur if space from the free list is not used. </p> @@ -4910,7 +4910,7 @@ III.F. Disk Format: Level 1F - Fractal Heap</a></h3> enough to store objects greater than 16 bytes or not. If the heap ID length is 18 bytes or smaller, the ‘normal’ tiny heap ID form is used. If the heap ID length is greater than 18 bytes in - length, the “extented” form is used. See format description below + length, the “extended” form is used. See format description below for both sub-types. </p> </td> @@ -7884,7 +7884,7 @@ IV.A.2. Disk Format: Level 2A2 - Data Object Header Messages</a></h3> <tr> <td align="center"><code>3</code></td> - <td>Message stored is not shared, but is sharable. + <td>Message stored is not shared, but is shareable. </td> </tr> diff --git a/doxygen/examples/H5.format.html b/doxygen/examples/H5.format.html index e16805f..cbcb387 100644 --- a/doxygen/examples/H5.format.html +++ b/doxygen/examples/H5.format.html @@ -936,7 +936,7 @@ <td> <p>This is the absolute file address of the first byte past the end of all HDF5 data. It is used to determine whether a - file has been accidently truncated and as an address where + file has been accidentally truncated and as an address where file data allocation can occur if space from the free list is not used. </p> @@ -8691,7 +8691,7 @@ three rows are needed. <tr> <td align="center"><code>3</code></td> - <td>Message stored is not shared, but is sharable. + <td>Message stored is not shared, but is shareable. </td> </tr> @@ -20202,7 +20202,7 @@ disk address for the chunk.</p> </tr> <tr> - <td><p>Length fo External File Name</p></td> + <td><p>Length of External File Name</p></td> <td><p>This is the length for the external file name. <p>This field exists if bit 0 of <em>flags</em> is set.</p> </p> diff --git a/doxygen/examples/H5E_examples.c b/doxygen/examples/H5E_examples.c new file mode 100644 index 0000000..deea838 --- /dev/null +++ b/doxygen/examples/H5E_examples.c @@ -0,0 +1,97 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <assert.h> +#include <stdio.h> +#include <stdlib.h> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [create] --> + { + __label__ fail_push, fail_minor, fail_major, fail_class; + hid_t cls, major, minor; + + // register a new error class for this "application" + if ((cls = H5Eregister_class("Custom error class", "H5E_examples", "0.1")) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_class; + } + + // create custom major and minor error codes + if ((major = H5Ecreate_msg(cls, H5E_MAJOR, "Okay, Houston, we've had a problem here")) == + H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_major; + } + if ((minor = H5Ecreate_msg(cls, H5E_MINOR, "Oops!")) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_minor; + } + + // push a custom error message onto the default stack + if (H5Epush2(H5E_DEFAULT, __FILE__, __FUNCTION__, __LINE__, cls, major, minor, "Hello, Error!\n") < + 0) { + ret_val = EXIT_FAILURE; + goto fail_push; + } + + // print the default error stack + if (H5Eprint(H5E_DEFAULT, stderr) < 0) { + ret_val = EXIT_FAILURE; + } + +fail_push: + H5Eclose_msg(minor); +fail_minor: + H5Eclose_msg(major); +fail_major: + H5Eunregister_class(cls); +fail_class:; + } + //! <!-- [create] --> + + //! <!-- [read] --> + { + __label__ fail_count; + + // check the number of error messages on the default stack + // and print what's there + ssize_t count = H5Eget_num(H5E_DEFAULT); + if (count < 0) { + ret_val = EXIT_FAILURE; + goto fail_count; + } + else if (H5Eprint(H5E_DEFAULT, stderr) < 0) { + ret_val = EXIT_FAILURE; + } + +fail_count:; + } + //! <!-- [read] --> + + //! <!-- [update] --> + { + // pop 10 error messages off the default error stack + // popping off non-existent messages is OK, but might be confusing + if (H5Epop(H5E_DEFAULT, 10) < 0) + ret_val = EXIT_FAILURE; + } + //! <!-- [update] --> + + //! <!-- [delete] --> + { + // clear the default error stack (for the current thread) + if (H5Eclear2(H5E_DEFAULT) < 0) + ret_val = EXIT_FAILURE; + } + //! <!-- [delete] --> + + assert(ret_val == EXIT_SUCCESS); + + return ret_val; +} diff --git a/doxygen/examples/H5G_examples.c b/doxygen/examples/H5G_examples.c new file mode 100644 index 0000000..3109efb --- /dev/null +++ b/doxygen/examples/H5G_examples.c @@ -0,0 +1,186 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <assert.h> +#include <stdio.h> +#include <stdlib.h> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [create] --> + { + __label__ fail_group, fail_prop, fail_lcpl, fail_file; + hid_t file, lcpl, group; + char fname[] = "g1.h5"; + char path[] = "/αυτή/είναι/μια/νέα/ομάδα"; + + if ((file = H5Fcreate(fname, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + + if ((lcpl = H5Pcreate(H5P_LINK_CREATE)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_lcpl; + } + // ensure that intermediate groups are created automatically + if (H5Pset_create_intermediate_group(lcpl, 1) < 0) { + ret_val = EXIT_FAILURE; + goto fail_prop; + } + // use UTF-8 encoding for link names + if (H5Pset_char_encoding(lcpl, H5T_CSET_UTF8) < 0) { + ret_val = EXIT_FAILURE; + goto fail_prop; + } + // create five groups + if ((group = H5Gcreate(file, path, lcpl, H5P_DEFAULT, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_group; + } + + H5Gclose(group); +fail_group: +fail_prop: + H5Pclose(lcpl); +fail_lcpl: + H5Fclose(file); +fail_file:; + } + //! <!-- [create] --> + + //! <!-- [read] --> + { + __label__ fail_file; + char fname[] = "g1.h5"; + char path[] = "/αυτή/είναι"; + hid_t file; + H5G_info_t info; + + if ((file = H5Fopen(fname, H5F_ACC_RDONLY, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + // open one of the intermediate groups + if (H5Gget_info_by_name(file, path, &info, H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + goto fail_info; + } + + printf("Link count: %llu\n", info.nlinks); + switch (info.storage_type) { + case H5G_STORAGE_TYPE_COMPACT: + printf("Compact storage\n"); + break; + case H5G_STORAGE_TYPE_DENSE: + printf("Compact storage\n"); + break; + case H5G_STORAGE_TYPE_SYMBOL_TABLE: + printf("Symbol table\n"); + break; + default: + printf("UFO\n"); + break; + } + +fail_info: + H5Fclose(file); +fail_file:; + } + //! <!-- [read] --> + + //! <!-- [update] --> + { + __label__ fail_group, fail_prop, fail_lcpl, fail_file; + hid_t file, lcpl, group; + char fname[] = "g1.h5"; + char path[] = "/αυτή/είναι/μια/άλλη/νέα/ομάδα"; + + if ((file = H5Fopen(fname, H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + + if ((lcpl = H5Pcreate(H5P_LINK_CREATE)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_lcpl; + } + // ensure that intermediate groups are created automatically + if (H5Pset_create_intermediate_group(lcpl, 1) < 0) { + ret_val = EXIT_FAILURE; + goto fail_prop; + } + // use UTF-8 encoding for link names + if (H5Pset_char_encoding(lcpl, H5T_CSET_UTF8) < 0) { + ret_val = EXIT_FAILURE; + goto fail_prop; + } + // create an anonymous group + if ((group = H5Gcreate_anon(file, H5P_DEFAULT, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_group; + } + // link the new group to existing the group at "/αυτή/είναι/μια" + if (H5Lcreate_hard(group, ".", file, path, lcpl, H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + } + + H5Gclose(group); +fail_group: +fail_prop: + H5Pclose(lcpl); +fail_lcpl: + H5Fclose(file); +fail_file:; + } + //! <!-- [update] --> + + //! <!-- [delete] --> + { + __label__ fail_info, fail_object, fail_file; + hid_t file, obj; + char fname[] = "g1.h5"; + char path[] = "/αυτή/είναι/μια/άλλη/νέα/ομάδα"; + char delete_path[] = "/αυτή/είναι/μια"; + H5O_info_t info; + + if ((file = H5Fopen(fname, H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + + // open a "leaf" group as object + if ((obj = H5Oopen(file, path, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_object; + } + // delete the link to an intermediate group on the path to the leaf + if (H5Ldelete(file, delete_path, H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + } + // link deletion will propagate along hard links along all paths + // reachable from the intermediate group and cause reference counts to + // be decremented, freeing the objects if the count reaches 0 + if (H5Oget_info(obj, &info, H5O_INFO_BASIC) < 0) { + ret_val = EXIT_FAILURE; + goto fail_info; + } + + printf("Leaf reference count: %d\n", info.rc); + +fail_info: + H5Oclose(obj); +fail_object: + H5Fclose(file); +fail_file:; + } + //! <!-- [delete] --> + + assert(ret_val == EXIT_SUCCESS); + + return ret_val; +} diff --git a/doxygen/examples/H5I_examples.c b/doxygen/examples/H5I_examples.c new file mode 100644 index 0000000..4aa4783 --- /dev/null +++ b/doxygen/examples/H5I_examples.c @@ -0,0 +1,242 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <assert.h> +#include <stdio.h> +#include <stdlib.h> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [create] --> + { + __label__ fail_dcpl; + hid_t dcpl; + + // create an ID of a pre-defined ID type + if ((dcpl = H5Pcreate(H5P_DATASET_XFER)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dcpl; + } + + // we can reliably predict the ID type + assert(H5Iget_type(dcpl) == H5I_GENPROP_LST); + printf("%d\n", H5Iget_type(dcpl)); + + H5Pclose(dcpl); +fail_dcpl:; + } + //! <!-- [create] --> + + //! <!-- [read] --> + { + __label__ fail_dcpl; + hid_t dcpl; + + // create an ID of a pre-defined ID type + if ((dcpl = H5Pcreate(H5P_DATASET_XFER)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dcpl; + } + + // this better be valid + assert(H5Iis_valid(dcpl) > 0); + + // this ID is NOT associated with any HDF5 file; + // see the error message + assert(H5Iget_file_id(dcpl) == H5I_INVALID_HID); + + H5Pclose(dcpl); +fail_dcpl:; + } + //! <!-- [read] --> + + //! <!-- [update] --> + { + __label__ fail_rc, fail_dcpl; + hid_t dcpl; + int rc; + + // create an ID of a pre-defined ID type + if ((dcpl = H5Pcreate(H5P_DATASET_XFER)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dcpl; + } + + // retrieve the IDs reference count + if ((rc = H5Iget_ref(dcpl)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_rc; + } + printf("Reference count: %d\n", rc); + + // bump its reference count (by 1) + if ((rc = H5Iinc_ref(dcpl)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_rc; + } + printf("Reference count: %d\n", rc); + +fail_rc: + H5Pclose(dcpl); +fail_dcpl:; + } + //! <!-- [update] --> + + //! <!-- [delete] --> + { + __label__ fail_rc, fail_dcpl; + hid_t dcpl; + int rc; + + // create an ID of a pre-defined ID type + if ((dcpl = H5Pcreate(H5P_DATASET_XFER)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dcpl; + } + + // decrease its reference count (from 1) to 0 + if ((rc = H5Idec_ref(dcpl)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_rc; + } + printf("Reference count: %d\n", rc); + + // at this point, the ID is no longer valid + assert(H5Iis_valid(dcpl) == 0); + + // dropping the ref. count to 0 has the side-effect of closing + // the associated item, and calling H5Pclose would create an error + goto fail_dcpl; + +fail_rc: + H5Pclose(dcpl); +fail_dcpl:; + } + //! <!-- [delete] --> + + //! <!-- [create_ud] --> + herr_t free_func(void *obj) + { + printf("Calling free_func...\n"); + H5free_memory(obj); + return 0; + } + + { + __label__ fail_id, fail_obj, fail_register; + H5I_type_t type; + int * obj; + hid_t obj_id; + + // register a new ID type + if ((type = H5Iregister_type(128, 1024, &free_func)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_register; + } + printf("New identifier type ID: %d\n", type); + + // create a new object + if ((obj = H5allocate_memory(10 * sizeof(int), 0)) == NULL) { + ret_val = EXIT_FAILURE; + goto fail_obj; + } + + // obtain an ID for the new object + if ((obj_id = H5Iregister(type, obj)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_id; + } + printf("New object identifier: %ld\n", obj_id); + +fail_id: + H5Iclear_type(type, 1); +fail_obj: + H5Idestroy_type(type); +fail_register:; + } + //! <!-- [create_ud] --> + + //! <!-- [read_ud] --> + { + __label__ fail_query, fail_register; + H5I_type_t type; + hsize_t count; + + // register a new ID type + if ((type = H5Iregister_type(128, 1024, NULL)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_register; + } + printf("New FOO identifier type ID: %d\n", type); + + // return the number of identifiers of TYPE currently in use + if (H5Inmembers(type, &count) < 0) { + ret_val = EXIT_FAILURE; + goto fail_query; + } + printf("%llu FOO identifiers in use\n", count); + +fail_query: + H5Idestroy_type(type); +fail_register:; + } + //! <!-- [read_ud] --> + + //! <!-- [update_ud] --> + { + __label__ fail_id, fail_register; + H5I_type_t type; + int obj = 42; + hid_t obj_id; + + // register a new ID type + if ((type = H5Iregister_type(128, 1024, NULL)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_register; + } + printf("New identifier type ID: %d\n", type); + + // obtain an ID for the new object + if ((obj_id = H5Iregister(type, &obj)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_id; + } + printf("New object identifier: %ld\n", obj_id); + + // bump the reference count + assert(H5Iinc_ref(obj_id) == 2); + + // force the deletion of all IDs regardless of reference count + H5Iclear_type(type, 1); +fail_id: + H5Idestroy_type(type); +fail_register:; + } + //! <!-- [update_ud] --> + + //! <!-- [delete_ud] --> + { + __label__ fail_register; + H5I_type_t type; + + // register a new ID type + if ((type = H5Iregister_type(128, 1024, NULL)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_register; + } + printf("New identifier type ID: %d\n", type); + + // decrementing the identifier type's ref. count to 0 triggers + // the type to be destroyed + assert(H5Idec_type_ref(type) == 0); + +fail_register:; + } + //! <!-- [delete_ud] --> + + return ret_val; +} diff --git a/doxygen/examples/H5L_examples.c b/doxygen/examples/H5L_examples.c new file mode 100644 index 0000000..63f54fe --- /dev/null +++ b/doxygen/examples/H5L_examples.c @@ -0,0 +1,156 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <assert.h> +#include <stdio.h> +#include <stdlib.h> + +//! <!-- [iter_cb] --> +herr_t +iter_cb(hid_t group, const char *name, const H5L_info_t *info, void *op_data) +{ + printf("Link \"%s\" is a", name); + switch (info->type) { + case H5L_TYPE_HARD: + printf(" hard link.\n"); + break; + case H5L_TYPE_SOFT: + printf(" soft link.\n"); + break; + case H5L_TYPE_EXTERNAL: + printf("n external link.\n"); + break; + default: + printf(" UFO link.\n"); + break; + } + + return 0; +} +//! <!-- [iter_cb] --> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [create] --> + { + __label__ fail_link, fail_prop, fail_lcpl, fail_create; + + hid_t file, lcpl; + + if ((file = H5Fcreate("l1.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_create; + } + + // make link creation easier by auto-creating intermediate + // groups and UTF-8 encoding of link names + if ((lcpl = H5Pcreate(H5P_LINK_CREATE)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_lcpl; + } + if (H5Pset_create_intermediate_group(lcpl, 1) < 0 || H5Pset_char_encoding(lcpl, H5T_CSET_UTF8) < 0) { + ret_val = EXIT_FAILURE; + goto fail_prop; + } + + // create a loop by hard linking the root group + if (H5Lcreate_hard(file, ".", file, "√", lcpl, H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + goto fail_link; + } + // create a soft link to nowhere + if (H5Lcreate_soft("e1 62 80 87 04 09 43 ba 02 d3", file, "/path/to/nowhere", lcpl, H5P_DEFAULT) < + 0) { + ret_val = EXIT_FAILURE; + goto fail_link; + } + // create an external link to nowhere in a non-existent file + if (H5Lcreate_external("non-existent-file.h5", "???", file, "external", lcpl, H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + goto fail_link; + } + +fail_link: +fail_prop: + H5Pclose(lcpl); +fail_lcpl: + H5Fclose(file); +fail_create:; + } + //! <!-- [create] --> + + //! <!-- [read] --> + { + __label__ fail_iterate, fail_read; + hid_t file; + hsize_t idx = 0; + + if ((file = H5Fopen("l1.h5", H5F_ACC_RDONLY, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_read; + } + + if (H5Literate(file, H5_INDEX_NAME, H5_ITER_NATIVE, &idx, iter_cb, NULL) < 0) { + ret_val = EXIT_FAILURE; + goto fail_iterate; + } + +fail_iterate: + H5Fclose(file); +fail_read:; + } + //! <!-- [read] --> + + //! <!-- [update] --> + { + __label__ fail_move, fail_update; + hid_t file; + + if ((file = H5Fopen("l1.h5", H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_update; + } + + // move the "√" link to the group at "/path/to" + // the cycle remains! + if (H5Lmove(file, "√", file, "path/to/√", H5P_DEFAULT, H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + goto fail_move; + } + +fail_move: + H5Fclose(file); +fail_update:; + } + //! <!-- [update] --> + + //! <!-- [delete] --> + { + __label__ fail_delete, fail_file; + hid_t file; + + if ((file = H5Fopen("l1.h5", H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + + // delete the "external" link + if (H5Ldelete(file, "external", H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + goto fail_delete; + } + +fail_delete: + H5Fclose(file); +fail_file:; + } + //! <!-- [delete] --> + + assert(ret_val == EXIT_SUCCESS); + + return ret_val; +} diff --git a/doxygen/examples/H5O_examples.c b/doxygen/examples/H5O_examples.c new file mode 100644 index 0000000..296acd1 --- /dev/null +++ b/doxygen/examples/H5O_examples.c @@ -0,0 +1,193 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <stdio.h> +#include <stdlib.h> + +#define H5P_DEFAULTx2 H5P_DEFAULT, H5P_DEFAULT + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [create] --> + { + __label__ fail_file; + hid_t file, group; + char src_path[] = "/a/few/groups"; + + if ((file = H5Fcreate("o1.h5", H5F_ACC_TRUNC, H5P_DEFAULTx2)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + + // create a few groups + { + __label__ fail_group, fail_lcpl; + hid_t lcpl; + if ((lcpl = H5Pcreate(H5P_LINK_CREATE)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_lcpl; + } + if (H5Pset_create_intermediate_group(lcpl, 1) < 0) { + ret_val = EXIT_FAILURE; + goto fail_group; + } + if ((group = H5Gcreate(file, src_path, lcpl, H5P_DEFAULTx2)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_group; + } + + H5Gclose(group); +fail_group: + H5Pclose(lcpl); +fail_lcpl:; + } + + // create a copy + if (H5Ocopy(file, ".", file, "copy of", H5P_DEFAULTx2) < 0) { + ret_val = EXIT_FAILURE; + } + + H5Fclose(file); +fail_file:; + } + //! <!-- [create] --> + + //! <!-- [read] --> + { + __label__ fail_info, fail_file; + hid_t file; + char path[] = "/a/few/groups"; + H5O_info2_t info; + + if ((file = H5Fopen("o1.h5", H5F_ACC_RDONLY, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + + // retrieve information about the object + if (H5Oget_info_by_name(file, path, &info, H5O_INFO_BASIC | H5O_INFO_NUM_ATTRS, H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + goto fail_info; + } + + // determine the object type + switch (info.type) { + case H5O_TYPE_GROUP: + printf("HDF5 group\n"); + break; + case H5O_TYPE_DATASET: + printf("HDF5 dataset\n"); + break; + case H5O_TYPE_NAMED_DATATYPE: + printf("HDF5 datatype\n"); + break; + default: + printf("UFO?\n"); + break; + } + // print basic information + printf("Reference count: %u\n", info.rc); + printf("Attribute count: %lld\n", info.num_attrs); + +fail_info: + H5Fclose(file); +fail_file:; + } + //! <!-- [read] --> + + //! <!-- [update] --> + { + __label__ fail_obj, fail_incr, fail_file; + hid_t file, obj; + char path[] = "/a/few/groups"; + H5O_info2_t info; + + if ((file = H5Fopen("o1.h5", H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + + // open an object by path name + if ((obj = H5Oopen(file, path, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_obj; + } + + // bump its reference count (by 1) + if (H5Oincr_refcount(obj) < 0) { + ret_val = EXIT_FAILURE; + goto fail_incr; + } + + // confirm the new reference count + if (H5Oget_info(obj, &info, H5O_INFO_BASIC) < 0) { + ret_val = EXIT_FAILURE; + goto fail_incr; + } + printf("Reference count: %u\n", info.rc); + +fail_incr: + H5Oclose(obj); +fail_obj: + H5Fclose(file); +fail_file:; + } + //! <!-- [update] --> + + //! <!-- [delete] --> + { + __label__ fail_obj, fail_delete, fail_file; + hid_t file, obj; + char path[] = "/a/few/groups"; + H5O_info2_t info; + + if ((file = H5Fopen("o1.h5", H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + + // open an object by path name + if ((obj = H5Oopen(file, path, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_obj; + } + + // render it inaccessible from the root group by deleting the one and + // only link to it; this drops the reference count by 1 + if (H5Ldelete(file, path, H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + goto fail_delete; + } + + // confirm the new reference count + if (H5Oget_info(obj, &info, H5O_INFO_BASIC) < 0) { + ret_val = EXIT_FAILURE; + goto fail_delete; + } + printf("Reference count: %u\n", info.rc); + + // if we close the file at this point, we'd be creating a tombstone, + // an object that cannot be reached and that cannot be reclaimed by the + // freespace manager; decrement the reference count to zero to prevent that + if (H5Idec_ref(obj) < 0) { + ret_val = EXIT_FAILURE; + goto fail_delete; + } + else + // attempting to close the object would be like a double H5Oclose and fail + goto fail_obj; + +fail_delete: + H5Oclose(obj); +fail_obj: + H5Fclose(file); +fail_file:; + } + //! <!-- [delete] --> + + return ret_val; +} diff --git a/doxygen/examples/H5PL_examples.c b/doxygen/examples/H5PL_examples.c new file mode 100644 index 0000000..e27b432 --- /dev/null +++ b/doxygen/examples/H5PL_examples.c @@ -0,0 +1,96 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <stdio.h> +#include <stdlib.h> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [create] --> + { + __label__ fail_set; + // enable ONLY filter plugins + if (H5PLset_loading_state(H5PL_FILTER_PLUGIN) < 0) { + ret_val = EXIT_FAILURE; + goto fail_set; + } + + // ensure that "/tmp" is at the front of the search path list + if (H5PLprepend("/tmp") < 0) { + ret_val = EXIT_FAILURE; + } + +fail_set:; + } + //! <!-- [create] --> + + //! <!-- [read] --> + { + __label__ fail_read; + unsigned size, mask; + char buf[255]; + + // retrieve the number of entries in the plugin path list + if (H5PLsize(&size) < 0) { + ret_val = EXIT_FAILURE; + goto fail_read; + } + printf("Number of stored plugin paths: %d\n", size); + + // check the plugin state mask + if (H5PLget_loading_state(&mask) < 0) { + ret_val = EXIT_FAILURE; + goto fail_read; + } + printf("Filter plugins %s be loaded.\n", (mask & H5PL_FILTER_PLUGIN) == 1 ? "can" : "can't"); + + // print the paths in the plugin path list + for (unsigned i = 0; i < size; ++i) { + if (H5PLget(i, buf, 255) < 0) { + ret_val = EXIT_FAILURE; + break; + } + printf("%s\n", buf); + } + +fail_read:; + } + //! <!-- [read] --> + + //! <!-- [update] --> + { + // replace "/tmp" with something more sensible + if (H5PLreplace("/foo/bar", 0) < 0) { + ret_val = EXIT_FAILURE; + } + } + //! <!-- [update] --> + + //! <!-- [delete] --> + { + __label__ fail_delete; + unsigned size; + + if (H5PLsize(&size) < 0) { + ret_val = EXIT_FAILURE; + goto fail_delete; + } + + // clean out the list of plugin paths + for (int i = size - 1; i >= 0; --i) { + if (H5PLremove(i) < 0) { + ret_val = EXIT_FAILURE; + break; + } + } + +fail_delete:; + } + //! <!-- [delete] --> + + return ret_val; +} diff --git a/doxygen/examples/H5P_examples.c b/doxygen/examples/H5P_examples.c new file mode 100644 index 0000000..cdfc03b --- /dev/null +++ b/doxygen/examples/H5P_examples.c @@ -0,0 +1,227 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <assert.h> +#include <stdio.h> +#include <stdlib.h> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [create] --> + { + __label__ fail_dcpl; + hid_t dcpl; + + // every property list is created as an instance of a suitable + // property list class + if ((dcpl = H5Pcreate(H5P_DATASET_CREATE)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dcpl; + } + + // ... + + H5Pclose(dcpl); +fail_dcpl:; + } + //! <!-- [create] --> + + //! <!-- [read] --> + { + __label__ fail_dcpl, fail_plist_cls_id; + hid_t dcpl, plist_cls_id; + + if ((dcpl = H5Pcreate(H5P_DATASET_CREATE)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dcpl; + } + // to perform introspection on any kind of property list, + // we need to determine its property list class by obtaining a handle + if ((plist_cls_id = H5Pget_class(dcpl)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_plist_cls_id; + } + // Compare the handle to the handles of built-in or user-defined + // property list classes + assert(H5Pequal(plist_cls_id, H5P_DATASET_CREATE) > 0); + +fail_plist_cls_id: + H5Pclose(dcpl); +fail_dcpl:; + } + //! <!-- [read] --> + + //! <!-- [update] --> + { + __label__ fail_dcpl, fail_prop; + hid_t dcpl; + + if ((dcpl = H5Pcreate(H5P_DATASET_CREATE)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dcpl; + } + + // a property list is updated by adding (or removing) properties + if (H5Pset_fill_time(dcpl, H5D_FILL_TIME_NEVER) < 0) { + ret_val = EXIT_FAILURE; + goto fail_prop; + } + +fail_prop: + H5Pclose(dcpl); +fail_dcpl:; + } + //! <!-- [update] --> + + //! <!-- [delete] --> + { + __label__ fail_dcpl; + hid_t dcpl; + + if ((dcpl = H5Pcreate(H5P_DATASET_CREATE)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dcpl; + } + + // a property list is "deleted" by closing it + H5Pclose(dcpl); +fail_dcpl:; + } + //! <!-- [delete] --> + + //! <!-- [create_class] --> + { + __label__ fail_cls, fail_prop; + hid_t plist_cls, plist; + int izero = 0; + double dzero = 0.0; + + // create a new property list class + if ((plist_cls = H5Pcreate_class(H5P_ROOT, "int & double", NULL, NULL, NULL, NULL, NULL, NULL)) == + H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_cls; + } + // add a permanent integer property + if (H5Pregister2(plist_cls, "int", sizeof(int), &izero, NULL, NULL, NULL, NULL, NULL, NULL, NULL) < + 0) { + ret_val = EXIT_FAILURE; + goto fail_prop; + } + // add a permanent double property + if (H5Pregister2(plist_cls, "double", sizeof(double), &dzero, NULL, NULL, NULL, NULL, NULL, NULL, + NULL) < 0) { + ret_val = EXIT_FAILURE; + goto fail_prop; + } + // create an instance of this user-defined property list class + if ((plist = H5Pcreate(plist_cls)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_prop; + } + + // ... + + H5Pclose(plist); +fail_prop: + H5Pclose_class(plist_cls); +fail_cls:; + } + //! <!-- [create_class] --> + + //! <!-- [read_class] --> + { + __label__ fail_cls, fail_prop, fail_plist; + hid_t plist_cls, plist; + size_t nprops; + + if ((plist_cls = H5Pcreate_class(H5P_ROOT, "ud_plist", NULL, NULL, NULL, NULL, NULL, NULL)) == + H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_cls; + } + if ((plist = H5Pcreate(plist_cls)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_prop; + } + if (H5Pinsert2(plist, "temp", 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL) < 0) { + ret_val = EXIT_FAILURE; + goto fail_plist; + } + // count the registered properties of this class + if (H5Pget_nprops(plist_cls, &nprops) < 0) { + ret_val = EXIT_FAILURE; + goto fail_plist; + } + // this will be 0 as there are no registered properties + printf("Property list class has %lu registered properties.\n", nprops); + + // count the properties in this property list + if (H5Pget_nprops(plist, &nprops) < 0) { + ret_val = EXIT_FAILURE; + goto fail_plist; + } + // will be 1 as there is one temporary property + printf("Property list has %lu property.\n", nprops); + +fail_plist: + H5Pclose(plist); +fail_prop: + H5Pclose_class(plist_cls); +fail_cls:; + } + //! <!-- [read_class] --> + + //! <!-- [update_class] --> + { + __label__ fail_cls, fail_prop, fail_plist; + hid_t plist_cls, plist; + + if ((plist_cls = H5Pcreate_class(H5P_ROOT, "ud_plist", NULL, NULL, NULL, NULL, NULL, NULL)) == + H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_cls; + } + // create an instance of this user-defined property list class + if ((plist = H5Pcreate(plist_cls)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_prop; + } + // insert a temporary property + if (H5Pinsert2(plist, "temp", 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL) < 0) { + ret_val = EXIT_FAILURE; + goto fail_plist; + } + +fail_plist: + H5Pclose(plist); +fail_prop: + H5Pclose_class(plist_cls); +fail_cls:; + } + //! <!-- [update_class] --> + + //! <!-- [delete_class] --> + { + __label__ fail_cls; + hid_t plist_cls; + + if ((plist_cls = H5Pcreate_class(H5P_ROOT, "int & double", NULL, NULL, NULL, NULL, NULL, NULL)) == + H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_cls; + } + // ... + + // a user defined property list class is destroyed by closing the handle + H5Pclose_class(plist_cls); +fail_cls:; + } + //! <!-- [delete_class] --> + + return ret_val; +} diff --git a/doxygen/examples/H5R_examples.c b/doxygen/examples/H5R_examples.c new file mode 100644 index 0000000..b40b992 --- /dev/null +++ b/doxygen/examples/H5R_examples.c @@ -0,0 +1,171 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <assert.h> +#include <stdio.h> +#include <stdlib.h> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [create] --> + { + __label__ fail_file, fail_fspace, fail_dset, fail_sel, fail_aspace, fail_attr, fail_awrite; + hid_t file, fspace, dset, aspace, attr; + H5R_ref_t ref; + + if ((file = H5Fcreate("reference.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + // create a region reference which selects all elements of the dataset at "/data" + if ((fspace = H5Screate_simple(2, (hsize_t[]){10, 20}, NULL)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_fspace; + } + if ((dset = H5Dcreate(file, "data", H5T_STD_I32LE, fspace, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT)) == + H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dset; + } + if (H5Sselect_all(fspace) < 0 || H5Rcreate_region(file, "data", fspace, H5P_DEFAULT, &ref) < 0) { + ret_val = EXIT_FAILURE; + goto fail_sel; + } + // store the region reference in a scalar attribute of the root group called "region" + if ((aspace = H5Screate(H5S_SCALAR)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_aspace; + } + if ((attr = H5Acreate(file, "region", H5T_STD_REF, aspace, H5P_DEFAULT, H5P_DEFAULT)) == + H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_attr; + } + if (H5Awrite(attr, H5T_STD_REF, &ref) < 0) { + ret_val = EXIT_FAILURE; + goto fail_awrite; + } + +fail_awrite: + H5Aclose(attr); +fail_attr: + H5Sclose(aspace); +fail_aspace: + H5Rdestroy(&ref); +fail_sel: + H5Dclose(dset); +fail_dset: + H5Sclose(fspace); +fail_fspace: + H5Fclose(file); +fail_file:; + } + //! <!-- [create] --> + + //! <!-- [read] --> + { + __label__ fail_file, fail_attr, fail_aread; + hid_t file, attr; + H5R_ref_t ref; + + if ((file = H5Fopen("reference.h5", H5F_ACC_RDONLY, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + + // read the dataset region reference from the attribute + if ((attr = H5Aopen(file, "region", H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_attr; + } + if (H5Aread(attr, H5T_STD_REF, &ref) < 0) { + ret_val = EXIT_FAILURE; + goto fail_aread; + } + assert(H5Rget_type(&ref) == H5R_DATASET_REGION2); + + // get an HDF5 path name for the dataset of the region reference + { + char buf[255]; + if (H5Rget_obj_name(&ref, H5P_DEFAULT, buf, 255) < 0) { + ret_val = EXIT_FAILURE; + } + printf("Object name: \"%s\"\n", buf); + } + + H5Rdestroy(&ref); +fail_aread: + H5Aclose(attr); +fail_attr: + H5Fclose(file); +fail_file:; + } + //! <!-- [read] --> + + //! <!-- [update] --> + { + __label__ fail_file, fail_attr, fail_ref; + hid_t file, attr; + H5R_ref_t ref; + + if ((file = H5Fopen("reference.h5", H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + + // H5T_STD_REF is a generic reference type + // we can "update" the attribute value to refer to the attribute itself + if ((attr = H5Aopen(file, "region", H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_attr; + } + if (H5Rcreate_attr(file, "data", "region", H5P_DEFAULT, &ref) < 0) { + ret_val = EXIT_FAILURE; + goto fail_ref; + } + + assert(H5Rget_type(&ref) == H5R_ATTR); + + if (H5Awrite(attr, H5T_STD_REF, &ref) < 0) { + ret_val = EXIT_FAILURE; + } + + H5Rdestroy(&ref); +fail_ref: + H5Aclose(attr); +fail_attr: + H5Fclose(file); +fail_file:; + } + //! <!-- [update] --> + + //! <!-- [delete] --> + { + __label__ fail_file, fail_ref; + hid_t file; + H5R_ref_t ref; + + // create an HDF5 object reference to the root group + if ((file = H5Fopen("reference.h5", H5F_ACC_RDONLY, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + if (H5Rcreate_object(file, ".", H5P_DEFAULT, &ref) < 0) { + ret_val = EXIT_FAILURE; + goto fail_ref; + } + + // H5Rdestroy() releases all resources associated with an HDF5 reference + H5Rdestroy(&ref); +fail_ref: + H5Fclose(file); +fail_file:; + } + //! <!-- [delete] --> + + return ret_val; +} diff --git a/doxygen/examples/H5S_examples.c b/doxygen/examples/H5S_examples.c new file mode 100644 index 0000000..c542ec0 --- /dev/null +++ b/doxygen/examples/H5S_examples.c @@ -0,0 +1,132 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <stdio.h> +#include <stdlib.h> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [create] --> + { + __label__ fail_dspace; + hid_t dspace; + + // create a 2D chess board shape (8x8) + if ((dspace = H5Screate_simple(2, (hsize_t[]){8, 8}, NULL)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dspace; + } + + H5Sclose(dspace); +fail_dspace:; + } + //! <!-- [create] --> + + //! <!-- [read] --> + { + __label__ fail_dspace; + hid_t dspace; + + if ((dspace = H5Screate(H5S_NULL)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dspace; + } + + // make changes to the selection on DSPACE + // ... + // parse the resulting selection + + switch (H5Sget_select_type(dspace)) { + case H5S_SEL_HYPERSLABS: + // we are dealing with a hyperslab selection + // determine the regularity and block structure + break; + case H5S_SEL_POINTS: + // we are dealing with a point selection + // for example, retrieve the point list + break; + case H5S_SEL_ALL: + // all dataset elements are selected + break; + case H5S_SEL_NONE: + // the selection is empty + break; + default: + ret_val = EXIT_FAILURE; + break; + } + + if (dspace != H5S_ALL) + H5Sclose(dspace); + +fail_dspace:; + } + //! <!-- [read] --> + + //! <!-- [update] --> + { + __label__ fail_select, fail_dspace; + hid_t dspace; + + // create a 2D chess board shape (8x8) + if ((dspace = H5Screate_simple(2, (hsize_t[]){8, 8}, NULL)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dspace; + } + // select all black fields: do this w/ a hyperslab union in two steps + + // select the black fields on even rows + if (H5Sselect_hyperslab(dspace, H5S_SELECT_SET, (hsize_t[]){0, 0}, (hsize_t[]){2, 2}, + (hsize_t[]){4, 4}, NULL) < 0) { + ret_val = EXIT_FAILURE; + goto fail_select; + } + // select the black fields on odd rows + // notice the H5S_SELECT_OR operator + if (H5Sselect_hyperslab(dspace, H5S_SELECT_OR, (hsize_t[]){1, 1}, (hsize_t[]){2, 2}, + (hsize_t[]){4, 4}, NULL) < 0) { + ret_val = EXIT_FAILURE; + goto fail_select; + } + + // should be 32 + printf("%lld elements selected.\n", H5Sget_select_npoints(dspace)); + +fail_select: + H5Sclose(dspace); +fail_dspace:; + } + //! <!-- [update] --> + + //! <!-- [delete] --> + { + __label__ fail_select, fail_dspace; + hid_t dspace; + + if ((dspace = H5Screate(H5S_NULL)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dspace; + } + + // make changes to and work with the selection on DSPACE + // ... + // finally, clear the selection + + if (H5Sselect_none(dspace) < 0) { + ret_val = EXIT_FAILURE; + goto fail_select; + } + +fail_select: + if (dspace != H5S_ALL) + H5Sclose(dspace); +fail_dspace:; + } + //! <!-- [delete] --> + + return ret_val; +} diff --git a/doxygen/examples/H5T_examples.c b/doxygen/examples/H5T_examples.c new file mode 100644 index 0000000..7cfa7d4 --- /dev/null +++ b/doxygen/examples/H5T_examples.c @@ -0,0 +1,136 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <stdio.h> +#include <stdlib.h> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [create] --> + { + __label__ fail_insert, fail_dtype, fail_file; + hid_t file, dtype; + + if ((file = H5Fcreate("t1.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + // create a compound datatype with room for real and imaginary parts + if ((dtype = H5Tcreate(H5T_COMPOUND, 2 * sizeof(double))) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dtype; + } + // add the real part now and the imaginary part later + if (H5Tinsert(dtype, "re", 0, H5T_IEEE_F64LE) < 0) { + ret_val = EXIT_FAILURE; + goto fail_insert; + } + // commit the datatype definition to the file + if (H5Tcommit(file, "pre-complex", dtype, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + } + +fail_insert: + H5Tclose(dtype); +fail_dtype: + H5Fclose(file); +fail_file:; + } + //! <!-- [create] --> + + //! <!-- [read] --> + { + __label__ fail_dtype, fail_file; + hid_t file, dtype; + + if ((file = H5Fopen("t1.h5", H5F_ACC_RDONLY, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + // open the datatype object stored in the file + if ((dtype = H5Topen(file, "pre-complex", H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dtype; + } + + switch (H5Tget_class(dtype)) { // this time we are only interested in compounds + case H5T_COMPOUND: + printf("Record size: %lu bytes\n", H5Tget_size(dtype)); + printf("Record has %d field(s).\n", H5Tget_nmembers(dtype)); + break; + default: + break; + } + + H5Tclose(dtype); +fail_dtype: + H5Fclose(file); +fail_file:; + } + //! <!-- [read] --> + + //! <!-- [update] --> + { + __label__ fail_insert, fail_clone, fail_dtype, fail_file; + hid_t file, dtype, clone; + + if ((file = H5Fopen("t1.h5", H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + // open the datatype object stored in the file + if ((dtype = H5Topen(file, "pre-complex", H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dtype; + } + // the original datatype object is immutable and we need to clone it + if ((clone = H5Tcopy(dtype)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_clone; + } + // remember that the original has enough room for real and imaginary parts + // add the imaginary part + if (H5Tinsert(clone, "im", sizeof(double), H5T_IEEE_F64LE) < 0) { + ret_val = EXIT_FAILURE; + goto fail_insert; + } + // commit the "updated" datatype definition to the file + if (H5Tcommit(file, "complex", clone, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + } + +fail_insert: + H5Tclose(clone); +fail_clone: + H5Tclose(dtype); +fail_dtype: + H5Fclose(file); +fail_file:; + } + //! <!-- [update] --> + + //! <!-- [delete] --> + { + __label__ fail_file; + hid_t file; + + if ((file = H5Fopen("t1.h5", H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + // delete the "pre-complex" datatype by unlinking + if (H5Ldelete(file, "pre-complex", H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + } + + H5Fclose(file); +fail_file:; + } + //! <!-- [delete] --> + + return ret_val; +} diff --git a/doxygen/examples/H5Z_examples.c b/doxygen/examples/H5Z_examples.c new file mode 100644 index 0000000..28a1ea2 --- /dev/null +++ b/doxygen/examples/H5Z_examples.c @@ -0,0 +1,108 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <assert.h> +#include <stdio.h> +#include <stdlib.h> + +//! <!-- [filter] --> +size_t +filter(unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[], size_t nbytes, size_t *buf_size, + void **buf) +{ + buf_size = 0; + + if (flags & H5Z_FLAG_REVERSE) { + // read data, e.g., decompress data + // ... + } + else { + // write data, e.g., compress data + // ... + } + + return nbytes; +} +//! <!-- [filter] --> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [create] --> + { + __label__ fail_register; + H5Z_class_t cls; + cls.version = H5Z_CLASS_T_VERS; + cls.id = 256; + cls.encoder_present = 1; + cls.decoder_present = 1; + cls.name = "Identity filter"; + cls.can_apply = NULL; + cls.set_local = NULL; + cls.filter = &filter; + + // register the filter + if (H5Zregister(&cls) < 0) { + ret_val = EXIT_FAILURE; + goto fail_register; + } + + // do something with filter + // ... + + // unregister the filter if no longer required + // ... + +fail_register:; + } + //! <!-- [create] --> + + //! <!-- [read] --> + { + __label__ fail_avail; + + H5Z_filter_t flt = H5Z_FILTER_DEFLATE; + unsigned flags = 0; + + // check if the deflate filter is available + if (H5Zfilter_avail(flt) < 0) { + ret_val = EXIT_FAILURE; + goto fail_avail; + } + // retrieve the deflate filter info + if (H5Zget_filter_info(flt, &flags) < 0) { + ret_val = EXIT_FAILURE; + goto fail_avail; + } + + // check if the deflate encoder or decoder is enabled + if (H5Z_FILTER_CONFIG_ENCODE_ENABLED & flags) + printf("Deflate encoder enabled.\n"); + if (H5Z_FILTER_CONFIG_DECODE_ENABLED & flags) + printf("Deflate decoder enabled.\n"); + +fail_avail:; + } + //! <!-- [read] --> + + //! <!-- [update] --> + { + // N/A + } //! <!-- [update] --> + + //! <!-- [delete] --> + { + // unregister the identity filter + if (H5Zunregister(256) < 0) { + ret_val = EXIT_FAILURE; + } + } + //! <!-- [delete] --> + + assert(ret_val == EXIT_SUCCESS); + + return ret_val; +} diff --git a/doxygen/examples/IOFlow.html b/doxygen/examples/IOFlow.html new file mode 100644 index 0000000..6b2c27e --- /dev/null +++ b/doxygen/examples/IOFlow.html @@ -0,0 +1,137 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<!-- saved from url=(0064)https://gamma.hdfgroup.org/papers/HISS/030821.IOFlow/IOFlow.html --> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> + <title>HDF5 Raw I/O Flow Notes</title> + + <meta name="author" content="Quincey Koziol"> +</head> + +<body text="#000000" bgcolor="#FFFFFF"> + +<style type="text/css"> +OL.loweralpha { list-style-type: lower-alpha } +OL.upperroman { list-style-type: upper-roman } +</style> + +<center><h1>HDF5 Raw I/O Flow Notes</h1></center> +<center><h3>Quincey Koziol<br> + koziol@ncsa.uiuc.edu<br> + August 20, 2003 +</h3></center> + +<ol class="upperroman"> + +<li><h3><u>Document's Audience:</u></h3> + +<ul> + <li>Current H5 library designers and knowledgable external developers.</li> +</ul> + +</li><li><h3><u>Background Reading:</u></h3> + +</li><li><h3><u>Introduction:</u></h3> + +<dl> + <dt><strong>What is this document about?</strong></dt> + <dd>This document attempts to supplement the flow charts describing + the flow of control for raw data I/O in the library. + </dd> <br> +</dl> + +</li><li><h3><u>Figures:</u></h3> +<p>The following figures provide the main information:</p> + <table> + <tr><td><img src="IOFlow.gif" alt="High-Level View of Writing Raw Data" style="height:50%;"></td></tr> + <tr><td><img src="IOFlow2.gif" alt="Perform Serial or Parallel I/O" style="height:50%;"></td></tr> + <tr><td><img src="IOFlow3.gif" alt="Gather/Convert/Scatter" style="height:50%;"></td></tr> + </table> + +</li><li><h3><u>Notes From Accompanying Figures:</u></h3> + +<p>This section provides notes to augment the information in the accompanying + figures. +</p> + +<ol> + <li><b>Validate Parameters</b> - Resolve any H5S_ALL parameters + for dataspace selections to actual dataspaces, allocate + conversion buffers, etc. + </li> + + <li><b>Space Allocated in File?</b> - Space may not have been allocated + in the file to store the dataset data, if "late allocation" was chosen + for the allocation time when the dataset was created. + </li> + + <li><b>Allocate & Fill Space</b> - These operations allocate both contiguous + and chunked dataset's space in the file. The chunked dataset space + allocation iterates through all the chunks in the file and allocates + both the B-tree information and the raw data in the file. Because of + the way filters work, fill-values are written out for chunked datasets + as they are allocated, instead of as a separate step. + In parallel + I/O, the chunked dataset allocation can potentially be time-consuming, + since all the raw data in the dataset is allocated from one process. + </li> + + <li><b>Datatype Conversion Needed?</b> - This currently is the deciding + factor between doing "direct I/O" (in serial or parallel) and needing + to perform gather/convert/scatter operations. I believe that MPI + is capable of performing a limited range of type conversions and if so, + we should add support to detect when they can be used. This will + allow more I/O operations to be performed collectively. + </li> + + <li><b>Collective I/O Requested/Allowed?</b> - A user has to both request + that collective I/O occur and also their I/O operation must meet the + requirements that the library sets for supporting collective parallel + I/O: + <ul> + <li>The dataspace must be scalar or simple (which is a no-op really, + since we don't support "complex" dataspaces in the library + currently). + </li> + <li>The selection must be regular. "all" selections + and hyperslab selections that were + made with only one call to H5Sselect_hyperslab() (i.e. not a + hyperslab selection that has been aggregated over multiple + selection calls) are regular. Supporting point and + irregular hyperslab selections are on the "to do" list. + </li> + <li>The dataset must be stored contiguously on disk (as shown in the + figure also). Supporting chunked dataset storage is also + on the "to do" list. + </li> + </ul> + </li> + + <li><b>Build "chunk map"</b> - This step still has some scalability issues + as it creates a data structure that is proportional to the number of + chunks which will be written to, which could potentially be very large. + Building the "chunk map" information incrementally is on the "to do" + list also. + </li> + + <li><b>Perform Chunked I/O</b> - As the figure shows, there is no support + for collective parallel I/O on chunked datasets currently. As noted + earlier, this is on the "to do" list. + </li> + + <li><b>Perform "Direct" Serial I/O</b> - "Direct" serial I/O writes data + from the application's buffer, without any intervening buffer or memory + copies. For maximum efficiency and performance, the elements in the + selections should be adjoining. + </li> + + <li><b>Perform Collective Parallel I/O</b> - This step also writes data + directly from an application buffer, but additionally uses collective + MPI I/O operations to combine the data from each process in the parallel + application in an efficient manner. + </li> +</ol> + +</li></ol> + + + +</body></html> diff --git a/doxygen/examples/ThreadSafeLibrary.html b/doxygen/examples/ThreadSafeLibrary.html index 8daf386..ebb193e 100644 --- a/doxygen/examples/ThreadSafeLibrary.html +++ b/doxygen/examples/ThreadSafeLibrary.html @@ -165,7 +165,7 @@ The structure is defined in <code>H5private.h</code> as: <blockquote> <pre> - /* cancelability structure */ + /* cancellability structure */ typedef struct H5_cancel_struct { int previous_state; unsigned int cancel_count; diff --git a/doxygen/examples/VFL.html b/doxygen/examples/VFL.html index 9776f96..624d942 100644 --- a/doxygen/examples/VFL.html +++ b/doxygen/examples/VFL.html @@ -306,7 +306,7 @@ H5Dread(dataset, type, mspace, fspace, buffer, dxpl); </PRE> <P> -The transfer propery list can be queried in a manner similar to the file +The transfer property list can be queried in a manner similar to the file access property list: the driver provides a function (or functions) to return various information about the transfer property list: @@ -1210,7 +1210,7 @@ Flush all data for file <VAR>file</VAR> to storage. </P> <P> <STRONG>Example:</STRONG> The sec2 driver doesn't cache any data but it also doesn't -extend the Unix file as agressively as it should. Therefore, when finalizing a +extend the Unix file as aggressively as it should. Therefore, when finalizing a file it should write a zero to the last byte of the allocated region so that when reopening the file later the EOF marker will be at least as large as the EOA marker saved in the superblock (otherwise HDF5 will refuse to open the diff --git a/doxygen/hdf5_navtree_hacks.js b/doxygen/hdf5_navtree_hacks.js index 942970c..dda8984 100644 --- a/doxygen/hdf5_navtree_hacks.js +++ b/doxygen/hdf5_navtree_hacks.js @@ -223,7 +223,7 @@ $(document).ready(function() { (function (){ // wait until the first "selected" element has been created try { - // this line will triger an exception if there is no #selected element, i.e., before the tree structure is complete. + // this line will trigger an exception if there is no #selected element, i.e., before the tree structure is complete. document.getElementById("selected").className = "item selected"; // ok, the default tree has been created, we can keep going... diff --git a/doxygen/hdf5doxy_layout.xml b/doxygen/hdf5doxy_layout.xml index 7f71c24..24642b5 100644 --- a/doxygen/hdf5doxy_layout.xml +++ b/doxygen/hdf5doxy_layout.xml @@ -7,10 +7,12 @@ <tab type="user" url="@ref Cookbook" title="Cookbook" /> <tab type="user" url="https://portal.hdfgroup.org/display/HDF5/HDF5+User+Guides" title="User Guides" /> <tab type="user" url="https://portal.hdfgroup.org/display/HDF5/HDF5+Application+Developer%27s+Guide" title="Application Developer's Guide" /> - <tab type="user" url="https://portal.hdfgroup.org/display/HDF5/HDF5+Glossary" title="Glossary" /> + <tab type="user" url="@ref GLS" title="Glossary" /> <tab type="user" url="@ref RM" title="Reference Manual" /> <tab type="user" url="@ref TN" title="Technical Notes" /> <tab type="user" url="@ref SPEC" title="Specifications" /> + <tab type="user" url="@ref RFC" title="RFCs" /> + <tab type="user" url="@ref FTS" title="Full-Text Search" /> <tab type="user" url="@ref About" title="About" /> </navindex> diff --git a/doxygen/img/HDF5.png b/doxygen/img/HDF5.png Binary files differnew file mode 100644 index 0000000..0458fa8 --- /dev/null +++ b/doxygen/img/HDF5.png diff --git a/hl/src/H5LTpublic.h b/hl/src/H5LTpublic.h index 2af9b07..47bb334 100644 --- a/hl/src/H5LTpublic.h +++ b/hl/src/H5LTpublic.h @@ -19,7 +19,7 @@ #define H5LT_FILE_IMAGE_DONT_COPY 0x0002 /* The HDF5 lib won't copy */ /* user supplied image buffer. The same image is open with the core driver. */ #define H5LT_FILE_IMAGE_DONT_RELEASE 0x0004 /* The HDF5 lib won't */ -/* deallocate user supplied image buffer. The user application is reponsible */ +/* deallocate user supplied image buffer. The user application is responsible */ /* for doing so. */ #define H5LT_FILE_IMAGE_ALL 0x0007 diff --git a/src/H5ACprivate.h b/src/H5ACprivate.h index 166ba8d..1fce17e 100644 --- a/src/H5ACprivate.h +++ b/src/H5ACprivate.h @@ -91,9 +91,9 @@ typedef enum { #define H5AC__DEFAULT_MIN_CLEAN_SIZE H5C__DEFAULT_MIN_CLEAN_SIZE /* - * Class methods pertaining to caching. Each type of cached object will + * Class methods pertaining to caching. Each type of cached object will * have a constant variable with permanent life-span that describes how - * to cache the object. That variable will be of type H5AC_class_t and + * to cache the object. That variable will be of type H5AC_class_t and * have the following required fields... * * LOAD: Loads an object from disk to memory. The function @@ -181,7 +181,6 @@ extern H5P_genplist_t *H5AC_ind_dxpl_g; extern hid_t H5AC_ind_dxpl_id; /* Default cache configuration. */ - #define H5AC__DEFAULT_METADATA_WRITE_STRATEGY H5AC_METADATA_WRITE_STRATEGY__DISTRIBUTED /* clang-format off */ diff --git a/src/H5ACpublic.h b/src/H5ACpublic.h index a7d30ec..5ac4521 100644 --- a/src/H5ACpublic.h +++ b/src/H5ACpublic.h @@ -75,7 +75,7 @@ extern "C" { * field should be used to open a trace file for the cache. * * - * The trace file is a debuging feature that allow the capture of + * The trace file is a debugging feature that allow the capture of * top level metadata cache requests for purposes of debugging and/or * optimization. This field should normally be set to FALSE, as * trace file collection imposes considerable overhead. @@ -120,7 +120,7 @@ extern "C" { * H5C_incr__off ) && ( decr_mode == H5C_decr__off )). There * is no logical reason why this should be so, but it simplifies * implementation and testing, and I can't think of any reason - * why it would be desireable. If you can think of one, I'll + * why it would be desirable. If you can think of one, I'll * revisit the issue. * * set_initial_size: Boolean flag indicating whether the size of the @@ -393,7 +393,7 @@ extern "C" { * * When the sync point is reached (or when there is a user generated * flush), process zero flushes sufficient entries to bring it into - * complience with its min clean size (or flushes all dirty entries in + * compliance with its min clean size (or flushes all dirty entries in * the case of a user generated flush), broad casts the list of * entries just cleaned to all the other processes, and then exits * the sync point. @@ -573,7 +573,7 @@ typedef struct H5AC_cache_config_t { size_t min_size; /**< Lower bound (in bytes) on the range of values that the - * adaptive cache resize code can select as the mininum cache * size. */ + * adaptive cache resize code can select as the minimum cache * size. */ long int epoch_length; /**< Number of cache accesses between runs of the adaptive cache resize @@ -705,13 +705,13 @@ typedef struct H5AC_cache_config_t { * of bytes of dirty metadata created since the last synchronization exceeds * this limit.\n This field only applies to the parallel case. While it is * ignored elsewhere, it can still draw a value out of bounds error.\n It - * must be consistant across all caches on any given file.\n By default, + * must be consistent across all caches on any given file.\n By default, * this field is set to 256 KB. It shouldn't be more than half the current * max cache size times the min clean fraction. */ int metadata_write_strategy; /**< Desired metadata write strategy. The valid values for this field - * are:\n #H5AC_METADATA_WRITE_STRATEGY__PROCESS_0_ONLY: Specifies tha only + * are:\n #H5AC_METADATA_WRITE_STRATEGY__PROCESS_0_ONLY: Specifies the only * process zero is allowed to write dirty metadata to disk.\n * #H5AC_METADATA_WRITE_STRATEGY__DISTRIBUTED: Specifies that process zero * still makes the decisions as to what entries should be flushed, but the diff --git a/src/H5Apublic.h b/src/H5Apublic.h index 2bd2686..f6205e8 100644 --- a/src/H5Apublic.h +++ b/src/H5Apublic.h @@ -22,6 +22,26 @@ * support partial I/O operations for attributes and they cannot be compressed * or extended. * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5A_examples.c create + * </td> + * <td> + * \snippet{lineno} H5A_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5A_examples.c update + * </td> + * <td> + * \snippet{lineno} H5A_examples.c delete + * </td> + * </tr> + * </table> + * */ /* @@ -91,11 +111,11 @@ extern "C" { * * \return \herr_t * - * \details H5Aclose() terminates access to the attribute specified by - * \p attr_id by releasing the identifier. + * \details H5Aclose() terminates access to the attribute through + * \p attr_id and releases the identifier. * - * \attention Further use of a released attribute identifier is illegal; a - * function using such an identifier will generate an error. + * \par Example + * \snippet H5A_examples.c create * * \since 1.0.0 * @@ -123,27 +143,19 @@ H5_DLL herr_t H5Aclose(hid_t attr_id); * The attribute name, \p attr_name, must be unique for the object. * * The attribute is created with the specified datatype and dataspace, - * \p type_id and \p space_id, which are created with the H5T and - * H5S interfaces, respectively. - * - * If \p type_id is either a fixed-length or variable-length string, - * it is important to set the string length when defining the - * datatype. String datatypes are derived from #H5T_C_S1 (or - * #H5T_FORTRAN_S1 for Fortran), which defaults to 1 character in - * size. See H5Tset_size() and Creating variable-length string - * datatypes. + * \p type_id and \p space_id. * - * The access property list is currently unused, but will be used in - * the future. This property list should currently be #H5P_DEFAULT. + * \plist_unused{acpl} * * The attribute identifier returned by this function must be released * with H5Aclose() resource leaks will develop. * - * \note The \p aapl parameter is currently not used; specify #H5P_DEFAULT. - * * \note If \p loc_id is a file identifier, the attribute will be attached * that file’s root group. * + * \par Example + * \snippet H5A_examples.c create + * * \since 1.8.0 * * \see H5Aclose() @@ -173,28 +185,19 @@ H5_DLL hid_t H5Acreate2(hid_t loc_id, const char *attr_name, hid_t type_id, hid_ * attached to the object specified by \p loc_id and \p obj_name. * * \p loc_id is a location identifier; \p obj_name is the object - * name relative to \p loc_id. If \p loc_id fully specifies the - * object to which the attribute is to be attached, \p obj_name - * should be '.' (a dot). + * name relative to \p loc_id. * * The attribute name, \p attr_name, must be unique for the object. * * The attribute is created with the specified datatype and - * dataspace, \p type_id and \p space_id, which are created with - * the H5T and H5S interfaces respectively. + * dataspace, \p type_id and \p space_id. * - * The attribute creation and access property lists are currently - * unused, but will be used in the future for optional attribute - * creation and access properties. These property lists should - * currently be #H5P_DEFAULT. + * \plist_unused{aapl} * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to access * the object, \p obj_name. * - * The attribute identifier returned by this function must be - * released with H5close() or resource leaks will develop. - * * \since 1.8.0 * */ @@ -213,10 +216,14 @@ H5_DLL hid_t H5Acreate_by_name(hid_t loc_id, const char *obj_name, const char *a * * \details H5Adelete() removes the attribute specified by its name, * \p attr_name, from a file, dataset, group, or named datatype. - * This function should not be used when attribute identifiers - * are open on \p loc_id as it may cause the internal indexes of - * the attributes to change and future writes to the open - * attributes to produce incorrect results. + * + * \attention This function should not be used when other attribute identifiers + * are open on \p loc_id. This may cause the internal indexes of + * the attributes to change and future writes to the open + * attributes to produce incorrect results. + * + * \par Example + * \snippet H5A_examples.c delete * * \since 1.0.0 * @@ -243,27 +250,16 @@ H5_DLL herr_t H5Adelete(hid_t loc_id, const char *attr_name); * * The object from which the attribute is to be removed is * specified by a location identifier and name, \p loc_id and - * \p obj_name, respectively. If \p loc_id fully specifies the - * object from which the attribute is to be removed, \p obj_name - * should be '.' (a dot). + * \p obj_name, respectively. * * The attribute to be removed is specified by a position in an - * index, \p n. The type of index is specified by \p idx_type and - * may be #H5_INDEX_NAME, for an alpha-numeric index by name, or - * #H5_INDEX_CRT_ORDER, for an index by creation order. The order - * in which the index is to be traversed is specified by \p order - * and may be #H5_ITER_INC (increment) for top-down iteration, - * #H5_ITER_DEC (decrement) for bottom-up iteration, or - * #H5_ITER_NATIVE, in which case HDF5 will iterate in the - * fastest-available order. For example, if \p idx_type, \p order, + * index, \p n. The type of index is specified by \p idx_type. + * The order in which the index is to be traversed is specified by + * \p order. For example, if \p idx_type, \p order, * and \p n are set to #H5_INDEX_NAME, #H5_ITER_INC, and 5, - * respectively, the fifth attribute by alpha-numeric order of + * respectively, the fifth attribute in lexicographic order of * attribute names will be removed. * - * For a discussion of \p idx_type and \p order, the valid values - * of those parameters, and the use of \p n, see the description - * of H5Aiterate2(). - * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to access * the object, \p obj_name. @@ -291,9 +287,6 @@ H5_DLL herr_t H5Adelete_by_idx(hid_t loc_id, const char *obj_name, H5_index_t id * from an object specified by location and name, \p loc_id and * \p obj_name, respectively. * - * If \p loc_id fully specifies the object from which the - * attribute is to be removed, \p obj_name should be '.' (a dot). - * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to * access the object, \p obj_name. @@ -342,9 +335,7 @@ H5_DLL htri_t H5Aexists(hid_t obj_id, const char *attr_name); * \p loc_id specifies a location in the file containing the object. * \p obj_name is the name of the object to which the attribute is * attached and can be a relative name, relative to \p loc_id, - * or an absolute name, based in the root group of the file. If - * \p loc_id fully specifies the object, \p obj_name should be '.' - * (a dot). + * or an absolute name, based in the root group of the file. * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to access @@ -368,9 +359,6 @@ H5_DLL htri_t H5Aexists_by_name(hid_t obj_id, const char *obj_name, const char * * creation property list associated with the attribute specified * by \p attr_id. * - * The creation property list identifier should be released with - * H5Pclose(). - * * \since 1.8.0 * */ @@ -387,32 +375,9 @@ H5_DLL hid_t H5Aget_create_plist(hid_t attr_id); * \return \herr_t * * \details H5Aget_info() retrieves attribute information, locating the - * attribute with an attribute identifier, \p attr_id, which is - * the identifier returned by H5Aopen() or H5Aopen_by_idx(). The + * attribute with an attribute identifier, \p attr_id. The * attribute information is returned in the \p ainfo struct. * - * The \p ainfo struct is defined as follows: - * \snippet this H5A_info_t_snip - * - * \p corder_valid indicates whether the creation order data is - * valid for this attribute. Note that if creation order is not - * being tracked, no creation order data will be valid. Valid - * values are \c TRUE and \c FALSE. - * - * \p corder is a positive integer containing the creation - * order of the attribute. This value is 0-based, so, for - * example, the third attribute created will have a \p corder - * value of 2. - * - * \p cset indicates the character set used for the attribute’s - * name; valid values are defined in H5Tpublic.h and include - * the following: - * \csets - * This value is set with H5Pset_char_encoding(). - * - * \p data_size indicates the size, in the number of characters, - * of the attribute. - * * \since 1.8.0 * */ @@ -440,16 +405,9 @@ H5_DLL herr_t H5Aget_info(hid_t attr_id, H5A_info_t *ainfo /*out*/); * The attribute is located by its index position and the attribute * information is returned in the \p ainfo struct. * - * If \p loc_id fully specifies the object to which the attribute - * is attached, \p obj_name should be '.' (a dot). - * * The attribute is located by means of an index type, an index * traversal order, and a position in the index, \p idx_type, - * \p order and \p n, respectively. These parameters and their - * valid values are discussed in the description of H5Aiterate2(). - * - * The \p ainfo struct, which will contain the returned attribute - * information, is described in H5Aget_info(). + * \p order and \p n, respectively. * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to access @@ -467,8 +425,7 @@ H5_DLL herr_t H5Aget_info_by_idx(hid_t loc_id, const char *obj_name, H5_index_t * \brief Retrieves attribute information, by attribute name * * \fgdt_loc_id - * - * \param[in] obj_name Name of object to which attribute is attached, + * \param[in] obj_name Name of the object to which an attribute is attached, * relative to location * \param[in] attr_name Attribute name * \param[out] ainfo Struct containing returned attribute information @@ -481,11 +438,6 @@ H5_DLL herr_t H5Aget_info_by_idx(hid_t loc_id, const char *obj_name, H5_index_t * location and name, \p loc_id and \p obj_name, respectively. * The attribute information is returned in the \p ainfo struct. * - * If \p loc_id fully specifies the object to which the attribute - * is attached, \p obj_name should be '.' (a dot). - * - * The \p ainfo struct is described in H5Aget_info(). - * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to * access the object, \p obj_name. @@ -516,8 +468,8 @@ H5_DLL herr_t H5Aget_info_by_name(hid_t loc_id, const char *obj_name, const char * string terminator is stored in the last position of the buffer * to properly terminate the string. * - * If the user only wants to find out the size of this name, the - * values 0 and NULL can be passed in for the parameters + * If the user only wants to retrieve the name length, the + * values 0 and NULL should be passed for the parameters * \p bufsize and \p buf. * * \since 1.0.0 @@ -528,7 +480,7 @@ H5_DLL ssize_t H5Aget_name(hid_t attr_id, size_t buf_size, char *buf); /** * \ingroup H5A * - * \brief Gets an attribute name, by attribute index position + * \brief Gets an attribute name by attribute index position * * \fgdt_loc_id * \param[in] obj_name Name of object to which attribute is attached, @@ -549,13 +501,9 @@ H5_DLL ssize_t H5Aget_name(hid_t attr_id, size_t buf_size, char *buf); * located by its index position, the size of the name is specified * in \p size, and the attribute name is returned in \p name. * - * If \p loc_id fully specifies the object to which the attribute - * is attached, \p obj_name should be '.' (a dot). - * * The attribute is located by means of an index type, an index * traversal order, and a position in the index, \p idx_type, - * \p order and \p n, respectively. These parameters and their - * valid values are discussed in the description of H5Aiterate2(). + * \p order and \p n, respectively. * * If the attribute name’s size is unknown, the values 0 and NULL * can be passed in for the parameters \p size and \p name. The @@ -595,7 +543,7 @@ H5_DLL hid_t H5Aget_space(hid_t attr_id); /** * \ingroup H5A * - * \brief Returns the amount of storage required for an attribute + * \brief Returns the amount of storage used to store an attribute * * \attr_id * @@ -613,17 +561,16 @@ H5_DLL hsize_t H5Aget_storage_size(hid_t attr_id); /** * \ingroup H5A * - * \brief Gets an attribute datatype + * \brief Gets an attribute's datatype * * \attr_id * * \return \hid_t{datatype} * - * \details H5Aget_type() retrieves a copy of the datatype for an attribute. + * \details H5Aget_type() retrieves a copy of the attribute's datatype. * The datatype is reopened if it is a named type before returning * it to the application. The datatypes returned by this function - * are always read-only. If an error occurs when atomizing the - * return datatype, then the datatype is closed. + * are always read-only. * * The datatype identifier returned from this function must be * released with H5Tclose() or resource leaks will develop. @@ -636,7 +583,7 @@ H5_DLL hid_t H5Aget_type(hid_t attr_id); /** * \ingroup H5A * - * \brief Calls user-defined function for each attribute on an object + * \brief Calls a user-defined function for each attribute on an object * * \fgdt_loc_id * \param[in] idx_type Type of index @@ -663,24 +610,13 @@ H5_DLL hid_t H5Aget_type(hid_t attr_id); * are specified by three parameters: the index type, * \p idx_type; the order in which the index is to be traversed, * \p order; and the attribute’s position in the index, \p idx. - * - * The type of index specified by \p idx_type can be one of the - * following: - * - * \indexes - * - * The order in which the index is to be traversed, as specified - * by \p order, can be one of the following: - * - * \orders - * * The next attribute to be operated on is specified by \p idx, * a position in the index. * * For example, if \p idx_type, \p order, and \p idx are set to * #H5_INDEX_NAME, #H5_ITER_INC, and 5, respectively, the attribute * in question is the fifth attribute from the beginning of the - * alpha-numeric index of attribute names. If \p order were set to + * alphanumeric index of attribute names. If \p order were set to * #H5_ITER_DEC, it would be the fifth attribute from the end of * the index. * @@ -690,11 +626,6 @@ H5_DLL hid_t H5Aget_type(hid_t attr_id); * the value returned identifies the parameter to be operated on * in the next step of the iteration. * - * \p op is a user-defined function whose prototype is defined - * as follows: - * \snippet this H5A_operator2_t_snip - * \click4more - * * \note This function is also available through the H5Aiterate() macro. * * \since 1.8.0 @@ -730,31 +661,17 @@ H5_DLL herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t ord * additional information as defined below, is passed to a * user-defined function, \p op, which operates on that attribute. * - * If \p loc_id fully specifies the object to which these - * attributes are attached, \p obj_name should be '.' (a dot). - * * The order of the iteration and the attributes iterated over * are specified by three parameters: the index type, \p idx_type; * the order in which the index is to be traversed, \p order; * and the attribute’s position in the index, \p idx. - * - * The type of index specified by \p idx_type can be one of the - * following: - * - * \indexes - * - * The order in which the index is to be traversed, as specified - * by \p order, can be one of the following: - * - * \orders - * * The next attribute to be operated on is specified by \p idx, * a position in the index. * * For example, if \p idx_type, \p order, and \p idx are set to * #H5_INDEX_NAME, #H5_ITER_INC, and 5, respectively, the attribute * in question is the fifth attribute from the beginning of the - * alpha-numeric index of attribute names. If \p order were set to + * alphanumeric index of attribute names. If \p order were set to * #H5_ITER_DEC, it would be the fifth attribute from the end of * the index. * @@ -764,25 +681,6 @@ H5_DLL herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t ord * the value returned identifies the parameter to be operated on in * the next step of the iteration. * - * \p op is a user-defined function whose prototype is defined - * as follows: - * \snippet this H5A_operator2_t_snip - * \click4more - * - * Valid return values from an operator and the resulting - * H5Aiterate_by_name() and \p op behavior are as follows: - * - * \li Zero causes the iterator to continue, returning zero when - * all attributes have been processed. - * \li A positive value causes the iterator to immediately return - * that positive value, indicating short-circuit success. - * The iterator can be restarted at the next attribute, as - * indicated by the return value of \p idx. - * \li A negative value causes the iterator to immediately return - * that value, indicating failure. The iterator can be - * restarted at the next attribute, as indicated by the return - * value of \p idx. - * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to access * the object, \p obj_name. @@ -809,8 +707,7 @@ H5_DLL herr_t H5Aiterate_by_name(hid_t loc_id, const char *obj_name, H5_index_t * \details H5Aopen() opens an existing attribute, \p attr_name, that is * attached to object specified by an object identifier, \p obj_id. * - * The attribute access property list, \p aapl_id, is currently unused - * and should be #H5P_DEFAULT. + * \plist_unused{aapl_id} * * This function, H5Aopen_by_idx() or H5Aopen_by_name() must be called * before the attribute can be accessed for any further purpose, @@ -819,6 +716,9 @@ H5_DLL herr_t H5Aiterate_by_name(hid_t loc_id, const char *obj_name, H5_index_t * The attribute identifier returned by this function must be released * with H5Aclose() or resource leaks will develop. * + * \par Example + * \snippet H5A_examples.c read + * * \since 1.8.0 * * \see H5Aclose(), H5Acreate() @@ -843,17 +743,13 @@ H5_DLL hid_t H5Aopen(hid_t obj_id, const char *attr_name, hid_t aapl_id); * * \details H5Aopen_by_idx() opens an existing attribute that is attached * to an object specified by location and name, \p loc_id and - * \p obj_name, respectively. If \p loc_id fully specifies the - * object to which the attribute is attached, \p obj_name, should - * be '.' (a dot). + * \p obj_name, respectively. * * The attribute is identified by an index type, an index traversal * order, and a position in the index, \p idx_type, \p order and - * \p n, respectively. These parameters and their valid values are - * discussed in the description of H5Aiterate2(). + * \p n, respectively. * - * The attribute access property list, \p aapl_id, is currently - * unused and should currently be #H5P_DEFAULT. + * \plist_unused{aapl_id} * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to access @@ -892,11 +788,9 @@ H5_DLL hid_t H5Aopen_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_t * * \p loc_id specifies a location from which the target object can * be located and \p obj_name is an object name relative to - * \p loc_id. If \p loc_id fully specifies the object to which the - * attribute is attached, \p obj_name should be '.' (a dot). + * \p loc_id. * - * The attribute access property list, \p aapl_id, is currently - * unused and should currently be #H5P_DEFAULT. + * \plist_unused{aapl_id} * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to access @@ -933,6 +827,9 @@ H5_DLL hid_t H5Aopen_by_name(hid_t loc_id, const char *obj_name, const char *att * Datatype conversion takes place at the time of a read or write and * is automatic. * + * \par Example + * \snippet H5A_examples.c read + * * \version 1.8.8 Fortran updated to Fortran2003. * \version 1.4.2 The \p dims parameter was added to the Fortran API in this * release. @@ -980,15 +877,12 @@ H5_DLL herr_t H5Arename(hid_t loc_id, const char *old_name, const char *new_name * attribute's in-memory datatype is specified with \p type_id. * The entire attribute is written from \p buf to the file. * - * If \p type_id is either a fixed-length or variable-length string, - * it is important to set the string length when defining the datatype. - * String datatypes are derived from #H5T_C_S1 (or #H5T_FORTRAN_S1 for - * Fortran codes), which defaults to 1 character in size. - * See H5Tset_size() and Creating variable-length string datatypes. - * * Datatype conversion takes place at the time of a read or write and * is automatic. * + * \par Example + * \snippet H5A_examples.c update + * * \version 1.8.8 Fortran updated to Fortran2003. * \version 1.4.2 Fortran \p dims parameter added in this release * \since 1.0.0 @@ -1070,9 +964,9 @@ typedef herr_t (*H5A_operator1_t)(hid_t location_id /*in*/, const char *attr_nam * * \return \hid_tv{attribute} * - * \note The \p acpl parameters is currently not used; specify #H5P_DEFAULT. + * \deprecation_note{H5Acreate2()} * - * \deprecated Deprecated in favor of H5Acreate2() + * \plist_unused{acpl} * * \details H5Acreate1() creates an attribute, \p name, which is attached * to the object specified by the identifier \p loc_id. @@ -1080,18 +974,7 @@ typedef herr_t (*H5A_operator1_t)(hid_t location_id /*in*/, const char *attr_nam * The attribute name, \p name, must be unique for the object. * * The attribute is created with the specified datatype and dataspace, - * \p type_id and \p space_id, which are created with the H5T and - * H5S interfaces, respectively. - * - * If \p type_id is either a fixed-length or variable-length string, - * it is important to set the string length when defining the - * datatype. String datatypes are derived from #H5T_C_S1 (or - * #H5T_FORTRAN_S1 for Fortran), which defaults to 1 character in - * size. See H5Tset_size() and Creating variable-length string - * datatypes. - * - * The attribute identifier returned by this function must be released - * with H5Aclose() resource leaks will develop. + * \p type_id and \p space_id. * * \since 1.8.0 * @@ -1113,8 +996,7 @@ H5_DLL hid_t H5Acreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t spa * \return Returns the number of attributes if successful; otherwise returns * a negative value. * - * \deprecated This function is deprecated in favor of the functions - * H5Oget_info(), H5Oget_info_by_name(), and H5Oget_info_by_idx(). + * \deprecation_note{H5Oget_info(), H5Oget_info_by_name(), and H5Oget_info_by_idx()} * * \details H5Aget_num_attrs() returns the number of attributes attached to * the object specified by its identifier, \p loc_id. @@ -1137,8 +1019,7 @@ H5_DLL int H5Aget_num_attrs(hid_t loc_id); * * \return \herr_t * - * \deprecated This function is deprecated in favor of the function - * H5Aiterate2(). + * \deprecation_note{H5Aiterate2()} * * \details H5Aiterate1() iterates over the attributes of the object * specified by its identifier, \p loc_id. The object can be a @@ -1150,10 +1031,6 @@ H5_DLL int H5Aget_num_attrs(hid_t loc_id); * \p op, is returned in \p idx. If \p idx is the null pointer, * then all attributes are processed. * - * \p op is a user-defined function whose prototype is defined as follows: - * \snippet this H5A_operator1_t_snip - * \click4more - * * \version 1.8.0 The function \p H5Aiterate was renamed to H5Aiterate1() * and deprecated in this release. * \since 1.0.0 @@ -1171,8 +1048,7 @@ H5_DLL herr_t H5Aiterate1(hid_t loc_id, unsigned *idx, H5A_operator1_t op, void * * \return \hid_tv{attribute} * - * \deprecated This function is deprecated in favor of the function - * H5Aopen_by_idx(). + * \deprecation_note{H5Aopen_by_idx()} * * \details H5Aopen_idx() opens an attribute which is attached to the * object specified with \p loc_id . The location object may be @@ -1198,8 +1074,7 @@ H5_DLL hid_t H5Aopen_idx(hid_t loc_id, unsigned idx); * * \return \hid_tv{attribute} * - * \deprecated This function is deprecated in favor of the function - * H5Aopen_by_name(). + * \deprecation_note{H5Aopen_by_name()} * * \details H5Aopen_name() opens an attribute specified by its name, * \p name, which is attached to the object specified with diff --git a/src/H5B2private.h b/src/H5B2private.h index de823e4..1a7d0c8 100644 --- a/src/H5B2private.h +++ b/src/H5B2private.h @@ -29,7 +29,7 @@ #include "H5B2public.h" /* Private headers needed by this file */ -#include "H5Fprivate.h" /* File access */ +#include "H5Fprivate.h" /* File access */ /**************************/ /* Library Private Macros */ diff --git a/src/H5Cpkg.h b/src/H5Cpkg.h index 69ac9b1..ac1d018 100644 --- a/src/H5Cpkg.h +++ b/src/H5Cpkg.h @@ -1030,11 +1030,11 @@ struct H5C_t * * from the H5C__DLL_PRE_REMOVE_SC macro. With the addition of the * epoch markers used in the age out based cache size reduction algorithm, - * this invarient need not hold, as the epoch markers are of size 0. + * this invariant need not hold, as the epoch markers are of size 0. * * One could argue that I should have given the epoch markers a positive * size, but this would break the index_size = LRU_list_size + pl_size - * + pel_size invarient. + * + pel_size invariant. * * Alternatively, I could pass the current decr_mode in to the macro, * and just skip the check whenever epoch markers may be in use. @@ -1419,23 +1419,6 @@ if ( ( (entry_ptr) == NULL ) || \ * H5C__UPDATE_CACHE_HIT_RATE_STATS(), which is always active as * the cache hit rate stats are always collected and available. * - * Changes: - * - * JRM -- 3/21/06 - * Added / updated macros for pinned entry related stats. - * - * JRM -- 8/9/06 - * More pinned entry stats related updates. - * - * JRM -- 3/31/07 - * Updated H5C__UPDATE_STATS_FOR_PROTECT() to keep stats on - * read and write protects. - * - * MAM -- 1/15/09 - * Created H5C__UPDATE_MAX_INDEX_SIZE_STATS to contain - * common code within macros that update the maximum - * index, clean_index, and dirty_index statistics fields. - * ***********************************************************************/ #define H5C__UPDATE_CACHE_HIT_RATE_STATS(cache_ptr, hit) \ @@ -2218,8 +2201,8 @@ if ( (cache_ptr)->index_size != \ * Function: H5C__REMOVE_ENTRY_FROM_SLIST * * Purpose: Remove the specified instance of H5C_cache_entry_t from the - * index skip list in the specified instance of H5C_t. Update - * the associated length and size fields. + * index skip list in the specified instance of H5C_t. Update + * the associated length and size fields. * * Return: N/A * @@ -2227,20 +2210,20 @@ if ( (cache_ptr)->index_size != \ * * Modifications: * - * JRM -- 7/21/04 - * Updated function for the addition of the hash table. + * JRM -- 7/21/04 + * Updated function for the addition of the hash table. * - * JRM - 7/27/04 - * Converted from the function H5C_remove_entry_from_tree() - * to the macro H5C__REMOVE_ENTRY_FROM_TREE in the hopes of - * wringing a little more performance out of the cache. + * JRM - 7/27/04 + * Converted from the function H5C_remove_entry_from_tree() + * to the macro H5C__REMOVE_ENTRY_FROM_TREE in the hopes of + * wringing a little more performance out of the cache. * - * QAK -- 11/27/04 - * Switched over to using skip list routines. + * QAK -- 11/27/04 + * Switched over to using skip list routines. * - * JRM -- 3/28/07 - * Updated sanity checks for the new is_read_only and - * ro_ref_count fields in H5C_cache_entry_t. + * JRM -- 3/28/07 + * Updated sanity checks for the new is_read_only and + * ro_ref_count fields in H5C_cache_entry_t. * *------------------------------------------------------------------------- */ @@ -2276,7 +2259,7 @@ if ( (cache_ptr)->index_size != \ * Function: H5C__UPDATE_SLIST_FOR_SIZE_CHANGE * * Purpose: Update cache_ptr->slist_size for a change in the size of - * and entry in the slist. + * and entry in the slist. * * Return: N/A * @@ -2284,15 +2267,15 @@ if ( (cache_ptr)->index_size != \ * * Modifications: * - * JRM -- 8/27/06 - * Added the H5C_DO_SANITY_CHECKS version of the macro. + * JRM -- 8/27/06 + * Added the H5C_DO_SANITY_CHECKS version of the macro. * - * This version maintains the slist_size_increase field - * that are used in sanity checks in the flush routines. + * This version maintains the slist_size_increase field + * that are used in sanity checks in the flush routines. * - * All this is needed as the fractal heap needs to be - * able to dirty, resize and/or move entries during the - * flush. + * All this is needed as the fractal heap needs to be + * able to dirty, resize and/or move entries during the + * flush. * *------------------------------------------------------------------------- */ @@ -2405,16 +2388,16 @@ if ( (cache_ptr)->index_size != \ /* modified LRU specific code */ \ \ /* remove the entry from the LRU list, and re-insert it at the head.\ - */ \ + */ \ \ H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ /* Use the dirty flag to infer whether the entry is on the clean or \ @@ -2468,16 +2451,16 @@ if ( (cache_ptr)->index_size != \ /* modified LRU specific code */ \ \ /* remove the entry from the LRU list, and re-insert it at the head \ - */ \ + */ \ \ H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ /* End modified LRU specific code. */ \ @@ -2660,28 +2643,28 @@ if ( (cache_ptr)->index_size != \ /* modified LRU specific code */ \ \ /* remove the entry from the LRU list, and re-insert it at the \ - * head. \ - */ \ + * head. \ + */ \ \ H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ /* since the entry is being flushed or cleared, one would think \ - * that it must be dirty -- but that need not be the case. Use the \ - * dirty flag to infer whether the entry is on the clean or dirty \ - * LRU list, and remove it. Then insert it at the head of the \ - * clean LRU list. \ + * that it must be dirty -- but that need not be the case. Use the \ + * dirty flag to infer whether the entry is on the clean or dirty \ + * LRU list, and remove it. Then insert it at the head of the \ + * clean LRU list. \ * \ * The function presumes that a dirty entry will be either cleared \ - * or flushed shortly, so it is OK if we put a dirty entry on the \ - * clean LRU list. \ + * or flushed shortly, so it is OK if we put a dirty entry on the \ + * clean LRU list. \ */ \ \ if ( (entry_ptr)->is_dirty ) { \ @@ -2722,17 +2705,17 @@ if ( (cache_ptr)->index_size != \ /* modified LRU specific code */ \ \ /* remove the entry from the LRU list, and re-insert it at the \ - * head. \ - */ \ + * head. \ + */ \ \ H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ /* End modified LRU specific code. */ \ @@ -2816,7 +2799,7 @@ if ( (cache_ptr)->index_size != \ \ H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ /* insert the entry at the head of the clean or dirty LRU list as \ @@ -2857,7 +2840,7 @@ if ( (cache_ptr)->index_size != \ (cache_ptr)->pel_tail_ptr, \ (cache_ptr)->pel_len, \ (cache_ptr)->pel_size, (fail_val)) \ - \ + \ } else { \ \ /* modified LRU specific code */ \ @@ -2866,7 +2849,7 @@ if ( (cache_ptr)->index_size != \ \ H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ /* End modified LRU specific code. */ \ @@ -2935,12 +2918,12 @@ if ( (cache_ptr)->index_size != \ HDassert( !((entry_ptr)->is_read_only) ); \ HDassert( ((entry_ptr)->ro_ref_count) == 0 ); \ HDassert( (entry_ptr)->size > 0 ); \ - \ + \ if ( (entry_ptr)->is_pinned ) { \ \ H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->pel_head_ptr, \ - (cache_ptr)->pel_tail_ptr, \ - (cache_ptr)->pel_len, \ + (cache_ptr)->pel_tail_ptr, \ + (cache_ptr)->pel_len, \ (cache_ptr)->pel_size, (fail_val)) \ HDassert( (cache_ptr)->pel_len >= 0 ); \ \ @@ -2952,7 +2935,7 @@ if ( (cache_ptr)->index_size != \ \ H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ /* Similarly, remove the entry from the clean or dirty LRU list \ @@ -2998,12 +2981,12 @@ if ( (cache_ptr)->index_size != \ HDassert( !((entry_ptr)->is_read_only) ); \ HDassert( ((entry_ptr)->ro_ref_count) == 0 ); \ HDassert( (entry_ptr)->size > 0 ); \ - \ + \ if ( (entry_ptr)->is_pinned ) { \ \ H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->pel_head_ptr, \ - (cache_ptr)->pel_tail_ptr, \ - (cache_ptr)->pel_len, \ + (cache_ptr)->pel_tail_ptr, \ + (cache_ptr)->pel_len, \ (cache_ptr)->pel_size, (fail_val)) \ HDassert( (cache_ptr)->pel_len >= 0 ); \ \ @@ -3015,7 +2998,7 @@ if ( (cache_ptr)->index_size != \ \ H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ /* End modified LRU specific code. */ \ @@ -3066,20 +3049,20 @@ if ( (cache_ptr)->index_size != \ HDassert( (entry_ptr)->size > 0 ); \ \ if ( ! ( (entry_ptr)->is_pinned ) ) { \ - \ + \ /* modified LRU specific code */ \ \ /* remove the entry from the LRU list, and re-insert it at the head. \ - */ \ + */ \ \ H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ /* remove the entry from either the clean or dirty LUR list as \ @@ -3088,7 +3071,7 @@ if ( (cache_ptr)->index_size != \ if ( was_dirty ) { \ \ H5C__AUX_DLL_REMOVE((entry_ptr), \ - (cache_ptr)->dLRU_head_ptr, \ + (cache_ptr)->dLRU_head_ptr, \ (cache_ptr)->dLRU_tail_ptr, \ (cache_ptr)->dLRU_list_len, \ (cache_ptr)->dLRU_list_size, \ @@ -3097,34 +3080,34 @@ if ( (cache_ptr)->index_size != \ } else { \ \ H5C__AUX_DLL_REMOVE((entry_ptr), \ - (cache_ptr)->cLRU_head_ptr, \ + (cache_ptr)->cLRU_head_ptr, \ (cache_ptr)->cLRU_tail_ptr, \ (cache_ptr)->cLRU_list_len, \ (cache_ptr)->cLRU_list_size, \ - (fail_val)) \ + (fail_val)) \ } \ \ /* insert the entry at the head of either the clean or dirty \ - * LRU list as appropriate. \ + * LRU list as appropriate. \ */ \ \ if ( (entry_ptr)->is_dirty ) { \ \ H5C__AUX_DLL_PREPEND((entry_ptr), \ - (cache_ptr)->dLRU_head_ptr, \ + (cache_ptr)->dLRU_head_ptr, \ (cache_ptr)->dLRU_tail_ptr, \ (cache_ptr)->dLRU_list_len, \ (cache_ptr)->dLRU_list_size, \ - (fail_val)) \ + (fail_val)) \ \ } else { \ \ H5C__AUX_DLL_PREPEND((entry_ptr), \ - (cache_ptr)->cLRU_head_ptr, \ + (cache_ptr)->cLRU_head_ptr, \ (cache_ptr)->cLRU_tail_ptr, \ (cache_ptr)->cLRU_list_len, \ (cache_ptr)->cLRU_list_size, \ - (fail_val)) \ + (fail_val)) \ } \ \ /* End modified LRU specific code. */ \ @@ -3144,20 +3127,20 @@ if ( (cache_ptr)->index_size != \ HDassert( (entry_ptr)->size > 0 ); \ \ if ( ! ( (entry_ptr)->is_pinned ) ) { \ - \ + \ /* modified LRU specific code */ \ \ /* remove the entry from the LRU list, and re-insert it at the head. \ - */ \ + */ \ \ H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ /* End modified LRU specific code. */ \ @@ -3211,43 +3194,43 @@ if ( (cache_ptr)->index_size != \ HDassert( ((entry_ptr)->ro_ref_count) == 0 ); \ HDassert( (entry_ptr)->size > 0 ); \ HDassert( new_size > 0 ); \ - \ + \ if ( (entry_ptr)->is_pinned ) { \ \ - H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->pel_len, \ - (cache_ptr)->pel_size, \ - (entry_ptr)->size, \ - (new_size)); \ - \ + H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->pel_len, \ + (cache_ptr)->pel_size, \ + (entry_ptr)->size, \ + (new_size)); \ + \ } else { \ \ /* modified LRU specific code */ \ \ - /* Update the size of the LRU list */ \ + /* Update the size of the LRU list */ \ \ - H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->LRU_list_len, \ - (cache_ptr)->LRU_list_size, \ - (entry_ptr)->size, \ - (new_size)); \ + H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_size, \ + (entry_ptr)->size, \ + (new_size)); \ \ /* Similarly, update the size of the clean or dirty LRU list as \ - * appropriate. At present, the entry must be clean, but that \ - * could change. \ + * appropriate. At present, the entry must be clean, but that \ + * could change. \ */ \ \ if ( (entry_ptr)->is_dirty ) { \ \ - H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->dLRU_list_len, \ - (cache_ptr)->dLRU_list_size, \ - (entry_ptr)->size, \ - (new_size)); \ + H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->dLRU_list_len, \ + (cache_ptr)->dLRU_list_size, \ + (entry_ptr)->size, \ + (new_size)); \ \ } else { \ \ - H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->cLRU_list_len, \ - (cache_ptr)->cLRU_list_size, \ - (entry_ptr)->size, \ - (new_size)); \ + H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->cLRU_list_len, \ + (cache_ptr)->cLRU_list_size, \ + (entry_ptr)->size, \ + (new_size)); \ } \ \ /* End modified LRU specific code. */ \ @@ -3270,21 +3253,21 @@ if ( (cache_ptr)->index_size != \ \ if ( (entry_ptr)->is_pinned ) { \ \ - H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->pel_len, \ - (cache_ptr)->pel_size, \ - (entry_ptr)->size, \ - (new_size)); \ + H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->pel_len, \ + (cache_ptr)->pel_size, \ + (entry_ptr)->size, \ + (new_size)); \ \ } else { \ \ /* modified LRU specific code */ \ \ - /* Update the size of the LRU list */ \ + /* Update the size of the LRU list */ \ \ - H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->LRU_list_len, \ - (cache_ptr)->LRU_list_size, \ - (entry_ptr)->size, \ - (new_size)); \ + H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_size, \ + (entry_ptr)->size, \ + (new_size)); \ \ /* End modified LRU specific code. */ \ } \ @@ -3344,39 +3327,39 @@ if ( (cache_ptr)->index_size != \ (cache_ptr)->pel_size, (fail_val)) \ HDassert( (cache_ptr)->pel_len >= 0 ); \ \ - /* modified LRU specific code */ \ + /* modified LRU specific code */ \ \ - /* insert the entry at the head of the LRU list. */ \ + /* insert the entry at the head of the LRU list. */ \ \ - H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \ - (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ - (cache_ptr)->LRU_list_size, (fail_val)) \ + H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \ + (cache_ptr)->LRU_tail_ptr, \ + (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_size, (fail_val)) \ \ - /* Similarly, insert the entry at the head of either the clean \ - * or dirty LRU list as appropriate. \ - */ \ + /* Similarly, insert the entry at the head of either the clean \ + * or dirty LRU list as appropriate. \ + */ \ \ - if ( (entry_ptr)->is_dirty ) { \ + if ( (entry_ptr)->is_dirty ) { \ \ - H5C__AUX_DLL_PREPEND((entry_ptr), \ - (cache_ptr)->dLRU_head_ptr, \ - (cache_ptr)->dLRU_tail_ptr, \ - (cache_ptr)->dLRU_list_len, \ - (cache_ptr)->dLRU_list_size, \ - (fail_val)) \ + H5C__AUX_DLL_PREPEND((entry_ptr), \ + (cache_ptr)->dLRU_head_ptr, \ + (cache_ptr)->dLRU_tail_ptr, \ + (cache_ptr)->dLRU_list_len, \ + (cache_ptr)->dLRU_list_size, \ + (fail_val)) \ \ - } else { \ + } else { \ \ - H5C__AUX_DLL_PREPEND((entry_ptr), \ - (cache_ptr)->cLRU_head_ptr, \ - (cache_ptr)->cLRU_tail_ptr, \ - (cache_ptr)->cLRU_list_len, \ - (cache_ptr)->cLRU_list_size, \ - (fail_val)) \ - } \ + H5C__AUX_DLL_PREPEND((entry_ptr), \ + (cache_ptr)->cLRU_head_ptr, \ + (cache_ptr)->cLRU_tail_ptr, \ + (cache_ptr)->cLRU_list_len, \ + (cache_ptr)->cLRU_list_size, \ + (fail_val)) \ + } \ \ - /* End modified LRU specific code. */ \ + /* End modified LRU specific code. */ \ \ } /* H5C__UPDATE_RP_FOR_UNPIN */ diff --git a/src/H5Cprivate.h b/src/H5Cprivate.h index ce03ba0..d7a1949 100644 --- a/src/H5Cprivate.h +++ b/src/H5Cprivate.h @@ -44,7 +44,8 @@ #define H5C_MAX_ENTRY_SIZE ((size_t)(32 * 1024 * 1024)) /* H5C_COLLECT_CACHE_STATS controls overall collection of statistics - * on cache activity. In general, this #define should be set to 0. + * on cache activity. In general, this #define should be set to 1 in + * debug mode, and 0 in production mode.. */ #define H5C_COLLECT_CACHE_STATS 0 diff --git a/src/H5Dpkg.h b/src/H5Dpkg.h index 31c0bd1..04e02e9 100644 --- a/src/H5Dpkg.h +++ b/src/H5Dpkg.h @@ -78,17 +78,17 @@ typedef struct H5D_type_info_t { hid_t dst_type_id; /* Destination datatype ID */ /* Computed/derived values */ - size_t src_type_size; /* Size of source type */ - size_t dst_type_size; /* Size of destination type*/ + size_t src_type_size; /* Size of source type */ + size_t dst_type_size; /* Size of destination type */ size_t max_type_size; /* Size of largest source/destination type */ hbool_t is_conv_noop; /* Whether the type conversion is a NOOP */ hbool_t is_xform_noop; /* Whether the data transform is a NOOP */ const H5T_subset_info_t *cmpd_subset; /* Info related to the compound subset conversion functions */ H5T_bkg_t need_bkg; /* Type of background buf needed */ - size_t request_nelmts; /* Requested strip mine */ - uint8_t * tconv_buf; /* Datatype conv buffer */ + size_t request_nelmts; /* Requested strip mine */ + uint8_t * tconv_buf; /* Datatype conv buffer */ hbool_t tconv_buf_allocated; /* Whether the type conversion buffer was allocated */ - uint8_t * bkg_buf; /* Background buffer */ + uint8_t * bkg_buf; /* Background buffer */ hbool_t bkg_buf_allocated; /* Whether the background buffer was allocated */ } H5D_type_info_t; @@ -385,7 +385,7 @@ typedef struct H5D_rdcc_t { struct H5D_rdcc_ent_t * head; /* Head of doubly linked list */ struct H5D_rdcc_ent_t * tail; /* Tail of doubly linked list */ size_t nbytes_used; /* Current cached raw data in bytes */ - int nused; /* Number of chunk slots in use */ + int nused; /* Number of chunk slots in use */ H5D_chunk_cached_t last; /* Cached copy of last chunk information */ struct H5D_rdcc_ent_t **slot; /* Chunk slots, each points to a chunk*/ H5SL_t * sel_chunks; /* Skip list containing information for each chunk selected */ @@ -404,7 +404,7 @@ typedef struct H5D_rdcdc_t { /* * A dataset is made of two layers, an H5D_t struct that is unique to - * each instance of an opened datset, and a shared struct that is only + * each instance of an opened dataset, and a shared struct that is only * created once for a given dataset. Thus, if a dataset is opened twice, * there will be two IDs and two H5D_t structs, both sharing one H5D_shared_t. */ diff --git a/src/H5Dpublic.h b/src/H5Dpublic.h index 5170f67..ed4fbc1 100644 --- a/src/H5Dpublic.h +++ b/src/H5Dpublic.h @@ -11,6 +11,12 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/* + * This file contains public declarations for the H5D module. + */ +#ifndef H5Dpublic_H +#define H5Dpublic_H + /**\defgroup H5D H5D * * Use the functions in this module to manage HDF5 datasets, including the @@ -19,14 +25,31 @@ * name or by a handle. Such handles can be obtained by either creating or * opening the dataset. * + * Typical stages in the HDF5 dataset life cycle are shown below in introductory + * examples. + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5D_examples.c create + * </td> + * <td> + * \snippet{lineno} H5D_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5D_examples.c update + * </td> + * <td> + * \snippet{lineno} H5D_examples.c delete + * </td> + * </tr> + * </table> + * */ -/* - * This file contains public declarations for the H5D module. - */ -#ifndef H5Dpublic_H -#define H5Dpublic_H - /* System headers needed by this file */ /* Public headers needed by this file */ @@ -62,12 +85,11 @@ * Values for the H5D_LAYOUT property */ typedef enum H5D_layout_t { - H5D_LAYOUT_ERROR = -1, - - H5D_COMPACT = 0, /**< raw data is very small */ - H5D_CONTIGUOUS = 1, /**< the default */ - H5D_CHUNKED = 2, /**< slow and fancy */ - H5D_NLAYOUTS = 3 /**< this one must be last! */ + H5D_LAYOUT_ERROR = -1, /**< error */ + H5D_COMPACT = 0, /**< raw data is small (< 64KB) */ + H5D_CONTIGUOUS = 1, /**< contiguous layout */ + H5D_CHUNKED = 2, /**< chunked or tiled layout */ + H5D_NLAYOUTS = 3 /**< this one must be last! */ } H5D_layout_t; //! <!-- [H5D_layout_t_snip] --> @@ -85,11 +107,11 @@ typedef enum H5D_chunk_index_t { * Values for the space allocation time property */ typedef enum H5D_alloc_time_t { - H5D_ALLOC_TIME_ERROR = -1, - H5D_ALLOC_TIME_DEFAULT = 0, - H5D_ALLOC_TIME_EARLY = 1, - H5D_ALLOC_TIME_LATE = 2, - H5D_ALLOC_TIME_INCR = 3 + H5D_ALLOC_TIME_ERROR = -1, /**< Error */ + H5D_ALLOC_TIME_DEFAULT = 0, /**< Default (layout dependent) */ + H5D_ALLOC_TIME_EARLY = 1, /**< Allocate on creation */ + H5D_ALLOC_TIME_LATE = 2, /**< Allocate on first write */ + H5D_ALLOC_TIME_INCR = 3 /**< Allocate incrementally (by chunk) */ } H5D_alloc_time_t; //! <!-- [H5D_alloc_time_t_snip] --> @@ -98,10 +120,11 @@ typedef enum H5D_alloc_time_t { * Values for the status of space allocation */ typedef enum H5D_space_status_t { - H5D_SPACE_STATUS_ERROR = -1, - H5D_SPACE_STATUS_NOT_ALLOCATED = 0, - H5D_SPACE_STATUS_PART_ALLOCATED = 1, - H5D_SPACE_STATUS_ALLOCATED = 2 + H5D_SPACE_STATUS_ERROR = -1, /**< Error */ + H5D_SPACE_STATUS_NOT_ALLOCATED = 0, /**< Space has not been allocated for this dataset. */ + H5D_SPACE_STATUS_PART_ALLOCATED = 1, /**< Space has been partially allocated for this dataset. + (Used only for datasets with chunked storage.) */ + H5D_SPACE_STATUS_ALLOCATED = 2 /**< Space has been allocated for this dataset. */ } H5D_space_status_t; //! <!-- [H5D_space_status_t_snip] --> @@ -110,10 +133,10 @@ typedef enum H5D_space_status_t { * Values for time of writing fill value property */ typedef enum H5D_fill_time_t { - H5D_FILL_TIME_ERROR = -1, - H5D_FILL_TIME_ALLOC = 0, - H5D_FILL_TIME_NEVER = 1, - H5D_FILL_TIME_IFSET = 2 + H5D_FILL_TIME_ERROR = -1, /**< Error */ + H5D_FILL_TIME_ALLOC = 0, /**< Fill on allocation */ + H5D_FILL_TIME_NEVER = 1, /**< Never write fill values */ + H5D_FILL_TIME_IFSET = 2 /**< Fill if fill-value was set */ } H5D_fill_time_t; //! <!-- [H5D_fill_time_t_snip] --> @@ -122,10 +145,10 @@ typedef enum H5D_fill_time_t { * Values for fill value status */ typedef enum H5D_fill_value_t { - H5D_FILL_VALUE_ERROR = -1, - H5D_FILL_VALUE_UNDEFINED = 0, - H5D_FILL_VALUE_DEFAULT = 1, - H5D_FILL_VALUE_USER_DEFINED = 2 + H5D_FILL_VALUE_ERROR = -1, /**< Error */ + H5D_FILL_VALUE_UNDEFINED = 0, /**< No fill value defined */ + H5D_FILL_VALUE_DEFAULT = 1, /**< Default fill-value */ + H5D_FILL_VALUE_USER_DEFINED = 2 /**< User-defined fill-value */ } H5D_fill_value_t; //! <!-- [H5D_fill_value_t_snip] --> @@ -223,7 +246,7 @@ typedef herr_t (*H5D_gather_func_t)(const void *dst_buf, size_t dst_buf_bytes_us * \brief Creates a new dataset and links it into the file * * \fgdta_loc_id - * \param[in] name Name of the dataset to create + * \param[in] name Name of the dataset to create * \type_id * \space_id * \lcpl_id @@ -248,13 +271,6 @@ typedef herr_t (*H5D_gather_func_t)(const void *dst_buf, size_t dst_buf_bytes_us * \p name may be either an absolute path in the file or a relative * path from \p loc_id naming the dataset. * - * \p dtype_id specifies the datatype of each data element as stored - * in the file. If \p dtype_id is either a fixed-length or - * variable-length string, it is important to set the string length - * when defining the datatype. String datatypes are derived from - * #H5T_C_S1 (or #H5T_FORTRAN_S1 for Fortran codes), which defaults - * to 1 character in size. - * * If \p dtype_id is a committed datatype, and if the file location * associated with the committed datatype is different from the * file location where the dataset will be created, the datatype @@ -262,19 +278,19 @@ typedef herr_t (*H5D_gather_func_t)(const void *dst_buf, size_t dst_buf_bytes_us * * The link creation property list, \p lcpl_id, governs creation * of the link(s) by which the new dataset is accessed and the - * creation of any * intermediate groups that may be missing. + * creation of any intermediate groups that may be missing. * * The datatype and dataspace properties and the dataset creation * and access property lists are attached to the dataset, so the * caller may derive new datatypes, dataspaces, and creation and * access properties from the old ones and reuse them in calls to * create additional datasets. Once created, the dataset can be - * read from or written to. Reading data from a datatset that was + * read from or written to. Reading data from a dataset that was * not previously written, the HDF5 library will return default * or user-defined fill values. * - * To conserve and release resources, the dataset should be closed - * when access is no longer required. + * \par Example + * \snippet H5D_examples.c create * * \since 1.8.0 * @@ -313,34 +329,14 @@ H5_DLL hid_t H5Dcreate2(hid_t loc_id, const char *name, hid_t type_id, hid_t spa * the file, which may differ from the datatype and dataspace * in application memory. * - * Dataset creation property list and dataset access creation - * property list are specified by \p dcpl_id and \p dapl_id. - * * H5Dcreate_anon() returns a new dataset identifier. Using * this identifier, the new dataset must be linked into the * HDF5 file structure with H5Olink() or it will be deleted - * from the file when the file is closed. - * - * See H5Dcreate2() for further details and considerations on - * the use of H5Dcreate2() and H5Dcreate_anon(). - * - * The differences between this function and H5Dcreate2() are - * as follows: - * \li H5Dcreate_anon() explicitly includes a dataset access property - * list. H5Dcreate() always uses default dataset access properties. - * - * \li H5Dcreate_anon() neither provides the new dataset’s name nor - * links it into the HDF5 file structure; those actions must be - * performed separately through a call to H5Olink(), which offers - * greater control over linking. - * - * A dataset created with this function should be closed with - * H5Dclose() when the dataset is no longer needed so that resource - * leaks will not develop. + * when the file is closed. * * \since 1.8.0 * - * \see H5Olink(), H5Dcreate(), Using Identifiers + * \see H5Olink(), H5Dcreate() * */ H5_DLL hid_t H5Dcreate_anon(hid_t loc_id, hid_t type_id, hid_t space_id, hid_t dcpl_id, hid_t dapl_id); @@ -366,12 +362,6 @@ H5_DLL hid_t H5Dcreate_anon(hid_t loc_id, hid_t type_id, hid_t space_id, hid_t d * specified then the dataset will be opened at the location * where the attribute, dataset, or named datatype is attached. * - * The dataset access property list, \p dapl_id, provides - * information regarding access to the dataset. - * - * To conserve and release resources, the dataset should be closed - * when access is no longer required. - * * \since 1.8.0 * * \see H5Dcreate2(), H5Dclose() @@ -397,6 +387,9 @@ H5_DLL hid_t H5Dopen2(hid_t loc_id, const char *name, hid_t dapl_id); * be released with H5Sclose() when the identifier is no longer * needed so that resource leaks will not occur. * + * \par Example + * \snippet H5D_examples.c update + * * \see H5Sclose() * */ @@ -405,7 +398,19 @@ H5_DLL hid_t H5Dget_space(hid_t dset_id); /** * -------------------------------------------------------------------------- * \ingroup H5D - * \todo Document this function! + * + * \brief Determines whether space has been allocated for a dataset + * + * \dset_id + * \param[out] allocation Space allocation status + * + * \return \herr_t + * + * \details H5Dget_space_status() determines whether space has been allocated + * for the dataset \p dset_id. + * + * \since 1.6.0 + * */ H5_DLL herr_t H5Dget_space_status(hid_t dset_id, H5D_space_status_t *allocation); @@ -424,27 +429,7 @@ H5_DLL herr_t H5Dget_space_status(hid_t dset_id, H5D_space_status_t *allocation) * * If a dataset has a named datatype, then an identifier to the * opened datatype is returned. Otherwise, the returned datatype - * is read-only. If atomization of the datatype fails, then the - * datatype is closed. - * - * A datatype identifier returned from this function should be - * released with H5Tclose() when the identifier is no longer - * needed to prevent resource leaks. - * - * \note Datatype Identifiers - * - * Please note that the datatype identifier is actually an object - * identifier or a handle returned from opening the datatype. It - * is not persistent and its value can be different from one HDF5 - * session to the next. - * - * H5Tequal() can be used to compare datatypes. - * - * HDF5 High Level APIs that may also be of interest are: - * - * H5LTdtype_to_text() creates a text description of a - * datatype. H5LTtext_to_dtype() creates an HDF5 datatype - * given a text description. + * is read-only. * */ H5_DLL hid_t H5Dget_type(hid_t dset_id); @@ -464,9 +449,6 @@ H5_DLL hid_t H5Dget_type(hid_t dset_id); * a copy of the dataset creation property list associated with * the dataset specified by \p dset_id. * - * The creation property list identifier should be released - * with H5Pclose() to prevent resource leaks. - * */ H5_DLL hid_t H5Dget_create_plist(hid_t dset_id); @@ -500,10 +482,6 @@ H5_DLL hid_t H5Dget_create_plist(hid_t dset_id); * All link access properties in the returned list will be set * to the default values. * - * The access property list identifier should be released with - * H5Pclose() when the identifier is no longer needed so that - * resource leaks will not develop. - * * \since 1.8.3 * */ @@ -522,11 +500,8 @@ H5_DLL hid_t H5Dget_access_plist(hid_t dset_id); * \details H5Dget_storage_size() returns the amount of storage, * in bytes, that is allocated in the file for the raw data of * the dataset specified by \p dset_id. - * - * \note The amount of storage in this case is the storage - * allocated in the written file, which will typically differ - * from the space required to hold a dataset in working memory. - * + * H5Dget_storage_size() reports only the space required to store + * the dataset elements, excluding any metadata. * \li For contiguous datasets, the returned size equals the current * allocated size of the raw data. * \li For unfiltered chunked datasets, the returned size is the @@ -536,21 +511,19 @@ H5_DLL hid_t H5Dget_access_plist(hid_t dset_id); * compression filter is in use, H5Dget_storage_size() will return * the total space required to store the compressed chunks. * - * H5Dget_storage_size() reports only the space required to store - * the data, not including that of any metadata. + * \note Note that H5Dget_storage_size() is not generally an + * appropriate function to use when determining the amount + * of memory required to work with a dataset. In such + * circumstances, you must determine the number of data + * points in a dataset and the size of an individual dataset + * element. H5Sget_simple_extent_npoints() and H5Tget_size() + * can be used to calculate that amount. * - * \attention H5Dget_storage_size() does not differentiate between 0 (zero), + * \warning H5Dget_storage_size() does not differentiate between 0 (zero), * the value returned for the storage size of a dataset * with no stored values, and 0 (zero), the value returned to * indicate an error. * - * \note Note that H5Dget_storage_size() is not generally an - * appropriate function to use when determining the amount - * of memory required to work with a dataset. In such - * circumstances, you must determine the number of data - * points in a dataset and the size of an individual data - * element. H5Sget_simple_extent_npoints() and H5Tget_size() - * can be used to get that information. * */ H5_DLL hsize_t H5Dget_storage_size(hid_t dset_id); @@ -588,7 +561,7 @@ H5_DLL herr_t H5Dget_chunk_storage_size(hid_t dset_id, const hsize_t *offset, hs * * \dset_id * - * \return Returns the offset in bytes; otherwise, returns \c HADDR_UNDEF, + * \return Returns the offset in bytes; otherwise, returns #HADDR_UNDEF, * a negative value. * * \details H5Dget_offset() returns the address in the file of @@ -637,9 +610,8 @@ H5_DLL haddr_t H5Dget_offset(hid_t dset_id); * used for the memory dataspace and the selection defined with \p * file_space_id is used for the selection within that dataspace. * - * If raw data storage space has not been allocated for the dataset - * and a fill value has been defined, the returned buffer \p buf - * is filled with the fill value. + * The number of elements selected in the memory dataspace \Emph{must} + * be equal to the number of elements selected in the file dataspace. * * The behavior of the library for the various combinations of * valid dataspace identifiers and #H5S_ALL for the \p mem_space_id @@ -684,14 +656,12 @@ H5_DLL haddr_t H5Dget_offset(hid_t dset_id); * </tr> * </table> * - * \details Setting an #H5S_ALL selection indicates that the entire - * dataspace, as defined by the current dimensions of a dataspace, - * will be selected. The number of elements selected in the memory - * dataspace must match the number of elements selected in the - * file dataspace. + * \note If no storage space was allocated for the dataset + * and a fill value is defined, the returned buffer \p buf + * is filled with the fill value. * - * \p dxpl_id can be the constant #H5P_DEFAULT, in which case the - * default data transfer properties are used. + * \par Example + * \snippet H5D_examples.c read * */ H5_DLL herr_t H5Dread(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, @@ -795,6 +765,8 @@ H5_DLL herr_t H5Dread(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_ * time if the dataset's fill time is set to #H5D_FILL_TIME_IFSET * or #H5D_FILL_TIME_ALLOC. * + * \par_compr_note + * * \attention If a dataset's storage layout is 'compact', care must be * taken when writing data to the dataset in parallel. A compact * dataset's raw data is cached in memory and may be flushed @@ -802,6 +774,9 @@ H5_DLL herr_t H5Dread(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_ * applications should always attempt to write identical data to * the dataset from all processes. * + * \par Example + * \snippet H5D_examples.c update + * * \see H5Pset_fill_time(), H5Pset_alloc_time() * */ @@ -830,52 +805,9 @@ H5_DLL herr_t H5Dwrite(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid * in the memory buffer \p buf, executing the callback function * \p op once for each such data element. * - * The prototype of the callback function \p op is as follows - * (as defined in the source code file H5Lpublic.h): - * \snippet this H5D_operator_t_snip - * The parameters of this callback function are: - * - * <table> - * <tr><td>\c elem</td> - * <td><tt>[in,out]</tt></td> - * <td>Pointer to the memory buffer containing the current - * data element</td></tr> - * <tr><td>\c type_id</td> - * <td><tt>[in]</tt></td> - * <td>Datatype identifier of the elements stored in elem</td></tr> - * <tr><td>\c ndim</td> - * <td><tt>[in]</tt></td> - * <td>Number of dimensions for the point array</td></tr> - * <tr><td>\c point</td> - * <td><tt>[in]</tt></td> - * <td>Array containing the location of the element within - * the original dataspace</td></tr> - * <tr><td>\c operator_data</td> - * <td><tt>[in,out]</tt></td> - * <td>Pointer to any user-defined data associated with the - * operation</td></tr> - * </table> - * - * The possible return values from the callback function, and - * the effect ofeach,are as follows: - * - * \li Zero causes the iterator to continue, returning zero - * when all data elements have been processed. - * \li A positive value causes the iterator to immediately - * return that positive value, indicating short-circuit success. - * \li A negative value causes the iterator to immediately return - * that value, indicating failure. - * - * The \p operator_data parameter is a user-defined pointer to - * the data required to process dataset elements in the course - * of the iteration. If operator needs to pass data back to the - * application, such data can be returned in this same buffer. This - * pointer is passed back to each step of the iteration in the - * operator callback function’s operator_data parameter. - * - * Unlike other HDF5 iterators, this iteration operation cannot - * be restarted at the point of exit; a second H5Diterate() - * call will always restart at the beginning. + * \attention Unlike other HDF5 iterators, this iteration operation cannot + * be restarted at the point of exit; a second H5Diterate() + * call will always restart at the beginning. * * * \since 1.10.2 @@ -959,30 +891,25 @@ H5_DLL herr_t H5Dvlen_get_buf_size(hid_t dset_id, hid_t type_id, hid_t space_id, * * \return \herr_t * - * \details H5Dfill() fills the dataspace selection in memory, \p space_id, + * \details H5Dfill() fills the dataspace selection, \p space_id, in memory * with the fill value specified in \p fill. If \p fill is NULL, * a fill value of 0 (zero) is used. * * \p fill_type_id specifies the datatype of the fill value. - * \p buf specifies the buffer in which the dataspace elements - * will be written. - * \p buf_type_id specifies the datatype of those data elements. + * \p buf specifies the buffer in which the fill elements + * will be written. \p buf_type_id specifies the datatype of + * those data elements. * * \note Note that if the fill value datatype differs from the memory - * buffer datatype, the fill value will be converted to the memory - * buffer datatype before filling the selection. + * buffer datatype, the fill value will be converted to the memory + * buffer datatype before filling the selection. * * \note Applications sometimes write data only to portions of an - * allocated dataset. It is often useful in such cases to fill - * the unused space with a known fill value. See the following - * function for more information: - * - H5Pset_fill_value() - * - H5Pget_fill_value() - * - H5Pfill_value_defined() - * - H5Pset_fill_time() - * - H5Pget_fill_time() - * - H5Pcreate() - * - H5Pcreate_anon() + * allocated dataset. It is often useful in such cases to fill + * the unused space with a known fill value. + * + * \see H5Pset_fill_value(), H5Pget_fill_value(), H5Pfill_value_defined(), + * H5Pset_fill_time(), H5Pget_fill_time(), H5Pcreate(), H5Dcreate_anon() * */ H5_DLL herr_t H5Dfill(const void *fill, hid_t fill_type_id, void *buf, hid_t buf_type_id, hid_t space_id); @@ -1029,22 +956,21 @@ H5_DLL herr_t H5Dfill(const void *fill, hid_t fill_type_id, void *buf, hid_t buf * - If the dataset’s fill time is set to #H5D_FILL_TIME_ALLOC * (see H5Pset_alloc_time()) * - * \note - * \li If the sizes specified in \p size array are smaller than - * the dataset’s current dimension sizes, H5Dset_extent() will reduce - * the dataset’s dimension sizes to the specified values. It is the - * user application’s responsibility to ensure that valuable data is - * not lost as H5Dset_extent() does not check. + * \note If the sizes specified in \p size array are smaller than the dataset’s + * current dimension sizes, H5Dset_extent() will reduce the dataset’s + * dimension sizes to the specified values. It is the user application’s + * responsibility to ensure that valuable data is not lost as + * H5Dset_extent() does not check. * - * \li Except for external datasets, H5Dset_extent() is for use with - * chunked datasets only, not contiguous datasets. + * \note Except for external datasets, H5Dset_extent() is for use with + * chunked datasets only, not contiguous datasets. * - * \li A call to H5Dset_extent() affects the dataspace of a dataset. - * If a dataspace handle was opened for a dataset prior to a call to - * H5Dset_extent() then that dataspace handle will no longer reflect - * the correct dataspace extent of the dataset. H5Dget_space() must - * be called (after closing the previous handle) to obtain the current - * dataspace extent. + * \note A call to H5Dset_extent() affects the dataspace of a dataset. If a + * dataspace handle was opened for a dataset prior to a call to + * H5Dset_extent() then that dataspace handle will no longer reflect the + * correct dataspace extent of the dataset. H5Dget_space() must be called + * (after closing the previous handle) to obtain the current dataspace + * extent. * * \since 1.8.0 * @@ -1082,40 +1008,7 @@ H5_DLL herr_t H5Dset_extent(hid_t dset_id, const hsize_t size[]); * * To retrieve the data to be scattered, H5Dscatter() repeatedly * calls \p op, which should return a valid source buffer, until - * enough data to fill the selection has been retrieved. The - * prototype of the callback function \p op is as follows (as - * defined in the source code file H5Dpublic.h): - * \snippet this H5D_scatter_func_t_snip - * The parameters of this callback function are described below: - * - * <table> - * <tr><td>\c src_buf</td> - * <td><tt>[out]</tt></td> - * <td>Pointer to the buffer holding the next set of elements to - * scatter. On entry, the value of where \c src_buf points to - * is undefined. The callback function should set \c src_buf - * to point to the next set of elements.</td></tr> - * <tr><td>\c src_buf_bytes_used</td> - * <td><tt>[out]</tt></td> - * <td>Pointer to the number of valid bytes in \c src_buf. On - * entry, the value where \c src_buf_bytes_used points to is - * undefined. The callback function should set - * \c src_buf_bytes_used to the of valid bytes in \c src_buf. - * This number must be a multiple of the datatype size. - * </td></tr> - * <tr><td>\c op_data</td> - * <td><tt>[in,out]</tt></td> - * <td>User-defined pointer to data required by the callback - * function. A pass-through of the \c op_data pointer provided - * with the H5Dscatter() function call.</td></tr> - * </table> - * - * The callback function should always return at least one - * element in \p src_buf, and must not return more elements - * than are remaining to be scattered. This function will be - * repeatedly called until all elements to be scattered have - * been returned. The callback function should return zero (0) - * to indicate success, and a negative value to indicate failure. + * enough data to fill the selection has been retrieved. * * \since 1.10.2 * @@ -1167,27 +1060,9 @@ H5_DLL herr_t H5Dscatter(H5D_scatter_func_t op, void *op_data, hid_t type_id, hi * If no callback function is provided, H5Dgather() simply gathers * the data into \p dst_buf and returns. If a callback function is * provided, H5Dgather() repeatedly gathers up to \p dst_buf_size - * bytes to process the serialized data. The prototype of the - * callback function \p op is as follows (as defined in the source - * code file H5Dpublic.h): - * \snippet this H5D_gather_func_t_snip - * The parameters of this callback function are described in the - * table below. - * <table> - * <tr><td>\c dst_buf</td> - * <td>Pointer to the destination buffer which has been filled - * with the next set of elements gathered. This will always be - * identical to the \p dst_buf passed to H5Dgather().</td></tr> - * <tr><td>\c dst_buf_bytes_used</td> - * <td>Pointer to the number of valid bytes in \p dst_buf. - * This number must be a multiple of the datatype - * size.</td></tr> - * <tr><td>\c op_data</td> - * <td>User-defined pointer to data required by the callback - * function; a pass-through of the \p op_data pointer - * provided with the H5Dgather() function call.</td></tr> - * </table> - * The callback function should process, store, or otherwise, + * bytes to process the serialized data. + * + * The callback function \p op should process, store, or otherwise, * make use of the data returned in \p dst_buf before it returns, * because the buffer will be overwritten unless it is the last * call to the callback. This function will be repeatedly called @@ -1211,11 +1086,11 @@ H5_DLL herr_t H5Dgather(hid_t src_space_id, const void *src_buf, hid_t type_id, * * \return \herr_t * - * \details H5Dclose() ends access to a dataset specified by \p dset_id - * and releases resources used by it. + * \details H5Dclose() terminates access to a dataset via the identifier + * \p dset_id and releases the underlying resources. * - * \attention Further use of a released dataset identifier is illegal; a - * function using such an identifier will generate an error. + * \par Example + * \snippet H5D_examples.c read * * \since 1.8.0 * @@ -1252,8 +1127,7 @@ H5_DLL herr_t H5Ddebug(hid_t dset_id); * * \return \hid_t{dataset} * - * \deprecated This function is deprecated in favor of the function H5Dcreate2() - * or the macro H5Dcreate(). + * \deprecation_note{H5Dcreate2() or the macro H5Dcreate()} * * \details H5Dcreate1() creates a data set with a name, \p name, in the * location specified by the identifier \p loc_id. \p loc_id may be a @@ -1319,8 +1193,7 @@ H5_DLL hid_t H5Dcreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t spa * * \return \hid_t{dataset} * - * \deprecated This function is deprecated in favor of the function H5Dopen2() - * or the macro H5Dopen(). + * \deprecation_note{H5Dopen2() or the macro H5Dopen()} * * \details H5Dopen1() opens an existing dataset for access at the location * specified by \p loc_id. \p loc_id may be a file, group, dataset, @@ -1350,10 +1223,10 @@ H5_DLL hid_t H5Dopen1(hid_t loc_id, const char *name); * * \return \herr_t * - * \deprecated This function is deprecated in favor of the function H5Dset_extent(). + * \deprecation_note{H5Dset_extent()} * * \details H5Dextend() verifies that the dataset is at least of size \p size, - * extending it if necessary. The dimensionality of size is the same as + * extending it if necessary. The length of \p size is the same as * that of the dataspace of the dataset being changed. * * This function can be applied to the following datasets: @@ -1373,7 +1246,7 @@ H5_DLL hid_t H5Dopen1(hid_t loc_id, const char *name); * the sizes specified in size. The function H5Dset_extent() must be * used if the dataset dimension sizes are are to be reduced. * - * \version 1.8.0 Function Function deprecated in this release. Parameter size + * \version 1.8.0 Function deprecated in this release. Parameter size * syntax changed to \Code{const hsize_t size[]} in this release. * */ diff --git a/src/H5Epublic.h b/src/H5Epublic.h index f95261a..9ec9d32 100644 --- a/src/H5Epublic.h +++ b/src/H5Epublic.h @@ -16,6 +16,26 @@ * Use the functions in this module to manage HDF5 error stacks and error * messages. * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5E_examples.c create + * </td> + * <td> + * \snippet{lineno} H5E_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5E_examples.c update + * </td> + * <td> + * \snippet{lineno} H5E_examples.c delete + * </td> + * </tr> + * </table> + * * \internal The \c FUNC_ENTER macro clears the error stack whenever an * interface function is entered. When an error is detected, an entry * is pushed onto the stack. As the functions unwind, additional @@ -68,9 +88,9 @@ typedef struct H5E_error2_t { hid_t cls_id; /**< Class ID */ hid_t maj_num; - /**< Major error ID */ + /**< Major error ID */ hid_t min_num; - /**< Minor error number */ + /**< Minor error number */ unsigned line; /**< Line in file where error occurs */ const char *func_name; @@ -726,12 +746,13 @@ typedef herr_t (*H5E_auto1_t)(void *client_data); * * \return \herr_t * + * \deprecated 1.8.0 Function H5Eclear() renamed to H5Eclear1() and deprecated + * in this release. + * * \details H5Eclear1() clears the error stack for the current thread.\n * The stack is also cleared whenever an API function is called, with * certain exceptions (for instance, H5Eprint1()). * - * \deprecated 1.8.0 Function H5Eclear() renamed to H5Eclear1() and deprecated - * in this release. */ H5_DLL herr_t H5Eclear1(void); /** @@ -747,6 +768,9 @@ H5_DLL herr_t H5Eclear1(void); * function * \return \herr_t * + * \deprecated 1.8.0 Function H5Eget_auto() renamed to H5Eget_auto1() and + * deprecated in this release. + * * \details H5Eget_auto1() returns the current settings for the automatic error * stack traversal function, \p func, and its data, * \p client_data. Either or both arguments may be \c NULL, in which case the @@ -773,8 +797,6 @@ H5_DLL herr_t H5Eclear1(void); * H5Eprint2(), mixing H5Eset_auto1() and H5Eget_auto2() or mixing * H5Eset_auto2() and H5Eget_auto1() does not fail. * - * \deprecated 1.8.0 Function H5Eget_auto() renamed to H5Eget_auto1() and - * deprecated in this release. */ H5_DLL herr_t H5Eget_auto1(H5E_auto1_t *func, void **client_data); /** @@ -791,6 +813,9 @@ H5_DLL herr_t H5Eget_auto1(H5E_auto1_t *func, void **client_data); * \param[in] str Error description string * \return \herr_t * + * \deprecated 1.8.0 Function H5Epush() renamed to H5Epush1() and + * deprecated in this release. + * * \details H5Epush1() pushes a new error record onto the error stack for the * current thread.\n * The error has major and minor numbers \p maj_num @@ -801,8 +826,6 @@ H5_DLL herr_t H5Eget_auto1(H5E_auto1_t *func, void **client_data); * allocated. * * \since 1.4.0 - * \deprecated 1.8.0 Function H5Epush() renamed to H5Epush1() and - * deprecated in this release. */ H5_DLL herr_t H5Epush1(const char *file, const char *func, unsigned line, H5E_major_t maj, H5E_minor_t min, const char *str); @@ -815,6 +838,9 @@ H5_DLL herr_t H5Epush1(const char *file, const char *func, unsigned line, H5E_ma * \param[in] stream File pointer, or \c NULL for \c stderr * \return \herr_t * + * \deprecated 1.8.0 Function H5Eprint() renamed to H5Eprint1() and + * deprecated in this release. + * * \details H5Eprint1() prints prints the error stack for the current thread * on the specified stream, \p stream. Even if the error stack is empty, a * one-line message of the following form will be printed: @@ -825,8 +851,6 @@ H5_DLL herr_t H5Epush1(const char *file, const char *func, unsigned line, H5E_ma * that prints error messages. Users are encouraged to write their own * more specific error handlers. * - * \deprecated 1.8.0 Function H5Eprint() renamed to H5Eprint1() and - * deprecated in this release. */ H5_DLL herr_t H5Eprint1(FILE *stream); /** @@ -839,6 +863,9 @@ H5_DLL herr_t H5Eprint1(FILE *stream); * \param[in] client_data Data passed to the error function * \return \herr_t * + * \deprecated 1.8.0 Function H5Eset_auto() renamed to H5Eset_auto1() and + * deprecated in this release. + * * \details H5Eset_auto1() turns on or off automatic printing of errors. When * turned on (non-null \p func pointer), any API function which returns * an error indication will first call \p func, passing it \p @@ -855,8 +882,6 @@ H5_DLL herr_t H5Eprint1(FILE *stream); * Automatic stack traversal is always in the #H5E_WALK_DOWNWARD * direction. * - * \deprecated 1.8.0 Function H5Eset_auto() renamed to H5Eset_auto1() and - * deprecated in this release. */ H5_DLL herr_t H5Eset_auto1(H5E_auto1_t func, void *client_data); /** @@ -870,6 +895,9 @@ H5_DLL herr_t H5Eset_auto1(H5E_auto1_t func, void *client_data); * \param[in] client_data Data to be passed to \p func * \return \herr_t * + * \deprecated 1.8.0 Function H5Ewalk() renamed to H5Ewalk1() and + * deprecated in this release. + * * \details H5Ewalk1() walks the error stack for the current thread and calls * the function specified in \p func for each error along the way. * @@ -887,8 +915,6 @@ H5_DLL herr_t H5Eset_auto1(H5E_auto1_t func, void *client_data); * is as follows: * \snippet this H5E_walk1_t_snip * - * \deprecated 1.8.0 Function H5Ewalk() renamed to H5Ewalk1() and - * deprecated in this release. */ H5_DLL herr_t H5Ewalk1(H5E_direction_t direction, H5E_walk1_t func, void *client_data); /** @@ -901,6 +927,8 @@ H5_DLL herr_t H5Ewalk1(H5E_direction_t direction, H5E_walk1_t func, void *client * \param[in] maj Major error number * \return \herr_t * + * \deprecated 1.8.0 Function deprecated in this release. + * * \details Given a major error number, H5Eget_major() returns a constant * character string that describes the error. * @@ -908,7 +936,6 @@ H5_DLL herr_t H5Ewalk1(H5E_direction_t direction, H5E_walk1_t func, void *client * array). An application calling this function must free the memory * associated with the return value to prevent a memory leak. * - * \deprecated 1.8.0 Function deprecated in this release. */ H5_DLL char *H5Eget_major(H5E_major_t maj); /** @@ -921,6 +948,8 @@ H5_DLL char *H5Eget_major(H5E_major_t maj); * \param[in] min Minor error number * \return \herr_t * + * \deprecated 1.8.0 Function deprecated and return type changed in this release. + * * \details Given a minor error number, H5Eget_minor() returns a constant * character string that describes the error. * @@ -930,7 +959,6 @@ H5_DLL char *H5Eget_major(H5E_major_t maj); * the memory associated with the return value to prevent a memory * leak. This is a change from the 1.6.x release series. * - * \deprecated 1.8.0 Function deprecated and return type changed in this release. */ H5_DLL char *H5Eget_minor(H5E_minor_t min); #endif /* H5_NO_DEPRECATED_SYMBOLS */ diff --git a/src/H5FDmpio.h b/src/H5FDmpio.h index 7e40151..341264f 100644 --- a/src/H5FDmpio.h +++ b/src/H5FDmpio.h @@ -224,7 +224,7 @@ H5_DLL herr_t H5Pset_dxpl_mpio_collective_opt(hid_t dxpl_id, H5FD_mpio_collectiv * * Use of this function is optional. * - * \todo Add missing version information + * \since 1.8.0 * */ H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt(hid_t dxpl_id, H5FD_mpio_chunk_opt_t opt_mode); @@ -248,7 +248,7 @@ H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt(hid_t dxpl_id, H5FD_mpio_chunk_opt_t op * otherwise, a separate I/O process will be invoked for each chunk * (multi-chunk I/O). * - * \todo Add missing version information + * \since 1.8.0 * */ H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt_num(hid_t dxpl_id, unsigned num_chunk_per_proc); @@ -273,7 +273,7 @@ H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt_num(hid_t dxpl_id, unsigned num_chunk_p * percent_proc_per_chunk, the library will do collective I/O for this * chunk; otherwise, independent I/O will be done for the chunk. * - * \todo Add missing version information + * \since 1.8.0 * */ H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt_ratio(hid_t dxpl_id, unsigned percent_num_proc_per_chunk); diff --git a/src/H5FDs3comms.h b/src/H5FDs3comms.h index da6a62d..b81bfae 100644 --- a/src/H5FDs3comms.h +++ b/src/H5FDs3comms.h @@ -179,7 +179,7 @@ * HTTP header fields, of particular use when composing an * "S3 Canonical Request" for authentication. * - * - The creation of a Canoncial Request involves: + * - The creation of a Canonical Request involves: * - convert field names to lower case * - sort by this lower-case name * - convert ": " name-value separator in HTTP string to ":" @@ -459,7 +459,7 @@ typedef struct { * * Pointer to NULL-terminated string for "secret" access id to S3 resource. * - * Requred to authenticate. + * Required to authenticate. * * `signing_key` (unsigned char *) * @@ -470,7 +470,7 @@ typedef struct { * which may be re-used for several (up to seven (7)) days from creation? * Computed once upon file open. * - * Requred to authenticate. + * Required to authenticate. * *---------------------------------------------------------------------------- */ diff --git a/src/H5FLprivate.h b/src/H5FLprivate.h index 0f9131e..7bedfe7 100644 --- a/src/H5FLprivate.h +++ b/src/H5FLprivate.h @@ -148,8 +148,8 @@ typedef struct H5FL_reg_head_t { typedef union H5FL_blk_list_t { size_t size; /* Size of the page */ union H5FL_blk_list_t *next; /* Pointer to next block in free list */ - double unused1; /* Unused normally, just here for aligment */ - haddr_t unused2; /* Unused normally, just here for aligment */ + double unused1; /* Unused normally, just here for alignment */ + haddr_t unused2; /* Unused normally, just here for alignment */ } H5FL_blk_list_t; /* Data structure for priority queue node of block free lists */ @@ -163,9 +163,9 @@ typedef struct H5FL_blk_node_t { /* Data structure for priority queue of native block free lists */ typedef struct H5FL_blk_head_t { unsigned init; /* Whether the free list has been initialized */ - unsigned allocated; /* Number of blocks allocated */ - unsigned onlist; /* Number of blocks on free list */ - size_t list_mem; /* Amount of memory in block on free list */ + unsigned allocated; /* Total number of blocks allocated */ + unsigned onlist; /* Total number of blocks on free list */ + size_t list_mem; /* Total amount of memory in blocks on free list */ const char * name; /* Name of the type */ H5FL_blk_node_t *head; /* Pointer to first free list in queue */ } H5FL_blk_head_t; @@ -221,8 +221,8 @@ typedef struct H5FL_blk_head_t { typedef union H5FL_arr_list_t { union H5FL_arr_list_t *next; /* Pointer to next block in free list */ size_t nelem; /* Number of elements in this array */ - double unused1; /* Unused normally, just here for aligment */ - haddr_t unused2; /* Unused normally, just here for aligment */ + double unused1; /* Unused normally, just here for alignment */ + haddr_t unused2; /* Unused normally, just here for alignment */ } H5FL_arr_list_t; /* Data structure for each size of array element */ @@ -235,7 +235,7 @@ typedef struct H5FL_arr_node_t { /* Data structure for free list of array blocks */ typedef struct H5FL_arr_head_t { unsigned init; /* Whether the free list has been initialized */ - unsigned allocated; /* Number of blocks allocated */ + unsigned allocated; /* Total number of blocks allocated */ size_t list_mem; /* Amount of memory in block on free list */ const char * name; /* Name of the type */ int maxelem; /* Maximum number of elements in an array */ diff --git a/src/H5Fpkg.h b/src/H5Fpkg.h index 4c968db..528ba86 100644 --- a/src/H5Fpkg.h +++ b/src/H5Fpkg.h @@ -238,7 +238,7 @@ struct H5F_file_t { /* (if aggregating "small data" allocations) */ /* Metadata accumulator information */ - H5F_meta_accum_t accum; /* Metadata accumulator info */ + H5F_meta_accum_t accum; /* Metadata accumulator info */ }; /* @@ -247,13 +247,13 @@ struct H5F_file_t { * to shared H5F_file_t structs. */ struct H5F_t { - char * open_name; /* Name used to open file */ + char * open_name; /* Name used to open file */ char * actual_name; /* Actual name of the file, after resolving symlinks, etc. */ char * extpath; /* Path for searching target external link file */ - H5F_file_t * shared; /* The shared file info */ + H5F_file_t * shared; /* The shared file info */ unsigned nopen_objs; /* Number of open object headers*/ H5FO_t * obj_count; /* # of time each object is opened through top file structure */ - hid_t file_id; /* ID of this file */ + hid_t file_id; /* ID of this file */ hbool_t closing; /* File is in the process of being closed */ struct H5F_t *parent; /* Parent file that this file is mounted to */ unsigned nmounts; /* Number of children mounted to this file */ diff --git a/src/H5Fprivate.h b/src/H5Fprivate.h index 3d8e8d3..fdd7641 100644 --- a/src/H5Fprivate.h +++ b/src/H5Fprivate.h @@ -217,30 +217,30 @@ /* clang-format off */ /* Address-related macros */ -#define H5F_addr_overflow(X,Z) (HADDR_UNDEF==(X) || \ - HADDR_UNDEF==(X)+(haddr_t)(Z) || \ +#define H5F_addr_overflow(X,Z) (HADDR_UNDEF==(X) || \ + HADDR_UNDEF==(X)+(haddr_t)(Z) || \ (X)+(haddr_t)(Z)<(X)) #define H5F_addr_hash(X,M) ((unsigned)((X)%(M))) #define H5F_addr_defined(X) ((X)!=HADDR_UNDEF) /* The H5F_addr_eq() macro guarantees that Y is not HADDR_UNDEF by making * certain that X is not HADDR_UNDEF and then checking that X equals Y */ -#define H5F_addr_eq(X,Y) ((X)!=HADDR_UNDEF && \ +#define H5F_addr_eq(X,Y) ((X)!=HADDR_UNDEF && \ (X)==(Y)) #define H5F_addr_ne(X,Y) (!H5F_addr_eq((X),(Y))) -#define H5F_addr_lt(X,Y) ((X)!=HADDR_UNDEF && \ - (Y)!=HADDR_UNDEF && \ +#define H5F_addr_lt(X,Y) ((X)!=HADDR_UNDEF && \ + (Y)!=HADDR_UNDEF && \ (X)<(Y)) -#define H5F_addr_le(X,Y) ((X)!=HADDR_UNDEF && \ - (Y)!=HADDR_UNDEF && \ +#define H5F_addr_le(X,Y) ((X)!=HADDR_UNDEF && \ + (Y)!=HADDR_UNDEF && \ (X)<=(Y)) -#define H5F_addr_gt(X,Y) ((X)!=HADDR_UNDEF && \ - (Y)!=HADDR_UNDEF && \ +#define H5F_addr_gt(X,Y) ((X)!=HADDR_UNDEF && \ + (Y)!=HADDR_UNDEF && \ (X)>(Y)) -#define H5F_addr_ge(X,Y) ((X)!=HADDR_UNDEF && \ - (Y)!=HADDR_UNDEF && \ +#define H5F_addr_ge(X,Y) ((X)!=HADDR_UNDEF && \ + (Y)!=HADDR_UNDEF && \ (X)>=(Y)) -#define H5F_addr_cmp(X,Y) (H5F_addr_eq((X), (Y)) ? 0 : \ +#define H5F_addr_cmp(X,Y) (H5F_addr_eq((X), (Y)) ? 0 : \ (H5F_addr_lt((X), (Y)) ? -1 : 1)) #define H5F_addr_pow2(N) ((haddr_t)1<<(N)) #define H5F_addr_overlap(O1,L1,O2,L2) (((O1) < (O2) && ((O1) + (L1)) > (O2)) || \ @@ -498,11 +498,11 @@ #define HDF5_BTREE_SNODE_IK_DEF 16 #define HDF5_BTREE_CHUNK_IK_DEF \ 32 /* Note! this value is assumed \ - to be 32 for version 0 \ - of the superblock and \ - if it is changed, the code \ - must compensate. -QAK \ - */ + to be 32 for version 0 \ + of the superblock and \ + if it is changed, the code \ + must compensate. -QAK \ + */ #define HDF5_BTREE_IK_MAX_ENTRIES 65536 /* 2^16 - 2 bytes for storing entries (children) */ /* See format specification on version 1 B-trees */ diff --git a/src/H5Fpublic.h b/src/H5Fpublic.h index c44e729..82d79c8 100644 --- a/src/H5Fpublic.h +++ b/src/H5Fpublic.h @@ -22,6 +22,27 @@ * creation or access \c mode control the interaction with the underlying * storage such as file systems. * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5F_examples.c create + * </td> + * <td> + * \snippet{lineno} H5F_examples.c read + * </td> + * </tr> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5F_examples.c update + * </td> + * <td> + * \snippet{lineno} H5F_examples.c delete + * </td> + * </tr> + * </table> + * * In addition to general file management functions, there are three categories * of functions that deal with advanced file management tasks and use cases: * 1. The control of the HDF5 \ref MDC @@ -61,7 +82,7 @@ * We're assuming that these constants are used rather early in the hdf5 * session. * - * H5F_ACC_DEBUG no longer has any prints any special debug info. The symbol is + * H5F_ACC_DEBUG no longer prints any special debug info. The symbol is * being retained and will be listed as deprecated in HDF5 1.10.0. */ #define H5F_ACC_RDONLY (H5CHECK 0x0000u) /**< Absence of RDWR: read-only */ @@ -967,11 +988,11 @@ H5_DLL ssize_t H5Fget_name(hid_t obj_id, char *name, size_t size); * \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. * + * * \since 1.8.0 * */ diff --git a/src/H5Gpublic.h b/src/H5Gpublic.h index b8b0421..4110cb7 100644 --- a/src/H5Gpublic.h +++ b/src/H5Gpublic.h @@ -15,6 +15,26 @@ * * Use the functions in this module to manage HDF5 groups. * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5G_examples.c create + * </td> + * <td> + * \snippet{lineno} H5G_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5G_examples.c update + * </td> + * <td> + * \snippet{lineno} H5G_examples.c delete + * </td> + * </tr> + * </table> + * * \details \Bold{Groups in HDF5:} A group associates names with objects and * provides a mechanism for mapping a name to an object. Since all * objects appear in at least one group (with the possible exception of @@ -1131,7 +1151,7 @@ H5_DLL herr_t H5Gget_objinfo(hid_t loc_id, const char *name, hbool_t follow_link * actual object name length, the object name is truncated to * \Code{max_size - 1} characters. * - * Note that if the size of the object's name is unkown, a preliminary + * Note that if the size of the object's name is unknown, a preliminary * call to H5Gget_objname_by_idx() with \p name set to \c NULL will * return the length of the object's name. A second call to * H5Gget_objname_by_idx() can then be used to retrieve the actual diff --git a/src/H5Ipublic.h b/src/H5Ipublic.h index 2e66b36..83ee6be 100644 --- a/src/H5Ipublic.h +++ b/src/H5Ipublic.h @@ -11,48 +11,6 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -/**\defgroup H5I H5I - * - * Use the functions in this module to manage identifiers defined by the HDF5 - * library. See \ref H5IUD for user-defined identifiers and identifier - * types. - * - * HDF5 identifiers are usually created as a side-effect of creating HDF5 - * entities such as groups, datasets, attributes, or property lists. - * - * Identifiers defined by the HDF5 library can be used to retrieve information - * such as path names and reference counts, and their validity can be checked. - * - * Identifiers can be updated by manipulating their reference counts. - * - * Unused identifiers should be reclaimed by closing the associated item, e.g., - * HDF5 object, or decrementing the reference count to 0. - * - * \note Identifiers (of type \ref hid_t) are run-time auxiliaries and - * not persisted in the file. - * - * \defgroup H5IUD User-defined ID Types - * \ingroup H5I - * - * The \ref H5I module contains functions to define new identifier types. - * For convenience, handles of type \ref hid_t can then be associated with the - * new identifier types and user objects. - * - * New identifier types can be created by registering a new identifier type - * with the HDF5 library. Once a new identifier type has bee registered, - * it can be used to generate identifiers for user objects. - * - * User-defined identifier types can be searched and iterated. - * - * Like library-defined identifiers, user-defined identifiers \Emph{and} - * identifier types are reference counted, and the reference counts can be - * manipulated accordingly. - * - * User-defined identifiers no longer in use should be deleted or reclaimed, - * and identifier types should be destroyed if they are no longer required. - * - */ - /* * This file contains function prototypes for each exported function in * the H5I module. @@ -130,7 +88,7 @@ extern "C" { /* Public API functions */ /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Registers an object under a type and returns an ID for it * @@ -152,7 +110,7 @@ extern "C" { */ H5_DLL hid_t H5Iregister(H5I_type_t type, const void *object); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Returns the object referenced by an ID * @@ -175,7 +133,7 @@ H5_DLL hid_t H5Iregister(H5I_type_t type, const void *object); */ H5_DLL void *H5Iobject_verify(hid_t id, H5I_type_t type); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Removes an ID from its type * @@ -214,12 +172,7 @@ H5_DLL void *H5Iremove_verify(hid_t id, H5I_type_t type); * \return Returns the object type if successful; otherwise #H5I_BADID. * * \details H5Iget_type() retrieves the type of the object identified by - * \p id. - * - * Valid types returned by the function are: - * \id_types - * - * If no valid type can be determined or the identifier submitted is + * \p id. If no valid type can be determined or the identifier submitted is * invalid, the function returns #H5I_BADID. * * This function is of particular use in determining the type of @@ -415,7 +368,7 @@ H5_DLL int H5Idec_ref(hid_t id); */ H5_DLL int H5Iget_ref(hid_t id); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Creates and returns a new ID type * @@ -447,7 +400,7 @@ H5_DLL int H5Iget_ref(hid_t id); */ H5_DLL H5I_type_t H5Iregister_type(size_t hash_size, unsigned reserved, H5I_free_t free_func); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Deletes all identifiers of the given type * @@ -471,7 +424,7 @@ H5_DLL H5I_type_t H5Iregister_type(size_t hash_size, unsigned reserved, H5I_free */ H5_DLL herr_t H5Iclear_type(H5I_type_t type, hbool_t force); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Removes an identifier type and all identifiers within that type * @@ -494,7 +447,7 @@ H5_DLL herr_t H5Iclear_type(H5I_type_t type, hbool_t force); */ H5_DLL herr_t H5Idestroy_type(H5I_type_t type); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Increments the reference count on an ID type * @@ -513,7 +466,7 @@ H5_DLL herr_t H5Idestroy_type(H5I_type_t type); */ H5_DLL int H5Iinc_type_ref(H5I_type_t type); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Decrements the reference count on an identifier type * @@ -533,11 +486,11 @@ H5_DLL int H5Iinc_type_ref(H5I_type_t type); */ H5_DLL int H5Idec_type_ref(H5I_type_t type); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Retrieves the reference count on an ID type * - * \param[in] type The identifier of the type whose reference count is to be retieved + * \param[in] type The identifier of the type whose reference count is to be retrieved * * \return Returns the current reference count on success, negative on failure. * @@ -552,7 +505,7 @@ H5_DLL int H5Idec_type_ref(H5I_type_t type); */ H5_DLL int H5Iget_type_ref(H5I_type_t type); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Finds the memory referred to by an ID within the given ID type such * that some criterion is satisfied @@ -593,7 +546,7 @@ H5_DLL int H5Iget_type_ref(H5I_type_t type); */ H5_DLL void *H5Isearch(H5I_type_t type, H5I_search_func_t func, void *key); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Returns the number of identifiers in a given identifier type * @@ -613,7 +566,7 @@ H5_DLL void *H5Isearch(H5I_type_t type, H5I_search_func_t func, void *key); */ H5_DLL herr_t H5Inmembers(H5I_type_t type, hsize_t *num_members); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Determines whether an identifier type is registered * diff --git a/src/H5Lpublic.h b/src/H5Lpublic.h index 2896ba4..a3a6b33 100644 --- a/src/H5Lpublic.h +++ b/src/H5Lpublic.h @@ -11,16 +11,6 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -/**\defgroup H5L H5L - * - * Use the functions in this module to manage HDF5 links and link types. - * - * \defgroup TRAV Link Traversal - * \ingroup H5L - * \defgroup H5LA Advanced Link Functions - * \ingroup H5L - */ - /*------------------------------------------------------------------------- * * Created: H5Lpublic.h @@ -34,6 +24,37 @@ #ifndef H5Lpublic_H #define H5Lpublic_H +/**\defgroup H5L H5L + * + * Use the functions in this module to manage HDF5 links and link types. + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5L_examples.c create + * </td> + * <td> + * \snippet{lineno} H5L_examples.c iter_cb + * \snippet{lineno} H5L_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5L_examples.c update + * </td> + * <td> + * \snippet{lineno} H5L_examples.c delete + * </td> + * </tr> + * </table> + * + * \defgroup TRAV Link Traversal + * \ingroup H5L + * \defgroup H5LA Advanced Link Functions + * \ingroup H5L + */ + /* Public headers needed by this file */ #include "H5public.h" /* Generic Functions */ #include "H5Ipublic.h" /* IDs */ @@ -500,7 +521,7 @@ H5_DLL herr_t H5Ldelete_by_idx(hid_t loc_id, const char *group_name, H5_index_t * * \return \herr_t * - * \details H5Lget_val() returns tha value of link \p name. For smbolic links, + * \details H5Lget_val() returns the value of link \p name. For smbolic links, * this is the path to which the link points, including the null * terminator. For external and user-defined links, it is the link * buffer. @@ -530,7 +551,7 @@ H5_DLL herr_t H5Ldelete_by_idx(hid_t loc_id, const char *group_name, H5_index_t * * This function should be used only after H5Lget_info() has been * called to verify that \p name is a symbolic link. This can be - * deteremined from the \c link_type field of the \ref H5L_info_t + * determined from the \c link_type field of the \ref H5L_info_t * \c struct. * * \note This function will fail if called on a hard link. @@ -618,7 +639,7 @@ H5_DLL herr_t H5Lget_val_by_idx(hid_t loc_id, const char *group_name, H5_index_t * name includes either a relative path or an absolute path to the * target link, intermediate steps along the path must be verified * before the existence of the target link can be safely checked. If - * the path is not verified and an intermediate element of the path + * the path is not verified, and an intermediate element of the path * does not exist, H5Lexists() will fail. The example in the next * paragraph illustrates one step-by-step method for verifying the * existence of a link with a relative or absolute path. @@ -663,7 +684,7 @@ H5_DLL herr_t H5Lget_val_by_idx(hid_t loc_id, const char *group_name, H5_index_t * root group of an HDF5 file, and let \c lapl denote a valid link * access property list identifier. A call to H5Lexists() with * arguments c root, \c "/", and \c lapl returns a positive value; - * in other words, \Code{H5Lexists(root, "/", lapl)} returns a postive + * in other words, \Code{H5Lexists(root, "/", lapl)} returns a positive * value. In HDF5 version 1.8.16, this function returns 0.</li> * </ol> * Note that the function accepts link names and path names. This is @@ -705,38 +726,37 @@ H5_DLL htri_t H5Lexists(hid_t loc_id, const char *name, hid_t lapl_id); * specifies the link being queried. * * \p lapl_id is the link access property list associated with the - * link \p name. In the general case, when default link access - * properties are acceptable, this can be passed in as #H5P_DEFAULT. - * An example of a situation that requires a non-default link access - * property list is when the link is an external link; an external - * link may require that a link prefix be set in a link access - * property list (see H5Pset_elink_prefix()). + * link name. In the general case, when default link access properties + * are acceptable, this can be passed in as #H5P_DEFAULT. An example + * of a situation that requires a non-default link access property + * list is when the link is an external link; an external link may + * require that a link prefix be set in a link access property list + * (see H5Pset_elink_prefix()). * * H5Lget_info() returns information about name in the data structure - * \ref H5L_info_t, which is described below and defined in - * H5Lpublic.h. This structure is returned in the buffer \p linfo. + * H5L_info_t, which is described below and defined in H5Lpublic.h. + * This structure is returned in the buffer \p linfo. * \snippet this H5L_info_t_snip - * In the above struct, type specifies the link class. Valid values + * In the above struct, \c type specifies the link class. Valid values * include the following: * \link_types * There will be additional valid values if user-defined links have * been registered. * - * \c corder specifies the link’s creation order position while - * \c corder_valid indicates whether the value in \c corder is valid. - * - * If \c corder_valid is \c TRUE, the value in \c corder is known to - * be valid; if \c corder_valid is \c FALSE, the value in \c corder is - * presumed to be invalid; + * \p corder specifies the link’s creation order position while + * \p corder_valid indicates whether the value in corder is valid. * - * \c corder starts at zero (0) and is incremented by one (1) as new - * links are created. But higher-numbered entries are not adjusted - * when a lower-numbered link is deleted; the deleted link’s creation - * order position is simply left vacant. In such situations, the value - * of \c corder for the last link created will be larger than the - * number of links remaining in the group. + * If \p corder_valid is \c TRUE, the value in \p corder is known to + * be valid; if \p corder_valid is \c FALSE, the value in \p corder is + * presumed to be invalid; \p corder starts at zero (0) and is + * incremented by one (1) as new links are created. But + * higher-numbered entries are not adjusted when a lower-numbered link + * is deleted; the deleted link's creation order position is simply + * left vacant. In such situations, the value of \p corder for the + * last link created will be larger than the number of links remaining + * in the group. * - * \c cset specifies the character set in which the link name is + * \p cset specifies the character set in which the link name is * encoded. Valid values include the following: * \csets * This value is set with H5Pset_char_encoding(). @@ -776,9 +796,8 @@ H5_DLL herr_t H5Lget_info(hid_t loc_id, const char *name, H5L_info_t *linfo, hid * \return \herr_t * * \details H5get_info_by_idx() returns the metadata for a link in a group - * according to a specified field or index and a specified order. - * - * The link for which information is to be returned is specified by \p + * according to a specified field or index and a specified order. The + * link for which information is to be returned is specified by \p * idx_type, \p order, and \p n as follows: * * - \p idx_type specifies the field by which the links in \p @@ -939,19 +958,18 @@ H5_DLL herr_t H5Literate(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t orde /** * \ingroup TRAV * - * \brief Iterates through links in a group by its name + * \brief Iterates through links in a group * * \loc_id * \param[in] group_name Group name * \idx_type * \order * \param[in,out] idx iteration position at which to start (\Emph{IN}) or - * position at which an interrupted iteration may be restarted - * (\Emph{OUT}) + * position at which an interrupted iteration may be restarted + * (\Emph{OUT}) * \op * \op_data * \lapl_id - * * \return \success{The return value of the first operator that returns * non-zero, or zero if all members were processed with no * operator returning non-zero.} @@ -1014,7 +1032,6 @@ H5_DLL herr_t H5Literate_by_name(hid_t loc_id, const char *group_name, H5_index_ * \order * \op * \op_data - * * \return \success{The return value of the first operator that returns * non-zero, or zero if all members were processed with no * operator returning non-zero.} @@ -1101,11 +1118,7 @@ H5_DLL herr_t H5Lvisit(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, * \op_data * \lapl_id * - * \return \success{The return value of the first operator that returns - * non-zero, or zero if all members were processed with no - * operator returning non-zero.} - * \return \failure{Negative if an error occurs in the library, or the negative - * value returned by one of the operators.} + * \return \herr_t * * \details H5Lvisit_by_name() is a recursive iteration function to visit all * links in and below a group in an HDF5 file, thus providing a @@ -1130,7 +1143,7 @@ H5_DLL herr_t H5Lvisit(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, * \p idx_type specifies the index to be used. If the links have not * been indexed by the index type, they will first be sorted by that * index then the iteration will begin; if the links have been so - * indexed, the sorting step will be unnecesary, so the iteration may + * indexed, the sorting step will be unnecessary, so the iteration may * begin more quickly. Valid values include the following: * \indexes * diff --git a/src/H5Opkg.h b/src/H5Opkg.h index e0ba5c5..06cecdd 100644 --- a/src/H5Opkg.h +++ b/src/H5Opkg.h @@ -227,15 +227,15 @@ struct H5O_msg_class_t { }; struct H5O_mesg_t { - const H5O_msg_class_t *type; /*type of message */ - hbool_t dirty; /*raw out of date wrt native */ - hbool_t locked; /*message is locked into chunk */ - uint8_t flags; /*message flags */ - H5O_msg_crt_idx_t crt_idx; /*message creation index */ - unsigned chunkno; /*chunk number for this mesg */ - void * native; /*native format message */ - uint8_t * raw; /*ptr to raw data */ - size_t raw_size; /*size with alignment */ + const H5O_msg_class_t *type; /* type of message */ + hbool_t dirty; /* raw out of date wrt native */ + hbool_t locked; /* message is locked into chunk */ + uint8_t flags; /* message flags */ + H5O_msg_crt_idx_t crt_idx; /* message creation index */ + unsigned chunkno; /* chunk number for this mesg */ + void * native; /* native format message */ + uint8_t * raw; /* pointer to raw data */ + size_t raw_size; /* size with alignment */ }; typedef struct H5O_chunk_t { diff --git a/src/H5Oprivate.h b/src/H5Oprivate.h index cdc0eef..27a0a4a 100644 --- a/src/H5Oprivate.h +++ b/src/H5Oprivate.h @@ -25,11 +25,11 @@ #define H5Oprivate_H /* Include the public header file for this API */ -#include "H5Opublic.h" /* Object header functions */ +#include "H5Opublic.h" /* Object header functions */ /* Public headers needed by this file */ -#include "H5Dpublic.h" /* Dataset functions */ -#include "H5Lpublic.h" /* Link functions */ +#include "H5Dpublic.h" /* Dataset functions */ +#include "H5Lpublic.h" /* Link functions */ #include "H5Spublic.h" /* Dataspace functions */ /* Private headers needed by this file */ @@ -37,7 +37,7 @@ #include "H5Fprivate.h" /* File access */ #include "H5SLprivate.h" /* Skip lists */ #include "H5Tprivate.h" /* Datatype functions */ -#include "H5Zprivate.h" /* I/O pipeline filters */ +#include "H5Zprivate.h" /* I/O pipeline filters */ /* Forward references of package typedefs */ typedef struct H5O_msg_class_t H5O_msg_class_t; @@ -229,7 +229,7 @@ typedef struct H5O_copy_t { #define H5O_SHARE_TYPE_UNSHARED 0 /* Message is not shared */ #define H5O_SHARE_TYPE_SOHM 1 /* Message is stored in SOHM heap */ #define H5O_SHARE_TYPE_COMMITTED 2 /* Message is stored in another object header */ -#define H5O_SHARE_TYPE_HERE 3 /* Message is stored in this object header, but is sharable */ +#define H5O_SHARE_TYPE_HERE 3 /* Message is stored in this object header, but is shareable */ /* Detect messages that aren't stored in message's object header */ #define H5O_IS_STORED_SHARED(T) \ @@ -433,7 +433,7 @@ typedef struct H5O_layout_chunk_t { uint32_t dim[H5O_LAYOUT_NDIMS]; /* Size of chunk in elements */ uint32_t size; /* Size of chunk in bytes */ hsize_t nchunks; /* Number of chunks in dataset */ - hsize_t chunks[H5O_LAYOUT_NDIMS]; /* # of chunks in dataset dimensions */ + hsize_t chunks[H5O_LAYOUT_NDIMS]; /* # of chunks in each dataset dimension */ hsize_t down_chunks[H5O_LAYOUT_NDIMS]; /* "down" size of number of chunks in each dimension */ } H5O_layout_chunk_t; diff --git a/src/H5Opublic.h b/src/H5Opublic.h index 24bf397..a4eef44 100644 --- a/src/H5Opublic.h +++ b/src/H5Opublic.h @@ -33,6 +33,26 @@ * reference count to zero, which can (but should not usually) be effected * by a function in this module. * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5O_examples.c create + * </td> + * <td> + * \snippet{lineno} H5O_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5O_examples.c update + * </td> + * <td> + * \snippet{lineno} H5O_examples.c delete + * </td> + * </tr> + * </table> + * */ /*------------------------------------------------------------------------- @@ -59,14 +79,14 @@ /*****************/ /* Flags for object copy (H5Ocopy) */ -#define H5O_COPY_SHALLOW_HIERARCHY_FLAG (0x0001u) /* Copy only immediate members */ -#define H5O_COPY_EXPAND_SOFT_LINK_FLAG (0x0002u) /* Expand soft links into new objects */ -#define H5O_COPY_EXPAND_EXT_LINK_FLAG (0x0004u) /* Expand external links into new objects */ -#define H5O_COPY_EXPAND_REFERENCE_FLAG (0x0008u) /* Copy objects that are pointed by references */ -#define H5O_COPY_WITHOUT_ATTR_FLAG (0x0010u) /* Copy object without copying attributes */ -#define H5O_COPY_PRESERVE_NULL_FLAG (0x0020u) /* Copy NULL messages (empty space) */ -#define H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG (0x0040u) /* Merge committed datatypes in dest file */ -#define H5O_COPY_ALL (0x007Fu) /* All object copying flags (for internal checking) */ +#define H5O_COPY_SHALLOW_HIERARCHY_FLAG (0x0001u) /**< Copy only immediate members */ +#define H5O_COPY_EXPAND_SOFT_LINK_FLAG (0x0002u) /**< Expand soft links into new objects */ +#define H5O_COPY_EXPAND_EXT_LINK_FLAG (0x0004u) /**< Expand external links into new objects */ +#define H5O_COPY_EXPAND_REFERENCE_FLAG (0x0008u) /**< Copy objects that are pointed by references */ +#define H5O_COPY_WITHOUT_ATTR_FLAG (0x0010u) /**< Copy object without copying attributes */ +#define H5O_COPY_PRESERVE_NULL_FLAG (0x0020u) /**< Copy NULL messages (empty space) */ +#define H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG (0x0040u) /**< Merge committed datatypes in dest file */ +#define H5O_COPY_ALL (0x007Fu) /**< All object copying flags (for internal checking) */ /* Flags for shared message indexes. * Pass these flags in using the mesg_type_flags parameter in @@ -75,25 +95,27 @@ * but we need to assign each kind of message to a different bit so that * one index can hold multiple types.) */ -#define H5O_SHMESG_NONE_FLAG 0x0000 /* No shared messages */ -#define H5O_SHMESG_SDSPACE_FLAG ((unsigned)1 << 0x0001) /* Simple Dataspace Message. */ -#define H5O_SHMESG_DTYPE_FLAG ((unsigned)1 << 0x0003) /* Datatype Message. */ -#define H5O_SHMESG_FILL_FLAG ((unsigned)1 << 0x0005) /* Fill Value Message. */ -#define H5O_SHMESG_PLINE_FLAG ((unsigned)1 << 0x000b) /* Filter pipeline message. */ -#define H5O_SHMESG_ATTR_FLAG ((unsigned)1 << 0x000c) /* Attribute Message. */ +#define H5O_SHMESG_NONE_FLAG 0x0000 /**< No shared messages */ +#define H5O_SHMESG_SDSPACE_FLAG ((unsigned)1 << 0x0001) /**< Simple Dataspace Message. */ +#define H5O_SHMESG_DTYPE_FLAG ((unsigned)1 << 0x0003) /**< Datatype Message. */ +#define H5O_SHMESG_FILL_FLAG ((unsigned)1 << 0x0005) /**< Fill Value Message. */ +#define H5O_SHMESG_PLINE_FLAG ((unsigned)1 << 0x000b) /**< Filter pipeline message. */ +#define H5O_SHMESG_ATTR_FLAG ((unsigned)1 << 0x000c) /**< Attribute Message. */ #define H5O_SHMESG_ALL_FLAG \ (H5O_SHMESG_SDSPACE_FLAG | H5O_SHMESG_DTYPE_FLAG | H5O_SHMESG_FILL_FLAG | H5O_SHMESG_PLINE_FLAG | \ H5O_SHMESG_ATTR_FLAG) +/* clang-format off */ /* Object header status flag definitions */ -#define H5O_HDR_CHUNK0_SIZE 0x03 /* 2-bit field indicating # of bytes to store the size of chunk 0's data */ -#define H5O_HDR_ATTR_CRT_ORDER_TRACKED 0x04 /* Attribute creation order is tracked */ -#define H5O_HDR_ATTR_CRT_ORDER_INDEXED 0x08 /* Attribute creation order has index */ -#define H5O_HDR_ATTR_STORE_PHASE_CHANGE 0x10 /* Non-default attribute storage phase change values stored */ -#define H5O_HDR_STORE_TIMES 0x20 /* Store access, modification, change & birth times for object */ +#define H5O_HDR_CHUNK0_SIZE 0x03 /**< 2-bit field indicating # of bytes to store the size of chunk 0's data */ +#define H5O_HDR_ATTR_CRT_ORDER_TRACKED 0x04 /**< Attribute creation order is tracked */ +#define H5O_HDR_ATTR_CRT_ORDER_INDEXED 0x08 /**< Attribute creation order has index */ +#define H5O_HDR_ATTR_STORE_PHASE_CHANGE 0x10 /**< Non-default attribute storage phase change values stored */ +#define H5O_HDR_STORE_TIMES 0x20 /**< Store access, modification, change & birth times for object */ #define H5O_HDR_ALL_FLAGS \ (H5O_HDR_CHUNK0_SIZE | H5O_HDR_ATTR_CRT_ORDER_TRACKED | H5O_HDR_ATTR_CRT_ORDER_INDEXED | \ H5O_HDR_ATTR_STORE_PHASE_CHANGE | H5O_HDR_STORE_TIMES) +/* clang-format on */ /* Maximum shared message values. Number of indexes is 8 to allow room to add * new types of messages. @@ -161,7 +183,7 @@ typedef struct H5O_info_t { struct { H5_ih_info_t obj; /**< v1/v2 B-tree & local/fractal heap for groups, B-tree for chunked datasets */ H5_ih_info_t attr; /**< v2 B-tree & heap for attributes */ - } meta_size; + } meta_size; /**< Extra metadata storage for obj & attributes */ } H5O_info_t; //! <!-- [H5O_info_t_snip] --> @@ -172,7 +194,18 @@ typedef uint32_t H5O_msg_crt_idx_t; //! <!-- [H5O_iterate_t_snip] --> /** - * Prototype for H5Ovisit(), H5Ovisit_by_name() operator + * Prototype for H5Ovisit(), H5Ovisit_by_name() operator (version 3) + * + * \param[in] obj Object that serves as the root of the iteration; + * the same value as the H5Ovisit() \c obj_id parameter + * \param[in] name Name of object, relative to \p obj, being examined at current + * step of the iteration + * \param[out] info Information about that object + * \param[in,out] op_data User-defined pointer to data required by the application + * in processing the object; a pass-through of the \c op_data + * pointer provided with the H5Ovisit3() function call + * \return \herr_t_iter + * */ typedef herr_t (*H5O_iterate_t)(hid_t obj, const char *name, const H5O_info_t *info, void *op_data); //! <!-- [H5O_iterate_t_snip] --> @@ -520,19 +553,19 @@ H5_DLL herr_t H5Oget_info(hid_t loc_id, H5O_info_t *oinfo); *------------------------------------------------------------------------- * \ingroup H5O * - * \brief Retrieves the metadata for an object, identifying the object - * by location and relative name + * \brief Retrieves the metadata for an object, identifying the object by + * location and relative name * * \fgdta_loc_obj_id{loc_id} - * \param[in] name Name of group, relative to \p loc_id + * \param[in] name Name of object, relative to \p loc_id * \param[out] oinfo Buffer in which to return object information * \lapl_id * * \return \herr_t * - * \details H5Oget_info_by_name() specifies an object’s location and name, \p loc_id - * and \p name, respectively, and retrieves the metadata describing that object - * in \p oinfo, an H5O_info1_t \c struct. + * \details H5Oget_info_by_name() specifies an object’s location and name, + * \p loc_id and \p name, respectively, and retrieves the metadata + * describing that object in \p oinfo, an H5O_info1_t struct. * * The \c struct H5O_info_t is defined in H5Opublic.h and described * in the H5Oget_info() function entry. @@ -1029,10 +1062,10 @@ H5_DLL ssize_t H5Oget_comment_by_name(hid_t loc_id, const char *name, char *comm * \details H5Ovisit() is a recursive iteration function to visit the * object \p obj_id and, if \p obj_id is a group, all objects in * and below it in an HDF5 file, thus providing a mechanism for - * an application to perform a common set of operations across all - * of those objects or a dynamically selected subset. For - * non-recursive iteration across the members of a group, - * see H5Literate(). + * an application to perform a common set of operations across + * all of those objects or a dynamically selected subset. + * For non-recursive iteration across the members of a group, + * see H5Literate1(). * * If \p obj_id is a group identifier, that group serves as the * root of a recursive iteration. If \p obj_id is a file identifier, @@ -1058,7 +1091,7 @@ H5_DLL ssize_t H5Oget_comment_by_name(hid_t loc_id, const char *name, char *comm * <em>best effort</em> setting. If the application passes in * a value indicating iteration in creation order and a group is * encountered that was not tracked in creation order, that group - * will be iterated over in alpha-numeric order by name, or + * will be iterated over in alphanumeric order by name, or * <em>name order</em>. (<em>Name order</em> is the native order * used by the HDF5 library and is always available.) * @@ -1156,7 +1189,7 @@ H5_DLL herr_t H5Ovisit(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order, *------------------------------------------------------------------------- * \ingroup H5O * - * \brief Recursively visits all objects starting from a specified object + * \brief Recursively visits all objects accessible from a specified object * * \fgdta_loc_obj_id{loc_id} * \param[in] obj_name Name of the object, generally relative to @@ -1213,7 +1246,7 @@ H5_DLL herr_t H5Ovisit(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order, * <em>best effort</em> setting. If the application passes in a * value indicating iteration in creation order and a group is * encountered that was not tracked in creation order, that group - * will be iterated over in alpha-numeric order by name, or + * will be iterated over in alphanumeric order by name, or * <em>name order</em>. (<em>Name order</em> is the native order * used by the HDF5 library and is always available.) * diff --git a/src/H5PLpublic.h b/src/H5PLpublic.h index 7bcd817..1d1bc11 100644 --- a/src/H5PLpublic.h +++ b/src/H5PLpublic.h @@ -10,24 +10,44 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/* + * This file contains public declarations for the H5PL module. + */ + +#ifndef H5PLpublic_H +#define H5PLpublic_H + /**\defgroup H5PL H5PL * * Use the functions in this module to manage the loading behavior of HDF5 * plugins. * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet H5PL_examples.c create + * </td> + * <td> + * \snippet H5PL_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet H5PL_examples.c update + * </td> + * <td> + * \snippet H5PL_examples.c delete + * </td> + * </tr> + * </table> + * * \attention The loading behavior of HDF5 plugins can be controlled via the * functions described below and certain environment variables, such * as \c HDF5_PLUGIN_PRELOAD and \c HDF5_PLUGIN_PATH. * */ -/* - * This file contains public declarations for the H5PL module. - */ - -#ifndef H5PLpublic_H -#define H5PLpublic_H - /* Public headers needed by this file */ #include "H5public.h" /* Generic Functions */ diff --git a/src/H5Ppublic.h b/src/H5Ppublic.h index 962552f..e4bab2e 100644 --- a/src/H5Ppublic.h +++ b/src/H5Ppublic.h @@ -23,6 +23,26 @@ * or writing data. Property lists can be modified by adding or changing * properties. Property lists are deleted by closing the associated handles. * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5P_examples.c create + * </td> + * <td> + * \snippet{lineno} H5P_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5P_examples.c update + * </td> + * <td> + * \snippet{lineno} H5P_examples.c delete + * </td> + * </tr> + * </table> + * * \defgroup ALCAPL Attribute and Link Creation Properties * \ingroup H5P * Currently, there are only two creation properties that you can use to control @@ -73,7 +93,8 @@ * * \defgroup GAPL General Access Properties * \ingroup H5P - * \todo Should this be as standalone page? + * The functions in this section can be applied to different kinds of property + * lists. * * \defgroup GCPL Group Creation Properties * \ingroup H5P @@ -88,6 +109,26 @@ * * Use the functions in this module to manage HDF5 property lists. * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5P_examples.c create + * </td> + * <td> + * \snippet{lineno} H5P_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5P_examples.c update + * </td> + * <td> + * \snippet{lineno} H5P_examples.c delete + * </td> + * </tr> + * </table> + * * \defgroup GPLOA General Property List Operations (Advanced) * \ingroup H5P * @@ -95,17 +136,39 @@ * functions described below. Arbitrary user-defined properties can also * be inserted into existing property lists as so-called temporary properties. * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * + * <tr valign="top"> + * <td> + * \snippet{lineno} H5P_examples.c create_class + * </td> + * <td> + * \snippet{lineno} H5P_examples.c read_class + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5P_examples.c update_class + * </td> + * <td> + * \snippet{lineno} H5P_examples.c delete_class + * </td> + * </tr> + * </table> + * * \defgroup LAPL Link Access Properties * \ingroup H5P * - * \defgroup MAPL Map Access Properties - * \ingroup H5P + * * \defgroup OCPL Object Creation Properties * \ingroup H5P * + * * \defgroup OCPPL Object Copy Properties * \ingroup H5P * + * */ /* @@ -186,7 +249,9 @@ #define H5P_CRT_ORDER_TRACKED 0x0001 #define H5P_CRT_ORDER_INDEXED 0x0002 -/* Default value for all property list classes */ +/** + * Default value of type \ref hid_t for all property list classes + */ #define H5P_DEFAULT (hid_t)0 #ifdef __cplusplus @@ -199,14 +264,72 @@ extern "C" { /* Define property list class callback function pointer types */ //! <!-- [H5P_cls_create_func_t_snip] --> +/** + * \brief Callback function for H5Pcreate_class() + * + * \param[in] prop_id The identifier of the property list class being created + * \param[in] create_data User pointer to any class creation data required + * \return \herr_t + * + * \details This function is called when a new property list of the class + * with which this function was registered is being created. The + * function is called after any registered parent create function is + * called for each property value. + * + * If the create function returns a negative value, the new list is not + * returned to the user and the property list creation routine returns + * an error value. + * + * \since 1.4.0 + * + */ typedef herr_t (*H5P_cls_create_func_t)(hid_t prop_id, void *create_data); //! <!-- [H5P_cls_create_func_t_snip] --> //! <!-- [H5P_cls_copy_func_t_snip] --> +/** + * \brief Callback function for H5Pcreate_class() + * + * \param[in] new_prop_id The identifier of the property list copy + * \param[in] old_prop_id The identifier of the property list being copied + * \param[in] copy_data User pointer to any copy data required + * \return \herr_t + * + * \details This function is called when an existing property list of this + * class is copied. The copy callback function is called after any + * registered parent copy callback function is called for each property + * value. + * + * If the copy routine returns a negative value, the new list is not + * returned to the user and the property list copy function returns an + * error value. + * + * \since 1.4.0 + * + */ typedef herr_t (*H5P_cls_copy_func_t)(hid_t new_prop_id, hid_t old_prop_id, void *copy_data); //! <!-- [H5P_cls_copy_func_t_snip] --> //! <!-- [H5P_cls_close_func_t_snip] --> +/** + * \brief Callback function for H5Pcreate_class() + * + * \param[in] prop_id The identifier of the property list class being created + * \param[in] close_data User pointer to any close data required + * \return \herr_t + * + * \details This function is called when a property list of the class + * with which this function was registered is being closed. The + * function is called after any registered parent close function is + * called for each property value. + * + * If the close function returns a negative value, the new list is not + * returned to the user and the property list close routine returns + * an error value. + * + * \since 1.4.0 + * + */ typedef herr_t (*H5P_cls_close_func_t)(hid_t prop_id, void *close_data); //! <!-- [H5P_cls_close_func_t_snip] --> @@ -220,8 +343,8 @@ typedef herr_t (*H5P_cls_close_func_t)(hid_t prop_id, void *close_data); * \param[in,out] value The value for the property * \return \herr_t * - * \details The H5P_prp_cb1_t() describes the parameters used by the - * property create,copy and close callback functions. + * \details The H5P_prp_cb1_t() function describes the parameters used by the + * property create, copy and close callback functions. */ typedef herr_t (*H5P_prp_cb1_t)(const char *name, size_t size, void *value); //! <!-- [H5P_prp_cb1_t_snip] --> @@ -236,8 +359,8 @@ typedef herr_t (*H5P_prp_cb1_t)(const char *name, size_t size, void *value); * \param[in] value The value for the property * \return \herr_t * - * \details The H5P_prp_cb2_t() describes the parameters used by the - * property set ,copy and delete callback functions. + * \details The H5P_prp_cb2_t() function describes the parameters used by the + * property set, copy and delete callback functions. */ typedef herr_t (*H5P_prp_cb2_t)(hid_t prop_id, const char *name, size_t size, void *value); //! <!-- [H5P_prp_cb2_t_snip] --> @@ -249,6 +372,18 @@ typedef H5P_prp_cb2_t H5P_prp_delete_func_t; typedef H5P_prp_cb1_t H5P_prp_copy_func_t; //! <!-- [H5P_prp_compare_func_t_snip] --> +/** + * \brief Callback function for comparing property values + * + * \param[in] value1 A property value + * \param[in] value2 A property value + * \param[in] size The size of the \p value1 and \p value2 buffers + * \return Returns a positive value if \c value1 is greater than \c value2, a + * negative value if \c value2 is greater than \c value1 and zero if + * \c value1 and \c value2 are equal. + * + * \see H5Pregister(), H5Pinsert() + */ typedef int (*H5P_prp_compare_func_t)(const void *value1, const void *value2, size_t size); //! <!-- [H5P_prp_compare_func_t_snip] --> @@ -256,6 +391,21 @@ typedef H5P_prp_cb1_t H5P_prp_close_func_t; /* Define property list iteration function type */ //! <!-- [H5P_iterate_t_snip] --> +/** + * \brief Callback function for H5Piterate() + * + * \param[in] id The identifier of a property list or property list class + * \param[in] name The name of the current property + * \param[in,out] iter_data The user context passed to H5Piterate() + * \return \herr_t_iter + * + * \details This function is called for each property encountered when + * iterating over a property list or property list class + * via H5Piterate(). + * + * \since 1.4.0 + * + */ typedef herr_t (*H5P_iterate_t)(hid_t id, const char *name, void *iter_data); //! <!-- [H5P_iterate_t_snip] --> @@ -321,11 +471,12 @@ typedef enum H5D_mpio_no_collective_cause_t { H5D_MPIO_DATA_TRANSFORMS = 0x04, /**< Collective I/O was not performed because data transforms needed to be applied */ H5D_MPIO_MPI_OPT_TYPES_ENV_VAR_DISABLED = 0x08, - /**< \todo FIXME! */ + /**< Collective I/O was disabled by environment variable (\Code{HDF5_MPI_OPT_TYPES}) */ H5D_MPIO_NOT_SIMPLE_OR_SCALAR_DATASPACES = 0x10, /**< Collective I/O was not performed because one of the dataspaces was neither simple nor scalar */ H5D_MPIO_NOT_CONTIGUOUS_OR_CHUNKED_DATASET = 0x20, - H5D_MPIO_FILTERS = 0x40 + /**< Collective I/O was not performed because the dataset was neither contiguous nor chunked */ + H5D_MPIO_FILTERS = 0x40 } H5D_mpio_no_collective_cause_t; //! <!-- [H5D_mpio_no_collective_cause_t_snip] --> @@ -612,9 +763,9 @@ H5_DLL hid_t H5Pcreate(hid_t cls_id); * those existing properties, only add or remove their own class * properties. Property list classes defined and supported in the * HDF5 library distribution are listed and briefly described in - * H5Pcreate(). The \p create routine is called when a new property - * list of this class is being created. The #H5P_cls_create_func_t - * callback function is defined as follows: + * H5Pcreate(). The \p create, \p copy, \p close functions are called + * when a property list of the new class is created, copied, or closed, + * respectively. * * \snippet this H5P_cls_create_func_t_snip * @@ -1328,15 +1479,11 @@ H5_DLL htri_t H5Pisa_class(hid_t plist_id, hid_t pclass_id); * returned in this case, the iterator cannot be restarted if * one of the calls to its operator returns non-zero. * - * The prototype for the #H5P_iterate_t operator is as follows: - * \snippet this H5P_iterate_t_snip - * - * The operation receives the property list or class + * The operation \p iter_func receives the property list or class * identifier for the object being iterated over, \p id, the * name of the current property within the object, \p name, * and the pointer to the operator data passed in to H5Piterate(), - * \p iter_data. The valid return values from an operator are - * as follows: + * \p iter_data. * * <table> * <tr> @@ -1829,9 +1976,6 @@ H5_DLL herr_t H5Pget_attr_phase_change(hid_t plist_id, unsigned *max_compact, un * * \brief Returns information about a filter in a pipeline * - * \todo Signature for H5Pget_filter2 is different in H5Pocpl.c than in - * H5Ppublic.h - * * \ocpl_id{plist_id} * \param[in] idx Sequence number within the filter pipeline of the filter * for which information is sought @@ -2190,7 +2334,7 @@ H5_DLL herr_t H5Pset_attr_creation_order(hid_t plist_id, unsigned crt_order_flag */ H5_DLL herr_t H5Pset_attr_phase_change(hid_t plist_id, unsigned max_compact, unsigned min_dense); /** - * \ingroup OCPL + * \ingroup DCPL * * \brief Sets deflate (GNU gzip) compression method and compression level * @@ -2199,6 +2343,8 @@ H5_DLL herr_t H5Pset_attr_phase_change(hid_t plist_id, unsigned max_compact, uns * * \return \herr_t * + * \par_compr_note + * * \details H5Pset_deflate() sets the deflate compression method and the * compression level, \p level, for a dataset or group creation * property list, \p plist_id. @@ -3751,17 +3897,14 @@ H5_DLL herr_t H5Pset_alignment(hid_t fapl_id, hsize_t threshold, hsize_t alignme * * \note Note: Raw dataset chunk caching is not currently * supported when using the MPI I/O and MPI POSIX file drivers - * in read/write mode; see H5Pset_fapl_mpio() and - * H5Pset_fapl_mpiposix(), respectively. When using one of these - * file drivers, all calls to H5Dread() and H5Dwrite() will access + * in read/write mode; see H5Pset_fapl_mpio(). When using this + * file driver, all calls to H5Dread() and H5Dwrite() will access * the disk directly, and H5Pset_cache() will have no effect on * performance. * * \note Raw dataset chunk caching is supported when these drivers are * used in read-only mode. * - * \todo Check on H5Pset_fapl_mpio() and H5Pset_fapl_mpiposix(). - * * \version 1.8.0 The use of the \p mdc_nelmts parameter was discontinued. * Metadata cache configuration is managed with * H5Pset_mdc_config() and H5Pget_mdc_config(). @@ -3869,7 +4012,7 @@ H5_DLL herr_t H5Pset_driver(hid_t plist_id, hid_t driver_id, const void *driver_ * The <em>external link open file cache</em> holds files open after * they have been accessed via an external link. This cache reduces * the number of times such files are opened when external links are - * accessed repeatedly and can siginificantly improves performance in + * accessed repeatedly and can significantly improves performance in * certain heavy-use situations and when low-level file opens or closes * are expensive. * @@ -4638,6 +4781,7 @@ H5_DLL herr_t H5Pget_alloc_time(hid_t plist_id, H5D_alloc_time_t *alloc_time /*o */ H5_DLL int H5Pget_chunk(hid_t plist_id, int max_ndims, hsize_t dim[] /*out*/); /** + * * \ingroup DCPL * * \brief Returns information about an external file @@ -5047,6 +5191,8 @@ H5_DLL herr_t H5Pset_fill_value(hid_t plist_id, hid_t type_id, const void *value * * \return \herr_t * + * \par_compr_note + * * \details H5Pset_shuffle() sets the shuffle filter, #H5Z_FILTER_SHUFFLE, * in the dataset creation property list \p plist_id. The shuffle * filter de-interlaces a block of data by reordering the bytes. @@ -5116,6 +5262,8 @@ H5_DLL herr_t H5Pset_layout(hid_t plist_id, H5D_layout_t layout); * * \return \herr_t * + * \par_compr_note + * * \details H5Pset_nbit() sets the N-Bit filter, #H5Z_FILTER_NBIT, in the * dataset creation property list \p plist_id. * @@ -5138,10 +5286,10 @@ H5_DLL herr_t H5Pset_layout(hid_t plist_id, H5D_layout_t layout); * <td>byte 0</td> * </tr> * <tr> - * <td>????????</td> - * <td>????SPPP</td> - * <td>PPPPPPPP</td> - * <td>PPPP????</td> + * <td> ???????? </td> + * <td> ????SPPP </td> + * <td> PPPPPPPP </td> + * <td> PPPP???? </td> * </tr> * </table> * Note: S - sign bit, P - significant bit, ? - padding bit; For @@ -5209,6 +5357,8 @@ H5_DLL herr_t H5Pset_nbit(hid_t plist_id); * * \return \herr_t * + * \par_compr_note + * * \details H5Pset_scaleoffset() sets the scale-offset filter, * #H5Z_FILTER_SCALEOFFSET, for a dataset. * @@ -5318,6 +5468,8 @@ H5_DLL herr_t H5Pset_scaleoffset(hid_t plist_id, H5Z_SO_scale_type_t scale_type, * * \return \herr_t * + * \par_compr_note + * * \details H5Pset_szip() sets an SZIP compression filter, #H5Z_FILTER_SZIP, * for a dataset. SZIP is a compression method designed for use with * scientific data. @@ -5800,10 +5952,6 @@ H5_DLL size_t H5Pget_buffer(hid_t plist_id, void **tconv /*out*/, void **bkg /*o * If an error occurs, the buffer pointed to by \p expression is * unchanged, and the function returns a negative value. * - * \par Example - * An example snippet from examples/h5_dtransform.c: - * \snippet h5_dtransform.c H5Pget_data_transform_snip - * * \since 1.8.0 * */ @@ -5867,8 +6015,11 @@ H5_DLL herr_t H5Pget_hyper_vector_size(hid_t fapl_id, size_t *size /*out*/); * \details H5Pget_preserve() checks the status of the dataset transfer * property list. * + * \since 1.0.0 + * * \version 1.6.0 The flag parameter was changed from INTEGER to LOGICAL to * better match the C API. (Fortran 90) + * \version 1.8.2 Deprecated. * */ H5_DLL int H5Pget_preserve(hid_t plist_id); @@ -5896,6 +6047,8 @@ H5_DLL int H5Pget_preserve(hid_t plist_id); * * Please refer to the function H5Pset_type_conv_cb() for more details. * + * \since 1.8.0 + * */ H5_DLL herr_t H5Pget_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t *op, void **operate_data); /** @@ -5919,6 +6072,8 @@ H5_DLL herr_t H5Pget_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t *op, voi * H5Pset_vlen_mem_manager(), returning the parameters set by * that function. * + * \since 1.0.0 + * */ H5_DLL herr_t H5Pget_vlen_mem_manager(hid_t plist_id, H5MM_allocate_t *alloc_func, void **alloc_info, H5MM_free_t *free_func, void **free_info); @@ -6162,8 +6317,9 @@ H5_DLL herr_t H5Pset_hyper_vector_size(hid_t plist_id, size_t size); * I/O pipeline treats the destination datapoints as completely * uninitialized. * - * \todo Add missing version information: introduction, deprecation, etc. - * Why is the declaration not in the deprecated section? + * \since 1.0.0 + * + * \version 1.8.2 Deprecated. * */ H5_DLL herr_t H5Pset_preserve(hid_t plist_id, hbool_t status); @@ -6191,7 +6347,7 @@ H5_DLL herr_t H5Pset_preserve(hid_t plist_id, hbool_t status); * function prototype is as follows: * \snippet H5Tpublic.h H5T_conv_except_func_t_snip * - * \todo Add version information. + * \since 1.8.0 * */ H5_DLL herr_t H5Pset_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t op, void *operate_data); @@ -6241,7 +6397,8 @@ H5_DLL herr_t H5Pset_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t op, void * set to \c NULL and the \p alloc_info and \p free_info parameters are * ignored. * - * \todo Add version information. + * \since 1.0.0 + * */ H5_DLL herr_t H5Pset_vlen_mem_manager(hid_t plist_id, H5MM_allocate_t alloc_func, void *alloc_info, H5MM_free_t free_func, void *free_info); @@ -7720,9 +7877,6 @@ H5_DLL herr_t H5Pset_mcdt_search_cb(hid_t plist_id, H5O_mcdt_search_cb_t func, v * The #H5P_prp_cb2_t is as follows: * \snippet this H5P_prp_cb2_t_snip * - * - * \cpp_c_api_note - * */ /* Function prototypes */ @@ -7836,8 +7990,7 @@ H5_DLL herr_t H5Pregister1(hid_t cls_id, const char *name, size_t size, void *de * * The #H5P_prp_cb2_t is as follows: * \snippet this H5P_prp_cb2_t_snip - - * \cpp_c_api_note + * */ H5_DLL herr_t H5Pinsert1(hid_t plist_id, const char *name, size_t size, void *value, H5P_prp_set_func_t prp_set, H5P_prp_get_func_t prp_get, diff --git a/src/H5Rpublic.h b/src/H5Rpublic.h index 4ba7da1..a84e4e8 100644 --- a/src/H5Rpublic.h +++ b/src/H5Rpublic.h @@ -11,6 +11,12 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/* + * This file contains public declarations for the H5R module. + */ +#ifndef H5Rpublic_H +#define H5Rpublic_H + /** * \defgroup H5R H5R * @@ -18,14 +24,28 @@ * be HDF5 objects, attributes, and selections on datasets a.k.a. dataset * regions. * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5R_examples.c create + * </td> + * <td> + * \snippet{lineno} H5R_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5R_examples.c update + * </td> + * <td> + * \snippet{lineno} H5R_examples.c delete + * </td> + * </tr> + * </table> + * */ -/* - * This file contains public declarations for the H5R module. - */ -#ifndef H5Rpublic_H -#define H5Rpublic_H - /* Public headers needed by this file */ #include "H5public.h" #include "H5Gpublic.h" @@ -62,7 +82,7 @@ typedef enum { H5R_BADTYPE = (-1), /**< Invalid reference type */ H5R_OBJECT, /**< Object reference */ H5R_DATASET_REGION, /**< Dataset Region Reference */ - H5R_MAXTYPE /**< Highest type (Invalid as true type) */ + H5R_MAXTYPE /**< Highest type (invalid) */ } H5R_type_t; //! <!-- [H5R_type_t_snip] --> diff --git a/src/H5Spkg.h b/src/H5Spkg.h index e2eae2a..f1a7ba5 100644 --- a/src/H5Spkg.h +++ b/src/H5Spkg.h @@ -206,12 +206,15 @@ typedef struct { /* Selection information object */ typedef struct { const H5S_select_class_t *type; /* Pointer to selection's class info */ - hbool_t offset_changed; /* Indicate that the offset for the selection has been changed */ - hssize_t offset[H5S_MAX_RANK]; /* Offset within the extent */ - hsize_t num_elem; /* Number of elements in selection */ + + hbool_t offset_changed; /* Indicate that the offset for the selection has been changed */ + hssize_t offset[H5S_MAX_RANK]; /* Offset within the extent */ + + hsize_t num_elem; /* Number of elements in selection */ + union { - H5S_pnt_list_t * pnt_lst; /* List of selected points (order is important) */ - H5S_hyper_sel_t *hslab; /* Info about hyperslab selections */ + H5S_pnt_list_t * pnt_lst; /* Info about list of selected points (order is important) */ + H5S_hyper_sel_t *hslab; /* Info about hyperslab selection */ } sel_info; } H5S_select_t; diff --git a/src/H5Spublic.h b/src/H5Spublic.h index dbe0a51..18b10a8 100644 --- a/src/H5Spublic.h +++ b/src/H5Spublic.h @@ -11,6 +11,12 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/* + * This file contains public declarations for the H5S module. + */ +#ifndef H5Spublic_H +#define H5Spublic_H + /**\defgroup H5S H5S * * Use the functions in this module to manage HDF5 dataspaces \Emph{and} selections. @@ -23,14 +29,28 @@ * using \Emph{selections}. Furthermore, certain set operations are supported * for selections. * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5S_examples.c create + * </td> + * <td> + * \snippet{lineno} H5S_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5S_examples.c update + * </td> + * <td> + * \snippet{lineno} H5S_examples.c delete + * </td> + * </tr> + * </table> + * */ -/* - * This file contains public declarations for the H5S module. - */ -#ifndef H5Spublic_H -#define H5Spublic_H - /* Public headers needed by this file */ #include "H5public.h" #include "H5Ipublic.h" @@ -39,71 +59,90 @@ #define H5S_ALL (hid_t)0 #define H5S_UNLIMITED ((hsize_t)(hssize_t)(-1)) -/* Define user-level maximum number of dimensions */ +/** + * The maximum dataspace rank or number of dimensions + */ #define H5S_MAX_RANK 32 -/* Different types of dataspaces */ +/** + * Types of dataspaces + */ typedef enum H5S_class_t { - H5S_NO_CLASS = -1, /*error */ - H5S_SCALAR = 0, /*scalar variable */ - H5S_SIMPLE = 1, /*simple dataspace */ - H5S_NULL = 2 /*null dataspace */ + H5S_NO_CLASS = -1, /**< Error */ + H5S_SCALAR = 0, /**< Singleton (scalar) */ + H5S_SIMPLE = 1, /**< Regular grid */ + H5S_NULL = 2 /**< Empty set */ } H5S_class_t; -/* Different ways of combining selections */ +/** + * Different ways of combining selections + */ typedef enum H5S_seloper_t { - H5S_SELECT_NOOP = -1, /* error */ - H5S_SELECT_SET = 0, /* Select "set" operation */ - H5S_SELECT_OR, /* Binary "or" operation for hyperslabs + H5S_SELECT_NOOP = -1, /**< Error */ + H5S_SELECT_SET = 0, /**< Select "set" operation */ + H5S_SELECT_OR, /**< Binary "or" operation for hyperslabs * (add new selection to existing selection) + * \code * Original region: AAAAAAAAAA * New region: BBBBBBBBBB * A or B: CCCCCCCCCCCCCCCC + * \endcode */ - H5S_SELECT_AND, /* Binary "and" operation for hyperslabs + H5S_SELECT_AND, /**< Binary "and" operation for hyperslabs * (only leave overlapped regions in selection) + * \code * Original region: AAAAAAAAAA * New region: BBBBBBBBBB * A and B: CCCC + * \endcode */ - H5S_SELECT_XOR, /* Binary "xor" operation for hyperslabs + H5S_SELECT_XOR, /**< Binary "xor" operation for hyperslabs * (only leave non-overlapped regions in selection) + * \code * Original region: AAAAAAAAAA * New region: BBBBBBBBBB * A xor B: CCCCCC CCCCCC + * \endcode */ - H5S_SELECT_NOTB, /* Binary "not" operation for hyperslabs + H5S_SELECT_NOTB, /**< Binary "not" operation for hyperslabs * (only leave non-overlapped regions in original selection) + * \code * Original region: AAAAAAAAAA * New region: BBBBBBBBBB * A not B: CCCCCC + * \endcode */ - H5S_SELECT_NOTA, /* Binary "not" operation for hyperslabs + H5S_SELECT_NOTA, /**< Binary "not" operation for hyperslabs * (only leave non-overlapped regions in new selection) + * \code * Original region: AAAAAAAAAA * New region: BBBBBBBBBB * B not A: CCCCCC + * \endcode */ - H5S_SELECT_APPEND, /* Append elements to end of point selection */ - H5S_SELECT_PREPEND, /* Prepend elements to beginning of point selection */ - H5S_SELECT_INVALID /* Invalid upper bound on selection operations */ + H5S_SELECT_APPEND, /**< Append elements to end of point selection */ + H5S_SELECT_PREPEND, /**< Prepend elements to beginning of point selection */ + H5S_SELECT_INVALID /**< Invalid upper bound on selection operations */ } H5S_seloper_t; -/* Enumerated type for the type of selection */ +/** + * Selection type + */ typedef enum { - H5S_SEL_ERROR = -1, /* Error */ - H5S_SEL_NONE = 0, /* Nothing selected */ - H5S_SEL_POINTS = 1, /* Points / elements selected */ - H5S_SEL_HYPERSLABS = 2, /* Hyperslab selected */ - H5S_SEL_ALL = 3, /* Entire extent selected */ - H5S_SEL_N /*THIS MUST BE LAST */ + H5S_SEL_ERROR = -1, /**< Error */ + H5S_SEL_NONE = 0, /**< Empty selection */ + H5S_SEL_POINTS = 1, /**< Set of points */ + H5S_SEL_HYPERSLABS = 2, /**< Hyperslab */ + H5S_SEL_ALL = 3, /**< Everything */ + H5S_SEL_N /**< Sentinel \internal THIS MUST BE LAST */ } H5S_sel_type; #ifdef __cplusplus extern "C" { #endif -/* Operations on dataspaces */ +/* Operations on dataspaces, dataspace selections and selection iterators */ + /** * \ingroup H5S * @@ -257,31 +296,31 @@ H5_DLL hid_t H5Sdecode(const void *buf); * * \space_id{obj_id} * \param[in,out] buf Buffer for the object to be encoded into; - * If the provided buffer is NULL, only the size of - * buffer needed is returned through \p nalloc. + * If the provided buffer is NULL, only the size + * of buffer needed is returned through \p nalloc. * \param[in,out] nalloc The size of the allocated buffer * * \return \herr_t * * \details Given the data space identifier \p obj_id, H5Sencode() converts - * a data space description into binary form in a buffer. Using - * this binary form in the buffer, a data space object can be - * reconstructed using H5Sdecode() to return a new object handle - * (\p hid_t) for this data space. + * a data space description into binary form in a buffer. Using this + * binary form in the buffer, a data space object can be + * reconstructed with H5Sdecode() to return a new object handle + * (#hid_t) for this data space. * - * A preliminary H5Sencode() call can be made to find out the size - * of the buffer needed. This value is returned as \p nalloc. That - * value can then be assigned to \p nalloc for a second H5Sencode1() - * call, which will retrieve the actual encoded object. + * A preliminary H5Sencode() call can be made to determine the + * size of the buffer needed. This value is returned in \p nalloc. + * That value can then be assigned to \p nalloc for a second + * H5Sencode()call, which will retrieve the actual encoded object. * - * If the library finds out \p nalloc is not big enough for the + * If the library determines that \p nalloc is not big enough for the * object, it simply returns the size of the buffer needed through * \p nalloc without encoding the provided buffer. * - * The types of data space addressed in this function are null, - * scalar, and simple space. For a simple data space, the information - * on the selection, for example, hyperslab selection, is also - * encoded and decoded. A complex data space has not been + * The types of data space that are addressed in this function are + * null, scalar, and simple space. For a simple data space, the + * information on the selection, for example, hyperslab selection, + * is also encoded and decoded. A complex data space has not been * implemented in the library. * * \since 1.8.0 diff --git a/src/H5TSprivate.h b/src/H5TSprivate.h index a0cb353..485b173 100644 --- a/src/H5TSprivate.h +++ b/src/H5TSprivate.h @@ -13,11 +13,9 @@ /*------------------------------------------------------------------------- * - * Created: H5TSprivate.h - * May 2 2000 - * Chee Wai LEE + * Created: H5TSprivate.h * - * Purpose: Private non-prototype header. + * Purpose: Thread-safety abstractions used by the library * *------------------------------------------------------------------------- */ @@ -25,9 +23,10 @@ #define H5TSprivate_H_ #ifdef H5_HAVE_THREADSAFE + /* Public headers needed by this file */ #ifdef LATER -#include "H5TSpublic.h" /*Public API prototypes */ +#include "H5TSpublic.h" /* Public API prototypes */ #endif /* LATER */ #ifdef H5_HAVE_WIN_THREADS @@ -38,6 +37,8 @@ typedef struct H5TS_mutex_struct { CRITICAL_SECTION CriticalSection; } H5TS_mutex_t; + +/* Portability wrappers around Windows Threads types */ typedef CRITICAL_SECTION H5TS_mutex_simple_t; typedef HANDLE H5TS_thread_t; typedef HANDLE H5TS_attr_t; @@ -50,7 +51,7 @@ typedef INIT_ONCE H5TS_once_t; #define H5TS_SCOPE_PROCESS 0 #define H5TS_CALL_CONV WINAPI -/* Functions */ +/* Portability function aliases */ #define H5TS_get_thread_local_value(key) TlsGetValue(key) #define H5TS_set_thread_local_value(key, value) TlsSetValue(key, value) #define H5TS_attr_init(attr_ptr) 0 @@ -80,6 +81,8 @@ typedef struct H5TS_mutex_struct { pthread_cond_t cond_var; /* condition variable */ unsigned int lock_count; } H5TS_mutex_t; + +/* Portability wrappers around pthread types */ typedef pthread_t H5TS_thread_t; typedef pthread_attr_t H5TS_attr_t; typedef pthread_mutex_t H5TS_mutex_simple_t; @@ -91,7 +94,7 @@ typedef pthread_once_t H5TS_once_t; #define H5TS_SCOPE_PROCESS PTHREAD_SCOPE_PROCESS #define H5TS_CALL_CONV /* unused - Windows only */ -/* Functions */ +/* Portability function aliases */ #define H5TS_get_thread_local_value(key) pthread_getspecific(key) #define H5TS_set_thread_local_value(key, value) pthread_setspecific(key, value) #define H5TS_attr_init(attr_ptr) pthread_attr_init((attr_ptr)) @@ -101,6 +104,8 @@ typedef pthread_once_t H5TS_once_t; #define H5TS_mutex_init(mutex) pthread_mutex_init(mutex, NULL) #define H5TS_mutex_lock_simple(mutex) pthread_mutex_lock(mutex) #define H5TS_mutex_unlock_simple(mutex) pthread_mutex_unlock(mutex) + +/* Pthread-only routines */ H5_DLL uint64_t H5TS_thread_id(void); #endif /* H5_HAVE_WIN_THREADS */ @@ -128,6 +133,7 @@ H5_DLL H5TS_thread_t H5TS_create_thread(void *(*func)(void *), H5TS_attr_t *attr #else /* H5_HAVE_THREADSAFE */ +/* Non-threadsafe code needs this */ #define H5TS_thread_id() ((uint64_t)0) #endif /* H5_HAVE_THREADSAFE */ diff --git a/src/H5Tpkg.h b/src/H5Tpkg.h index 53112f7..564de61 100644 --- a/src/H5Tpkg.h +++ b/src/H5Tpkg.h @@ -116,7 +116,7 @@ #endif /* Define an internal macro for converting unsigned long long to long double. SGI compilers give - * some incorect conversion. 64-bit Solaris does different rounding. Windows Visual Studio 6 does + * some incorrect conversion. 64-bit Solaris does different rounding. Windows Visual Studio 6 does * not support unsigned long long. For FreeBSD(sleipnir), the last 2 bytes of mantissa are lost when * compiler tries to do the conversion. For Cygwin, compiler doesn't do rounding correctly. * Mac OS 10.4 gives some incorrect result. */ diff --git a/src/H5Tprivate.h b/src/H5Tprivate.h index b7c203c..7ec8aff 100644 --- a/src/H5Tprivate.h +++ b/src/H5Tprivate.h @@ -17,11 +17,11 @@ #ifndef H5Tprivate_H #define H5Tprivate_H -/* Get package's public header */ +/* Include package's public header */ #include "H5Tpublic.h" /* Other public headers needed by this file */ -#include "H5MMpublic.h" /* Memory management */ +#include "H5MMpublic.h" /* Memory management */ /* Private headers needed by this file */ #include "H5private.h" /* Generic Functions */ diff --git a/src/H5Tpublic.h b/src/H5Tpublic.h index b5dc566..8485bd9 100644 --- a/src/H5Tpublic.h +++ b/src/H5Tpublic.h @@ -11,6 +11,12 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/* + * This file contains public declarations for the H5T module. + */ +#ifndef H5Tpublic_H +#define H5Tpublic_H + /**\defgroup H5T H5T * * Use the functions in this module to manage HDF5 datatypes. @@ -24,6 +30,26 @@ * to HDF5 files and linked to groups as HDF5 datatype objects or so-called * \Emph{committed datatypes}. * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5T_examples.c create + * </td> + * <td> + * \snippet{lineno} H5T_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5T_examples.c update + * </td> + * <td> + * \snippet{lineno} H5T_examples.c delete + * </td> + * </tr> + * </table> + * * \defgroup ARRAY Array Datatypes * \ingroup H5T * \defgroup ATOM Atomic Datatypes @@ -91,12 +117,6 @@ * */ -/* - * This file contains public declarations for the H5T module. - */ -#ifndef H5Tpublic_H -#define H5Tpublic_H - /* Public headers needed by this file */ #include "H5public.h" #include "H5Ipublic.h" @@ -228,7 +248,7 @@ typedef enum H5T_pad_t { H5T_PAD_ONE = 1, /**< always set to one */ H5T_PAD_BACKGROUND = 2, /**< set to background value */ - H5T_NPAD = 3 /**< sentinal: THIS MUST BE LAST */ + H5T_NPAD = 3 /**< sentinel: THIS MUST BE LAST */ } H5T_pad_t; //! <!-- [H5T_pad_t_snip] --> @@ -276,9 +296,9 @@ typedef enum H5T_pers_t { */ //! <!-- [H5T_direction_t_snip] --> typedef enum H5T_direction_t { - H5T_DIR_DEFAULT = 0, /**< default direction is inscendent */ - H5T_DIR_ASCEND = 1, /**< in inscendent order */ - H5T_DIR_DESCEND = 2 /**< in descendent order */ + H5T_DIR_DEFAULT = 0, /**< default direction is ascending */ + H5T_DIR_ASCEND = 1, /**< in ascending order */ + H5T_DIR_DESCEND = 2 /**< in descending order */ } H5T_direction_t; //! <!-- [H5T_direction_t_snip] --> @@ -359,7 +379,7 @@ typedef herr_t (*H5T_conv_t)(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, siz * \returns Valid callback function return values are #H5T_CONV_ABORT, * #H5T_CONV_UNHANDLED and #H5T_CONV_HANDLED. * - * \details If an exception like overflow happenes during conversion, this + * \details If an exception like overflow happens during conversion, this * function is called if it's registered through H5Pset_type_conv_cb(). * */ @@ -1278,7 +1298,7 @@ H5_DLL herr_t H5Tlock(hid_t type_id); * the link(s) by which the new committed datatype is accessed and * the creation of any intermediate groups that may be missing. * - * Once commited, this datatype may be used to define the datatype + * Once committed, this datatype may be used to define the datatype * of any other dataset or attribute in the file. * * This function will not accept a datatype that cannot actually hold @@ -1288,7 +1308,7 @@ H5_DLL herr_t H5Tlock(hid_t type_id); * Committed datatypes are sometimes referred to as named datatypes. * * \version 1.8.7 Function modified in this release to reject datatypes that - * will not accomodate actual data, such as a compound datatype + * will not accommodate actual data, such as a compound datatype * with no fields or an enumerated datatype with no members. * * \since 1.8.0 @@ -1366,7 +1386,7 @@ H5_DLL hid_t H5Topen2(hid_t loc_id, const char *name, hid_t tapl_id); * fields and enumerated datatypes with no members. * * \version 1.8.7 Function modified in this release to reject datatypes that - * will not accomodate actual data, such as a compound datatype + * will not accommodate actual data, such as a compound datatype * with no fields or an enumerated datatype with no members. * * \since 1.2.0 @@ -2698,7 +2718,6 @@ H5_DLL herr_t H5Tset_cset(hid_t type_id, H5T_cset_t cset); */ H5_DLL herr_t H5Tset_strpad(hid_t type_id, H5T_str_t strpad); -/* Type conversion database */ /** * \ingroup CONV * diff --git a/src/H5Zpublic.h b/src/H5Zpublic.h index e1b3312..bb92595 100644 --- a/src/H5Zpublic.h +++ b/src/H5Zpublic.h @@ -11,6 +11,13 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/* Programmer: Robb Matzke + * Thursday, April 16, 1998 + */ + +#ifndef H5Zpublic_H +#define H5Zpublic_H + /**\defgroup H5Z H5Z * * Use the functions in this module to manage HDF5 filters. @@ -25,6 +32,27 @@ * * Filters are deleted by unregistering. * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5Z_examples.c filter + * \snippet{lineno} H5Z_examples.c create + * </td> + * <td> + * \snippet{lineno} H5Z_examples.c read + * </td> + * </tr> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5Z_examples.c update + * </td> + * <td> + * \snippet{lineno} H5Z_examples.c delete + * </tr> + * </table> + * * HDF5 supports a filter pipeline that provides the capability for standard and * customized raw data processing during I/O operations. HDF5 is distributed * with a small set of standard filters such as compression (gzip, SZIP, and a @@ -78,13 +106,6 @@ * */ -/* Programmer: Robb Matzke - * Thursday, April 16, 1998 - */ - -#ifndef H5Zpublic_H -#define H5Zpublic_H - /* Public headers needed by this file */ #include "H5public.h" @@ -754,4 +775,5 @@ typedef struct H5Z_class1_t { #ifdef __cplusplus } #endif -#endif + +#endif /* _H5Zpublic_H */ diff --git a/src/H5private.h b/src/H5private.h index ef0bd82..d388fbd 100644 --- a/src/H5private.h +++ b/src/H5private.h @@ -82,9 +82,9 @@ #endif /* - * The `struct stat' data type for stat() and fstat(). This is a Posix file - * but often apears on non-Posix systems also. The `struct stat' is required - * for hdf5 to compile, although only a few fields are actually used. + * The `struct stat' data type for stat() and fstat(). This is a POSIX file + * but often apears on non-POSIX systems also. The `struct stat' is required + * for HDF5 to compile, although only a few fields are actually used. */ #ifdef H5_HAVE_SYS_STAT_H #include <sys/stat.h> @@ -164,6 +164,7 @@ #define H5_DEFAULT_VFD H5FD_SEC2 #ifdef H5_HAVE_WIN32_API + /* The following two defines must be before any windows headers are included */ #define WIN32_LEAN_AND_MEAN /* Exclude rarely-used stuff from Windows headers */ #define NOGDI /* Exclude Graphic Display Interface macros */ @@ -581,259 +582,259 @@ typedef struct { #ifndef HDabort #define HDabort() abort() -#endif /* HDabort */ +#endif #ifndef HDabs #define HDabs(X) abs(X) -#endif /* HDabs */ +#endif #ifndef HDaccess #define HDaccess(F, M) access(F, M) -#endif /* HDaccess */ +#endif #ifndef HDacos #define HDacos(X) acos(X) -#endif /* HDacos */ +#endif #ifndef HDalarm #ifdef H5_HAVE_ALARM #define HDalarm(N) alarm(N) -#else /* H5_HAVE_ALARM */ +#else #define HDalarm(N) (0) -#endif /* H5_HAVE_ALARM */ -#endif /* HDalarm */ +#endif +#endif #ifndef HDasctime #define HDasctime(T) asctime(T) -#endif /* HDasctime */ +#endif #ifndef HDasin #define HDasin(X) asin(X) -#endif /* HDasin */ +#endif #ifndef HDasprintf #define HDasprintf asprintf /*varargs*/ -#endif /* HDasprintf */ +#endif #ifndef HDassert #define HDassert(X) assert(X) -#endif /* HDassert */ +#endif #ifndef HDatan #define HDatan(X) atan(X) -#endif /* HDatan */ +#endif #ifndef HDatan2 #define HDatan2(X, Y) atan2(X, Y) -#endif /* HDatan2 */ +#endif #ifndef HDatexit #define HDatexit(F) atexit(F) -#endif /* HDatexit */ +#endif #ifndef HDatof #define HDatof(S) atof(S) -#endif /* HDatof */ +#endif #ifndef HDatoi #define HDatoi(S) atoi(S) -#endif /* HDatoi */ +#endif #ifndef HDatol #define HDatol(S) atol(S) -#endif /* HDatol */ +#endif #ifndef HDatoll #define HDatoll(S) atoll(S) -#endif /* HDatol */ +#endif #ifndef HDbsearch #define HDbsearch(K, B, N, Z, F) bsearch(K, B, N, Z, F) -#endif /* HDbsearch */ +#endif #ifndef HDcalloc #define HDcalloc(N, Z) calloc(N, Z) -#endif /* HDcalloc */ +#endif #ifndef HDceil #define HDceil(X) ceil(X) -#endif /* HDceil */ +#endif #ifndef HDcfgetispeed #define HDcfgetispeed(T) cfgetispeed(T) -#endif /* HDcfgetispeed */ +#endif #ifndef HDcfgetospeed #define HDcfgetospeed(T) cfgetospeed(T) -#endif /* HDcfgetospeed */ +#endif #ifndef HDcfsetispeed #define HDcfsetispeed(T, S) cfsetispeed(T, S) -#endif /* HDcfsetispeed */ +#endif #ifndef HDcfsetospeed #define HDcfsetospeed(T, S) cfsetospeed(T, S) -#endif /* HDcfsetospeed */ +#endif #ifndef HDchdir #define HDchdir(S) chdir(S) -#endif /* HDchdir */ +#endif #ifndef HDchmod #define HDchmod(S, M) chmod(S, M) -#endif /* HDchmod */ +#endif #ifndef HDchown #define HDchown(S, O, G) chown(S, O, G) -#endif /* HDchown */ +#endif #ifndef HDclearerr #define HDclearerr(F) clearerr(F) -#endif /* HDclearerr */ +#endif #ifndef HDclock #define HDclock() clock() -#endif /* HDclock */ +#endif #ifndef HDclose #define HDclose(F) close(F) -#endif /* HDclose */ +#endif #ifndef HDclosedir #define HDclosedir(D) closedir(D) -#endif /* HDclosedir */ +#endif #ifndef HDcos #define HDcos(X) cos(X) -#endif /* HDcos */ +#endif #ifndef HDcosh #define HDcosh(X) cosh(X) -#endif /* HDcosh */ +#endif #ifndef HDcreat #define HDcreat(S, M) creat(S, M) -#endif /* HDcreat */ +#endif #ifndef HDctermid #define HDctermid(S) ctermid(S) -#endif /* HDctermid */ +#endif #ifndef HDctime #define HDctime(T) ctime(T) -#endif /* HDctime */ +#endif #ifndef HDcuserid #define HDcuserid(S) cuserid(S) -#endif /* HDcuserid */ +#endif #ifndef HDdifftime #ifdef H5_HAVE_DIFFTIME #define HDdifftime(X, Y) difftime(X, Y) -#else /* H5_HAVE_DIFFTIME */ +#else #define HDdifftime(X, Y) ((double)(X) - (double)(Y)) -#endif /* H5_HAVE_DIFFTIME */ -#endif /* HDdifftime */ +#endif +#endif #ifndef HDdiv #define HDdiv(X, Y) div(X, Y) -#endif /* HDdiv */ +#endif #ifndef HDdup #define HDdup(F) dup(F) -#endif /* HDdup */ +#endif #ifndef HDdup2 #define HDdup2(F, I) dup2(F, I) -#endif /* HDdup2 */ +#endif /* execl() variable arguments */ /* execle() variable arguments */ /* execlp() variable arguments */ #ifndef HDexecv #define HDexecv(S, AV) execv(S, AV) -#endif /* HDexecv */ +#endif #ifndef HDexecve #define HDexecve(S, AV, E) execve(S, AV, E) -#endif /* HDexecve */ +#endif #ifndef HDexecvp #define HDexecvp(S, AV) execvp(S, AV) -#endif /* HDexecvp */ +#endif #ifndef HDexit #define HDexit(N) exit(N) -#endif /* HDexit */ +#endif #ifndef HD_exit #define HD_exit(N) _exit(N) -#endif /* HD_exit */ +#endif #ifndef HDexp #define HDexp(X) exp(X) -#endif /* HDexp */ +#endif #ifndef HDexp2 #define HDexp2(X) exp2(X) -#endif /* HDexp2 */ +#endif #ifndef HDfabs #define HDfabs(X) fabs(X) -#endif /* HDfabs */ +#endif /* use ABS() because fabsf() fabsl() are not common yet. */ #ifndef HDfabsf #define HDfabsf(X) ABS(X) -#endif /* HDfabsf */ +#endif #ifndef HDfabsl #define HDfabsl(X) ABS(X) -#endif /* HDfabsl */ +#endif #ifndef HDfclose #define HDfclose(F) fclose(F) -#endif /* HDfclose */ +#endif /* fcntl() variable arguments */ #ifndef HDfdopen #define HDfdopen(N, S) fdopen(N, S) -#endif /* HDfdopen */ +#endif #ifndef HDfeof #define HDfeof(F) feof(F) -#endif /* HDfeof */ +#endif #ifndef HDferror #define HDferror(F) ferror(F) -#endif /* HDferror */ +#endif #ifndef HDfflush #define HDfflush(F) fflush(F) -#endif /* HDfflush */ +#endif #ifndef HDfgetc #define HDfgetc(F) fgetc(F) -#endif /* HDfgetc */ +#endif #ifndef HDfgetpos #define HDfgetpos(F, P) fgetpos(F, P) -#endif /* HDfgetpos */ +#endif #ifndef HDfgets #define HDfgets(S, N, F) fgets(S, N, F) -#endif /* HDfgets */ +#endif #ifndef HDfileno #define HDfileno(F) fileno(F) -#endif /* HDfileno */ +#endif #ifndef HDfloor #define HDfloor(X) floor(X) -#endif /* HDfloor */ +#endif #ifndef HDfmod #define HDfmod(X, Y) fmod(X, Y) -#endif /* HDfmod */ +#endif #ifndef HDfopen #define HDfopen(S, M) fopen(S, M) -#endif /* HDfopen */ +#endif #ifndef HDfork #define HDfork() fork() -#endif /* HDfork */ +#endif #ifndef HDfpathconf #define HDfpathconf(F, N) fpathconf(F, N) -#endif /* HDfpathconf */ +#endif H5_DLL int HDfprintf(FILE *stream, const char *fmt, ...); #ifndef HDfputc #define HDfputc(C, F) fputc(C, F) -#endif /* HDfputc */ +#endif #ifndef HDfputs #define HDfputs(S, F) fputs(S, F) -#endif /* HDfputs */ +#endif #ifndef HDfread #define HDfread(M, Z, N, F) fread(M, Z, N, F) -#endif /* HDfread */ +#endif #ifndef HDfree #define HDfree(M) free(M) -#endif /* HDfree */ +#endif #ifndef HDfreopen #define HDfreopen(S, M, F) freopen(S, M, F) -#endif /* HDfreopen */ +#endif #ifndef HDfrexp #define HDfrexp(X, N) frexp(X, N) -#endif /* HDfrexp */ +#endif /* Check for Cray-specific 'frexpf()' and 'frexpl()' routines */ #ifndef HDfrexpf #ifdef H5_HAVE_FREXPF #define HDfrexpf(X, N) frexpf(X, N) -#else /* H5_HAVE_FREXPF */ +#else #define HDfrexpf(X, N) frexp(X, N) -#endif /* H5_HAVE_FREXPF */ -#endif /* HDfrexpf */ +#endif +#endif #ifndef HDfrexpl #ifdef H5_HAVE_FREXPL #define HDfrexpl(X, N) frexpl(X, N) -#else /* H5_HAVE_FREXPL */ +#else #define HDfrexpl(X, N) frexp(X, N) -#endif /* H5_HAVE_FREXPL */ -#endif /* HDfrexpl */ +#endif +#endif /* fscanf() variable arguments */ #ifndef HDfseek #define HDfseek(F, O, W) fseeko(F, O, W) -#endif /* HDfseek */ +#endif #ifndef HDfsetpos #define HDfsetpos(F, P) fsetpos(F, P) -#endif /* HDfsetpos */ +#endif #ifndef HDfstat #define HDfstat(F, B) fstat(F, B) -#endif /* HDfstat */ +#endif #ifndef HDlstat #define HDlstat(S, B) lstat(S, B) -#endif /* HDlstat */ +#endif #ifndef HDstat #define HDstat(S, B) stat(S, B) -#endif /* HDstat */ +#endif #ifndef H5_HAVE_WIN32_API /* These definitions differ in Windows and are defined in @@ -848,628 +849,633 @@ typedef off_t h5_stat_size_t; #ifndef HDftell #define HDftell(F) ftell(F) -#endif /* HDftell */ +#endif #ifndef HDftruncate #define HDftruncate(F, L) ftruncate(F, L) -#endif /* HDftruncate */ +#endif #ifndef HDfwrite #define HDfwrite(M, Z, N, F) fwrite(M, Z, N, F) -#endif /* HDfwrite */ +#endif #ifndef HDgetc #define HDgetc(F) getc(F) -#endif /* HDgetc */ +#endif #ifndef HDgetchar #define HDgetchar() getchar() -#endif /* HDgetchar */ +#endif #ifndef HDgetcwd #define HDgetcwd(S, Z) getcwd(S, Z) -#endif /* HDgetcwd */ +#endif #ifndef HDgetdcwd #define HDgetdcwd(D, S, Z) getcwd(S, Z) -#endif /* HDgetdcwd */ +#endif + +/* Windows only - set to zero on other systems */ #ifndef HDgetdrive #define HDgetdrive() 0 -#endif /* HDgetdrive */ +#endif + #ifndef HDgetegid #define HDgetegid() getegid() -#endif /* HDgetegid() */ +#endif #ifndef HDgetenv #define HDgetenv(S) getenv(S) -#endif /* HDgetenv */ +#endif #ifndef HDgeteuid #define HDgeteuid() geteuid() -#endif /* HDgeteuid */ +#endif #ifndef HDgetgid #define HDgetgid() getgid() -#endif /* HDgetgid */ +#endif #ifndef HDgetgrgid #define HDgetgrgid(G) getgrgid(G) -#endif /* HDgetgrgid */ +#endif #ifndef HDgetgrnam #define HDgetgrnam(S) getgrnam(S) -#endif /* HDgetgrnam */ +#endif #ifndef HDgetgroups #define HDgetgroups(Z, G) getgroups(Z, G) -#endif /* HDgetgroups */ +#endif #ifndef HDgethostname #define HDgethostname(N, L) gethostname(N, L) -#endif /* HDgethostname */ +#endif #ifndef HDgetlogin #define HDgetlogin() getlogin() -#endif /* HDgetlogin */ +#endif #ifndef HDgetpgrp #define HDgetpgrp() getpgrp() -#endif /* HDgetpgrp */ +#endif #ifndef HDgetpid #define HDgetpid() getpid() -#endif /* HDgetpid */ +#endif #ifndef HDgetppid #define HDgetppid() getppid() -#endif /* HDgetppid */ +#endif #ifndef HDgetpwnam #define HDgetpwnam(S) getpwnam(S) -#endif /* HDgetpwnam */ +#endif #ifndef HDgetpwuid #define HDgetpwuid(U) getpwuid(U) -#endif /* HDgetpwuid */ +#endif #ifndef HDgetrusage #define HDgetrusage(X, S) getrusage(X, S) -#endif /* HDgetrusage */ +#endif #ifndef HDgets #define HDgets(S) gets(S) -#endif /* HDgets */ +#endif #ifndef HDgettimeofday #define HDgettimeofday(S, P) gettimeofday(S, P) -#endif /* HDgettimeofday */ +#endif #ifndef HDgetuid #define HDgetuid() getuid() -#endif /* HDgetuid */ +#endif #ifndef HDgmtime #define HDgmtime(T) gmtime(T) -#endif /* HDgmtime */ +#endif #ifndef HDisalnum -#define HDisalnum(C) isalnum((int)(C)) /*cast for solaris warning*/ -#endif /* HDisalnum */ +#define HDisalnum(C) isalnum((int)(C)) /* Cast for Solaris warning */ +#endif #ifndef HDisalpha -#define HDisalpha(C) isalpha((int)(C)) /*cast for solaris warning*/ -#endif /* HDisalpha */ +#define HDisalpha(C) isalpha((int)(C)) /* Cast for Solaris warning */ +#endif #ifndef HDisatty #define HDisatty(F) isatty(F) -#endif /* HDisatty */ +#endif #ifndef HDiscntrl -#define HDiscntrl(C) iscntrl((int)(C)) /*cast for solaris warning*/ -#endif /* HDiscntrl */ +#define HDiscntrl(C) iscntrl((int)(C)) /* Cast for solaris warning */ +#endif #ifndef HDisdigit -#define HDisdigit(C) isdigit((int)(C)) /*cast for solaris warning*/ -#endif /* HDisdigit */ +#define HDisdigit(C) isdigit((int)(C)) /* Cast for Solaris warning */ +#endif #ifndef HDisgraph -#define HDisgraph(C) isgraph((int)(C)) /*cast for solaris warning*/ -#endif /* HDisgraph */ +#define HDisgraph(C) isgraph((int)(C)) /* Cast for Solaris warning*/ +#endif #ifndef HDislower -#define HDislower(C) islower((int)(C)) /*cast for solaris warning*/ -#endif /* HDislower */ +#define HDislower(C) islower((int)(C)) /* Cast for Solaris warning */ +#endif #ifndef HDisnan #define HDisnan(X) isnan(X) -#endif /* HDisnan */ +#endif #ifndef HDisprint -#define HDisprint(C) isprint((int)(C)) /*cast for solaris warning*/ -#endif /* HDisprint */ +#define HDisprint(C) isprint((int)(C)) /* Cast for Solaris warning */ +#endif #ifndef HDispunct -#define HDispunct(C) ispunct((int)(C)) /*cast for solaris warning*/ -#endif /* HDispunct */ +#define HDispunct(C) ispunct((int)(C)) /* Cast for Solaris warning */ +#endif #ifndef HDisspace -#define HDisspace(C) isspace((int)(C)) /*cast for solaris warning*/ -#endif /* HDisspace */ +#define HDisspace(C) isspace((int)(C)) /* Cast for Solaris warning */ +#endif #ifndef HDisupper -#define HDisupper(C) isupper((int)(C)) /*cast for solaris warning*/ -#endif /* HDisupper */ +#define HDisupper(C) isupper((int)(C)) /* Cast for Solaris warning */ +#endif #ifndef HDisxdigit -#define HDisxdigit(C) isxdigit((int)(C)) /*cast for solaris warning*/ -#endif /* HDisxdigit */ +#define HDisxdigit(C) isxdigit((int)(C)) /* Cast for Solaris warning */ +#endif #ifndef HDkill #define HDkill(P, S) kill(P, S) -#endif /* HDkill */ +#endif #ifndef HDlabs #define HDlabs(X) labs(X) -#endif /* HDlabs */ +#endif #ifndef HDldexp #define HDldexp(X, N) ldexp(X, N) -#endif /* HDldexp */ +#endif #ifndef HDldiv #define HDldiv(X, Y) ldiv(X, Y) -#endif /* HDldiv */ +#endif #ifndef HDlink #define HDlink(OLD, NEW) link(OLD, NEW) -#endif /* HDlink */ +#endif #ifndef HDllround #define HDllround(V) llround(V) -#endif /* HDround */ +#endif #ifndef HDllroundf #define HDllroundf(V) llroundf(V) -#endif /* HDllroundf */ +#endif #ifndef HDllroundl #define HDllroundl(V) llroundl(V) -#endif /* HDllroundl */ +#endif #ifndef HDlocaleconv #define HDlocaleconv() localeconv() -#endif /* HDlocaleconv */ +#endif #ifndef HDlocaltime #define HDlocaltime(T) localtime(T) -#endif /* HDlocaltime */ +#endif #ifndef HDlog #define HDlog(X) log(X) -#endif /* HDlog */ +#endif #ifndef HDlog10 #define HDlog10(X) log10(X) -#endif /* HDlog10 */ +#endif #ifndef HDlongjmp #define HDlongjmp(J, N) longjmp(J, N) -#endif /* HDlongjmp */ +#endif #ifndef HDlround #define HDlround(V) lround(V) -#endif /* HDround */ +#endif #ifndef HDlroundf #define HDlroundf(V) lroundf(V) -#endif /* HDlroundf */ +#endif #ifndef HDlroundl #define HDlroundl(V) lroundl(V) -#endif /* HDroundl */ +#endif #ifndef HDlseek #define HDlseek(F, O, W) lseek(F, O, W) -#endif /* HDlseek */ +#endif #ifndef HDmalloc #define HDmalloc(Z) malloc(Z) -#endif /* HDmalloc */ +#endif #ifndef HDposix_memalign #define HDposix_memalign(P, A, Z) posix_memalign(P, A, Z) -#endif /* HDposix_memalign */ +#endif #ifndef HDmblen #define HDmblen(S, N) mblen(S, N) -#endif /* HDmblen */ +#endif #ifndef HDmbstowcs #define HDmbstowcs(P, S, Z) mbstowcs(P, S, Z) -#endif /* HDmbstowcs */ +#endif #ifndef HDmbtowc #define HDmbtowc(P, S, Z) mbtowc(P, S, Z) -#endif /* HDmbtowc */ +#endif #ifndef HDmemchr #define HDmemchr(S, C, Z) memchr(S, C, Z) -#endif /* HDmemchr */ +#endif #ifndef HDmemcmp #define HDmemcmp(X, Y, Z) memcmp(X, Y, Z) -#endif /* HDmemcmp */ +#endif /* * The (char*) casts are required for the DEC when optimizations are turned * on and the source and/or destination are not aligned. */ #ifndef HDmemcpy #define HDmemcpy(X, Y, Z) memcpy((char *)(X), (const char *)(Y), Z) -#endif /* HDmemcpy */ +#endif #ifndef HDmemmove #define HDmemmove(X, Y, Z) memmove((char *)(X), (const char *)(Y), Z) -#endif /* HDmemmove */ +#endif #ifndef HDmemset #define HDmemset(X, C, Z) memset(X, C, Z) -#endif /* HDmemset */ +#endif #ifndef HDmkdir #define HDmkdir(S, M) mkdir(S, M) -#endif /* HDmkdir */ +#endif #ifndef HDmkfifo #define HDmkfifo(S, M) mkfifo(S, M) -#endif /* HDmkfifo */ +#endif #ifndef HDmktime #define HDmktime(T) mktime(T) -#endif /* HDmktime */ +#endif #ifndef HDmodf #define HDmodf(X, Y) modf(X, Y) -#endif /* HDmodf */ +#endif #ifndef HDnanosleep #define HDnanosleep(N, O) nanosleep(N, O) -#endif /* HDnanosleep */ +#endif #ifndef HDopen #define HDopen(F, ...) open(F, __VA_ARGS__) -#endif /* HDopen */ +#endif #ifndef HDopendir #define HDopendir(S) opendir(S) -#endif /* HDopendir */ +#endif #ifndef HDpathconf #define HDpathconf(S, N) pathconf(S, N) -#endif /* HDpathconf */ +#endif #ifndef HDpause #define HDpause() pause() -#endif /* HDpause */ +#endif #ifndef HDperror #define HDperror(S) perror(S) -#endif /* HDperror */ +#endif #ifndef HDpipe #define HDpipe(F) pipe(F) -#endif /* HDpipe */ +#endif #ifndef HDpow #define HDpow(X, Y) pow(X, Y) -#endif /* HDpow */ +#endif /* printf() variable arguments */ #ifndef HDprintf #define HDprintf(...) HDfprintf(stdout, __VA_ARGS__) -#endif /* HDprintf */ +#endif #ifndef HDputc #define HDputc(C, F) putc(C, F) -#endif /* HDputc*/ +#endif #ifndef HDputchar #define HDputchar(C) putchar(C) -#endif /* HDputchar */ +#endif #ifndef HDputs #define HDputs(S) puts(S) -#endif /* HDputs */ +#endif #ifndef HDqsort #define HDqsort(M, N, Z, F) qsort(M, N, Z, F) -#endif /* HDqsort*/ +#endif #ifndef HDraise #define HDraise(N) raise(N) -#endif /* HDraise */ +#endif +/* clang-format off */ #ifdef H5_HAVE_RAND_R -#ifndef HDrandom -#define HDrandom() HDrand() -#endif /* HDrandom */ -H5_DLL int HDrand(void); -#ifndef HDsrandom -#define HDsrandom(S) HDsrand(S) -#endif /* HDsrandom */ -H5_DLL void HDsrand(unsigned int seed); +# ifndef HDrandom +# define HDrandom() HDrand() +# endif + H5_DLL int HDrand(void); +# ifndef HDsrandom +# define HDsrandom(S) HDsrand(S) +# endif + H5_DLL void HDsrand(unsigned int seed); #elif defined(H5_HAVE_RANDOM) -#ifndef HDrand -#define HDrand() random() -#endif /* HDrand */ -#ifndef HDrandom -#define HDrandom() random() -#endif /* HDrandom */ -#ifndef HDsrand -#define HDsrand(S) srandom(S) -#endif /* HDsrand */ -#ifndef HDsrandom -#define HDsrandom(S) srandom(S) -#endif /* HDsrandom */ -#else /* H5_HAVE_RANDOM */ -#ifndef HDrand -#define HDrand() rand() -#endif /* HDrand */ -#ifndef HDrandom -#define HDrandom() rand() -#endif /* HDrandom */ -#ifndef HDsrand -#define HDsrand(S) srand(S) -#endif /* HDsrand */ -#ifndef HDsrandom -#define HDsrandom(S) srand(S) -#endif /* HDsrandom */ -#endif /* H5_HAVE_RANDOM */ +# ifndef HDrand +# define HDrand() random() +# endif +# ifndef HDrandom +# define HDrandom() random() +# endif +# ifndef HDsrand +# define HDsrand(S) srandom(S) +# endif +# ifndef HDsrandom +# define HDsrandom(S) srandom(S) +# endif +#else +# ifndef HDrand +# define HDrand() rand() +# endif +# ifndef HDrandom +# define HDrandom() rand() +# endif +# ifndef HDsrand +# define HDsrand(S) srand(S) +# endif +# ifndef HDsrandom +# define HDsrandom(S) srand(S) +# endif +#endif +/* clang-format on */ #ifndef HDread #define HDread(F, M, Z) read(F, M, Z) -#endif /* HDread */ +#endif #ifndef HDreaddir #define HDreaddir(D) readdir(D) -#endif /* HDreaddir */ +#endif #ifndef HDrealloc #define HDrealloc(M, Z) realloc(M, Z) -#endif /* HDrealloc */ +#endif #ifndef HDrealpath #define HDrealpath(F1, F2) realpath(F1, F2) -#endif /* HDrealloc */ +#endif #ifndef HDremove #define HDremove(S) remove(S) -#endif /* HDremove */ +#endif #ifndef HDrename #define HDrename(OLD, NEW) rename(OLD, NEW) -#endif /* HDrename */ +#endif #ifndef HDrewind #define HDrewind(F) rewind(F) -#endif /* HDrewind */ +#endif #ifndef HDrewinddir #define HDrewinddir(D) rewinddir(D) -#endif /* HDrewinddir */ +#endif #ifndef HDround #define HDround(V) round(V) -#endif /* HDround */ +#endif #ifndef HDroundf #define HDroundf(V) roundf(V) -#endif /* HDroundf */ +#endif #ifndef HDroundl #define HDroundl(V) roundl(V) -#endif /* HDroundl */ +#endif #ifndef HDrmdir #define HDrmdir(S) rmdir(S) -#endif /* HDrmdir */ +#endif /* scanf() variable arguments */ #ifndef HDselect #define HDselect(N, RD, WR, ER, T) select(N, RD, WR, ER, T) -#endif /* HDsetbuf */ +#endif #ifndef HDsetbuf #define HDsetbuf(F, S) setbuf(F, S) -#endif /* HDsetbuf */ +#endif #ifndef HDsetenv #define HDsetenv(N, V, O) setenv(N, V, O) -#endif /* HDsetenv */ +#endif #ifndef HDsetgid #define HDsetgid(G) setgid(G) -#endif /* HDsetgid */ +#endif #ifndef HDsetjmp #define HDsetjmp(J) setjmp(J) -#endif /* HDsetjmp */ +#endif #ifndef HDsetlocale #define HDsetlocale(N, S) setlocale(N, S) -#endif /* HDsetlocale */ +#endif #ifndef HDsetpgid #define HDsetpgid(P, PG) setpgid(P, PG) -#endif /* HDsetpgid */ +#endif #ifndef HDsetsid #define HDsetsid() setsid() -#endif /* HDsetsid */ +#endif #ifndef HDsetuid #define HDsetuid(U) setuid(U) -#endif /* HDsetuid */ +#endif #ifndef HDsetvbuf #define HDsetvbuf(F, S, M, Z) setvbuf(F, S, M, Z) -#endif /* HDsetvbuf */ +#endif #ifndef HDsigaddset #define HDsigaddset(S, N) sigaddset(S, N) -#endif /* HDsigaddset */ +#endif #ifndef HDsigdelset #define HDsigdelset(S, N) sigdelset(S, N) -#endif /* HDsigdelset */ +#endif #ifndef HDsigemptyset #define HDsigemptyset(S) sigemptyset(S) -#endif /* HDsigemptyset */ +#endif #ifndef HDsigfillset #define HDsigfillset(S) sigfillset(S) -#endif /* HDsigfillset */ +#endif #ifndef HDsigismember #define HDsigismember(S, N) sigismember(S, N) -#endif /* HDsigismember */ +#endif #ifndef HDsiglongjmp #define HDsiglongjmp(J, N) siglongjmp(J, N) -#endif /* HDsiglongjmp */ +#endif #ifndef HDsignal #define HDsignal(N, F) signal(N, F) -#endif /* HDsignal */ +#endif #ifndef HDsigpending #define HDsigpending(S) sigpending(S) -#endif /* HDsigpending */ +#endif #ifndef HDsigprocmask #define HDsigprocmask(H, S, O) sigprocmask(H, S, O) -#endif /* HDsigprocmask */ +#endif #ifndef HDsigsetjmp #define HDsigsetjmp(J, N) sigsetjmp(J, N) -#endif /* HDsigsetjmp */ +#endif #ifndef HDsigsuspend #define HDsigsuspend(S) sigsuspend(S) -#endif /* HDsigsuspend */ +#endif #ifndef HDsin #define HDsin(X) sin(X) -#endif /* HDsin */ +#endif #ifndef HDsinh #define HDsinh(X) sinh(X) -#endif /* HDsinh */ +#endif #ifndef HDsleep #define HDsleep(N) sleep(N) -#endif /* HDsleep */ +#endif #ifndef HDsnprintf #define HDsnprintf snprintf /*varargs*/ -#endif /* HDsnprintf */ +#endif #ifndef HDsprintf #define HDsprintf sprintf /*varargs*/ -#endif /* HDsprintf */ +#endif #ifndef HDsqrt #define HDsqrt(X) sqrt(X) -#endif /* HDsqrt */ +#endif #ifndef HDsscanf #define HDsscanf(S, FMT, ...) sscanf(S, FMT, __VA_ARGS__) -#endif /* HDsscanf */ +#endif #ifndef HDstrcat #define HDstrcat(X, Y) strcat(X, Y) -#endif /* HDstrcat */ +#endif #ifndef HDstrchr #define HDstrchr(S, C) strchr(S, C) -#endif /* HDstrchr */ +#endif #ifndef HDstrcmp #define HDstrcmp(X, Y) strcmp(X, Y) -#endif /* HDstrcmp */ +#endif #ifndef HDstrcasecmp #define HDstrcasecmp(X, Y) strcasecmp(X, Y) -#endif /* HDstrcasecmp */ +#endif #ifndef HDstrcoll #define HDstrcoll(X, Y) strcoll(X, Y) -#endif /* HDstrcoll */ +#endif #ifndef HDstrcpy #define HDstrcpy(X, Y) strcpy(X, Y) -#endif /* HDstrcpy */ +#endif #ifndef HDstrcspn #define HDstrcspn(X, Y) strcspn(X, Y) -#endif /* HDstrcspn */ +#endif #ifndef HDstrerror #define HDstrerror(N) strerror(N) -#endif /* HDstrerror */ +#endif #ifndef HDstrftime #define HDstrftime(S, Z, F, T) strftime(S, Z, F, T) -#endif /* HDstrftime */ +#endif #ifndef HDstrlen #define HDstrlen(S) strlen(S) -#endif /* HDstrlen */ +#endif #ifndef HDstrncat #define HDstrncat(X, Y, Z) strncat(X, Y, Z) -#endif /* HDstrncat */ +#endif #ifndef HDstrncmp #define HDstrncmp(X, Y, Z) strncmp(X, Y, Z) -#endif /* HDstrncmp */ +#endif #ifndef HDstrncpy #define HDstrncpy(X, Y, Z) strncpy(X, Y, Z) -#endif /* HDstrncpy */ +#endif #ifndef HDstrpbrk #define HDstrpbrk(X, Y) strpbrk(X, Y) -#endif /* HDstrpbrk */ +#endif #ifndef HDstrrchr #define HDstrrchr(S, C) strrchr(S, C) -#endif /* HDstrrchr */ +#endif #ifndef HDstrspn #define HDstrspn(X, Y) strspn(X, Y) -#endif /* HDstrspn */ +#endif #ifndef HDstrstr #define HDstrstr(X, Y) strstr(X, Y) -#endif /* HDstrstr */ +#endif #ifndef HDstrtod #define HDstrtod(S, R) strtod(S, R) -#endif /* HDstrtod */ +#endif #ifndef HDstrtok #define HDstrtok(X, Y) strtok(X, Y) -#endif /* HDstrtok */ +#endif #ifndef HDstrtok_r #define HDstrtok_r(X, Y, Z) strtok_r(X, Y, Z) -#endif /* HDstrtok */ +#endif #ifndef HDstrtol #define HDstrtol(S, R, N) strtol(S, R, N) -#endif /* HDstrtol */ +#endif #ifndef HDstrtoll #ifdef H5_HAVE_STRTOLL #define HDstrtoll(S, R, N) strtoll(S, R, N) #else H5_DLL int64_t HDstrtoll(const char *s, const char **rest, int base); -#endif /* H5_HAVE_STRTOLL */ -#endif /* HDstrtoll */ +#endif +#endif #ifndef HDstrtoul #define HDstrtoul(S, R, N) strtoul(S, R, N) -#endif /* HDstrtoul */ +#endif #ifndef HDstrtoull #define HDstrtoull(S, R, N) strtoull(S, R, N) -#endif /* HDstrtoul */ +#endif #ifndef HDstrtoumax #define HDstrtoumax(S, R, N) strtoumax(S, R, N) -#endif /* HDstrtoumax */ +#endif #ifndef HDstrxfrm #define HDstrxfrm(X, Y, Z) strxfrm(X, Y, Z) -#endif /* HDstrxfrm */ +#endif #ifdef H5_HAVE_SYMLINK #ifndef HDsymlink #define HDsymlink(F1, F2) symlink(F1, F2) -#endif /* HDsymlink */ -#endif /* H5_HAVE_SYMLINK */ +#endif +#endif #ifndef HDsysconf #define HDsysconf(N) sysconf(N) -#endif /* HDsysconf */ +#endif #ifndef HDsystem #define HDsystem(S) system(S) -#endif /* HDsystem */ +#endif #ifndef HDtan #define HDtan(X) tan(X) -#endif /* HDtan */ +#endif #ifndef HDtanh #define HDtanh(X) tanh(X) -#endif /* HDtanh */ +#endif #ifndef HDtcdrain #define HDtcdrain(F) tcdrain(F) -#endif /* HDtcdrain */ +#endif #ifndef HDtcflow #define HDtcflow(F, A) tcflow(F, A) -#endif /* HDtcflow */ +#endif #ifndef HDtcflush #define HDtcflush(F, N) tcflush(F, N) -#endif /* HDtcflush */ +#endif #ifndef HDtcgetattr #define HDtcgetattr(F, T) tcgetattr(F, T) -#endif /* HDtcgetattr */ +#endif #ifndef HDtcgetpgrp #define HDtcgetpgrp(F) tcgetpgrp(F) -#endif /* HDtcgetpgrp */ +#endif #ifndef HDtcsendbreak #define HDtcsendbreak(F, N) tcsendbreak(F, N) -#endif /* HDtcsendbreak */ +#endif #ifndef HDtcsetattr #define HDtcsetattr(F, O, T) tcsetattr(F, O, T) -#endif /* HDtcsetattr */ +#endif #ifndef HDtcsetpgrp #define HDtcsetpgrp(F, N) tcsetpgrp(F, N) -#endif /* HDtcsetpgrp */ +#endif #ifndef HDtime #define HDtime(T) time(T) -#endif /* HDtime */ +#endif #ifndef HDtimes #define HDtimes(T) times(T) -#endif /* HDtimes*/ +#endif #ifndef HDtmpfile #define HDtmpfile() tmpfile() -#endif /* HDtmpfile */ +#endif #ifndef HDtmpnam #define HDtmpnam(S) tmpnam(S) -#endif /* HDtmpnam */ +#endif #ifndef HDtolower #define HDtolower(C) tolower(C) -#endif /* HDtolower */ +#endif #ifndef HDtoupper #define HDtoupper(C) toupper(C) -#endif /* HDtoupper */ +#endif #ifndef HDttyname #define HDttyname(F) ttyname(F) -#endif /* HDttyname */ +#endif #ifndef HDtzset #define HDtzset() tzset() -#endif /* HDtzset */ +#endif #ifndef HDumask #define HDumask(N) umask(N) -#endif /* HDumask */ +#endif #ifndef HDuname #define HDuname(S) uname(S) -#endif /* HDuname */ +#endif #ifndef HDungetc #define HDungetc(C, F) ungetc(C, F) -#endif /* HDungetc */ +#endif #ifndef HDunlink #define HDunlink(S) unlink(S) -#endif /* HDunlink */ +#endif #ifndef HDutime #define HDutime(S, T) utime(S, T) -#endif /* HDutime */ +#endif #ifndef HDva_arg #define HDva_arg(A, T) va_arg(A, T) -#endif /* HDva_arg */ +#endif #ifndef HDva_copy #define HDva_copy(D, S) va_copy(D, S) -#endif /* HDva_copy */ +#endif #ifndef HDva_end #define HDva_end(A) va_end(A) -#endif /* HDva_end */ +#endif #ifndef HDva_start #define HDva_start(A, P) va_start(A, P) -#endif /* HDva_start */ +#endif #ifndef HDvasprintf #define HDvasprintf(RET, FMT, A) vasprintf(RET, FMT, A) -#endif /* HDvasprintf */ +#endif #ifndef HDvfprintf #define HDvfprintf(F, FMT, A) vfprintf(F, FMT, A) -#endif /* HDvfprintf */ +#endif #ifndef HDvprintf #define HDvprintf(FMT, A) vprintf(FMT, A) -#endif /* HDvprintf */ +#endif #ifndef HDvsprintf #define HDvsprintf(S, FMT, A) vsprintf(S, FMT, A) -#endif /* HDvsprintf */ +#endif #ifndef HDvsnprintf #define HDvsnprintf(S, N, FMT, A) vsnprintf(S, N, FMT, A) -#endif /* HDvsnprintf */ +#endif #ifndef HDwait #define HDwait(W) wait(W) -#endif /* HDwait */ +#endif #ifndef HDwaitpid #define HDwaitpid(P, W, O) waitpid(P, W, O) -#endif /* HDwaitpid */ +#endif #ifndef HDwcstombs #define HDwcstombs(S, P, Z) wcstombs(S, P, Z) -#endif /* HDwcstombs */ +#endif #ifndef HDwctomb #define HDwctomb(S, C) wctomb(S, C) -#endif /* HDwctomb */ +#endif #ifndef HDwrite #define HDwrite(F, M, Z) write(F, M, Z) -#endif /* HDwrite */ +#endif /* * And now for a couple non-Posix functions... Watch out for systems that @@ -1481,16 +1487,16 @@ extern char * strdup(const char *s); #ifndef HDstrdup #define HDstrdup(S) strdup(S) -#endif /* HDstrdup */ +#endif #ifndef HDpthread_self #define HDpthread_self() pthread_self() -#endif /* HDpthread_self */ +#endif /* Use this version of pthread_self for printing the thread ID */ #ifndef HDpthread_self_ulong #define HDpthread_self_ulong() ((unsigned long)pthread_self()) -#endif /* HDpthread_self_ulong */ +#endif /* Macro for "stringizing" an integer in the C preprocessor (use H5_TOSTRING) */ /* (use H5_TOSTRING, H5_STRINGIZE is just part of the implementation) */ @@ -1872,7 +1878,7 @@ extern H5_api_t H5_g; #define H5_API_LOCK #define H5_API_UNLOCK -/* disable cancelability (sequential version) */ +/* disable cancellability (sequential version) */ #define H5_API_UNSET_CANCEL #define H5_API_SET_CANCEL diff --git a/src/H5public.h b/src/H5public.h index 3c90c2a..aeb8664 100644 --- a/src/H5public.h +++ b/src/H5public.h @@ -11,19 +11,40 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/* + * This file contains public declarations for the HDF5 module. + */ +#ifndef H5public_H +#define H5public_H + /**\defgroup H5 H5 * * Use the functions in this module to manage the life cycle of HDF5 library * instances. * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5_examples.c create + * </td> + * <td> + * \snippet{lineno} H5_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5_examples.c update + * </td> + * <td> + * \snippet{lineno} H5_examples.c closing_shop + * \snippet{lineno} H5_examples.c delete + * </td> + * </tr> + * </table> + * */ -/* - * This file contains public declarations for the HDF5 module. - */ -#ifndef H5public_H -#define H5public_H - /* Include files for public use... */ /* * Since H5pubconf.h is a generated header file, it is messy to try @@ -63,6 +84,7 @@ #ifdef H5_HAVE_STDDEF_H #include <stddef.h> #endif + #ifdef H5_HAVE_PARALLEL /* Don't link against MPI C++ bindings */ #define MPICH_SKIP_MPICXX 1 @@ -199,8 +221,9 @@ extern "C" { * Status return values. Failed integer functions in HDF5 result almost * always in a negative value (unsigned failing functions sometimes return * zero for failure) while successful return is non-negative (often zero). - * The negative failure value is most commonly -1, but don't bet on it. The - * proper way to detect failure is something like: + * The negative failure value is most commonly -1, but don't bet on it. + * + * The proper way to detect failure is something like: * \code * if((dset = H5Dopen2(file, name)) < 0) * fprintf(stderr, "unable to open the requested dataset\n"); @@ -227,7 +250,14 @@ typedef int herr_t; typedef unsigned int hbool_t; typedef int htri_t; -/* Define the ssize_t type if it not is defined */ +/* The signed version of size_t + * + * ssize_t is POSIX and not defined in any C standard. It's used in some + * public HDF5 API calls so this work-around will define it if it's not + * present. + * + * Use of ssize_t should be discouraged in new code. + */ #if H5_SIZEOF_SSIZE_T == 0 /* Undefine this size, we will re-define it in one of the sections below */ #undef H5_SIZEOF_SSIZE_T @@ -245,8 +275,10 @@ typedef long long ssize_t; #endif #endif -/* int64_t type is used for creation order field for links. It may be - * defined in Posix.1g, otherwise it is defined here. +/** + * The size of file objects. + * + * \internal Defined as a (minimum) 64-bit integer type. */ #if H5_SIZEOF_INT64_T >= 8 #elif H5_SIZEOF_INT >= 8 @@ -291,9 +323,11 @@ typedef unsigned long long uint64_t; #error "nothing appropriate for uint64_t" #endif -/* - * The sizes of file objects have their own types defined here, use a minimum - * 64-bit type. +/** + * The size of file objects. Used when negative values are needed to indicate errors. + * + * \internal Defined as a (minimum) 64-bit integer type. Use of hssize_t + * should be discouraged in new code. */ #if H5_SIZEOF_LONG_LONG >= 8 H5_GCC_DIAG_OFF("long-long") @@ -313,8 +347,10 @@ H5_GCC_DIAG_ON("long-long") #error "nothing appropriate for hsize_t" #endif -/* - * File addresses have their own types. +/** + * The address of an object in the file. + * + * \internal Defined as a (minimum) 64-bit unsigned integer type. */ #if H5_SIZEOF_INT >= 8 typedef unsigned haddr_t; @@ -395,9 +431,9 @@ typedef enum { /* (Actually, any positive value will cause the iterator to stop and pass back * that positive value to the function that called the iterator) */ -#define H5_ITER_ERROR (-1) -#define H5_ITER_CONT (0) -#define H5_ITER_STOP (1) +#define H5_ITER_ERROR (-1) /**< Error, stop iteration */ +#define H5_ITER_CONT (0) /**< Continue iteration */ +#define H5_ITER_STOP (1) /**< Stop iteration, short-circuit success */ //! <!-- [H5_index_t_snip] --> /** diff --git a/src/H5win32defs.h b/src/H5win32defs.h index 10a5e83..308ba6d 100644 --- a/src/H5win32defs.h +++ b/src/H5win32defs.h @@ -95,6 +95,7 @@ typedef __int64 h5_stat_size_t; #else #define HDopen(S, F, ...) Wopen_utf8(S, F, ##__VA_ARGS__) #endif + #define HDread(F, M, Z) _read(F, M, Z) #define HDremove(S) Wremove_utf8(S) #define HDrmdir(S) _rmdir(S) diff --git a/tools/lib/h5diff.h b/tools/lib/h5diff.h index f14bcda..e811041 100644 --- a/tools/lib/h5diff.h +++ b/tools/lib/h5diff.h @@ -74,7 +74,7 @@ typedef struct { struct exclude_path_list *exclude_attr; /* keep exclude attribute list */ int count_bool; /* count, compare up to count */ hsize_t count; /* count value */ - diff_err_t err_stat; /* an error ocurred (2, error, 1, differences, 0, no error) */ + diff_err_t err_stat; /* an error occurred (2, error, 1, differences, 0, no error) */ hsize_t nelmts; /* total number of elements */ hsize_t hs_nelmts; /* number of elements to read at a time*/ int rank; /* dimensionality */ diff --git a/tools/lib/h5tools.h b/tools/lib/h5tools.h index 6308008..2ee83ef 100644 --- a/tools/lib/h5tools.h +++ b/tools/lib/h5tools.h @@ -218,7 +218,7 @@ typedef struct h5tool_format_t { * * fmt_schar: The printf() format to use when rendering data which is * typed `signed char'. The default is `%d'. This format is - * used ony if the `ascii' field is zero. + * used only if the `ascii' field is zero. * * fmt_uchar: The printf() format to use when rendering data which is * typed `unsigned char'. The default is `%u'. This format @@ -386,9 +386,9 @@ typedef struct h5tool_format_t { * sep: Each integer in the index list will be separated from the * others by this string, which defaults to a comma. * - * fmt: After the index values are formated individually and + * fmt: After the index values are formatted individually and * separated from one another by some string, the entire - * resulting string will be formated according to this + * resulting string will be formatted according to this * printf(3c) format which should include a format for a * character string. The default is "%s". */ @@ -458,7 +458,7 @@ typedef struct h5tool_format_t { const char *line_suf; /*string to append to each line */ const char *line_sep; /*separates lines */ int line_multi_new; /*split multi-line outputs? */ - const char *line_indent; /*for extra identation if we need it*/ + const char *line_indent; /*for extra indentation if we need it*/ /*used to skip the first set of checks for line length*/ int skip_first; @@ -552,7 +552,7 @@ typedef enum { } driver_idx; /* The following include, h5tools_str.h, must be after the - * above stucts are defined. There is a dependency in the following + * above structs are defined. There is a dependency in the following * include that hasn't been identified yet. */ #include "h5tools_str.h" diff --git a/tools/lib/h5tools_utils.h b/tools/lib/h5tools_utils.h index 63fda3f..6ed5aa4 100644 --- a/tools/lib/h5tools_utils.h +++ b/tools/lib/h5tools_utils.h @@ -151,7 +151,7 @@ typedef enum toolname_t { TOOL__H5DUMP /* add as necessary */ } h5tool_toolname_t; -/* this struct can be used to differntiate among tools */ +/* this struct can be used to differentiate among tools */ typedef struct { h5tool_toolname_t toolname; int msg_mode; diff --git a/tools/lib/h5trav.h b/tools/lib/h5trav.h index b62ff3d..2525e2b 100644 --- a/tools/lib/h5trav.h +++ b/tools/lib/h5trav.h @@ -87,7 +87,7 @@ typedef struct trav_link_t { } trav_link_t; /*------------------------------------------------------------------------- - * struct to store basic info needed for the h5trav table traversal algorythm + * struct to store basic info needed for the h5trav table traversal algorithm *------------------------------------------------------------------------- */ diff --git a/tools/lib/io_timer.h b/tools/lib/io_timer.h index 0269b93..02951e1b 100644 --- a/tools/lib/io_timer.h +++ b/tools/lib/io_timer.h @@ -27,7 +27,7 @@ #ifdef H5_HAVE_WINSOCK2_H #include <winsock2.h> -#endif /* H5_HAVE_WINSOCK2_H */ +#endif /* The different types of timers we can have */ typedef enum timer_type_ { |
