diff options
Diffstat (limited to 'doxygen')
61 files changed, 5430 insertions, 695 deletions
diff --git a/doxygen/CMakeLists.txt b/doxygen/CMakeLists.txt new file mode 100644 index 0000000..3462d50 --- /dev/null +++ b/doxygen/CMakeLists.txt @@ -0,0 +1,47 @@ +cmake_minimum_required (VERSION 3.12) +project (HDF5_DOXYGEN C) + +#----------------------------------------------------------------------------- +# Option to build documentation +#----------------------------------------------------------------------------- +if (DOXYGEN_FOUND) + set (DOXYGEN_PACKAGE ${HDF5_PACKAGE_NAME}) + set (DOXYGEN_VERSION_STRING ${HDF5_PACKAGE_VERSION_STRING}) + set (DOXYGEN_INCLUDE_ALIASES_PATH ${HDF5_DOXYGEN_DIR}) + set (DOXYGEN_INCLUDE_ALIASES aliases) + set (DOXYGEN_VERBATIM_VARS DOXYGEN_INCLUDE_ALIASES) + set (DOXYGEN_PROJECT_LOGO ${HDF5_DOXYGEN_DIR}/img/HDFG-logo.png) + set (DOXYGEN_PROJECT_BRIEF "C-API Reference") + set (DOXYGEN_INPUT_DIRECTORY "${HDF5_SOURCE_DIR} ${HDF5_DOXYGEN_DIR}/dox ${HDF5_GENERATED_SOURCE_DIR}") + set (DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES) + set (DOXYGEN_MACRO_EXPANSION YES) + set (DOXYGEN_OUTPUT_DIRECTORY ${HDF5_BINARY_DIR}/hdf5lib_docs) + set (DOXYGEN_EXAMPLES_DIRECTORY "${HDF5_DOXYGEN_DIR}/dox/cookbook ${HDF5_DOXYGEN_DIR}/examples ${HDF5_SRC_DIR} ${HDF5_SOURCE_DIR}/examples ${HDF5_TEST_SRC_DIR}") + set (DOXYGEN_LAYOUT_FILE ${HDF5_DOXYGEN_DIR}/hdf5doxy_layout.xml) + set (DOXYGEN_HTML_HEADER ${HDF5_DOXYGEN_DIR}/hdf5_header.html) + set (DOXYGEN_HTML_FOOTER ${HDF5_DOXYGEN_DIR}/hdf5_footer.html) + set (DOXYGEN_HTML_EXTRA_STYLESHEET ${HDF5_DOXYGEN_DIR}/hdf5doxy.css) + set (DOXYGEN_HTML_EXTRA_FILES "${HDF5_DOXYGEN_DIR}/hdf5_navtree_hacks.js ${HDF5_DOXYGEN_DIR}/img/ftv2node.png ${HDF5_DOXYGEN_DIR}/img/ftv2pnode.png") + set (DOXYGEN_TAG_FILE ${HDF5_BINARY_DIR}/hdf5.tag) + set (DOXYGEN_SERVER_BASED_SEARCH NO) + 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 + # Replace variables inside @@ with the current values + configure_file (${HDF5_DOXYGEN_DIR}/Doxyfile.in ${HDF5_BINARY_DIR}/Doxyfile @ONLY) + + install ( + DIRECTORY ${HDF5_BINARY_DIR}/hdf5lib_docs/html + DESTINATION ${HDF5_INSTALL_DATA_DIR} + COMPONENT Documents + ) + + if (NOT TARGET doxygen) + add_custom_target (doxygen) + endif () + +endif () diff --git a/doxygen/Doxyfile.in b/doxygen/Doxyfile.in index 29f3028..8c871de 100644 --- a/doxygen/Doxyfile.in +++ b/doxygen/Doxyfile.in @@ -170,7 +170,7 @@ FULL_PATH_NAMES = YES # will be relative from the directory where doxygen is started. # This tag requires that the tag FULL_PATH_NAMES is set to YES. -STRIP_FROM_PATH = +STRIP_FROM_PATH = @DOXYGEN_STRIP_FROM_PATH@ # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the # path mentioned in the documentation of a class, which tells the reader which @@ -179,7 +179,7 @@ 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 @@ -856,18 +856,24 @@ INPUT_ENCODING = UTF-8 FILE_PATTERNS = H5*public.h \ H5*module.h \ H5FDcore.h \ + H5FDdevelop.h \ H5FDdirect.h \ H5FDfamily.h \ + H5FDhdfs.h \ H5FDlog.h \ + H5FDmirror.h \ H5FDmpi.h \ H5FDmpio.h \ H5FDmulti.h \ + H5FDros3.h \ H5FDsec2.h \ + H5FDsplitter.h \ H5FDstdio.h \ H5FDwindows.h \ H5VLconnector.h \ H5VLconnector_passthru.h \ H5VLnative.h \ + H5Zdevelop.h \ H5version.h \ *.dox @@ -1121,13 +1127,6 @@ CLANG_DATABASE_PATH = ALPHABETICAL_INDEX = YES -# The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in -# which the alphabetical index list will be split. -# Minimum value: 1, maximum value: 20, default value: 5. -# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. - -COLS_IN_ALPHA_INDEX = 5 - # In case all classes in a project start with a common prefix, all classes will # be put under the same header in the alphabetical index. The IGNORE_PREFIX tag # can be used to specify a prefix (or a list of prefixes) that should be ignored @@ -2177,7 +2176,7 @@ INCLUDE_FILE_PATTERNS = # recursively expanded use the := operator instead of the = operator. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -PREDEFINED = H5_HAVE_PARALLEL +PREDEFINED = @DOXYGEN_PREDEFINED@ # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this # tag can be used to specify a list of macro names that should be expanded. The @@ -2221,7 +2220,7 @@ TAGFILES = # tag file that is based on the input files it reads. See section "Linking to # external documentation" for more information about the usage of tag files. -GENERATE_TAGFILE = +GENERATE_TAGFILE = @DOXYGEN_TAG_FILE@ # If the ALLEXTERNALS tag is set to YES, all external class will be listed in # the class index. If set to NO, only the inherited external classes will be diff --git a/doxygen/aliases b/doxygen/aliases index af43902..f83a875 100644 --- a/doxygen/aliases +++ b/doxygen/aliases @@ -16,11 +16,18 @@ ALIASES += success{1}="\Bold{Success:} \1" ALIASES += failure{1}="\Bold{Failure:} \1" ALIASES += herr_t="Returns a non-negative value if successful; otherwise returns a negative value." +ALIASES += herr_t_iter="\li Zero causes the iterator to continue, returning zero when the iteration is complete. \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." ALIASES += hid_t{1}="Returns a \1 identifier if successful; otherwise returns #H5I_INVALID_HID. " ALIASES += hid_ti{1}="Returns an \1 identifier if successful; otherwise returns #H5I_INVALID_HID. " ALIASES += hid_tv{1}="Returns an \1 identifier if successful; otherwise returns a negative value. " ALIASES += htri_t="Returns zero (false), a positive (true) or a negative (failure) value." +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." + ################################################################################ # General ################################################################################ @@ -131,6 +138,8 @@ ALIASES += map_id{1}="\param[in] \1 Map identifier" # Property lists ################################################################################ +ALIASES += plist_unused{1}="\note The \p \1 parameter is currently not used; specify #H5P_DEFAULT." + ALIASES += aapl_id="\param[in] aapl_id Attribute access property list identifier" ALIASES += aapl_id{1}="\param[in] \1 Attribute access property list identifier" @@ -217,9 +226,8 @@ 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" ################################################################################ @@ -241,6 +249,106 @@ ALIASES += ref_vlen_strings="\Emph{Creating variable-length string datatypes}" ALIASES += ref_vol_doc="VOL documentation" ################################################################################ +# RFCs +################################################################################ + +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>" +ALIASES += ref_rfc20180125="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/enhance_h5clear.docx.pdf\">Enhancement to the tool <tt>h5clear</tt></a>" +ALIASES += ref_rfc20170707="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/H5Sencode_format.docx.pdf\"><tt>H5Sencode/H5Sdecode</tt> Format Change</a>" +ALIASES += ref_rfc20160105="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC-bounds.pdf\">Setting Bounds for Object Creation in HDF5 1.10.0</a>" +ALIASES += ref_rfc20150915="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/2015-09-28-RFC-HDF5-1.10.0-File-Format-Superblock-Changes-EP.docx.pdf\">File Format Changes in HDF5 1.10.0</a>" +ALIASES += ref_rfc20150709="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC-Page_Buffering.pdf\">Page Buffering</a>" +ALIASES += ref_rfc20150615="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/cache_image_RFC_150929-QAK.docx.pdf\">Metadata Cache Image</a>" +ALIASES += ref_rfc20150429="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/new_datatypes.pdf\">New Datatypes</a>" +ALIASES += ref_rfc20150424="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC-CollectiveMetadataWrites.pdf\">Collective Metadata Writes</a>" +ALIASES += ref_rfc20150423="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC-CollectiveMetadataReads.pdf\">Enabling Collective Metadata Reads</a>" +ALIASES += ref_rfc20150301="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/sent_RFC_format_convert-v3.docx.pdf\">The Tool to Handle HDF5 File Format Compatibility for Chunked Datasets</a>" +ALIASES += ref_rfc20150212="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_H5LTget_hardlinkds.docx.pdf\"><tt>H5LTget_hardlinks</tt> – High-level API to list all the hard links to an object</a>" +ALIASES += ref_rfc20150205="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_F2003_v6.docx.pdf\">HDF5 Fortran Wrappers Maintenance: Dropping Support for Non-Fortran 2003 Standard Compliant Compilers</a>" +ALIASES += ref_rfc20150202="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC%20New%20Autotools%20Behavior.docx.pdf\">New Autotools Behavior</a>" +ALIASES += ref_rfc20141210="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/HDF5-VDS-requirements-use-cases-2014-12-10.pdf\">HDF5 Virtual Dataset</a>" +ALIASES += ref_rfc20141201="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC%20filter%20memory%20issues%20on%20Windows.docx.pdf\">Allocate/Free Mismatches in HDF5 Filter Code on Windows</a>" +ALIASES += ref_rfc20140916="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_VOL.pdf\">Virtual Object Layer</a>" +ALIASES += ref_rfc20140827="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/CompressNChunk_RFC.pdf\">Chunking and Compression Performance Tool Requirements</a>" +ALIASES += ref_rfc20140729="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/h5fis_accessible.pdf\">Replacing H5Fis_hdf5() with H5Fis_accessible()</a>" +ALIASES += ref_rfc20140722="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/64bit_hid_t-v1.docx.pdf\">Switching to a 64-bit <tt>hid_t</tt> Space in HDF5</a>" +ALIASES += ref_rfc20140717="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/analysis_ext.pdf\">Data Analysis Extensions</a>" +ALIASES += ref_rfc20140707="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/2014-08-28-RFC_VOL.pdf\">Virtual Object Layer</a>" +ALIASES += ref_rfc20140524="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC-Why%20does%20not%20compression%20work-GH-EP.docx.pdf\">HDF5 Compression Demystified</a>" +ALIASES += ref_rfc20140318="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC%20H5free_memory%20v2.pdf\">Freeing Memory Allocated by the HDF5 Library</a>" +ALIASES += ref_rfc20140313="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC-Compat-Tool-v2.docx.pdf\">Options to handle compatibility issues for HDF5 files</a>" +ALIASES += ref_rfc20140224="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/Design-MetadataCache-Logging-THG20140224-v4.pdf\">Design: Metadata Cache Logging</a>" +ALIASES += ref_rfc20131211="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC%20H5Ocork%20v5%20new%20fxn%20names.pdf\">Fine-Grained Control of Metadata Cache Flushes</a>" +ALIASES += ref_rfc20130930="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC-Read-Attempts-for-Metadata-with-Checksum-v3.pdf\">Read Attempts for Metadata with Checksum</a>" +ALIASES += ref_rfc20130919="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/core%20CFD%20paging%20v5.docx.pdf\">Core VFD Backing Store Paged Writes</a>" +ALIASES += ref_rfc20130630="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/Design-HDF5-FlushDependencyTesting-20130630-v1.1.pdf\">Flush Dependency Testing</a>" +ALIASES += ref_rfc20130316="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/HDF5DynamicallyLoadedFilters.pdf\">HDF5 Dynamically Loaded Filters</a>" +ALIASES += ref_rfc20121114="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/DECTRIS%20Integration%20RFC%202012-11-29.pdf\">Direct Chunk Write</a>" +ALIASES += ref_rfc20121024="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/FileSpaceManagement.pdf\">HDF5 File Space Management</a>" +ALIASES += ref_rfc20120828="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/H5HPC_MultiDset_RW_IO_RFC_v4_20130320.docx.pdf\">New HDF5 API Routines for HPC Applications</a>" +ALIASES += ref_rfc20120523="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/paged_aggregation.pdf\">HDF5 File Space Management: Paged Aggregation</a>" +ALIASES += ref_rfc20120501="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/HDF5FileImageOperations.pdf\">HDF5 File Image Operations</a>" +ALIASES += ref_rfc20120305="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC%20PHDF5%20Consistency%20Semantics%20MC%20120328.docx.pdf\">Enabling a Strict Consistency Semantics Model in Parallel HDF5</a>" +ALIASES += ref_rfc20120220="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/h5repack_improve_hyperslab_over_chunked_dataset_v1.pdf\"><tt>h5repack</tt>: Improved Hyperslab selections for Large Chunked Datasets</a>" +ALIASES += ref_rfc20120120="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/2012-1-25-Maintainers-guide-for-datatype.docx.pdf\">A Maintainer’s Guide for the Datatype Module in HDF5 Library</a>" +ALIASES += ref_rfc20120104="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_actual_io_v4-1_done.docx.pdf\">Actual I/O Mode</a>" +ALIASES += ref_rfc20111119="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC-H5Ocompare-review_v6.pdf\">New public functions to handle comparison</a>" +ALIASES += ref_rfc20110825="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/2011-08-31-RFC_H5Ocopy_Named_DT_v2.docx.pdf\">Merging Named Datatypes in H5Ocopy()</a>" +ALIASES += ref_rfc20110811="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_Enhancement_Hyperslab_Selection-1.4.docx.pdf\">Expanding the HDF5 Hyperslab Selection Interface</a>" +ALIASES += ref_rfc20110726="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/metadata_aggregation_RFC_v03.docx.pdf\">HDF5 File Space Allocation and Aggregation</a>" +ALIASES += ref_rfc20110614="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_h5dump_refactor_v3.docx.pdf\"> Refactor <tt>h5dump</tt> to Improve Maintenance</a>" +ALIASES += ref_rfc20110329="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_Tools_Extlink_Cache_v3_r2.docx.pdf\">Support External Link Open File Cache in HDF5 Tools</a>" +ALIASES += ref_rfc20110118="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC%20for%20h5diff%20Attribute%20Comparisons_v7.docx.pdf\"><tt>h5diff</tt> Attribute Comparisons</a>" +ALIASES += ref_rfc20101122="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_swmr_timeouts_v2.docx.pdf\">SWMR Timeouts</a>" +ALIASES += ref_rfc20101104="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/CacheExternalLinkFileOpens.pdf\">Caching Files Opened Through External Links</a>" +ALIASES += ref_rfc20101018="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/HDF5-comparisons_v3-RFC-2011-08-03.pdf\">HDF5 File and Object Comparison Specification</a>" +ALIASES += ref_rfc20100902="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/H5edit-RFC-Draft-v5.pdf\"><tt>h5edit</tt> – An HDF5 File Editing Tool</a>" +ALIASES += ref_rfc20100727="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_HDF5_reservedCharacters-v2.pdf\">Reserved Characters for HDF5 Applications</a>" +ALIASES += ref_rfc20100726="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/H5HPC_RFC-2010-09-28.pdf\">High-Level HDF5 API routines for HPC Applications</a>" +ALIASES += ref_rfc20100511="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_h5diff_exclude_obj_v1_3.pdf\"><tt>h5diff</tt> – Exclude Object(s) from Comparison</a>" +ALIASES += ref_rfc20100422="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_gen_attribute_tool_v2_f.pdf\">Generating attributes into an object with a tool</a>" +ALIASES += ref_rfc20100312="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_Support_HDF518_in_Tools.pdf\">Supporting HDF5 1.8 in HDF5 Command Line Tools</a>" +ALIASES += ref_rfc20091218="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RCF_h5diff_link_v1.2.docx.pdf\">Supporting soft-link and external-link for <tt>h5diff</tt></a>" +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>" +ALIASES += ref_rfc20071111="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/AURA-corruption-2007-11-12.pdf\">Addressing HDF5 file corruption issue</a>" +ALIASES += ref_rfc20071018="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_NaNsHDF5.pdf\"><tt>NaN</tt> detection in HDF5</a>" +ALIASES += ref_rfc20070801="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/Metadata_Journaling_RFC.pdf\">Metadata Journaling to Improve Crash Survivability</a>" +ALIASES += ref_rfc20070413="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/API_Compatibility_RFC.txt.pdf\">API Compatibility Strategies for HDF5</a>" +ALIASES += ref_rfc20070115="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/PrivateHeap.pdf\">A \"Private\" Heap for HDF5</a>" +ALIASES += ref_rfc20060623="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/coll_ind_dd6.pdf\">Performance Comparison of Collective I/O and Independent I/O with Derived Datatypes</a>" +ALIASES += ref_rfc20060604="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/h5stat_spec_v3_2006-06-04.pdf\"><tt>h5stat</tt> tool</a>" +ALIASES += ref_rfc20060505="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/Simple%20Performance%20Test%20on%20Fletcher32%20Filter.pdf\">Simple Performance Test on Fletcher32 Filter</a>" +ALIASES += ref_rfc20060410="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/h5chk_Requirements.pdf\">Requirement Specifications of an HDF5 File Format Validation Tool</a>" +ALIASES += ref_rfc20060317="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/sec2driver-RFC.pdf\">Proposed changes to the <tt>sec2</tt> driver </a>" +ALIASES += ref_rfc20060124="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/FITS%20to%20HDF5%20mapping.pdf\">Mapping FITS data to HDF5</a>" +ALIASES += ref_rfc20040811="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/text-dtype.htm.pdf\">Conversion Between Text and Datatype</a>" + +################################################################################ # The Usual Suspects ################################################################################ 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 3be9202..9000a78 100644 --- a/doxygen/dox/About.dox +++ b/doxygen/dox/About.dox @@ -1,5 +1,7 @@ /** \page About About +\section about_history History + The implementation of this documentation set is based on the fantastic work of the <a href="https://eigen.tuxfamily.org/index.php?title=Main_Page">Eigen project</a>. Please refer to their <a href="https://gitlab.com/libeigen/eigen">GitLab repository</a> @@ -8,4 +10,120 @@ 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>. -*/
\ No newline at end of file +\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! + +\todo Make the publication a GitHub action! + +*/ diff --git a/doxygen/dox/Cookbook.dox b/doxygen/dox/Cookbook.dox index 4abc896..666cfa1 100644 --- a/doxygen/dox/Cookbook.dox +++ b/doxygen/dox/Cookbook.dox @@ -2,4 +2,18 @@ Healthy, everyday recipes for every taste and budget... - */
\ No newline at end of file +\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 + + */ 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/FileFormatSpec.dox b/doxygen/dox/FileFormatSpec.dox deleted file mode 100644 index fc10574..0000000 --- a/doxygen/dox/FileFormatSpec.dox +++ /dev/null @@ -1,23 +0,0 @@ -/** \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 - -*/
\ No newline at end of file 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/H5Fget_info.dox b/doxygen/dox/H5Fget_info.dox deleted file mode 100644 index 9b02752..0000000 --- a/doxygen/dox/H5Fget_info.dox +++ /dev/null @@ -1,44 +0,0 @@ -/** - * \ingroup H5F - * \def H5Fget_info() - * H5Fget_info() is a macro that is mapped to either H5Fget_info1() - * or H5Fget_info2(), depending on the needs of the application. - * Similarly, the macro for the \ref H5F_info_t struct is mapped to either - * H5F_info1_t or H5F_info2_t. - * - * Such macros are provided to facilitate application compatibility. - * Their use and mappings are fully described in \ref api-compat-macros. - * - * When both the HDF5 library and the application are built and installed with - * no specific compatibility flags, H5Fget_info() is mapped to the most recent - * version of the function, currently H5Fget_info2(). If the library and/or - * application is compiled for Release 1.8 emulation, H5Fget_info() will be - * mapped to H5Fget_info1(). Since there was no H5Fget_info() function in - * Release 1.6, if the library and/or application is compiled for Release 1.6 - * emulation, H5Fget_info() will be mapped to the most recent version of the - * function, currently H5Fget_info2(). Function-specific flags are available to - * override these settings on a function-by-function basis when the application - * is compiled. - * - * Specific compile-time compatibility flags and the resulting - * mappings are as follows: - * - * \Bold{Global settings}\n - * \li No compatibility flag: H5Fget_info2() and H5F_info2_t - * \li Enable deprecated symbols: H5Fget_info2() and H5F_info2_t - * \li Disable deprecated symbols: H5Fget_info2() and H5F_info2_t - * \li Emulate Release 1.6 interface: H5Fget_info2() and H5F_info2_t - * \li Emulate Release 1.8 interface: H5Fget_info1() and H5F_info1_t - * - * \Bold{Function- and struct-level macros}\n - * \li \Code{H5Fget_info_vers=2}: H5Fget_info2() - * \li \Code{H5Fget_info_vers=1}: H5Fget_info1() - * \li \Code{H5F_info_t_vers=2}: H5F_info2_t - * \li \Code{H5F_info_t_vers=1}: H5F_info1_t - * - * \version 1.10.0 The C function H5Fget_info() and H5F_info_t renamed to - * H5Fget_info1() and H5F_info1_t, respectively, and deprecated - * in this release. The C macro #H5Fget_info, the C function - * H5Fget_info2(), and the struct H5F_info2_t introduced in this - * release. - */ diff --git a/doxygen/dox/H5Lget_info.dox b/doxygen/dox/H5Lget_info.dox deleted file mode 100644 index 2c0971e..0000000 --- a/doxygen/dox/H5Lget_info.dox +++ /dev/null @@ -1,17 +0,0 @@ - /** - * \ingroup LMGT - * \def H5Lget_info() - * H5Lget_info() is a macro that is mapped to either H5Lget_info1() - * or H5Lget_info2() Such macros are provided to facilitate application - * compatibility. Their use and mappings are fully described in \ref api-compat-macros. - * If the library and/or application is compiled for Release - * 1.12 emulation, H5Lget_info() will be mapped to H5Lget_info2() and - * H5Lget_info1() is deprecated. With earlier versions, H5Lget_info() is mapped to - * H5Lget_info1(). Specific compile-time compatibility flags and the resulting - * mappings are as follows: - * \li No compatibility flag: H5Lget_info2() (using 1.12 source) H5Lget_info1() - * (using 1.10 or 1.8 source) - * \li Emulate Release 1.12: H5Lget_info2() - * \li Emulate Release 1.8 or 1.10 interface: H5Lget_info1() - * - */ diff --git a/doxygen/dox/H5Lget_info_by_idx.dox b/doxygen/dox/H5Lget_info_by_idx.dox deleted file mode 100644 index bf76822..0000000 --- a/doxygen/dox/H5Lget_info_by_idx.dox +++ /dev/null @@ -1,17 +0,0 @@ - /** - * \ingroup LMGT - * \def H5Lget_info_by_idx() - * H5Lget_info_by_idx() is a macro that is mapped to either H5Lget_info_by_idx1() - * or H5Lget_info_by_idx2() Such macros are provided to facilitate application - * compatibility. Their use and mappings are fully described in \ref api-compat-macros. - * If the library and/or application is compiled for Release - * 1.12 emulation, H5Lget_info_by_idx() will be mapped to H5Lget_info_by_idx2() and - * H5Lget_info_by_idx1() is deprecated. With earlier versions, H5Lget_infoby_idx() is mapped to - * H5Lget_info_by_idx1(). Specific compile-time compatibility flags and the resulting - * mappings are as follows: - * \li No compatibility flag: H5Lget_info_by_idx2() (using 1.12 source) H5Lget_info_by_idx1() - * (using 1.10 or 1.8 source) - * \li Emulate Release 1.12: H5Lget_info_by_idx2() - * \li Emulate Release 1.8 or 1.10 interface: H5Lget_info_by_idx1() - * - */ diff --git a/doxygen/dox/H5Literate.dox b/doxygen/dox/H5Literate.dox deleted file mode 100644 index eaaf2fe..0000000 --- a/doxygen/dox/H5Literate.dox +++ /dev/null @@ -1,20 +0,0 @@ -/** - * \ingroup TRAV - * \def H5Literate() - * H5Literate() is a macro that is mapped to either H5Literate1() or - * H5Literate2() Such macros are provided to facilitate application - * compatibility. Their use and mappings are fully described in - * \ref api-compat-macros. If the library and/or application is - * compiled for Release 1.12 emulation, H5Literate() will be mapped to - * H5Literate2() and H5Literate1() is deprecated. With earlier versions, - * H5Literate() is mapped to H5Literate1(). Specific compile-time compatibility - * flags and the resulting mappings are as follows: - * \li No compatibility flag: H5Literate2() (using 1.12 source) H5Literate1() - * (using 1.10 or 1.8 source) - * \li Emulate Release 1.12: H5Literate2() - * \li Emulate Release 1.8 or 1.10 interface: H5Literate1() - * - * \version 1.12.0 The function H5Literate() was renamed to H5Literate1() and - * deprecated in this release. The macro H5Literate() and the - * function H5Literate2() were introduced in this release. - */ diff --git a/doxygen/dox/H5Literate_by_name.dox b/doxygen/dox/H5Literate_by_name.dox deleted file mode 100644 index 5ffd7c6..0000000 --- a/doxygen/dox/H5Literate_by_name.dox +++ /dev/null @@ -1,21 +0,0 @@ -/** - * \ingroup TRAV - * \def H5Literate_by_name() - * H5Literate_by_name() is a macro that is mapped to either - * H5Literate_by_name1() or H5Literate_by_name2() Such macros are provided to - * facilitate application compatibility. Their use and mappings are fully - * described in \ref api-compat-macros. If the library and/or application is - * compiled for Release 1.12 emulation, H5Literate_by_name() will be mapped to - * H5Literate_by_name2() and H5Literate_by_name1() is deprecated. With earlier - * versions, H5Literate_by_name() is mapped to H5Literate_by_name1(). - * Specific compile-time compatibility flags and the resulting mappings are as - * follows: - * \li No compatibility flag: H5Literate_by_name2() (using 1.12 source) - * H5Literate_by_name1() (using 1.10 or 1.8 source) - * \li Emulate Release 1.12: H5Literate_by_name2() - * \li Emulate Release 1.8 or 1.10 interface: H5Literate_by_name1() - * - * \version 1.12.0 The function H5Literate_by_name() was renamed to H5Literate_by_name1() and - * deprecated in this release. The macro H5Literate_by_name() and the - * function H5Literate_by_name2() were introduced in this release. - */ diff --git a/doxygen/dox/H5Lvisit.dox b/doxygen/dox/H5Lvisit.dox deleted file mode 100644 index 2dc547f..0000000 --- a/doxygen/dox/H5Lvisit.dox +++ /dev/null @@ -1,20 +0,0 @@ -/** - * \ingroup TRAV - * \def H5Lvisit() - * H5Lvisit() is a macro that is mapped to either H5Lvisit1() or - * H5Lvisit2() Such macros are provided to facilitate application - * compatibility. Their use and mappings are fully described in - * \ref api-compat-macros. If the library and/or application is - * compiled for Release 1.12 emulation, H5Lvisit() will be mapped to - * H5Lvisit2() and H5Lvisit1() is deprecated. With earlier versions, - * H5Lvisit() is mapped to H5Lvisit1(). Specific compile-time compatibility - * flags and the resulting mappings are as follows: - * \li No compatibility flag: H5Lvisit2() (using 1.12 source) H5Lvisit1() - * (using 1.10 or 1.8 source) - * \li Emulate Release 1.12: H5Lvisit2() - * \li Emulate Release 1.8 or 1.10 interface: H5Lvisit1() - * - * \version 1.12.0 The function H5Lvisit() was renamed to H5Lvisit1() and - * deprecated in this release. The macro H5Lvisit() and the - * function H5Lvisit2() were introduced in this release. - */ diff --git a/doxygen/dox/H5Lvisit_by_name.dox b/doxygen/dox/H5Lvisit_by_name.dox deleted file mode 100644 index 691787f..0000000 --- a/doxygen/dox/H5Lvisit_by_name.dox +++ /dev/null @@ -1,20 +0,0 @@ -/** - * \ingroup TRAV - * \def H5Lvisit_by_name() - * H5Lvisit_by_name() is a macro that is mapped to either H5Lvisit_by_name1() or - * H5Lvisit_by_name2() Such macros are provided to facilitate application - * compatibility. Their use and mappings are fully described in - * \ref api-compat-macros. If the library and/or application is - * compiled for Release 1.12 emulation, H5Lvisit_by_name() will be mapped to - * H5Lvisit_by_name2() and H5Lvisit_by_name1() is deprecated. With earlier versions, - * H5Lvisit_by_name() is mapped to H5Lvisit_by_name1(). Specific compile-time - * compatibility flags and the resulting mappings are as follows: - * \li No compatibility flag: H5Lvisit_by_name2() (using 1.12 source) H5Lvisit_by_name1() - * (using 1.10 or 1.8 source) - * \li Emulate Release 1.12: H5Lvisit_by_name2() - * \li Emulate Release 1.8 or 1.10 interface: H5Lvisit_by_name1() - * - * \version 1.12.0 The function H5Lvisit_by_name() was renamed to H5Lvisit_by_name1() and - * deprecated in this release. The macro H5Lvisit_by_name() and the - * function H5Lvisit_by_name2() were introduced in this release. - */ diff --git a/doxygen/dox/H5Oget_info.dox b/doxygen/dox/H5Oget_info.dox deleted file mode 100644 index ee4cd1c..0000000 --- a/doxygen/dox/H5Oget_info.dox +++ /dev/null @@ -1,72 +0,0 @@ -/** - * \ingroup H5O - * \def H5Oget_info - * - * #H5Oget_info is a macro that is mapped to: - * \li #H5Oget_info3 - * \li #H5Oget_info1 - * - * \details Such macros are provided to facilitate application - * compatibility. Their use and mappings are fully described in - * API Compatibility Macros in HDF5; we urge you to read that - * document closely. - * - * In HDF5 versions 1.12 and after, #H5Oget_info is mapped to - * #H5Oget_info3 and #H5Oget_info1 is deprecated. - * In version 1.10 #H5Oget_info is identical to #H5Oget_info1. - * - * Specific compile-time compatibility flags and the resulting - * mappings are as follows: - * \par - * <table> - * <tr> - * <th>Compatibility setting</th> - * <th>H5Oget_info</th> - * </tr> - * <tr> - * <td>No compatibility flag \n </td> - * <td>#H5Oget_info3 (in release 1.12) \n - * #H5Oget_info1 (in 1.8 or 1.10)</td> - * </tr> - * <tr> - * <td>Emulate Release 1.12</td> - * <td>#H5Oget_info3</td> - * </tr> - * <tr> - * <td>Emulate Release 1.10/1.8 interface</td> - * <td>#H5Oget_info1</td> - * </tr> - * </table> - * - * \note If you are iterating through a lot of different objects to - * retrieve information via the #H5Oget_info family of routines, - * you may see memory building up. This can be due to memory - * allocation for metadata such as object headers and messages - * when the iterated objects are put into the metadata cache. - * \note - * If the memory buildup is not desirable, you can configure a - * smaller cache via #H5Fset_mdc_config or set the file access - * property list via #H5Pset_mdc_config. A smaller sized cache - * will force metadata entries to be evicted from the cache, - * thus freeing the memory associated with the entries. - * - * \version 1.12.0 The macro #H5Oget_info and the function #H5Oget_info3 - * were added, and #H5Oget_info1 was deprecated. - * \version 1.10.5 The macro #H5Oget_info was removed. The functions - * #H5Oget_info1 and #H5Oget_info are identical - * in this release. This change was added to restore the - * broken API compatibility introduced in HDF5-1.10.3. - * \version 1.10.3 The function #H5Oget_info was renamed - * #H5Oget_info1. The macro #H5Oget_info and the function - * #H5Oget_info2 were introduced in this release. - * \version 1.8.15 Added a note about the valid values for the \c version field - * in the H5O_hdr_info_t structure. - * \version 1.8.11 Fortran subroutine introduced in this release. - * \version 1.8.10 Added #H5O_type_t structure to the Description section. - * Separated H5O_hdr_info_t structure from - * #H5O_info_t in the Description section. Clarified the - * definition and implementation of the time fields. - * - * \since 1.8.0 - * - */ diff --git a/doxygen/dox/H5Oget_info_by_idx.dox b/doxygen/dox/H5Oget_info_by_idx.dox deleted file mode 100644 index 49b8031..0000000 --- a/doxygen/dox/H5Oget_info_by_idx.dox +++ /dev/null @@ -1,55 +0,0 @@ -/** - * \ingroup H5O - * \def H5Oget_info_by_idx - * - * #H5Oget_info_by_idx is a macro that is mapped to: - * \li #H5Oget_info_by_idx3 - * \li #H5Oget_info_by_idx1 - * - * \details Such macros are provided to facilitate application - * compatibility. Their use and mappings are fully described in - * API Compatibility Macros in HDF5; we urge you to read that - * document closely. - * - * In HDF5 versions 1.12 and after, #H5Oget_info_by_idx is mapped to - * #H5Oget_info_by_idx3 and #H5Oget_info_by_idx1 is deprecated. - * In version 1.10 #H5Oget_info_by_idx is identical to #H5Oget_info_by_idx1. - * - * Specific compile-time compatibility flags and the resulting - * mappings are as follows: - * - * \par - * <table> - * <tr> - * <th>Compatibility setting</th> - * <th>H5Oget_info_by_idx</th> - * </tr> - * <tr> - * <td>No compatibility flag \n </td> - * <td>#H5Oget_info_by_idx3 for 1.12 \n - * #H5Oget_info_by_idx1 for 1.8/1.10</td> - * </tr> - * <tr> - * <td>Emulate Release 1.12</td> - * <td>#H5Oget_info_by_idx3</td> - * </tr> - * <tr> - * <td>Emulate Release 1.10/1.8 interface</td> - * <td>#H5Oget_info_by_idx1</td> - * </tr> - * </table> - * - * \version 1.12.0 The macro #H5Oget_info_by_idx and function #H5Oget_info_by_idx3 were added, - * and #H5Oget_info_by_idx1 was deprecated. - * \version 1.10.5 The macro #H5Oget_info_by_idx was removed. The functions - * #H5Oget_info_by_idx and #H5Oget_info_by_idx1 are - * identical in this release. This change was added to restore the - * broken API compatibility introduced in HDF5-1.10.3. - * \version 1.10.3 The function #H5Oget_info_by_idx was renamed #H5Oget_info_by_idx1. - * The macro #H5Oget_info_by_idx and the function #H5Oget_info_by_idx2 - * were introduced in this release. - * \version 1.8.11 Fortran subroutine introduced in this release. - * - * \since 1.8.0 - * - */ diff --git a/doxygen/dox/H5Oget_info_by_name.dox b/doxygen/dox/H5Oget_info_by_name.dox deleted file mode 100644 index 18f7d28..0000000 --- a/doxygen/dox/H5Oget_info_by_name.dox +++ /dev/null @@ -1,58 +0,0 @@ -/** - * \ingroup H5O - * \def H5Oget_info_by_name - * - * #H5Oget_info_by_name is a macro that is mapped to: - * \li #H5Oget_info_by_name3 - * \li #H5Oget_info_by_name1 - * - * \details Such macros are provided to facilitate application - * compatibility. Their use and mappings are fully described in - * API Compatibility Macros in HDF5; we urge you to read that - * document closely. - * - * In HDF5 versions 1.12 and after, #H5Oget_info_by_name is mapped to - * #H5Oget_info_by_name3. In version 1.10 #H5Oget_info_by_name is - * identical to #H5Oget_info_by_name1. - * - * Specific compile-time compatibility flags and the resulting - * mappings are as follows: - * - * \par - * <table> - * <tr> - * <th>Compatibility setting</th> - * <th>H5Oget_info_by_name</th> - * </tr> - * <tr> - * <td>No compatibility flag \n </td> - * <td>#H5Oget_info_by_name3 for 1.12 and above \n - * #H5Oget_info_by_name1 for 1.8 or 1.10</td> - * </tr> - * <tr> - * <td>Emulate Release 1.12</td> - * <td>#H5Oget_info_by_name3</td> - * </tr> - * <tr> - * <td>Emulate Release 1.10 or 1.8 interface</td> - * <td>#H5Oget_info_by_name1</td> - * </tr> - * </table> - * - * \version 1.12.0 The macro #H5Oget_info_by_name and function - * #H5Oget_info_by_name3 were added and - * #H5Oget_info_by_name1 was deprecated. - * \version 1.10.5 The macro #H5Oget_info_by_name was removed. The functions - * #H5Oget_info_by_name and #H5Oget_info_by_name1 are - * identical in this release. This change was added to restore - * the broken API compatibility introduced in HDF5-1.10.3. - * \version 1.10.3 The function #H5Oget_info_by_name was renamed - * to #H5Oget_info_by_name1. The macro #H5Oget_info_by_name - * and the function #H5Oget_info_by_name2 were introduced - * in this release. - * \version 1.8.8 Fortran 2003 subroutine and \c h5o_info_t derived - * type introduced in this release.</td> - * - * \since 1.8.0 - * - */ diff --git a/doxygen/dox/H5Ovisit.dox b/doxygen/dox/H5Ovisit.dox deleted file mode 100644 index 1e2a3ea..0000000 --- a/doxygen/dox/H5Ovisit.dox +++ /dev/null @@ -1,55 +0,0 @@ -/** - * \ingroup H5O - * \def H5Ovisit - * - * #H5Ovisit is a macro that is mapped to one of the following: - * \li #H5Ovisit3 - * \li #H5Ovisit1 - * - * \details Such macros are provided to facilitate application - * compatibility. Their use and mappings are fully described in - * API Compatibility Macros in HDF5; we urge you to read that - * document closely. - * - * In HDF5 versions 1.12 and after, #H5Ovisit is mapped to - * #H5Ovisit3. In version 1.10, #H5Ovisit is identical - * to #H5Ovisit1. - * - * Specific compile-time compatibility flags and the resulting - * mappings are as follows: - * - * \par - * <table> - * <tr> - * <th>Compatibility settings</th> - * <th>H5Ovisit</th> - * </tr> - * <tr> - * <td>No compatibility flag \n </td> - * <td>#H5Ovisit3 in 1.12 or after \n - * #H5Ovisit1 for 1.8 and 1.10</td> - * </tr> - * <tr> - * <td>Emulate Release 1.12</td> - * <td>#H5Ovisit3</td> - * </tr> - * <tr> - * <td>Emulate Release 1.10 or 1.8 interface</td> - * <td>#H5Ovisit1</td> - * </tr> - * </table> - * - * \version 1.12.0 The macro #H5Ovisit and function #H5Ovisit3 were added, - * and #H5Ovisit1 was deprecated. - * \version 1.10.5 The macro #H5Ovisit was removed. The functions - * #H5Ovisit and #H5Ovisit1 are identical in this release. - * This change was added to restore the broken API compatibility - * introduced in HDF5-1.10.3. - * \version 1.10.3 The function #H5Ovisit was renamed to #H5Ovisit1. - * The macro #H5Ovisit and the function #H5Ovisit2 were - * introduced in this release. - * \version 1.8.8 Fortran subroutine and data structure added. - * - * \since 1.8.0 - * - */ diff --git a/doxygen/dox/H5Ovisit_by_name.dox b/doxygen/dox/H5Ovisit_by_name.dox deleted file mode 100644 index 2ba4846..0000000 --- a/doxygen/dox/H5Ovisit_by_name.dox +++ /dev/null @@ -1,54 +0,0 @@ -/** - * \ingroup H5O - * \def H5Ovisit_by_name - * - * #H5Ovisit_by_name is a macro that is mapped to one of the following: - * \li #H5Ovisit_by_name3 - * \li #H5Ovisit_by_name1 - * - * \details Such macros are provided to facilitate application - * compatibility. Their use and mappings are fully described in - * API Compatibility Macros in HDF5; we urge you to read that - * document closely. - * - * In HDF5 versions 1.12 and after, #H5Ovisit_by_name is mapped to - * #H5Ovisit_by_name3. In version 1.10, #H5Ovisit_by_name - * is identical to #H5Ovisit_by_name1. - * - * Specific compile-time compatibility flags and the resulting - * mappings are as follows: - * - * \par - * <table> - * <tr> - * <th>Compatibility settings</th> - * <th>H5Ovisit_by_name</th> - * </tr> - * <tr> - * <td>No compatibility flag \n </td> - * <td>#H5Ovisit_by_name3 for 1.12 and above \n - * #H5Ovisit_by_name1 for 1.10 or 1.8</td> - * </tr> - * <tr> - * <td>Emulate Release 1.12 interface</td> - * <td>#H5Ovisit_by_name3</td> - * </tr> - * <tr> - * <td>Emulate Release 1.10 or 1.8 interface</td> - * <td>#H5Ovisit_by_name1</td> - * </tr> - * </table> - * - * \version 1.12.0 The macro #H5Ovisit_by_name and function #H5Ovisit_by_name3 were added. - * \version 1.10.5 The macro #H5Ovisit_by_name was removed. The functions - * #H5Ovisit_by_name and #H5Ovisit_by_name1 are identical - * in this release. This change was added to restore the - * broken API compatibility introduced in HDF5-1.10.3. - * \version 1.10.3 The function #H5Ovisit_by_name was renamed to #H5Ovisit_by_name1. - * The macro #H5Ovisit_by_name and the function #H5Ovisit_by_name2 - * were introduced in this release. - * \version 1.8.8 Fortran subroutine introduced in this release. - * - * \since 1.8.0 - * - */ diff --git a/doxygen/dox/H5Sencode.dox b/doxygen/dox/H5Sencode.dox deleted file mode 100644 index fe0995c..0000000 --- a/doxygen/dox/H5Sencode.dox +++ /dev/null @@ -1,5 +0,0 @@ -/** - * \ingroup H5S - * \def H5Sencode() - * H5Sencode() is a macro that is mapped to either H5Sencode1() or H5Sencode2(). -*/ diff --git a/doxygen/dox/MetadataCachingInHDF5.dox b/doxygen/dox/MetadataCachingInHDF5.dox index 9ba0fab..9b8e446 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 @@ -692,7 +692,7 @@ The \ref H5AC_cache_config_t.decrement "decrement" and \ref H5AC_cache_config_t.upper_hr_threshold "upper_hr_threshold" fields are ignored in this case. -\subsubsection awhrtcsr Ageout With Hit Rate Threshold Cache Size Reduction +\subsubsection dawhrtcsr Ageout With Hit Rate Threshold Cache Size Reduction If \ref H5AC_cache_config_t.decr_mode "decr_mode" is #H5C_decr__age_out_with_threshold, the cache size is decreased by the ageout @@ -1017,4 +1017,4 @@ and the average successful and unsuccessful search depths in the hash table. If these latter figures are significantly above 1, you should increase the size of the hash table. - */
\ No newline at end of file + */ 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/RFC.dox b/doxygen/dox/RFC.dox new file mode 100644 index 0000000..c2562b0 --- /dev/null +++ b/doxygen/dox/RFC.dox @@ -0,0 +1,102 @@ +/** \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>2021-02-19</td> <td>\ref_rfc20210219</td> <td></td></tr> +<tr> <td>2020-02-13</td> <td>\ref_rfc20200213</td> <td></td></tr> +<tr> <td>2020-02-10</td> <td>\ref_rfc20200210</td> <td></td></tr> +<tr> <td>2019-09-23</td> <td>\ref_rfc20190923</td> <td></td></tr> +<tr> <td>2019-07-15</td> <td>\ref_rfc20190715</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-08-30</td> <td>\ref_rfc20180830</td> <td></td> </tr> +<tr> <td>2018-08-29</td> <td>\ref_rfc20180829</td> <td></td> </tr> +<tr> <td>2018-08-15</td> <td>\ref_rfc20180815</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-12-05</td> <td>\ref_rfc20081205</td> <td></td> </tr> +<tr> <td>2008-10-30</td> <td>\ref_rfc20081030</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-07-28</td> <td>\ref_rfc20080728</td> <td></td> </tr> +<tr> <td>2008-07-23</td> <td>\ref_rfc20080723</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 596a224..1de53f2 100644 --- a/doxygen/dox/ReferenceManual.dox +++ b/doxygen/dox/ReferenceManual.dox @@ -3,41 +3,87 @@ 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 H5ES "Event Sets" — Functions for handling HDF5 event sets (\ref H5ES) -\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 H5M "Maps" — Management of HDF5 maps (\ref H5M) -\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) -\li \ref H5VL "Virtual Object Layer" — Management of the Virtual Object Layer (\ref H5VL) - -\par Asynchronous Functions - A subset of functions has \ref ASYNC "asynchronous variants". - -\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 H5ES "Event Sets (H5ES)" +\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 H5M "Maps (H5M)" +\li \ref H5O "Objects (H5O)" +\li \ref H5P "Property Lists (H5P)" +\li \ref H5PL "Dynamically-loaded Plugins (H5PL)" +\li \ref H5R "References (H5R)" +\li \ref H5VL "Virtual Object Layer (H5VL)" +</td><td style="border: none;vertical-align: top;"> +\li Functions with \ref ASYNC "asynchronous variants" +\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 H5ES \ref H5F \ref H5G \ref H5I \ref H5L +\ref H5M \ref H5O \ref H5P \ref H5PL \ref H5R \ref H5S \ref H5T \ref H5VL \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 -*/
\ No newline at end of file +\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. + +*/ diff --git a/doxygen/dox/Specifications.dox b/doxygen/dox/Specifications.dox index 4ae48d0..5a36d61 100644 --- a/doxygen/dox/Specifications.dox +++ b/doxygen/dox/Specifications.dox @@ -19,4 +19,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..f4cc905 --- /dev/null +++ b/doxygen/dox/cookbook/Accessibility.c @@ -0,0 +1,48 @@ +/* -*- 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, 10, 0) + if (H5Pset_libver_bounds(fapl, H5F_LIBVER_V18, H5F_LIBVER_V18) < 0) { +#elif 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..f4e894f --- /dev/null +++ b/doxygen/dox/cookbook/Attributes.c @@ -0,0 +1,61 @@ +/* -*- 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, 10, 0) + if (H5Pset_libver_bounds(fapl, H5F_LIBVER_V18, H5F_LIBVER_LATEST) < 0) { +#elif 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..b824933 --- /dev/null +++ b/doxygen/dox/cookbook/Files.c @@ -0,0 +1,87 @@ +/* -*- 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 H5_VERSION_GE(1, 10, 1) + if (H5Pset_file_space_strategy(fcpl, H5F_FSPACE_STRATEGY_FSM_AGGR, 1, 4096) < 0) { +#else +#error HDF5 1.10.1+ required +#endif + ret_val = EXIT_FAILURE; + goto fail_fapl; + } + + if ((fapl = H5Pcreate(H5P_FILE_ACCESS)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_fapl; + } +#if H5_VERSION_GE(1, 10, 1) + if (H5Pset_libver_bounds(fapl, H5F_LIBVER_V110, H5F_LIBVER_LATEST) < 0) { +#else +#error HDF5 1.10.x+ required +#endif + ret_val = EXIT_FAILURE; + goto fail_file; + } + + 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..169d638 --- /dev/null +++ b/doxygen/dox/cookbook/Files.dox @@ -0,0 +1,71 @@ +/** \page Files + +\section Files + +\subsection CB_FreeSpace Tracking Free Space in HDF5 Files + +\par Problem +You sometimes delete objects in HDF5 files and don't have new content to use the +free space, but would like to reuse it in the future. + +\par Solution +At file creation time, set the file space management strategy and persistence of +free space tracking information via H5Pset_file_space_strategy(). + +\note This feature is only supported in HDF5 1.10.1+. + +\snippet{lineno} Files.c free_space + +\par Discussion +Free space tracking is supported only in HDF5 versions 1.10.x and higher. +This has implications for the accessibility of your HDF5 files and +should be considered carefully. If compatibility with previous versions of +HDF5 must be maintained, space reclamation via \Code{h5repack} might be an option.\n +The file space strategy #H5F_FSPACE_STRATEGY_FSM_AGGR is not the only option +that supports free-space tracking. #H5F_FSPACE_STRATEGY_PAGE is another option, +which adds paged allocation and is used most effectively with page buffering.\n +For an in-depth account of HDF5 file space management, paged-allocation, and +page buffering, see the following documents: +\li \ref_rfc20121024 +\li \ref_rfc20120523 +\li \ref_rfc20150709 + +\par See Also +See \ref CB_MaintainCompat for HDF5 compatibility implications. + + +\subsection CB_RemoveUnusedSpace Removing Unused Space from HDF5 Files + +\par Problem +Based on estimates or \Code{h5stat} output you know that a large portion +of an HDF5 file consists of free or unaccounted space, and you would like +to remove it. + + +\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 index 25c905f..1bb53e0 100644 --- a/doxygen/dox/maybe_metadata_reads.dox +++ b/doxygen/dox/maybe_metadata_reads.dox @@ -13,62 +13,30 @@ * 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: * - * <pre> - * - * H5Awrite() - * H5Aread() - * H5Arename() - * H5Aiterate2() - * H5Adelete() - * H5Aexists() - * - * H5Dget_space_status() - * H5Dget_storage_size() - * H5Dset_extent() - * H5Ddebug() - * H5Dclose() - * H5Dget_create_plist() - * H5Dget_space() (when dataset is a virtual dataset) - * - * H5Gget_create_plist() - * H5Gget_info() - * H5Gclose() - * - * H5Literate() - * H5Lvisit() - * - * H5Rcreate() - * H5Rdereference2() (when reference is an object reference) - * 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() + * 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() + * H5Tget_create_plist(), H5Tclose() * * H5Zunregister() - * </pre> * * In addition, \b most deprecated functions fall into this category. * diff --git a/doxygen/dox/rm-template.dox b/doxygen/dox/rm-template.dox index 64e4770..070a0a1 100644 --- a/doxygen/dox/rm-template.dox +++ b/doxygen/dox/rm-template.dox @@ -1,72 +1,99 @@ -/**\ingroup H5XYZ - * - * \brief A synopsis of what H5XYZgreat_function does - * - * \param[in] name1 Description of IN parameter \p name1 - * \param[out] name2 Description of OUT parameter \p name2 - * \param[in,out] name3 Description of INOUT parameter \p name3 - * - * \return Returns what you always wanted - * - * \pre Describe preconditions for an entity. Can be repreated. - * - * \invariant Describe invariants for an entity. Can be repeated. - * - * \post Describe postconditions for an entity. Can be repreated. - * - * \deprecated This was my favorite function while it lasted. - * - * \details Describe the normal behavior flow of the function here. Try to be - * helpful! - * - * Make reference to other functions like this: H5Fopen(). - * - * Make reference to formal parameters like this: \p name1 - * - * Make reference to macros like this: #H5P_DEFAULT. - * - * Make reference to enumeration constants like this: #H5F_CLOSE_WEAK. - * - * Include code snippets like this: - * \snippet H5Zpublic.h H5Z_class2_t_snip - * - * Lists are supported: - * - mouse events - * -# mouse move event - * -# mouse click event\n - * More info about the click event. - * -# mouse double click event - * - keyboard events - * 1. key down event - * 2. key up event - * - * The distance between \f$(x_1,y_1)\f$ and \f$(x_2,y_2)\f$ is - * \f$\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}\f$.\n - * For tables, see - * <a href="https://www.doxygen.nl/manual/tables.html">this example</a>. - * - * This is an example of how to use the H5XYZgreat_function().\n - * The contents of the file hello_hdf5.c will be included. - * \include hello_hdf5.c - * - * \note Dear reader, ... - * - * \attention Colorless green ideas sleep furiously. - * - * \warning Don't do this at home! - * - * \author This function was written by an esteemed author. Repeat this - * command for multiple authors. - * - * \date Record the function's birthdate! - * - * \since 1.MAJOR.MINOR The 'since' command can also be used to record a - * function's introduction (via its initial release - * version). - * - * \version 1.MAJOR.MINOR An important event in the version history of this - * function. There can be multiple such events. - * - * \see H5XYZanother_great_function(), H5XYZnot_so_great_a_function() - * - */ +/** \page RMT Reference Manual (RM) Page Template + +We treat documentation like code and use +<a href="https://www.doxygen.nl/index.html">Doxygen</a> to +<a href="https://github.com/HDFGroup/hdf5/blob/develop/src/H5Fpublic.h">markup +comments in the code</a> or create +<a href="https://github.com/HDFGroup/hdf5/blob/develop/doxygen/dox/Overview.dox">stand-alone pages</a>. + +Every RM entry consists of a subset of the elements listed below. Not every RM +entry warrants the full set. More is better, and we can, perhaps, distinguish +minimal, typical, and great RM entries. + +A minimal RM entry must include elements 1-3, 8, 11, and 7 if applicable. + +A \Emph{typical} RM entry is a minimal RM entry that in addition has elements +9, 10, and 12. + +A \Bold{great} RM entry is a typical RM entry plus everything else. + +The current RM is a mixed bag. Take what's there with a pinch of salt and apply +the <a href="https://www.oreilly.com/library/view/97-things-every/9780596809515/ch08.html">Scout Rule</a>! + +\par RM entry elements + +1. Module indication + - Indicate the HDF5 module in which the function will appear. + \verbatim + * \ingroup H5XYZ + \endverbatim +2. Synopsis + - A phrase or sentence that summarizes the function's purpose + \verbatim + * \brief Simplifies your life + \endverbatim +3. Prototype (parameters and return value) + - A description of the function parameters and return value + \verbatim + * \param[in] name1 Description of IN parameter \p name1 + * \param[out] name2 Description of OUT parameter \p name2 + * \param[in,out] name3 Description of INOUT parameter \p name3 + * \return Returns what you always wanted + \endverbatim + - Clearly indicate the parameter direction as \c in, \c out, or + \Code{in,out} + - Make reference to other parameters using \Code{\\p} +4. Preconditions + - A set of preconditions that must be met. + \verbatim + * \pre The argmument supplied in parameter \p name2 must be even. + \endverbatim +5. Invariants + - A set of invariants. + \verbatim + * \invariant The mouse pointer will always be visible. + \endverbatim +6. Postconditions + - What will be true when the function returns. + \verbatim + * \post On error, the output parameters will be unmodified. + \endverbatim +7. Deprecation note + - If a function was deprecated, list the version in which the function was + deprecated (below), why it was deprecated, and which function(s) succeed it. + \verbatim + * \deprecated Deprecated in favor of another great function. + \endverbatim +8. Details + - A detailed description of the function's behavior + \verbatim + * \details This is the heart of the matter. Try to be helpful! + \endverbatim +9. Example + - The function in context and action, usually a (Doxygen) snippet. + \verbatim + * \par Example + * \snippet H5F_examples.c minimal + \endverbatim +10. Instruction (attention, note, warning) + - Behaviors, features, side-effects, etc. the user should be aware of + \verbatim + * \note Dear reader, ... + * + * \attention Colorless green ideas sleep furiously. + * + * \warning Don't do this at home! + \endverbatim +11. Since + - The HDF5 library version in which the function was introduced + \verbatim + * \since 1.MAJOR.MINOR + \endverbatim +12. Version + - Use this element to record a deprecation version, a change in parameter + types, changes in behavior, etc. + \verbatim + * \version 1.MAJOR.MINOR Function was deprecated in this release + \endverbatim + +*/ diff --git a/doxygen/examples/DebuggingHDF5Applications.html b/doxygen/examples/DebuggingHDF5Applications.html new file mode 100644 index 0000000..c6aaf74 --- /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 managment</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..2d5bc5e --- /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 + defned 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 agression 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 excercise 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 charaters + "< 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/H5D_examples.c b/doxygen/examples/H5D_examples.c index aad057d..4e54c1d 100644 --- a/doxygen/examples/H5D_examples.c +++ b/doxygen/examples/H5D_examples.c @@ -5,6 +5,86 @@ #include <stdio.h> #include <stdlib.h> +//! <!-- [H5Dchunk_iter_cb] --> +int +chunk_cb(const hsize_t *offset, uint32_t filter_mask, haddr_t addr, uint32_t nbytes, void *op_data) +{ + // only print the allocated chunk size only + printf("%d\n", nbytes); + return EXIT_SUCCESS; +} +//! <!-- [H5Dchunk_iter_cb] --> + +//! <!-- [H5Ovisit_cb] --> +herr_t +H5Ovisit_cb(hid_t obj, const char *name, const H5O_info2_t *info, void *op_data) +{ + herr_t retval = 0; + char * base_path = (char *)op_data; + + if (info->type == H5O_TYPE_DATASET) // current object is a dataset + { + hid_t dset, dcpl; + if ((dset = H5Dopen(obj, name, H5P_DEFAULT)) == H5I_INVALID_HID) { + retval = -1; + goto func_leave; + } + if ((dcpl = H5Dget_create_plist(dset)) == H5I_INVALID_HID) { + retval = -1; + goto fail_dcpl; + } + if (H5Pget_layout(dcpl) == H5D_CHUNKED) // dataset is chunked + { + __label__ fail_dtype, fail_dspace, fail_shape; + hid_t dspace, dtype; + size_t size, i; + int rank; + hsize_t cdims[H5S_MAX_RANK]; + + // get resources + if ((dtype = H5Dget_type(dset)) < 0) { + retval = -1; + goto fail_dtype; + } + if ((dspace = H5Dget_space(dset)) < 0) { + retval = -1; + goto fail_dspace; + } + // get the shape + if ((size = H5Tget_size(dtype)) == 0 || (rank = H5Sget_simple_extent_ndims(dspace)) < 0 || + H5Pget_chunk(dcpl, H5S_MAX_RANK, cdims) < 0) { + retval = -1; + goto fail_shape; + } + // calculate the nominal chunk size + size = 1; + for (i = 0; i < (size_t)rank; ++i) + size *= cdims[i]; + // print dataset info + printf("%s%s : nominal chunk size %lu [B] \n", base_path, name, size); + // get the allocated chunk sizes + if (H5Dchunk_iter(dset, H5P_DEFAULT, &chunk_cb, NULL) < 0) { + retval = -1; + goto fail_fig; + } + +fail_shape: + H5Sclose(dspace); +fail_dspace: + H5Tclose(dtype); +fail_dtype:; + } + + H5Pclose(dcpl); +fail_dcpl: + H5Dclose(dset); + } + +func_leave: + return retval; +} +//! <!-- [H5Ovisit_cb] --> + int main(void) { @@ -166,7 +246,6 @@ fail_delete: H5Fclose(file); fail_file:; } - //! <!-- [delete] --> return ret_val; 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/H5F_examples.c b/doxygen/examples/H5F_examples.c index a7ce6fb..4e89fde 100644 --- a/doxygen/examples/H5F_examples.c +++ b/doxygen/examples/H5F_examples.c @@ -10,7 +10,7 @@ main(void) { int ret_val = EXIT_SUCCESS; - //! <!-- [life_cycle] --> + //! <!-- [create] --> { __label__ fail_fapl, fail_fcpl, fail_file; hid_t fcpl, fapl, file; @@ -48,12 +48,13 @@ fail_fapl: H5Pclose(fcpl); fail_fcpl:; } - //! <!-- [life_cycle] --> + //! <!-- [create] --> - //! <!-- [life_cycle_w_open] --> + //! <!-- [read] --> { __label__ fail_fapl, fail_file; - hid_t fapl, file; + hid_t fapl, file; + hsize_t size; if ((fapl = H5Pcreate(H5P_FILE_ACCESS)) == H5I_INVALID_HID) { ret_val = EXIT_FAILURE; @@ -63,7 +64,7 @@ fail_fcpl:; // adjust the file access properties } - unsigned mode = H5F_ACC_RDWR; + unsigned mode = H5F_ACC_RDONLY; char name[] = "f1.h5"; if ((file = H5Fopen(name, mode, fapl)) == H5I_INVALID_HID) { @@ -71,14 +72,41 @@ fail_fcpl:; goto fail_file; } - // do something useful with FILE + if (H5Fget_filesize(file, &size) < 0) { + ret_val = EXIT_FAILURE; + } + + printf("File size: %llu bytes\n", size); H5Fclose(file); fail_file: H5Pclose(fapl); fail_fapl:; } - //! <!-- [life_cycle_w_open] --> + //! <!-- [read] --> + + //! <!-- [update] --> + { + __label__ fail_file; + hid_t file; + + unsigned mode = H5F_ACC_RDWR; + char name[] = "f1.h5"; + + if ((file = H5Fopen(name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + + // create a cycle by hard linking the root group in the root group + if (H5Lcreate_hard(file, ".", file, "loopback", H5P_DEFAULT, H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + } + + H5Fclose(file); +fail_file:; + } + //! <!-- [update] --> //! <!-- [minimal] --> { @@ -183,5 +211,18 @@ fail_fapl:; } //! <!-- [mount] --> + //! <!-- [delete] --> + { +#if H5_VERSION_GE(1, 12, 0) + + // this function is only available in HDF5 1.12.x + if (H5Fdelete("f1.h5", H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + } + +#endif + } + //! <!-- [delete] --> + 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..d012d1b --- /dev/null +++ b/doxygen/examples/H5PL_examples.c @@ -0,0 +1,97 @@ +/* -*- 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"); + printf("VOL plugins %s be loaded.\n", (mask & H5PL_VOL_PLUGIN) == 2 ? "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/H5_examples.c b/doxygen/examples/H5_examples.c new file mode 100644 index 0000000..ef52ed0 --- /dev/null +++ b/doxygen/examples/H5_examples.c @@ -0,0 +1,85 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <assert.h> +#include <stdio.h> +#include <stdlib.h> + +//! <!-- [closing_shop] --> +void +closing_shop(void *ctx) +{ + printf("GoodBye, Cruel World!\n"); +} +//! <!-- [closing_shop] --> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [create] --> + { + // an HDF5 library instance is automatically initialized as + // part of the first HDF5 API call, but there's no harm in + // calling H5open(). + if (H5open() < 0) { + ret_val = EXIT_FAILURE; + } + } + //! <!-- [create] --> + + //! <!-- [read] --> + { + __label__ fail_read; + unsigned majnum, minnum, relnum; + hbool_t flag; + + // retrieve the library version + if (H5get_libversion(&majnum, &minnum, &relnum) < 0) { + ret_val = EXIT_FAILURE; + goto fail_read; + } + // is this a thread-safe library build? + if (H5is_library_threadsafe(&flag) < 0) { + ret_val = EXIT_FAILURE; + goto fail_read; + } + + printf("Welcome to HDF5 %d.%d.%d\n", majnum, minnum, relnum); + printf("Thread-safety %s\n", (flag > 0) ? "enabled" : "disabled"); + +fail_read:; + } + //! <!-- [read] --> + + //! <!-- [update] --> + { + // update the library instance free list limits + if (H5set_free_list_limits(512 * 1024, 32 * 1024, 2048 * 1024, 128 * 1024, 8192 * 1024, 512 * 1024) < + 0) { + ret_val = EXIT_FAILURE; + } + } + //! <!-- [update] --> + + //! <!-- [delete] --> + { +#if H5_VERSION_GE(1, 13, 0) + // install a finalization routine + if (H5atclose(&closing_shop, NULL) < 0) { + ret_val = EXIT_FAILURE; + } +#endif + // close shop + if (H5close() < 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/hdf5_header.html b/doxygen/hdf5_header.html index 4a575d6..23f41f9 100644 --- a/doxygen/hdf5_header.html +++ b/doxygen/hdf5_header.html @@ -21,7 +21,7 @@ $mathjax </head> <body> -<div style="background:#FFDDDD;font-size:120%;text-align:center;margin:0;padding:5px">Please, help us to better know about our user community by answering the following short survey: <a href="https://www.hdfgroup.org/">https://www.hdfgroup.org/</a></div> +<div style="background:#FFDDDD;font-size:120%;text-align:center;margin:0;padding:5px">Please, help us to better know about our user community by answering the following short survey: <a href="https://www.hdfgroup.org/website-survey/">https://www.hdfgroup.org/website-survey/</a></div> <div id="top"><!-- do not remove this div, it is closed by doxygen! --> diff --git a/doxygen/hdf5doxy_layout.xml b/doxygen/hdf5doxy_layout.xml index 7f71c24..6efa690 100644 --- a/doxygen/hdf5doxy_layout.xml +++ b/doxygen/hdf5doxy_layout.xml @@ -11,6 +11,8 @@ <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/IOFlow.gif b/doxygen/img/IOFlow.gif Binary files differnew file mode 100644 index 0000000..3e79030 --- /dev/null +++ b/doxygen/img/IOFlow.gif diff --git a/doxygen/img/IOFlow2.gif b/doxygen/img/IOFlow2.gif Binary files differnew file mode 100644 index 0000000..c75ca79 --- /dev/null +++ b/doxygen/img/IOFlow2.gif diff --git a/doxygen/img/IOFlow3.gif b/doxygen/img/IOFlow3.gif Binary files differnew file mode 100644 index 0000000..316cd1e --- /dev/null +++ b/doxygen/img/IOFlow3.gif |
