mirror/hdf5
2
0
Fork 0
mirror of https://github.com/HDFGroup/hdf5.git synced 2025-03-19 16:50:46 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge doxygen2 into develop (#553)

Browse Source 
* Fixed warnings and started H5Epublic.h.

* Include H5FD* headers to correctly resolve references.

* Doxygen2 (#330)

* H5Eauto_is_v2.

* Added a few more calls.

* Added a few more H5E calls.

* First cut of H5E v2.

* Added the deprecated v1 calls.

* Updated spacing.

* Once more.

* Taking some inspiration from Eigen3.

* Add doxygen for the assigned functions: H5Pregister1,H5Pinsert1,H5Pen… (#352)

* Add doxygen for the assigned functions: H5Pregister1,H5Pinsert1,H5Pencode1, H5Pget_filter_by_id1,H5Pget_version, H5Pset_file_space,H5Pget_file_space. Someone already adds H5Pget_filter1. Also fixs an extra parameter 'close' call back function for HPregister2.

* doxygen work. fixs format by using clang-format.

* doxgen work for H5Pregister1 etc. Addressed Barbara and Gerd's comments.
For Quincey's comments, since we are not supposed to change the source code.
I leave this to future improvements.

* added documentation for H5P APIs (#350)

* add documenation for H5Pget_buffer,H5Pget_data_transform,H5Pget_edc_check,H5Pget_hyper_vector_size,H5Pget_preserve,H5Pget_type_conv_cb,H5Pget_vlen_mem_manager,H5Pset_btree_ratios

* format corrections

* fixed grammer

* fixed herr_t

* Better name.

* A fresh look.

* add doxygen to H5Ppublic.h

* use attention instead of warning

* Add doxygen comments in H5Ppublic.h (#375)

* Add doxygen comments in H5Ppublic.h

* H5Pset_meta_block_size
* H5Pset_metadata_read_attempts
* H5Pset_multi_type
* H5Pset_object_flush_cb
* H5Pset_sieve_buf_size
* H5Pset_small_data_block_size
* H5Pset_all_coll_metadata_ops
* H5Pget_all_coll_metadata_ops

* Add DOXYGEN_EXAMPLES_DIR to src/CMakeLists.txt

* Fix clang-format errors

* Fix filenames in doxygen/examples

* add doxygen to H5Ppublic.h (#378)

* add doxygen to H5Ppublic.h

* use attention instead of warning

Co-authored-by: Kimmy Mu <kmu@hdfgroup.org>

* Revert "add doxygen to H5Ppublic.h (#378)"

This reverts commit 2ee1821b138a5c00b15ea57ce9e950367480f5f2.

* Updated Doxygen variables.

* I forgot to copy two images.

* Enable desktop search by default.

* Add my assigned Doxygen documentation.

* Remove whitespace at EOL.  Appease clang-format.

* Addressed Chris' comments.

* Added an alias for asynchronous functions.

* One space is enough for all of us.

* Slightly restructured RM page.

* address some issues

* reformatting

* Style external links.

* reformatting

* reformatting

* Added "Metadata Caching in HDF5" as a technical note example.

* Revise this soon!

* Added specification examples.

* Fixed references.

* Added H5AC cache image stuff and file format study.

* Added older FMT versions. Where did 1.0 go?

* Updated C/C++ note and replaced ambiguous labels.

* Reformat source with clang v10.0.1.

* Added the VFL technical note.

* Added what I believe might be called version 1.0 of the format.

* Added the remaining specs.

* Added H5Z callback documentation and fixed a few mistakes.

* Added dox for deprecated H5G calls and fixed a few snippet blockIDs.

* clang-format happy?

* Ok?

* Bonus track: Deprecated H5D functions.

* Carry over the more detailed group description.

* Added documentation for the missing and deprecated H5R calls.

* Life is easier and less repetitive w/ snippets. Use them!

* Eliminate the snippet block ID artifacts in the HTML rendering.

* Fixed snippet HTML artifacts and added a few missing calls.

* Under 20 H5Ps to go!

* Almost complete!

* "This is a form of pedantry up with which I will not put." (Churchill)

* Let's not waste as much space on bulleted lists!

* First complete (?) draft of the Doxygen-based RM.

* Completeness check and minor fixes along the way.

* Pedantry.

* Adding missing H5FD calls checkpoint.

* Pedantry.

* More pedantry.

* Added H5Pset_fapl_log.

* First draft of H5ES.

* Fixed warnings.

* Prep. for map module.

* First cut of the map module.

* Pedantry.

* Possible H5F introduction.

* Fix the indentation.

* Pedantry.

* Ditto.

* Thanks to the reviewers for their comments.

* Added missing images.

* Line numbers are a distraction here.

* More examples, references, and clean-up. Don't repeat yourself!

* Clang pedantry.

* Ditto.

* More reviewer comments...

* Templatized references and cleaned up \todos.

* Committing clang-format changes

* Fixed MANIFEST.

* Addressed Quincey's comments. (OCPLs)

* Fixed a few more \todo items.

* Fixed more \todo items.

* Added attribute life cycle.

* Forgot the examples file.

* Committing clang-format changes

* Pedantry.

* Live and learn!

* Added a sample H5D life cycle.

* Committing clang-format changes

* Pedantry.

Co-authored-by: kyang2014 <kyang2014@users.noreply.github.com>
Co-authored-by: Scot Breitenfeld <brtnfld@hdfgroup.org>
Co-authored-by: Kimmy Mu <kmu@hdfgroup.org>
Co-authored-by: Christopher Hogan <ChristopherHogan@users.noreply.github.com>
Co-authored-by: jya-kmu <53388330+jya-kmu@users.noreply.github.com>
Co-authored-by: David Young <dyoung@hdfgroup.org>
Co-authored-by: Larry Knox <lrknox@hdfgroup.org>
Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
This commit is contained in:
Gerd Heber 2021-04-26 14:07:29 -05:00 committed by GitHub
parent 12082e728d
commit 1d680fe04c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
110 changed files with 61858 additions and 1719 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
MANIFEST
View File

@ -207,7 +207,12 @@
./doxygen/aliases
./doxygen/Doxyfile.in
./doxygen/dox/api-compat-macros.dox
./doxygen/dox/About.dox
./doxygen/dox/Cookbook.dox
./doxygen/dox/DDLBNF110.dox
./doxygen/dox/DDLBNF112.dox
./doxygen/dox/FileFormatSpec.dox
./doxygen/dox/GettingStarted.dox
./doxygen/dox/H5AC_cache_config_t.dox
./doxygen/dox/H5Acreate.dox
./doxygen/dox/H5Aiterate.dox
@ -224,12 +229,53 @@
./doxygen/dox/H5Ovisit_by_name.dox
./doxygen/dox/H5Ovisit.dox
./doxygen/dox/H5Sencode.dox
./doxygen/dox/mainpage.dox
./doxygen/dox/MetadataCachingInHDF5.dox
./doxygen/dox/OtherSpecs.dox
./doxygen/dox/Overview.dox
./doxygen/dox/ReferenceManual.dox
./doxygen/dox/Specifications.dox
./doxygen/dox/TechnicalNotes.dox
./doxygen/dox/api-compat-macros.dox
./doxygen/dox/maybe_metadata_reads.dox
./doxygen/dox/rm-template.dox
./doxygen/examples/FF-IH_FileGroup.gif
./doxygen/examples/FF-IH_FileObject.gif
./doxygen/examples/FileFormatSpecChunkDiagram.jpg
./doxygen/examples/H5Pset_metadata_read_attempts.c
./doxygen/examples/H5Pset_object_flush_cb.c
./doxygen/examples/H5.format.1.0.html
./doxygen/examples/H5.format.1.1.html
./doxygen/examples/H5.format.2.0.html
./doxygen/examples/H5.format.html
./doxygen/examples/H5A_examples.c
./doxygen/examples/H5D_examples.c
./doxygen/examples/H5Fclose.c
./doxygen/examples/H5Fcreate.c
./doxygen/examples/H5F_examples.c
./doxygen/examples/H5Pget_metadata_read_attempts.1.c
./doxygen/examples/H5Pget_metadata_read_attempts.2.c
./doxygen/examples/H5Pget_metadata_read_attempts.3.c
./doxygen/examples/H5Pget_object_flush_cb.c
./doxygen/examples/ImageSpec.html
./doxygen/examples/PaletteExample1.gif
./doxygen/examples/Palettes.fm.anc.gif
./doxygen/examples/TableSpec.html
./doxygen/examples/ThreadSafeLibrary.html
./doxygen/examples/VFL.html
./doxygen/examples/hello_hdf5.c
./doxygen/hdf5_footer.html
./doxygen/hdf5_header.html
./doxygen/hdf5_navtree_hacks.js
./doxygen/hdf5doxy.css
./doxygen/hdf5doxy_layout.xml
./doxygen/img/FF-IH_FileGroup.gif
./doxygen/img/FF-IH_FileObject.gif
./doxygen/img/FileFormatSpecChunkDiagram.jpg
./doxygen/img/HDFG-logo.png
./doxygen/img/PaletteExample1.gif
./doxygen/img/Palettes.fm.anc.gif
./doxygen/img/ftv2node.png
./doxygen/img/ftv2pnode.png
./examples/Attributes.txt
./examples/Makefile.am

24
configure.ac
View File

@ -95,12 +95,12 @@ AC_CONFIG_COMMANDS([pubconf], [
sed 's/#define /#define H5_/' <src/H5config.h |\
sed 's/#undef /#undef H5_/' >pubconf
if test ! -f src/H5pubconf.h; then
/bin/mv -f pubconf src/H5pubconf.h
mv -f pubconf src/H5pubconf.h
elif (diff pubconf src/H5pubconf.h >/dev/null); then
rm -f pubconf
echo "src/H5pubconf.h is unchanged"
else
/bin/mv -f pubconf src/H5pubconf.h
mv -f pubconf src/H5pubconf.h
fi
echo "Post process src/libhdf5.settings"
sed '/^#/d' < src/libhdf5.settings > libhdf5.settings.TMP
@ -1116,16 +1116,34 @@ if test "X$HDF5_DOXYGEN" = "Xyes"; then
AC_SUBST([DOXYGEN_OPTIMIZE_OUTPUT_FOR_C])
AC_SUBST([DOXYGEN_MACRO_EXPANSION])
AC_SUBST([DOXYGEN_OUTPUT_DIRECTORY])
AC_SUBST([DOXYGEN_EXAMPLES_DIRECTORY])
AC_SUBST([DOXYGEN_LAYOUT_FILE])
AC_SUBST([DOXYGEN_HTML_HEADER])
AC_SUBST([DOXYGEN_HTML_FOOTER])
AC_SUBST([DOXYGEN_HTML_EXTRA_STYLESHEET])
AC_SUBST([DOXYGEN_HTML_EXTRA_FILES])
AC_SUBST([DOXYGEN_SERVER_BASED_SEARCH])
AC_SUBST([DOXYGEN_EXTERNAL_SEARCH])
AC_SUBST([DOXYGEN_SEARCHENGINE_URL])
DOXYGEN_PACKAGE=${PACKAGE_NAME}
DOXYGEN_VERSION_STRING=${PACKAGE_VERSION}
DOXYGEN_INCLUDE_ALIASES='$(SRCDIR)/doxygen/aliases'
DOXYGEN_PROJECT_LOGO='$(SRCDIR)/doxygen/img/HDFG-logo.png'
DOXYGEN_PROJECT_BRIEF="C-API Reference"
DOXYGEN_PROJECT_BRIEF=
DOXYGEN_INPUT_DIRECTORY='$(SRCDIR) $(SRCDIR)/doxygen/dox'
DOXYGEN_OPTIMIZE_OUTPUT_FOR_C=YES
DOXYGEN_MACRO_EXPANSION=YES
DOXYGEN_OUTPUT_DIRECTORY=hdf5lib_docs
DOXYGEN_EXAMPLES_DIRECTORY='$(SRCDIR)/doxygen/examples'
DOXYGEN_LAYOUT_FILE='$(SRCDIR)/doxygen/hdf5doxy_layout.xml'
DOXYGEN_HTML_HEADER='$(SRCDIR)/doxygen/hdf5_header.html'
DOXYGEN_HTML_FOOTER='$(SRCDIR)/doxygen/hdf5_footer.html'
DOXYGEN_HTML_EXTRA_STYLESHEET='$(SRCDIR)/doxygen/hdf5doxy.css'
DOXYGEN_HTML_EXTRA_FILES='$(SRCDIR)/doxygen/hdf5_navtree_hacks.js $(SRCDIR)/doxygen/img/ftv2node.png $(SRCDIR)/doxygen/img/ftv2pnode.png'
DOXYGEN_SERVER_BASED_SEARCH=NO
DOXYGEN_EXTERNAL_SEARCH=NO
DOXYGEN_SEARCHENGINE_URL=
DX_INIT_DOXYGEN([HDF5], [../doxygen/Doxyfile], [hdf5lib_docs])

35
doxygen/Doxyfile.in
View File

@ -738,7 +738,7 @@ FILE_VERSION_FILTER =
# DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE
# tag is left empty.
LAYOUT_FILE =
LAYOUT_FILE = @DOXYGEN_LAYOUT_FILE@
# The CITE_BIB_FILES tag can be used to specify one or more bib files containing
# the reference definitions. This must be a list of .bib files. The .bib
@ -855,7 +855,16 @@ INPUT_ENCODING = UTF-8
FILE_PATTERNS = H5*public.h \
H5*module.h \
H5FDcore.h \
H5FDdirect.h \
H5FDfamily.h \
H5FDlog.h \
H5FDmpi.h \
H5FDmpio.h \
H5FDmulti.h \
H5FDsec2.h \
H5FDstdio.h \
H5FDwindows.h \
H5VLconnector.h \
H5VLconnector_passthru.h \
H5VLnative.h \
@ -908,7 +917,7 @@ EXCLUDE_SYMBOLS =
# that contain example code fragments that are included (see the \include
# command).
EXAMPLE_PATH = ../src ../examples ../test examples
EXAMPLE_PATH = ../src ../examples ../test @DOXYGEN_EXAMPLES_DIRECTORY@
# If the value of the EXAMPLE_PATH tag contains directories, you can use the
# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
@ -1169,7 +1178,7 @@ HTML_FILE_EXTENSION = .html
# of the possible markers and block names see the documentation.
# This tag requires that the tag GENERATE_HTML is set to YES.
HTML_HEADER =
HTML_HEADER = @DOXYGEN_HTML_HEADER@
# The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each
# generated HTML page. If the tag is left blank doxygen will generate a standard
@ -1179,7 +1188,7 @@ HTML_HEADER =
# that doxygen normally uses.
# This tag requires that the tag GENERATE_HTML is set to YES.
HTML_FOOTER =
HTML_FOOTER = @DOXYGEN_HTML_FOOTER@
# The HTML_STYLESHEET tag can be used to specify a user-defined cascading style
# sheet that is used by each HTML page. It can be used to fine-tune the look of
@ -1204,7 +1213,7 @@ HTML_STYLESHEET =
# list). For an example see the documentation.
# This tag requires that the tag GENERATE_HTML is set to YES.
HTML_EXTRA_STYLESHEET =
HTML_EXTRA_STYLESHEET = @DOXYGEN_HTML_EXTRA_STYLESHEET@
# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
# other source files which should be copied to the HTML output directory. Note
@ -1214,7 +1223,7 @@ HTML_EXTRA_STYLESHEET =
# files will be copied as-is; there are no commands or markers available.
# This tag requires that the tag GENERATE_HTML is set to YES.
HTML_EXTRA_FILES =
HTML_EXTRA_FILES = @DOXYGEN_HTML_EXTRA_FILES@
# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen
# will adjust the colors in the style sheet and background images according to
@ -1272,7 +1281,7 @@ HTML_DYNAMIC_MENUS = NO
# The default value is: NO.
# This tag requires that the tag GENERATE_HTML is set to YES.
HTML_DYNAMIC_SECTIONS = NO
HTML_DYNAMIC_SECTIONS = YES
# With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries
# shown in the various tree structured indices initially; the user can expand
@ -1484,7 +1493,7 @@ ECLIPSE_DOC_ID = org.doxygen.Project
# The default value is: NO.
# This tag requires that the tag GENERATE_HTML is set to YES.
DISABLE_INDEX = NO
DISABLE_INDEX = YES
# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index
# structure should be generated to display hierarchical information. If the tag
@ -1632,7 +1641,7 @@ MATHJAX_CODEFILE =
# The default value is: YES.
# This tag requires that the tag GENERATE_HTML is set to YES.
SEARCHENGINE = NO
SEARCHENGINE = YES
# When the SERVER_BASED_SEARCH tag is enabled the search engine will be
# implemented using a web server instead of a web client using JavaScript. There
@ -1644,7 +1653,7 @@ SEARCHENGINE = NO
# The default value is: NO.
# This tag requires that the tag SEARCHENGINE is set to YES.
SERVER_BASED_SEARCH = YES
SERVER_BASED_SEARCH = @DOXYGEN_SERVER_BASED_SEARCH@
# When EXTERNAL_SEARCH tag is enabled doxygen will no longer generate the PHP
# script for searching. Instead the search results are written to an XML file
@ -1660,7 +1669,7 @@ SERVER_BASED_SEARCH = YES
# The default value is: NO.
# This tag requires that the tag SEARCHENGINE is set to YES.
EXTERNAL_SEARCH = NO
EXTERNAL_SEARCH = @DOXYGEN_EXTERNAL_SEARCH@
# The SEARCHENGINE_URL should point to a search engine hosted by a web server
# which will return the search results when EXTERNAL_SEARCH is enabled.
@ -1671,7 +1680,7 @@ EXTERNAL_SEARCH = NO
# Searching" for details.
# This tag requires that the tag SEARCHENGINE is set to YES.
SEARCHENGINE_URL =
SEARCHENGINE_URL = @DOXYGEN_SEARCHENGINE_URL@
# When SERVER_BASED_SEARCH and EXTERNAL_SEARCH are both enabled the unindexed
# search data is written to a file for indexing by an external tool. With the
@ -2168,7 +2177,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 =
PREDEFINED = H5_HAVE_PARALLEL
# 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

63
doxygen/aliases
View File

@ -1,3 +1,5 @@
ALIASES += THG="The HDF Group"
################################################################################
# Styling
################################################################################
@ -35,6 +37,15 @@ ALIASES += op{1}="\param[in] \1 Callback function"
ALIASES += op_data="\param[in,out] op_data User-defined callback function context"
ALIASES += op_data{1}="\param[in,out] \1 User-defined callback function context"
ALIASES += op_data_in="\param[in] op_data User-defined callback function context"
ALIASES += op_data_in{1}="\param[in] \1 User-defined callback function context"
################################################################################
# Asynchronous
################################################################################
ALIASES += async_variant_of{1}="Asynchronous version of \1()"
################################################################################
# Attributes
################################################################################
@ -66,6 +77,13 @@ ALIASES += type_id{1}="\param[in] \1 Datatype identifier"
ALIASES += file_type_id{1}="\param[in] \1 Datatype (in-file) identifier"
ALIASES += mem_type_id{1}="\param[in] \1 Datatype (in-memory) identifier"
################################################################################
# Errors
################################################################################
ALIASES += estack_id="\param[in] estack_id Error stack identifier"
ALIASES += estack_id{1}="\param[in] \1 Error stack identifier"
################################################################################
# Files
################################################################################
@ -102,6 +120,13 @@ ALIASES += fgdta_loc_id{1}="\loc_id{\1}. The identifier may be that of a file, g
ALIASES += fg_loc_id="\loc_id. The identifier may be that of a file or group."
ALIASES += fg_loc_id{1}="\loc_id{\1}. The identifier may be that of a file or group."
################################################################################
# Maps
################################################################################
ALIASES += map_id="\param[in] map_id Map identifier"
ALIASES += map_id{1}="\param[in] \1 Map identifier"
################################################################################
# Property lists
################################################################################
@ -121,6 +146,9 @@ ALIASES += dcpl_id{1}="\param[in] \1 Dataset creation property list identifier"
ALIASES += dxpl_id="\param[in] dxpl_id Dataset transfer property list identifier"
ALIASES += dxpl_id{1}="\param[in] \1 Dataset transfer property list identifier"
ALIASES += gacpl_id="\param[in] plist_id File, group, dataset, datatype, link, or attribute access property list identifier"
ALIASES += gacpl_id{1}="\param[in] \1 File, group, dataset, datatype, link, or attribute access property list identifier"
ALIASES += gapl_id="\param[in] gapl_id Group access property list identifier"
ALIASES += gapl_id{1}="\param[in] \1 Group access property list identifier"
@ -133,9 +161,18 @@ ALIASES += lapl_id{1}="\param[in] \1 Link access property list identifier"
ALIASES += lcpl_id="\param[in] lcpl_id Link creation property list identifier"
ALIASES += lcpl_id{1}="\param[in] \1 Link creation property list identifier"
ALIASES += mapl_id="\param[in] mapl_id Map access property list identifier"
ALIASES += mapl_id{1}="\param[in] \1 Map access property list identifier"
ALIASES += mcpl_id="\param[in] mcpl_id Map creation property list identifier"
ALIASES += mcpl_id{1}="\param[in] \1 Map creation property list identifier"
ALIASES += oapl_id="\param[in] oapl_id Object access property list identifier"
ALIASES += oapl_id{1}="\param[in] \1 Object access property list identifier"
ALIASES += ocpl_id="\param[in] oapl_id Object creation property list identifier"
ALIASES += ocpl_id{1}="\param[in] \1 Object creation property list identifier"
ALIASES += plist_id="\param[in] plist_id Property list identifier"
ALIASES += plist_id{1}="\param[in] \1 Property list identifier"
@ -173,7 +210,8 @@ ALIASES += fgdta_loc_obj_id{1}="\loc_obj_id{\1}. The identifier may be that of a
ALIASES += app_file="\param[in] app_file For internal use only, not a visible user parameter"
ALIASES += app_func="\param[in] app_func For internal use only, not a visible user parameter"
ALIASES += app_line="\param[in] app_line For internal use only, not a visible user parameter"
ALIASES += es_id="\param[in] es_id The event set ID to add this asynchronous operation to. H5ES_NONE may be used for synchronous execution."
ALIASES += es_id="\param[in] es_id Event set identifier"
ALIASES += es_id{1}="\param[in] \1 Event set identifier"
################################################################################
# Others
@ -181,11 +219,32 @@ ALIASES += es_id="\param[in] es_id The event set ID to add this asynchronous ope
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 += 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"
################################################################################
# References
################################################################################
ALIASES += ref_cons_semantics="<a href=\"https://portal.hdfgroup.org/display/HDF5/Enabling+a+Strict+Consistency+Semantics+Model+in+Parallel+HDF5\">Enabling a Strict Consistency Semantics Model in Parallel HDF5</a>"
ALIASES += ref_dld_filters="<a href=\"https://portal.hdfgroup.org/display/HDF5/HDF5+Dynamically+Loaded+Filters\">HDF5 Dynamically Loaded Filters</a>"
ALIASES += ref_file_image_ops="<a href=\"https://portal.hdfgroup.org/display/HDF5/HDF5+File+Image+Operations\">HDF5 File Image Operations</a>"
ALIASES += ref_filter_pipe="<a href=\"https://portal.hdfgroup.org/display/HDF5/HDF5+Data+Flow+Pipeline+for+H5Dread\">Data Flow Pipeline for H5Dread()</a>"
ALIASES += ref_group_impls="<a href=\"https://portal.hdfgroup.org/display/HDF5/Groups\">Group implementations in HDF5</a>"
ALIASES += ref_h5lib_relver="<a href=\"https://portal.hdfgroup.org/display/HDF5/HDF5+Library+Release+Version+Numbers\">HDF5 Library Release Version Numbers</a>"
ALIASES += ref_mdc_in_hdf5="<a href=\"https://portal.hdfgroup.org/display/HDF5/Metadata+Caching+in+HDF5\">Metadata Caching in HDF5</a>"
ALIASES += ref_mdc_logging="<a href=\"https://portal.hdfgroup.org/display/HDF5/H5F_START_MDC_LOGGING\">Metadata Cache Logging</a>"
ALIASES += ref_news_112="<a href=\"https://portal.hdfgroup.org/display/HDF5/New+Features+in+HDF5+Release+1.12\">New Features in HDF5 Release 1.12</a>"
ALIASES += ref_h5ocopy="<a href=\"https://portal.hdfgroup.org/display/HDF5/Copying+Committed+Datatypes+with+H5Ocopy\">Copying Committed Datatypes with H5Ocopy()</a>"
ALIASES += ref_sencode_fmt_change="<a href=\"https://portal.hdfgroup.org/pages/viewpage.action?pageId=58100093&preview=/58100093/58100094/encode_format_RFC.pdf\">RFC H5Secnode() / H5Sdecode() Format Change</a>"
ALIASES += ref_vlen_strings="\Emph{Creating variable-length string datatypes}"
ALIASES += ref_vol_doc="VOL documentation"
################################################################################
# The Usual Suspects
################################################################################
ALIASES += click4more="(Click on a enumerator, field, or type for more information.)"
ALIASES += csets="<table><tr><td>#H5T_CSET_ASCII</td><td>US ASCII</td></tr><tr><td>#H5T_CSET_UTF8</td><td>UTF-8 Unicode encoding</td></tr></table>"
ALIASES += datatype_class=" \li #H5T_INTEGER \li #H5T_FLOAT \li #H5T_STRING \li #H5T_BITFIELD \li #H5T_OPAQUE \li #H5T_COMPOUND \li #H5T_REFERENCE \li #H5T_ENUM \li #H5T_VLEN \li #H5T_ARRAY"
ALIASES += file_access="<table><tr><td>#H5F_ACC_RDWR</td><td>File was opened with read/write access.</td></tr><tr><td>#H5F_ACC_RDONLY</td><td>File was opened with read-only access.</td></tr><tr><td>#H5F_ACC_SWMR_WRITE</td><td>File was opened with read/write access for a single-writer/multiple-reader (SWMR) scenario. Note that the writer process must also open the file with the #H5F_ACC_RDWR flag.</td></tr><tr><td>#H5F_ACC_SWMR_READ</td><td>File was opened with read-only access for a single-writer/multiple-reader (SWMR) scenario. Note that the reader process must also open the file with the #H5F_ACC_RDONLY flag.</td></tr></table>"
@ -201,5 +260,5 @@ ALIASES += scopes="<table><tr><td>#H5F_SCOPE_GLOBAL</td><td>Flushes the entire v
ALIASES += sign_prop="<table><tr><td>#H5T_SGN_NONE</td><td>0</td><td>Unsigned integer type</td></tr><tr><td>#H5T_SGN_2</td><td>1</td><td>Two's complement signed integer type</td></tr></table>"
ALIASES += storage_type="<table><tr><td>#H5G_STORAGE_TYPE_COMPACT</td><td>Compact storage</td></tr><tr><td>#H5G_STORAGE_TYPE_DENSE</td><td>Indexed storage</td></tr><tr><td>#H5G_STORAGE_TYPE_SYMBOL_TABLE</td><td>Symbol tables, the original HDF5 structure</td></tr></table>"
ALIASES += str_pad_type="<table><tr><td>#H5T_STR_NULLTERM</td><td>0</td><td>Null terminate (as C does)</td></tr><tr><td>#H5T_STR_NULLPAD</td><td>1</td><td>Pad with zeros</td></tr><tr><td>#H5T_STR_SPACEPAD</td><td>2</td><td>Pad with spaces (as FORTRAN does)</td></tr></table>"
ALIASES += virtual=" \see Supporting Functions: \li H5Pget_layout() \li H5Pset_layout() \li H5Sget_regular_hyperslab() \li H5Sis_regular_hyperslab() \li H5Sselect_hyperslab() \see VDS Functions: \li H5Pget_virtual_count() \li H5Pget_virtual_dsetname() \li H5Pget_virtual_filename() \li H5Pget_virtual_prefix() \li H5Pget_virtual_printf_gap() \li H5Pget_virtual_srcspace() \li H5Pget_virtual_view() \li H5Pget_virtual_vspace() \li H5Pset_virtual \li H5Pset_virtual_prefix() \li H5Pset_virtual_printf_gap() \li H5Pset_virtual_view()"
ALIASES += see_virtual=" \see Supporting Functions: H5Pget_layout(), H5Pset_layout(), H5Sget_regular_hyperslab(), H5Sis_regular_hyperslab(), H5Sselect_hyperslab() \see VDS Functions: H5Pget_virtual_count(), H5Pget_virtual_dsetname(), H5Pget_virtual_filename(), H5Pget_virtual_prefix(), H5Pget_virtual_printf_gap(), H5Pget_virtual_srcspace(), H5Pget_virtual_view(), H5Pget_virtual_vspace(), H5Pset_virtual(), H5Pset_virtual_prefix(), H5Pset_virtual_printf_gap(), H5Pset_virtual_view()"
ALIASES += obj_info_fields="<table><tr><th>Flag</th><th>Purpose</th></tr><tr><td>#H5O_INFO_BASIC</td><td>Fill in the fileno, addr, type, and rc fields</td></tr><tr> <td>#H5O_INFO_TIME</td><td>Fill in the atime, mtime, ctime, and btime fields</td></tr><tr> <td>#H5O_INFO_NUM_ATTRS</td> <td>Fill in the num_attrs field</td></tr><tr><td>#H5O_INFO_HDR</td><td>Fill in the num_attrs field</td></tr><tr><td>#H5O_INFO_META_SIZE</td><td>Fill in the meta_size field</td></tr><tr><td>#H5O_INFO_ALL</td><td>#H5O_INFO_BASIC | #H5O_INFO_TIME | #H5O_INFO_NUM_ATTRS | #H5O_INFO_HDR | #H5O_INFO_META_SIZE</td></tr></table>"

11
doxygen/dox/About.dox Normal file
View File

@ -0,0 +1,11 @@
/** \page About About
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>
and the online version of their
<a href="http://eigen.tuxfamily.org/dox/">Doxygen-based documentation</a>.
Not only does Eigen set a standard as a piece of software, but also as an example
of <em>documentation done right</em>.
*/

5
doxygen/dox/Cookbook.dox Normal file
View File

@ -0,0 +1,5 @@
/** \page Cookbook Cookbook
Healthy, everyday recipes for every taste and budget...
*/

650
doxygen/dox/DDLBNF110.dox Normal file
View File

@ -0,0 +1,650 @@
/** \page DDLBNF110 DDL in BNF through HDF5 1.10
\todo Revise this & break it up!
\section intro110 Introduction
This document contains the data description language (DDL) for an HDF5 file. The
description is in Backus-Naur Form (BNF).
\section expo110 Explanation of Symbols
This section contains a brief explanation of the symbols used in the DDL.
\code{.unparsed}
::= defined as
<tname> a token with the name tname
<a> | <b> one of <a> or <b>
<a>opt zero or one occurrence of <a>
<a>* zero or more occurrence of <a>
<a>+ one or more occurrence of <a>
[0-9] an element in the range between 0 and 9
'[' the token within the quotes (used for special characters)
TBD To Be Decided
\endcode
\section ddl110 The DDL
\code{.unparsed}
<file> ::= HDF5 <file_name> { <file_super_block>opt <root_group> }
<file_name> ::= <identifier>
<file_super_block> ::= SUPER_BLOCK {
SUPERBLOCK_VERSION <int_value>
FREELIST_VERSION <int_value>
SYMBOLTABLE_VERSION <int_value>
OBJECTHEADER_VERSION <int_value>
OFFSET_SIZE <int_value>
LENGTH_SIZE <int_value>
BTREE_RANK <int_value>
BTREE_LEAF <int_value>
ISTORE_K <int_value>
<super_block_filespace>
USER_BLOCK {
USERBLOCK_SIZE <int_value>
}
}
<super_block_filespace> ::= FILE_SPACE_STRATEGY <super_block_strategy>
FREE_SPACE_PERSIST <boolean_value>
FREE_SPACE_SECTION_THRESHOLD <int_value>
FILE_SPACE_PAGE_SIZE <int_value>
<super_block_strategy> ::= H5F_FSPACE_STRATEGY_FSM_AGGR | H5F_FSPACE_STRATEGY_PAGE |
H5F_FSPACE_STRATEGY_AGGR | H5F_FSPACE_STRATEGY_NONE |
Unknown strategy
<root_group> ::= GROUP "/" {
<anon_named_datatype>*
<object_id>opt
<group_comment>opt
<group_attribute>*
<group_member>*
}
<datatype> ::= <atomic_type> | <compound_type> | <variable_length_type> | <array_type>
<anon_named_datatype> ::= DATATYPE <anon_named_type_name> {
<datatype>
}
<anon_named_type_name> ::= the assigned name for anonymous named type is
in the form of #oid, where oid is the object id
of the type
<atomic_type> ::= <integer> | <float> | <time> | <string> |
<bitfield> | <opaque> | <reference> | <enum>
<boolean_value> ::= FALSE | TRUE
<integer> ::= H5T_STD_I8BE | H5T_STD_I8LE |
H5T_STD_I16BE | H5T_STD_I16LE |
H5T_STD_I32BE | H5T_STD_I32LE |
H5T_STD_I64BE | H5T_STD_I64LE |
H5T_STD_U8BE | H5T_STD_U8LE |
H5T_STD_U16BE | H5T_STD_U16LE |
H5T_STD_U32BE | H5T_STD_U32LE |
H5T_STD_U64BE | H5T_STD_U64LE |
H5T_NATIVE_CHAR | H5T_NATIVE_UCHAR |
H5T_NATIVE_SHORT | H5T_NATIVE_USHORT |
H5T_NATIVE_INT | H5T_NATIVE_UINT |
H5T_NATIVE_LONG | H5T_NATIVE_ULONG |
H5T_NATIVE_LLONG | H5T_NATIVE_ULLONG
<float> ::= H5T_IEEE_F32BE | H5T_IEEE_F32LE |
H5T_IEEE_F64BE | H5T_IEEE_F64LE |
H5T_NATIVE_FLOAT | H5T_NATIVE_DOUBLE |
H5T_NATIVE_LDOUBLE
<time> ::= H5T_TIME: not yet implemented
<string> ::= H5T_STRING {
STRSIZE <strsize>;
STRPAD <strpad>;
CSET <cset>;
CTYPE <ctype>;
}
<strsize> ::= <int_value>
<strpad> ::= H5T_STR_NULLTERM | H5T_STR_NULLPAD | H5T_STR_SPACEPAD
<cset> ::= H5T_CSET_ASCII | H5T_CSET_UTF8
<ctype> ::= H5T_C_S1 | H5T_FORTRAN_S1
<bitfield> ::= H5T_STD_B8BE | H5T_STD_B8LE |
H5T_STD_B16BE | H5T_STD_B16LE |
H5T_STD_B32BE | H5T_STD_B32LE |
H5T_STD_B64BE | H5T_STD_B64LE
<opaque> ::= H5T_OPAQUE {
OPAQUE_TAG <identifier>;
OPAQUE_SIZE <int_value>;opt
}
<reference> ::= H5T_REFERENCE { <ref_type> }
<ref_type> ::= H5T_STD_REF_OBJECT | H5T_STD_REF_DSETREG | H5T_STD_REF | UNDEFINED
<compound_type> ::= H5T_COMPOUND {
<member_type_def>+
}
<member_type_def> ::= <datatype> <field_name>;
<field_name> ::= <identifier>
<variable_length_type> ::= H5T_VLEN { <datatype> }
<array_type> ::= H5T_ARRAY { <dim_sizes> <datatype> }
<dim_sizes> ::= '['<dimsize>']' | '['<dimsize>']'<dim_sizes>
<dimsize> ::= <int_value>
<attribute> ::= ATTRIBUTE <attr_name> {
<dataset_type>
<dataset_space>
<data>opt
}
<attr_name> ::= <identifier>
<dataset_type> ::= DATATYPE <path_name> | <datatype>
<enum> ::= H5T_ENUM {
<enum_base_type> <enum_def>+
}
<enum_base_type> ::= <integer>
// Currently enums can only hold integer type data, but they may be expanded
// in the future to hold any datatype
<enum_def> ::= <enum_symbol> <enum_val>;
<enum_symbol> ::= <identifier>
<enum_val> ::= <int_value>
<path_name> ::= <path_part>+
<path_part> ::= /<identifier>
<dataspace> ::= <scalar_space> | <simple_space> | <complex_space> | <null_space>
<null_space> ::= NULL
<scalar_space> ::= SCALAR
<simple_space> ::= SIMPLE { <current_dims> / <max_dims> }
<complex_space> ::= COMPLEX { <complex_space_definition> }
<dataset_space> ::= DATASPACE <path_name> | <dataspace>
<current_dims> ::= <dims>
<max_dims> ::= '(' <max_dim_list> ')'
<max_dim_list> ::= <max_dim> | <max_dim>, <max_dim_list>
<max_dim> ::= <int_value> | H5S_UNLIMITED
<data> ::= <subset> | <data_values>
<data_values> ::= DATA {
<scalar_space_data> | <simple_space_data>
}
<scalar_space_data> ::= <any_element>
<any_element> ::= <atomic_element> | <compound_element> |
<variable_length_element> | <array_element>
<any_data_seq> ::= <any_element> | <any_element>, <any_data_seq>
<atomic_element> :: = <integer_data> | <float_data> | <time_data> |
<string_data> | <bitfield_data> | <opaque_data> |
<enum_data> | <reference_data>
<subset> ::= SUBSET {
<start>;
<stride>;
<count>;
<block>;
DATA {
<simple_space_data>
}
}
<start> ::= START (<coor_list>)
<stride> ::= STRIDE (<pos_list>)
<count> ::= COUNT (<max_dim_list>)
<block> ::= BLOCK (<max_dim_list>)
<coor_list> ::= <coor_data>, <coor_list> | <coor_data>
<coor_data> ::= <integer_data> | H5S_UNLIMITED
<integer_data> ::= <int_value>
<float_data> ::= a floating point number
<time_data> ::= DATA{ not yet implemented.}
<string_data> ::= a string
// A string is enclosed in double quotes.
// If a string is displayed on more than one line, string concatenate
// operator '//'is used.
<bitfield_data> ::= <hex_value>
<opaque_data> ::= <hex_value>:<hex_value> | <hex_value>
<enum_data> ::= <enum_symbol>
<reference_data> ::= <object_ref_data> | <data_region_data> | <attribute_data> | NULL
<object_ref_data> ::= <object_type> <object_num>
<object_type> ::= DATASET | GROUP | DATATYPE
<object_id> ::= OBJECTID { <object_num> }
<object_num> ::= <int_value>:<int_value> | <int_value>
<attribute_data> ::= ATTRIBUTE <attr_name>
<data_region_data> ::= DATASET <dataset_name> {
<data_region_type>opt <data_region_data_list>
<dataset_type>opt <dataset_space>opt
<data>opt
}
<data_region_type> ::= REGION_TYPE <data_region_data_type>
<data_region_data_type> ::= POINT | BLOCK
<data_region_data_list> ::= <data_region_data_info>, <data_region_data_list> |
<data_region_data_info>
<data_region_data_info> ::= <region_info> | <point_info>
<region_info> ::= (<lower_region_vals>)-(<upper_region_vals>)
<lower_region_vals> ::= <lower_bound>, <lower_region_vals> | <lower_bound>
<upper_region_vals> ::= <upper_bound>, <upper_region_vals> | <upper_bound>
<lower_bound> ::= <int_value>
<upper_bound> ::= <int_value>
<point_info> ::= (<point_vals>)
<point_vals> ::= <int_value> | <int_value>, <point_vals>
<compound_element> ::= { <any_data_seq> }
<atomic_simple_data> :: = <atomic_element>, <atomic_simple_data> |
<atomic_element>
<simple_space_data> :: = <any_data_seq>
<variable_length_element> ::= ( <any_data_seq> )
<array_element> ::= '[' <any_data_seq> ']'
<named_datatype> ::= DATATYPE <type_name> { <datatype> }
<type_name> ::= <identifier>
<hardlink> ::= HARDLINK <path_name>
<group> ::= GROUP <group_name> { <hardlink> | <group_info> }
<group_comment> ::= COMMENT <string_data>
<group_name> ::= <identifier>
<group_info> ::= <object_id>opt <group_comment>opt <group_attribute>*
<group_member>*
<group_attribute> ::= <attribute>
<group_member> ::= <named_datatype> | <group> | <dataset> |
<softlink> | <external_link>
<dataset> ::= DATASET <dataset_name> { <hardlink> | <dataset_info> }
<dataset_info> ::= <dataset_type>
<dataset_space>
<dcpl_info>opt
<dataset_attribute>* <object_id>opt
<data>opt
// Tokens above can be in any order as long as <data> is
// after <dataset_type> and <dataset_space>.
<dcpl_info> ::= <storagelayout>
<compression_filters>
<fillvalue>
<allocationtime>
<dataset_name> ::= <identifier>
<storagelayout> :: = STORAGE_LAYOUT {
<contiguous_layout> | <chunked_layout> |
<compact_layout> | <virtual_layout>
}
<contiguous_layout> ::= CONTIGUOUS
<internal_layout> | <external_layout>
<chunked_layout> ::= CHUNKED <dims>
<filter_ratio>opt
<compact_layout> ::= COMPACT
<size>
<internal_layout> ::= <size>
<offset>
<external_layout> ::= EXTERNAL {
<external_file>+
}
<virtual_layout> ::= <vmaps>*opt
<vmaps> ::= MAPPING <int_value> {
<virtual_map>
<source_map>
}
<virtual_map> ::= VIRTUAL {
<vmaps_selection>
}
<source_map> ::= SOURCE {
FILE <file_name>
DATASET <dataset_name>
<vmaps_selection>
}
<vmaps_selection> ::= <regular_hyperslab> | <irregular_hyperslab> |
<select_points> | <select_none> | <select_all>
<regular_hyperslab> ::= SELECTION REGULAR_HYPERSLAB {
<start>
<stride>
<count>
<block>
}
<irregular_hyperslab> ::= SELECTION IRREGULAR_HYPERSLAB {
<region_info>+
}
<select_points> ::= SELECTION POINT {
(<coor_list>)+
}
<select_none> ::= SELECTION NONE
<select_all> ::= SELECTION ALL
<dims> ::= (<dims_values>)
<dims_values> ::= <int_value> | <int_value>, <dims_values>
<external_file> ::= FILENAME <file_name> <size> <offset>
<offset> ::= OFFSET <int_value>
<size> ::= SIZE <int_value>
<filter_ratio> ::= <size> | <compressionratio>
<compressionratio> :: = <size> (<float_data>:1 COMPRESSION)
<compression_filters> :: = FILTERS {
<filter_type>+ | NONE
}
<filter_type> :: = <filter_deflate> | <filter_shuffle> |
<filter_flecther> | <filter_szip> |
<filter_nbit> | <filter_scaleoffset> |
<filter_default>
<filter_default> :: = <filter_user> {
FILTER_ID <int_value>
<filter_comment>opt
<filter_params>opt
}
<filter_user> :: = USER_DEFINED_FILTER
<filter_deflate> :: = COMPRESSION DEFLATE { LEVEL <int_value> }
<filter_shuffle> :: = PREPROCESSING SHUFFLE
<filter_flecther> :: = CHECKSUM FLETCHER32
<filter_szip> :: = COMPRESSION SZIP {
PIXELS_PER_BLOCK <int_value>
<filter_szip_mode>opt
<filter_szip_coding>opt
<filter_szip_order>opt
<filter_szip_header>opt
}
<filter_szip_mode> :: = MODE HARDWARE | K13
<filter_szip_coding> :: = CODING ENTROPY | NEAREST NEIGHBOUR
<filter_szip_order> :: = BYTE_ORDER LSB | MSB
<filter_szip_header> :: = HEADER RAW
<filter_nbit> :: = CHECKSUM NBIT
<filter_scaleoffset> :: = COMPRESSION SCALEOFFSET { MIN BITS <int_value> }
<filter_comment> :: = COMMENT <identifier>
<filter_params> :: = PARAMS { <int_value>* }
<fillvalue> ::= FILLVALUE {
FILL_TIME H5D_FILL_TIME_ALLOC | H5D_FILL_TIME_NEVER | H5D_FILL_TIME_IFSET
VALUE H5D_FILL_VALUE_UNDEFINED | H5D_FILL_VALUE_DEFAULT | <any_element>
}
<allocationtime> ::= ALLOCATION_TIME {
H5D_ALLOC_TIME_EARLY | H5D_ALLOC_TIME_INCR |
H5D_ALLOC_TIME_LATE
}
<dataset_attribute> ::= <attribute>
<softlink> ::= SOFTLINK <softlink_name> {
LINKTARGET <target>
}
<softlink_name> ::= <identifier>
<target> ::= <identifier>
<external_link> ::= EXTERNAL_LINK <external_link_name> {
TARGETFILE <targetfile>
TARGETPATH <targetpath> <targetobj>opt
}
<external_link_name> ::= <identifier>
<user_defined_link> ::= USERDEFINED_LINK <external_link_name> {
LINKCLASS <user_link_type>
}
<user_link_type> ::= <int_value>
<targetfile> ::= <file_name>
<targetpath> ::= <identifier>
<targetobj> ::= <named_datatype> | <group> | <dataset>
<identifier> ::= "a string"
// character '/' should be used with care.
<pos_list> ::= <pos_int>, <pos_list> | <pos_int>
<int_value> ::= 0 | <pos_int>
<pos_int> ::= [1-9][0-9]*
<hex_value> ::= 0x[0-F][0-F]+ | [0-F][0-F]+
\endcode
\section example110 An Example of an HDF5 File in DDL
\code{.unparsed}
HDF5 "example.h5" {
GROUP "/" {
ATTRIBUTE "attr1" {
DATATYPE H5T_STRING {
STRSIZE 17;
STRPAD H5T_STR_NULLTERM;
CSET H5T_CSET_ASCII;
CTYPE H5T_C_S1;
}
DATASPACE SCALAR
DATA {
"string attribute"
}
}
DATASET "dset1" {
DATATYPE H5T_STD_I32BE
DATASPACE SIMPLE { ( 10, 10 ) / ( 10, 10 ) }
DATA {
0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
0, 1, 2, 3, 4, 5, 6, 7, 8, 9
}
}
DATASET "dset2" {
DATATYPE H5T_COMPOUND {
H5T_STD_I32BE "a";
H5T_IEEE_F32BE "b";
H5T_IEEE_F64BE "c";
}
DATASPACE SIMPLE { ( 5 ) / ( 5 ) }
DATA {
{
1,
0.1,
0.01
},
{
2,
0.2,
0.02
},
{
3,
0.3,
0.03
},
{
4,
0.4,
0.04
},
{
5,
0.5,
0.05
}
}
}
GROUP "group1" {
COMMENT "This is a comment for group1";
DATASET "dset3" {
DATATYPE "/type1"
DATASPACE SIMPLE { ( 5 ) / ( 5 ) }
DATA {
{
[ 0, 1, 2, 3 ],
[ 0.1, 0.1, 0.1, 0.1, 0.1, 0.1,
0.2, 0.2, 0.2, 0.2, 0.2, 0.2,
0.3, 0.3, 0.3, 0.3, 0.3, 0.3,
0.4, 0.4, 0.4, 0.4, 0.4, 0.4,
0.5, 0.5, 0.5, 0.5, 0.5, 0.5 ]
},
{
[ 0, 1, 2, 3 ],
[ 0.1, 0.1, 0.1, 0.1, 0.1, 0.1,
0.2, 0.2, 0.2, 0.2, 0.2, 0.2,
0.3, 0.3, 0.3, 0.3, 0.3, 0.3,
0.4, 0.4, 0.4, 0.4, 0.4, 0.4,
0.5, 0.5, 0.5, 0.5, 0.5, 0.5 ]
},
{
[ 0, 1, 2, 3 ],
[ 0.1, 0.1, 0.1, 0.1, 0.1, 0.1,
0.2, 0.2, 0.2, 0.2, 0.2, 0.2,
0.3, 0.3, 0.3, 0.3, 0.3, 0.3,
0.4, 0.4, 0.4, 0.4, 0.4, 0.4,
0.5, 0.5, 0.5, 0.5, 0.5, 0.5 ]
},
{
[ 0, 1, 2, 3 ],
[ 0.1, 0.1, 0.1, 0.1, 0.1, 0.1,
0.2, 0.2, 0.2, 0.2, 0.2, 0.2,
0.3, 0.3, 0.3, 0.3, 0.3, 0.3,
0.4, 0.4, 0.4, 0.4, 0.4, 0.4,
0.5, 0.5, 0.5, 0.5, 0.5, 0.5 ]
},
{
[ 0, 1, 2, 3 ],
[ 0.1, 0.1, 0.1, 0.1, 0.1, 0.1,
0.2, 0.2, 0.2, 0.2, 0.2, 0.2,
0.3, 0.3, 0.3, 0.3, 0.3, 0.3,
0.4, 0.4, 0.4, 0.4, 0.4, 0.4,
0.5, 0.5, 0.5, 0.5, 0.5, 0.5 ]
}
}
}
}
DATASET "dset3" {
DATATYPE H5T_VLEN { H5T_STD_I32LE }
DATASPACE SIMPLE { ( 4 ) / ( 4 ) }
DATA {
(0), (10, 11), (20, 21, 22), (30, 31, 32, 33)
}
}
GROUP "group2" {
HARDLINK "/group1"
}
SOFTLINK "slink1" {
LINKTARGET "somevalue"
}
DATATYPE "type1" H5T_COMPOUND {
H5T_ARRAY { [4] H5T_STD_I32BE } "a";
H5T_ARRAY { [5][6] H5T_IEEE_F32BE } "b";
}
}
}
\endcode
*/

653
doxygen/dox/DDLBNF112.dox Normal file
View File

@ -0,0 +1,653 @@
/** \page DDLBNF112 DDL in BNF for HDF5 1.12 and above
\todo Revise this & break it up!
\section intro112 Introduction
This document contains the data description language (DDL) for an HDF5 file. The
description is in Backus-Naur Form (BNF).
\section expo112 Explanation of Symbols
This section contains a brief explanation of the symbols used in the DDL.
\code{.unparsed}
::= defined as
<tname> a token with the name tname
<a> | <b> one of <a> or <b>
<a>opt zero or one occurrence of <a>
<a>* zero or more occurrence of <a>
<a>+ one or more occurrence of <a>
[0-9] an element in the range between 0 and 9
'[' the token within the quotes (used for special characters)
TBD To Be Decided
\endcode
\section ddl112 The DDL
\code{.unparsed}
<file> ::= HDF5 <file_name> { <file_super_block>opt <root_group> }
<file_name> ::= <identifier>
<file_super_block> ::= SUPER_BLOCK {
SUPERBLOCK_VERSION <int_value>
FREELIST_VERSION <int_value>
SYMBOLTABLE_VERSION <int_value>
OBJECTHEADER_VERSION <int_value>
OFFSET_SIZE <int_value>
LENGTH_SIZE <int_value>
BTREE_RANK <int_value>
BTREE_LEAF <int_value>
ISTORE_K <int_value>
<super_block_filespace>
USER_BLOCK {
USERBLOCK_SIZE <int_value>
}
}
<super_block_filespace> ::= FILE_SPACE_STRATEGY <super_block_strategy>
FREE_SPACE_PERSIST <boolean_value>
FREE_SPACE_SECTION_THRESHOLD <int_value>
FILE_SPACE_PAGE_SIZE <int_value>
<super_block_strategy> ::= H5F_FSPACE_STRATEGY_FSM_AGGR | H5F_FSPACE_STRATEGY_PAGE |
H5F_FSPACE_STRATEGY_AGGR | H5F_FSPACE_STRATEGY_NONE |
Unknown strategy
<root_group> ::= GROUP "/" {
<anon_named_datatype>*
<object_id>opt
<group_comment>opt
<group_attribute>*
<group_member>*
}
<datatype> ::= <atomic_type> | <compound_type> | <variable_length_type> | <array_type>
<anon_named_datatype> ::= DATATYPE <anon_named_type_name> {
<datatype>
}
<anon_named_type_name> ::= the assigned name for anonymous named type is
in the form of #oid, where oid is the object id
of the type
<atomic_type> ::= <integer> | <float> | <time> | <string> |
<bitfield> | <opaque> | <reference> | <enum>
<boolean_value> ::= FALSE | TRUE
<integer> ::= H5T_STD_I8BE | H5T_STD_I8LE |
H5T_STD_I16BE | H5T_STD_I16LE |
H5T_STD_I32BE | H5T_STD_I32LE |
H5T_STD_I64BE | H5T_STD_I64LE |
H5T_STD_U8BE | H5T_STD_U8LE |
H5T_STD_U16BE | H5T_STD_U16LE |
H5T_STD_U32BE | H5T_STD_U32LE |
H5T_STD_U64BE | H5T_STD_U64LE |
H5T_NATIVE_CHAR | H5T_NATIVE_UCHAR |
H5T_NATIVE_SHORT | H5T_NATIVE_USHORT |
H5T_NATIVE_INT | H5T_NATIVE_UINT |
H5T_NATIVE_LONG | H5T_NATIVE_ULONG |
H5T_NATIVE_LLONG | H5T_NATIVE_ULLONG
<float> ::= H5T_IEEE_F32BE | H5T_IEEE_F32LE |
H5T_IEEE_F64BE | H5T_IEEE_F64LE |
H5T_NATIVE_FLOAT | H5T_NATIVE_DOUBLE |
H5T_NATIVE_LDOUBLE
<time> ::= H5T_TIME: not yet implemented
<string> ::= H5T_STRING {
STRSIZE <strsize>;
STRPAD <strpad>;
CSET <cset>;
CTYPE <ctype>;
}
<strsize> ::= <int_value>
<strpad> ::= H5T_STR_NULLTERM | H5T_STR_NULLPAD | H5T_STR_SPACEPAD
<cset> ::= H5T_CSET_ASCII | H5T_CSET_UTF8
<ctype> ::= H5T_C_S1 | H5T_FORTRAN_S1
<bitfield> ::= H5T_STD_B8BE | H5T_STD_B8LE |
H5T_STD_B16BE | H5T_STD_B16LE |
H5T_STD_B32BE | H5T_STD_B32LE |
H5T_STD_B64BE | H5T_STD_B64LE
<opaque> ::= H5T_OPAQUE {
OPAQUE_TAG <identifier>;
OPAQUE_SIZE <int_value>;opt
}
<reference> ::= H5T_REFERENCE { <ref_type> }
<ref_type> ::= H5T_STD_REF_OBJECT | H5T_STD_REF_DSETREG | H5T_STD_REF | UNDEFINED
<compound_type> ::= H5T_COMPOUND {
<member_type_def>+
}
<member_type_def> ::= <datatype> <field_name>;
<field_name> ::= <identifier>
<variable_length_type> ::= H5T_VLEN { <datatype> }
<array_type> ::= H5T_ARRAY { <dim_sizes> <datatype> }
<dim_sizes> ::= '['<dimsize>']' | '['<dimsize>']'<dim_sizes>
<dimsize> ::= <int_value>
<attribute> ::= ATTRIBUTE <attr_name> {
<dataset_type>
<dataset_space>
<data>opt
}
<attr_name> ::= <identifier>
<dataset_type> ::= DATATYPE <path_name> | <datatype>
<enum> ::= H5T_ENUM {
<enum_base_type> <enum_def>+
}
<enum_base_type> ::= <integer>
// Currently enums can only hold integer type data, but they may be expanded
// in the future to hold any datatype
<enum_def> ::= <enum_symbol> <enum_val>;
<enum_symbol> ::= <identifier>
<enum_val> ::= <int_value>
<path_name> ::= <path_part>+
<path_part> ::= /<identifier>
<dataspace> ::= <scalar_space> | <simple_space> | <complex_space> | <null_space>
<null_space> ::= NULL
<scalar_space> ::= SCALAR
<simple_space> ::= SIMPLE { <current_dims> / <max_dims> }
<complex_space> ::= COMPLEX { <complex_space_definition> }
<dataset_space> ::= DATASPACE <path_name> | <dataspace>
<current_dims> ::= <dims>
<max_dims> ::= '(' <max_dim_list> ')'
<max_dim_list> ::= <max_dim> | <max_dim>, <max_dim_list>
<max_dim> ::= <int_value> | H5S_UNLIMITED
<data> ::= <subset> | <data_values>
<data_values> ::= DATA {
<scalar_space_data> | <simple_space_data>
}
<scalar_space_data> ::= <any_element>
<any_element> ::= <atomic_element> | <compound_element> |
<variable_length_element> | <array_element>
<any_data_seq> ::= <any_element> | <any_element>, <any_data_seq>
<atomic_element> :: = <integer_data> | <float_data> | <time_data> |
<string_data> | <bitfield_data> | <opaque_data> |
<enum_data> | <reference_data>
<subset> ::= SUBSET {
<start>;
<stride>;
<count>;
<block>;
DATA {
<simple_space_data>
}
}
<start> ::= START (<coor_list>)
<stride> ::= STRIDE (<pos_list>)
<count> ::= COUNT (<max_dim_list>)
<block> ::= BLOCK (<max_dim_list>)
<coor_list> ::= <coor_data>, <coor_list> | <coor_data>
<coor_data> ::= <integer_data> | H5S_UNLIMITED
<integer_data> ::= <int_value>
<float_data> ::= a floating point number
<time_data> ::= DATA{ not yet implemented.}
<string_data> ::= a string
// A string is enclosed in double quotes.
// If a string is displayed on more than one line, string concatenate
// operator '//'is used.
<bitfield_data> ::= <hex_value>
<opaque_data> ::= <hex_value>:<hex_value> | <hex_value>
<enum_data> ::= <enum_symbol>
<reference_data> ::= <object_ref_data> | <data_region_data> | <attribute_data> | NULL
<object_ref_data> ::= <object_type> <object_ref>
<object_type> ::= ATTRIBUTE | DATASET | GROUP | DATATYPE
<object_ref> ::= <object_id>
<object_id> ::= <path_name> | OBJECTID { <object_num> }
<object_num> ::= <int_value>:<int_value> | <int_value>
<attribute_data> ::= ATTRIBUTE <attr_name>opt
<data>opt
<data_region_data> ::= DATASET <dataset_name> {
<data_region_type>opt <data_region_data_list>
<dataset_type>opt <dataset_space>opt
<data>opt
}
<data_region_type> ::= REGION_TYPE <data_region_data_type>
<data_region_data_type> ::= POINT | BLOCK
<data_region_data_list> ::= <data_region_data_info>, <data_region_data_list> |
<data_region_data_info>
<data_region_data_info> ::= <region_info> | <point_info>
<region_info> ::= (<lower_region_vals>)-(<upper_region_vals>)
<lower_region_vals> ::= <lower_bound>, <lower_region_vals> | <lower_bound>
<upper_region_vals> ::= <upper_bound>, <upper_region_vals> | <upper_bound>
<lower_bound> ::= <int_value>
<upper_bound> ::= <int_value>
<point_info> ::= (<point_vals>)
<point_vals> ::= <int_value> | <int_value>, <point_vals>
<compound_element> ::= { <any_data_seq> }
<atomic_simple_data> :: = <atomic_element>, <atomic_simple_data> |
<atomic_element>
<simple_space_data> :: = <any_data_seq>
<variable_length_element> ::= ( <any_data_seq> )
<array_element> ::= '[' <any_data_seq> ']'
<named_datatype> ::= DATATYPE <type_name> { <datatype> }
<type_name> ::= <identifier>
<hardlink> ::= HARDLINK <path_name>
<group> ::= GROUP <group_name> { <hardlink> | <group_info> }
<group_comment> ::= COMMENT <string_data>
<group_name> ::= <identifier>
<group_info> ::= <object_id>opt <group_comment>opt <group_attribute>*
<group_member>*
<group_attribute> ::= <attribute>
<group_member> ::= <named_datatype> | <group> | <dataset> |
<softlink> | <external_link>
<dataset> ::= DATASET <dataset_name> { <hardlink> | <dataset_info> }
<dataset_info> ::= <dataset_type>
<dataset_space>
<dcpl_info>opt
<dataset_attribute>* <object_id>opt
<data>opt
// Tokens above can be in any order as long as <data> is
// after <dataset_type> and <dataset_space>.
<dcpl_info> ::= <storagelayout>
<compression_filters>
<fillvalue>
<allocationtime>
<dataset_name> ::= <identifier>
<storagelayout> :: = STORAGE_LAYOUT {
<contiguous_layout> | <chunked_layout> |
<compact_layout> | <virtual_layout>
}
<contiguous_layout> ::= CONTIGUOUS
<internal_layout> | <external_layout>
<chunked_layout> ::= CHUNKED <dims>
<filter_ratio>opt
<compact_layout> ::= COMPACT
<size>
<internal_layout> ::= <size>
<offset>
<external_layout> ::= EXTERNAL {
<external_file>+
}
<virtual_layout> ::= <vmaps>*opt
<vmaps> ::= MAPPING <int_value> {
<virtual_map>
<source_map>
}
<virtual_map> ::= VIRTUAL {
<vmaps_selection>
}
<source_map> ::= SOURCE {
FILE <file_name>
DATASET <dataset_name>
<vmaps_selection>
}
<vmaps_selection> ::= <regular_hyperslab> | <irregular_hyperslab> |
<select_points> | <select_none> | <select_all>
<regular_hyperslab> ::= SELECTION REGULAR_HYPERSLAB {
<start>
<stride>
<count>
<block>
}
<irregular_hyperslab> ::= SELECTION IRREGULAR_HYPERSLAB {
<region_info>+
}
<select_points> ::= SELECTION POINT {
(<coor_list>)+
}
<select_none> ::= SELECTION NONE
<select_all> ::= SELECTION ALL
<dims> ::= (<dims_values>)
<dims_values> ::= <int_value> | <int_value>, <dims_values>
<external_file> ::= FILENAME <file_name> <size> <offset>
<offset> ::= OFFSET <int_value>
<size> ::= SIZE <int_value>
<filter_ratio> ::= <size> | <compressionratio>
<compressionratio> :: = <size> (<float_data>:1 COMPRESSION)
<compression_filters> :: = FILTERS {
<filter_type>+ | NONE
}
<filter_type> :: = <filter_deflate> | <filter_shuffle> |
<filter_flecther> | <filter_szip> |
<filter_nbit> | <filter_scaleoffset> |
<filter_default>
<filter_default> :: = <filter_user> {
FILTER_ID <int_value>
<filter_comment>opt
<filter_params>opt
}
<filter_user> :: = USER_DEFINED_FILTER
<filter_deflate> :: = COMPRESSION DEFLATE { LEVEL <int_value> }
<filter_shuffle> :: = PREPROCESSING SHUFFLE
<filter_flecther> :: = CHECKSUM FLETCHER32
<filter_szip> :: = COMPRESSION SZIP {
PIXELS_PER_BLOCK <int_value>
<filter_szip_mode>opt
<filter_szip_coding>opt
<filter_szip_order>opt
<filter_szip_header>opt
}
<filter_szip_mode> :: = MODE HARDWARE | K13
<filter_szip_coding> :: = CODING ENTROPY | NEAREST NEIGHBOUR
<filter_szip_order> :: = BYTE_ORDER LSB | MSB
<filter_szip_header> :: = HEADER RAW
<filter_nbit> :: = CHECKSUM NBIT
<filter_scaleoffset> :: = COMPRESSION SCALEOFFSET { MIN BITS <int_value> }
<filter_comment> :: = COMMENT <identifier>
<filter_params> :: = PARAMS { <int_value>* }
<fillvalue> ::= FILLVALUE {
FILL_TIME H5D_FILL_TIME_ALLOC | H5D_FILL_TIME_NEVER | H5D_FILL_TIME_IFSET
VALUE H5D_FILL_VALUE_UNDEFINED | H5D_FILL_VALUE_DEFAULT | <any_element>
}
<allocationtime> ::= ALLOCATION_TIME {
H5D_ALLOC_TIME_EARLY | H5D_ALLOC_TIME_INCR |
H5D_ALLOC_TIME_LATE
}
<dataset_attribute> ::= <attribute>
<softlink> ::= SOFTLINK <softlink_name> {
LINKTARGET <target>
}
<softlink_name> ::= <identifier>
<target> ::= <identifier>
<external_link> ::= EXTERNAL_LINK <external_link_name> {
TARGETFILE <targetfile>
TARGETPATH <targetpath> <targetobj>opt
}
<external_link_name> ::= <identifier>
<user_defined_link> ::= USERDEFINED_LINK <external_link_name> {
LINKCLASS <user_link_type>
}
<user_link_type> ::= <int_value>
<targetfile> ::= <file_name>
<targetpath> ::= <identifier>
<targetobj> ::= <named_datatype> | <group> | <dataset>
<identifier> ::= "a string"
// character '/' should be used with care.
<pos_list> ::= <pos_int>, <pos_list> | <pos_int>
<int_value> ::= 0 | <pos_int>
<pos_int> ::= [1-9][0-9]*
<hex_value> ::= 0x[0-F][0-F]+ | [0-F][0-F]+
\endcode
\section example112 An Example of an HDF5 File in DDL
\code{.unparsed}
HDF5 "example.h5" {
GROUP "/" {
ATTRIBUTE "attr1" {
DATATYPE H5T_STRING {
STRSIZE 17;
STRPAD H5T_STR_NULLTERM;
CSET H5T_CSET_ASCII;
CTYPE H5T_C_S1;
}
DATASPACE SCALAR
DATA {
"string attribute"
}
}
DATASET "dset1" {
DATATYPE H5T_STD_I32BE
DATASPACE SIMPLE { ( 10, 10 ) / ( 10, 10 ) }
DATA {
0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
0, 1, 2, 3, 4, 5, 6, 7, 8, 9
}
}
DATASET "dset2" {
DATATYPE H5T_COMPOUND {
H5T_STD_I32BE "a";
H5T_IEEE_F32BE "b";
H5T_IEEE_F64BE "c";
}
DATASPACE SIMPLE { ( 5 ) / ( 5 ) }
DATA {
{
1,
0.1,
0.01
},
{
2,
0.2,
0.02
},
{
3,
0.3,
0.03
},
{
4,
0.4,
0.04
},
{
5,
0.5,
0.05
}
}
}
GROUP "group1" {
COMMENT "This is a comment for group1";
DATASET "dset3" {
DATATYPE "/type1"
DATASPACE SIMPLE { ( 5 ) / ( 5 ) }
DATA {
{
[ 0, 1, 2, 3 ],
[ 0.1, 0.1, 0.1, 0.1, 0.1, 0.1,
0.2, 0.2, 0.2, 0.2, 0.2, 0.2,
0.3, 0.3, 0.3, 0.3, 0.3, 0.3,
0.4, 0.4, 0.4, 0.4, 0.4, 0.4,
0.5, 0.5, 0.5, 0.5, 0.5, 0.5 ]
},
{
[ 0, 1, 2, 3 ],
[ 0.1, 0.1, 0.1, 0.1, 0.1, 0.1,
0.2, 0.2, 0.2, 0.2, 0.2, 0.2,
0.3, 0.3, 0.3, 0.3, 0.3, 0.3,
0.4, 0.4, 0.4, 0.4, 0.4, 0.4,
0.5, 0.5, 0.5, 0.5, 0.5, 0.5 ]
},
{
[ 0, 1, 2, 3 ],
[ 0.1, 0.1, 0.1, 0.1, 0.1, 0.1,
0.2, 0.2, 0.2, 0.2, 0.2, 0.2,
0.3, 0.3, 0.3, 0.3, 0.3, 0.3,
0.4, 0.4, 0.4, 0.4, 0.4, 0.4,
0.5, 0.5, 0.5, 0.5, 0.5, 0.5 ]
},
{
[ 0, 1, 2, 3 ],
[ 0.1, 0.1, 0.1, 0.1, 0.1, 0.1,
0.2, 0.2, 0.2, 0.2, 0.2, 0.2,
0.3, 0.3, 0.3, 0.3, 0.3, 0.3,
0.4, 0.4, 0.4, 0.4, 0.4, 0.4,
0.5, 0.5, 0.5, 0.5, 0.5, 0.5 ]
},
{
[ 0, 1, 2, 3 ],
[ 0.1, 0.1, 0.1, 0.1, 0.1, 0.1,
0.2, 0.2, 0.2, 0.2, 0.2, 0.2,
0.3, 0.3, 0.3, 0.3, 0.3, 0.3,
0.4, 0.4, 0.4, 0.4, 0.4, 0.4,
0.5, 0.5, 0.5, 0.5, 0.5, 0.5 ]
}
}
}
}
DATASET "dset3" {
DATATYPE H5T_VLEN { H5T_STD_I32LE }
DATASPACE SIMPLE { ( 4 ) / ( 4 ) }
DATA {
(0), (10, 11), (20, 21, 22), (30, 31, 32, 33)
}
}
GROUP "group2" {
HARDLINK "/group1"
}
SOFTLINK "slink1" {
LINKTARGET "somevalue"
}
DATATYPE "type1" H5T_COMPOUND {
H5T_ARRAY { [4] H5T_STD_I32BE } "a";
H5T_ARRAY { [5][6] H5T_IEEE_F32BE } "b";
}
}
}
\endcode
*/

23
doxygen/dox/FileFormatSpec.dox Normal file
View File

@ -0,0 +1,23 @@
/** \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
*/

3
doxygen/dox/GettingStarted.dox Normal file
View File

@ -0,0 +1,3 @@
/** \page GettingStarted \Code{Hello, HDF5!}
*/

7
doxygen/dox/H5Fget_info.dox
View File

@ -6,9 +6,8 @@
* 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 "API Compatibility
* Macros in HDF5".
* 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
@ -37,8 +36,6 @@
* \li \Code{H5F_info_t_vers=2}: H5F_info2_t
* \li \Code{H5F_info_t_vers=1}: H5F_info1_t
*
* \todo Fix the reference.
*
* \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

5
doxygen/dox/H5Lget_info.dox
View File

@ -3,8 +3,8 @@
* \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 Compatibility
* Macros in HDF5. If the library and/or application is compiled for Release
* 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
@ -14,5 +14,4 @@
* \li Emulate Release 1.12: H5Lget_info2()
* \li Emulate Release 1.8 or 1.10 interface: H5Lget_info1()
*
* \todo Fix the reference.
*/

5
doxygen/dox/H5Lget_info_by_idx.dox
View File

@ -3,8 +3,8 @@
* \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 Compatibility
* Macros in HDF5. If the library and/or application is compiled for Release
* 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
@ -14,5 +14,4 @@
* \li Emulate Release 1.12: H5Lget_info_by_idx2()
* \li Emulate Release 1.8 or 1.10 interface: H5Lget_info_by_idx1()
*
* \todo Fix the reference.
*/

4
doxygen/dox/H5Literate.dox
View File

@ -4,7 +4,7 @@
* 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
* Compatibility Macros in HDF5. If the library and/or application is
* \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
@ -14,8 +14,6 @@
* \li Emulate Release 1.12: H5Literate2()
* \li Emulate Release 1.8 or 1.10 interface: H5Literate1()
*
* \todo Fix the reference.
*
* \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.

4
doxygen/dox/H5Literate_by_name.dox
View File

@ -4,7 +4,7 @@
* 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 Compatibility Macros in HDF5. If the library and/or application is
* 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().
@ -15,8 +15,6 @@
* \li Emulate Release 1.12: H5Literate_by_name2()
* \li Emulate Release 1.8 or 1.10 interface: H5Literate_by_name1()
*
* \todo Fix the reference.
*
* \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.

4
doxygen/dox/H5Lvisit.dox
View File

@ -4,7 +4,7 @@
* 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
* Compatibility Macros in HDF5. If the library and/or application is
* \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
@ -14,8 +14,6 @@
* \li Emulate Release 1.12: H5Lvisit2()
* \li Emulate Release 1.8 or 1.10 interface: H5Lvisit1()
*
* \todo Fix the reference.
*
* \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.

4
doxygen/dox/H5Lvisit_by_name.dox
View File

@ -4,7 +4,7 @@
* 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
* Compatibility Macros in HDF5. If the library and/or application is
* \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
@ -14,8 +14,6 @@
* \li Emulate Release 1.12: H5Lvisit_by_name2()
* \li Emulate Release 1.8 or 1.10 interface: H5Lvisit_by_name1()
*
* \todo Fix the reference.
*
* \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.

1020
doxygen/dox/MetadataCachingInHDF5.dox Normal file
View File

File diff suppressed because it is too large Load Diff

11
doxygen/dox/OtherSpecs.dox Normal file
View File

@ -0,0 +1,11 @@
/** \page IMG HDF5 Image and Palette Specification Version 1.2
\htmlinclude ImageSpec.html
*/
/** \page TBL HDF5 Table Specification Version 1.0
\htmlinclude TableSpec.html
*/

32
doxygen/dox/Overview.dox Normal file
View File

@ -0,0 +1,32 @@
/** \mainpage notitle
This is the documentation set for HDF5. You can
<a href="hdf5-doc.tgz">download</a> it as a tgz archive for offline reading.
This is the documention set for HDF5 in terms of specifications and software
developed and maintained by <a href="https://www.hdfgroup.org/">The HDF
Group</a>. It is impractical to document the entire HDF5 ecosystem in one place,
and you should also consult the documentation sets of the many outstanding
community projects.
For a first contact with HDF5, the best place is to have a look at the \link
GettingStarted getting started \endlink page that shows you how to write and
compile your first program with HDF5.
The \b main \b documentation is organized by documentation flavor. Most
technical documentation consists to varying degrees of information related to
<em>tasks</em>, <em>concepts</em>, or <em>reference</em> material. As its title
suggests, the \link RM Reference Manual \endlink is 100% reference material,
while the \link Cookbook \endlink is focused on tasks. The different guide-type
documents cover a mix of tasks, concepts, and reference, to help a certain
<em>audience</em> succeed.
Finally, do not miss the search engine (top right-hand corner)! If you are
looking for a specific function, it'll take you there directly. If unsure, it'll
give you an idea of what's on offer and a few promising leads.
\par ToDo List
There is plenty of <a href="./todo.html">unfinished business</a>.
*/

43
doxygen/dox/ReferenceManual.dox Normal file
View File

@ -0,0 +1,43 @@
/** \page RM Reference Manual
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
\cpp_c_api_note
*/

22
doxygen/dox/Specifications.dox Normal file
View File

@ -0,0 +1,22 @@
/** \page SPEC Specifications
\section DDL
\li \ref DDLBNF110 "DDL in BNF through HDF5 1.10"
\li \ref DDLBNF112 "DDL in BNF for HDF5 1.12 and above"
\section File Format
\li \ref FMT1 "HDF5 File Format Specification Version 1.0"
\li \ref FMT11 "HDF5 File Format Specification Version 1.1"
\li \ref FMT2 "HDF5 File Format Specification Version 2.0"
\li \ref FMT3 "HDF5 File Format Specification Version 3.0"
\section Other
\li \ref IMG "HDF5 Image and Palette Specification Version 1.2"
\li \ref TBL "HDF5 Table Specification Version 1.0"
\li <a href="https://support.hdfgroup.org/HDF5/doc/HL/H5DS_Spec.pdf">
HDF5 Dimension Scale Specification</a>
*/

20
doxygen/dox/TechnicalNotes.dox Normal file
View File

@ -0,0 +1,20 @@
/** \page TN Technical Notes
\li \link api-compat-macros API Compatibility Macros \endlink
\li \ref TNMDC "Metadata Caching in HDF5"
\li \ref MT "Thread Safe library"
\li \ref VFL "Virtual File Layer"
*/
/** \page MT HDF5 Thread Safe library
\htmlinclude ThreadSafeLibrary.html
*/
/** \page VFL HDF5 Virtual File Layer
\htmlinclude VFL.html
*/

1
doxygen/dox/api-compat-macros.dox
View File

@ -1,5 +1,4 @@
/** \page api-compat-macros API Compatibility Macros
\tableofcontents
\section audience Audience
The target audience for this document has existing applications that use the

44
doxygen/dox/mainpage.dox
View File

@ -1,44 +0,0 @@
/*! \mainpage HDF5 C-API Reference
*
* The HDF5 C-API provides applications with fine-grained control over all
* aspects HDF5 functionality. This functionality is 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 errors that occur within HDF5 (\ref H5E)
* \li \ref H5F "Files" — Management of HDF5 files (\ref H5F)
* \li \ref H5Z "Filters" — Configuration of filters that process data during I/O operation (\ref H5Z)
* \li \ref H5G "Groups" — Management of groups in HDF5 files (\ref H5G)
* \li \ref H5I "Identifiers" — Management of object identifiers and object names (\ref H5I)
* \li \ref H5 "Library" — General purpose library functions (\ref H5)
* \li \ref H5L "Links" — Management of links in HDF5 groups (\ref H5L)
* \li \ref H5O "Objects" — Management of objects in HDF5 files (\ref H5O)
* \li \ref H5PL "Plugins" — Programmatic control over dynamically loaded plugins (\ref H5PL)
* \li \ref H5P "Property Lists" — Management of property lists to control HDF5 library behavior (\ref H5P)
* \li \ref H5R "References" — Management of references to specific objects and data regions in an HDF5 file (\ref H5R)
* \li \ref H5VL "Virtual Object Layer" — Management of the Virtual Object Layer (\ref H5VL)
*
* Here are a few simple rules to follow:
*
* \li \Bold{Handle discipline:} If you acquire a handle (by creation or coopy), \Emph{you own it!} (..., i.e., you have to close it.)
* \li \Bold{Dynamic memory allocation:} ...
* \li \Bold{Use of locations:} Identifier + name combo
*
* \attention \Bold{C++ Developers using HDF5 C-API functions beware:}\n
* If a C routine that takes a function pointer as an argument is called from
* within C++ code, the C routine should be returned from normally.
* Examples of this kind of routine include callbacks such as H5Pset_elink_cb()
* and H5Pset_type_conv_cb() and functions such as H5Tconvert() and H5Ewalk2().\n
* Exiting the routine in its normal fashion allows the HDF5 C library to clean
* up its work properly. In other words, if the C++ application jumps out of
* the routine back to the C++ \c catch statement, the library is not given the
* opportunity to close any temporary data structures that were set up when the
* routine was called. The C++ application should save some state as the
* routine is started so that any problem that occurs might be diagnosed.
*
* \todo Fix the search form for server deployments.
* \todo Make it mobile-friendly
*
*/

82
doxygen/dox/maybe_metadata_reads.dox Normal file
View File

@ -0,0 +1,82 @@
/**
* \page maybe_metadata_reads Functions with No Access Property List Parameter that May Generate Metadata Reads
*
* \ingroup GACPL
*
* Currently there are several operations in HDF5 that can issue metadata reads
* from the metadata cache, but that take no property list. It is therefore not
* possible to set a collective requirement individually for those operations. The
* only solution with the HDF5 1.10.0 release is to set the collective requirement
* globally on H5Fopen() or H5Fcreate() for all metadata operations to be
* collective.
*
* The following is a list of those functions in the HDF5 library. This list is
* integral to the discussion in the H5Pset_all_coll_metadata_ops() entry:
*
* <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()
* H5Funmount()
*
* H5Iget_name()
*
* H5Tget_create_plist()
* H5Tclose()
*
* H5Zunregister()
* </pre>
*
* In addition, \b most deprecated functions fall into this category.
*
* The HDF Group may address the above limitation in a future major release, but
* no decision has been made at this time. Such a change might, for example,
* include adding new versions of some or all the above functions with an extra
* property list parameter to allow an individual setting for the collective
* calling requirement.
*
* \sa_metadata_ops
*/

BIN
doxygen/examples/FF-IH_FileGroup.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.3 KiB

BIN
doxygen/examples/FF-IH_FileObject.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.1 KiB

BIN
doxygen/examples/FileFormatSpecChunkDiagram.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 29 KiB

4050
doxygen/examples/H5.format.1.0.html Normal file
View File

File diff suppressed because it is too large Load Diff

6439
doxygen/examples/H5.format.1.1.html Normal file
View File

File diff suppressed because it is too large Load Diff

14902
doxygen/examples/H5.format.2.0.html Normal file
View File

File diff suppressed because it is too large Load Diff

20400
doxygen/examples/H5.format.html Normal file
View File

File diff suppressed because it is too large Load Diff

145
doxygen/examples/H5A_examples.c Normal file
View File

@ -0,0 +1,145 @@
/* -*- c-file-style: "stroustrup" -*- */
#include "hdf5.h"
#include <stdio.h>
#include <stdlib.h>
int
main(void)
{
int ret_val = EXIT_SUCCESS;
//! <!-- [create] -->
{
__label__ fail_acpl, fail_attr, fail_file;
hid_t file, acpl, fspace, attr;
unsigned mode = H5F_ACC_TRUNC;
char file_name[] = "f1.h5";
// attribute names can be arbitrary Unicode strings
char attr_name[] = "Χαρακτηριστικό";
if ((file = H5Fcreate(file_name, mode, H5P_DEFAULT, H5P_DEFAULT)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_file;
}
if ((acpl = H5Pcreate(H5P_ATTRIBUTE_CREATE)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_acpl;
}
// use UTF-8 encoding for the attribute name
if (H5Pset_char_encoding(acpl, H5T_CSET_UTF8) < 0) {
ret_val = EXIT_FAILURE;
goto fail_fspace;
}
// create a scalar (singleton) attribute
if ((fspace = H5Screate(H5S_SCALAR)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_fspace;
}
// create an attribute on the root group
if ((attr = H5Acreate2(file, attr_name, H5T_STD_I32LE, fspace, acpl, H5P_DEFAULT)) ==
H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_attr;
}
H5Aclose(attr);
fail_attr:
H5Sclose(fspace);
fail_fspace:
H5Pclose(acpl);
fail_acpl:
H5Fclose(file);
fail_file:;
}
//! <!-- [create] -->
//! <!-- [read] -->
{
__label__ fail_attr, fail_file;
hid_t file, attr;
unsigned mode = H5F_ACC_RDONLY;
char file_name[] = "f1.h5";
char attr_name[] = "Χαρακτηριστικό";
int value;
if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_file;
}
if ((attr = H5Aopen(file, attr_name, H5P_DEFAULT)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_attr;
}
// read the attribute value
if (H5Aread(attr, H5T_NATIVE_INT, &value) < 0)
ret_val = EXIT_FAILURE;
// do something w/ the attribute value
H5Aclose(attr);
fail_attr:
H5Fclose(file);
fail_file:;
}
//! <!-- [read] -->
//! <!-- [update] -->
{
__label__ fail_attr, fail_file;
hid_t file, attr;
unsigned mode = H5F_ACC_RDWR;
char file_name[] = "f1.h5";
char attr_name[] = "Χαρακτηριστικό";
int value = 1234;
if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_file;
}
if ((attr = H5Aopen(file, attr_name, H5P_DEFAULT)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_attr;
}
// update the attribute value
if (H5Awrite(attr, H5T_NATIVE_INT, &value) < 0)
ret_val = EXIT_FAILURE;
H5Aclose(attr);
fail_attr:
H5Fclose(file);
fail_file:;
}
//! <!-- [update] -->
//! <!-- [delete] -->
{
__label__ fail_attr, fail_file;
hid_t file;
unsigned mode = H5F_ACC_RDWR;
char file_name[] = "f1.h5";
char attr_name[] = "Χαρακτηριστικό";
if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_file;
}
// delete the attribute
if (H5Adelete(file, attr_name) < 0) {
ret_val = EXIT_FAILURE;
goto fail_attr;
}
fail_attr:
H5Fclose(file);
fail_file:;
}
//! <!-- [delete] -->
return ret_val;
}

173
doxygen/examples/H5D_examples.c Normal file
View File

@ -0,0 +1,173 @@
/* -*- c-file-style: "stroustrup" -*- */
#include "hdf5.h"
#include <stdio.h>
#include <stdlib.h>
int
main(void)
{
int ret_val = EXIT_SUCCESS;
//! <!-- [create] -->
{
__label__ fail_lcpl, fail_dset, fail_file;
hid_t file, lcpl, fspace, dset;
unsigned mode = H5F_ACC_TRUNC;
char file_name[] = "d1.h5";
// link names can be arbitrary Unicode strings
char dset_name[] = "σύνολο/δεδομένων";
if ((file = H5Fcreate(file_name, mode, 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;
}
// use UTF-8 encoding for link names
if (H5Pset_char_encoding(lcpl, H5T_CSET_UTF8) < 0) {
ret_val = EXIT_FAILURE;
goto fail_fspace;
}
// create intermediate groups as needed
if (H5Pset_create_intermediate_group(lcpl, 1) < 0) {
ret_val = EXIT_FAILURE;
goto fail_fspace;
}
// create a 1D dataspace
if ((fspace = H5Screate_simple(1, (hsize_t[]){10}, NULL)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_fspace;
}
// create a 32-bit integer dataset
if ((dset = H5Dcreate2(file, dset_name, H5T_STD_I32LE, fspace, lcpl, H5P_DEFAULT, H5P_DEFAULT)) ==
H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_dset;
}
H5Dclose(dset);
fail_dset:
H5Sclose(fspace);
fail_fspace:
H5Pclose(lcpl);
fail_lcpl:
H5Fclose(file);
fail_file:;
}
//! <!-- [create] -->
//! <!-- [read] -->
{
__label__ fail_dset, fail_file;
hid_t file, dset;
unsigned mode = H5F_ACC_RDONLY;
char file_name[] = "d1.h5";
// assume a priori knowledge of dataset name and size
char dset_name[] = "σύνολο/δεδομένων";
int elts[10];
if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_file;
}
if ((dset = H5Dopen2(file, dset_name, H5P_DEFAULT)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_dset;
}
// read all dataset elements
if (H5Dread(dset, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, elts) < 0)
ret_val = EXIT_FAILURE;
// do something w/ the dataset elements
H5Dclose(dset);
fail_dset:
H5Fclose(file);
fail_file:;
}
//! <!-- [read] -->
//! <!-- [update] -->
{
__label__ fail_update, fail_fspace, fail_dset, fail_file;
hid_t file, dset, fspace;
unsigned mode = H5F_ACC_RDWR;
char file_name[] = "d1.h5";
char dset_name[] = "σύνολο/δεδομένων";
int new_elts[6][2] = {{-1, 1}, {-2, 2}, {-3, 3}, {-4, 4}, {-5, 5}, {-6, 6}};
if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_file;
}
if ((dset = H5Dopen2(file, dset_name, H5P_DEFAULT)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_dset;
}
// get the dataset's dataspace
if ((fspace = H5Dget_space(dset)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_fspace;
}
// select the first 5 elements in odd positions
if (H5Sselect_hyperslab(fspace, H5S_SELECT_SET, (hsize_t[]){1}, (hsize_t[]){2}, (hsize_t[]){5},
NULL) < 0) {
ret_val = EXIT_FAILURE;
goto fail_update;
}
// (implicitly) select and write the first 5 elements of the second column of NEW_ELTS
if (H5Dwrite(dset, H5T_NATIVE_INT, H5S_ALL, fspace, H5P_DEFAULT, new_elts) < 0)
ret_val = EXIT_FAILURE;
fail_update:
H5Sclose(fspace);
fail_fspace:
H5Dclose(dset);
fail_dset:
H5Fclose(file);
fail_file:;
}
//! <!-- [update] -->
//! <!-- [delete] -->
{
__label__ fail_delete, fail_file;
hid_t file;
unsigned mode = H5F_ACC_RDWR;
char file_name[] = "d1.h5";
char group_name[] = "σύνολο";
char dset_name[] = "σύνολο/δεδομένων";
if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_file;
}
// delete (unlink) the dataset
if (H5Ldelete(file, dset_name, H5P_DEFAULT) < 0) {
ret_val = EXIT_FAILURE;
goto fail_delete;
}
// the previous call deletes (unlinks) only the dataset
if (H5Ldelete(file, group_name, H5P_DEFAULT) < 0) {
ret_val = EXIT_FAILURE;
goto fail_delete;
}
fail_delete:
H5Fclose(file);
fail_file:;
}
//! <!-- [delete] -->
return ret_val;
}

187
doxygen/examples/H5F_examples.c Normal file
View File

@ -0,0 +1,187 @@
/* -*- c-file-style: "stroustrup" -*- */
#include "hdf5.h"
#include <stdio.h>
#include <stdlib.h>
int
main(void)
{
int ret_val = EXIT_SUCCESS;
//! <!-- [life_cycle] -->
{
__label__ fail_fapl, fail_fcpl, fail_file;
hid_t fcpl, fapl, file;
if ((fcpl = H5Pcreate(H5P_FILE_CREATE)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_fcpl;
}
else {
// adjust the file creation properties
}
if ((fapl = H5Pcreate(H5P_FILE_ACCESS)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_fapl;
}
else {
// adjust the file access properties
}
unsigned mode = H5F_ACC_EXCL;
char name[] = "f1.h5";
if ((file = H5Fcreate(name, mode, fcpl, fapl)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_file;
}
// do something useful with FILE
H5Fclose(file);
fail_file:
H5Pclose(fapl);
fail_fapl:
H5Pclose(fcpl);
fail_fcpl:;
}
//! <!-- [life_cycle] -->
//! <!-- [life_cycle_w_open] -->
{
__label__ fail_fapl, fail_file;
hid_t fapl, file;
if ((fapl = H5Pcreate(H5P_FILE_ACCESS)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_fapl;
}
else {
// adjust the file access properties
}
unsigned mode = H5F_ACC_RDWR;
char name[] = "f1.h5";
if ((file = H5Fopen(name, mode, fapl)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_file;
}
// do something useful with FILE
H5Fclose(file);
fail_file:
H5Pclose(fapl);
fail_fapl:;
}
//! <!-- [life_cycle_w_open] -->
//! <!-- [minimal] -->
{
unsigned mode = H5F_ACC_TRUNC;
char name[] = "f11.h5";
hid_t file = H5Fcreate(name, mode, H5P_DEFAULT, H5P_DEFAULT);
if (file != H5I_INVALID_HID)
H5Fclose(file);
else
ret_val = EXIT_FAILURE;
}
//! <!-- [minimal] -->
//! <!-- [open] -->
{
unsigned mode = H5F_ACC_RDONLY;
char name[] = "f11.h5";
hid_t file = H5Fopen(name, mode, H5P_DEFAULT);
if (file != H5I_INVALID_HID)
H5Fclose(file);
else
ret_val = EXIT_FAILURE;
}
//! <!-- [open] -->
//! <!-- [flush] -->
{
unsigned mode = H5F_ACC_RDWR;
char name[] = "f11.h5";
hid_t file = H5Fopen(name, mode, H5P_DEFAULT);
if (file != H5I_INVALID_HID) {
int step;
for (step = 0; step < 1000; ++step) {
// do important work & flush every 20 steps
if (step % 20 == 0) {
if (H5Fflush(file, H5F_SCOPE_LOCAL) < 0) {
perror("H5Fflush failed.");
ret_val = EXIT_FAILURE;
break;
}
}
}
if (H5Fclose(file) < 0)
perror("H5Fclose failed.");
}
else
ret_val = EXIT_FAILURE;
}
//! <!-- [flush] -->
//! <!-- [libver_bounds] -->
{
unsigned mode = H5F_ACC_RDWR;
char name[] = "f11.h5";
hid_t file = H5Fopen(name, mode, H5P_DEFAULT);
if (file != H5I_INVALID_HID) {
if (H5Fset_libver_bounds(file, H5F_LIBVER_EARLIEST, H5F_LIBVER_V18) >= 0) {
// object creation will not exceed HDF5 version 1.8.x
}
else
perror("H5Fset_libver_bounds failed.");
if (H5Fclose(file) < 0)
perror("H5Fclose failed.");
}
else
ret_val = EXIT_FAILURE;
}
//! <!-- [libver_bounds] -->
//! <!-- [mount] -->
{
hid_t file = H5Fopen("f11.h5", H5F_ACC_RDWR, H5P_DEFAULT);
if (file != H5I_INVALID_HID) {
hid_t group, child;
if ((group = H5Gcreate1(file, "mount_point", H5P_DEFAULT)) != H5I_INVALID_HID) {
if ((child = H5Fopen("f1.h5", H5F_ACC_RDONLY, H5P_DEFAULT)) != H5I_INVALID_HID) {
if (H5Fmount(group, ".", child, H5P_DEFAULT) >= 0) {
// do something useful w/ the mounted file
}
else {
ret_val = EXIT_FAILURE;
perror("H5Fmount failed.");
}
H5Fclose(child);
}
H5Gclose(group);
}
H5Fclose(file);
}
else
ret_val = EXIT_FAILURE;
}
//! <!-- [mount] -->
return ret_val;
}

22
doxygen/examples/H5Pget_metadata_read_attempts.1.c Normal file
View File

@ -0,0 +1,22 @@
/* Get a copy of file access property list */
fapl = H5Pcreate(H5P_FILE_ACCESS);
/* Retrieve the # of read attempts from the file access property list */
H5Pget_metadata_read_attempts(fapl, &attempts);
/*
* The value returned in "attempts" will be 1 (default for non-SWMR access).
*/
/* Set the # of read attempts to 20 */
H5Pset_metadata_read_attempts(fapl, 20);
/* Retrieve the # of read attempts from the file access property list */
H5Pget_metadata_read_attempts(fapl, &attempts);
/*
* The value returned in "attempts" will be 20 as set.
*/
/* Close the property list */
H5Pclose(fapl);

44
doxygen/examples/H5Pget_metadata_read_attempts.2.c Normal file
View File

@ -0,0 +1,44 @@
/* Open the file with SWMR access and default file access property list */
fid = H5Fopen(FILE, (H5F_ACC_RDONLY | H5F_ACC_SWMR_READ), H5P_DEFAULT);
/* Get the file's file access roperty list */
file_fapl = H5Fget_access_plist(fid);
/* Retrieve the # of read attempts from the file's file access property list */
H5Pget_metadata_read_attempts(file_fapl, &attempts);
/*
* The value returned in "attempts" will be 100 (default for SWMR access).
*/
/* Close the property list */
H5Pclose(file_fapl);
/* Close the file */
H5Fclose(fid);
/* Create a copy of file access property list */
fapl = H5Pcreate(H5P_FILE_ACCESS);
/* Set the # of read attempts */
H5Pset_metadata_read_attempts(fapl, 20);
/* Open the file with SWMR access and the non-default file access property list */
fid = H5Fopen(FILE, (H5F_ACC_RDONLY | H5F_ACC_SWMR_READ), fapl);
/* Get the file's file access roperty list */
file_fapl = H5Fget_access_plist(fid);
/* Retrieve the # of read attempts from the file's file access property list */
H5Pget_metadata_read_attempts(file_fapl, &attempts);
/*
* The value returned in "attempts" will be 20.
*/
/* Close the property lists */
H5Pclose(file_fapl);
H5Pclose(fapl);
/* Close the file */
H5Fclose(fid);

44
doxygen/examples/H5Pget_metadata_read_attempts.3.c Normal file
View File

@ -0,0 +1,44 @@
/* Open the file with non-SWMR access and default file access property list */
fid = H5Fopen(FILE, H5F_ACC_RDONLY, H5P_DEFAULT);
/* Get the file's file access roperty list */
file_fapl = H5Fget_access_plist(fid);
/* Retrieve the # of read attempts from the file's file access property list */
H5Pget_metadata_read_attempts(file_fapl, &attempts);
/*
* The value returned in "attempts" will be 1 (default for non-SWMR access).
*/
/* Close the property list */
H5Pclose(file_fapl);
/* Close the file */
H5Fclose(fid);
/* Create a copy of file access property list */
fapl = H5Pcreate(H5P_FILE_ACCESS);
/* Set the # of read attempts */
H5Pset_metadata_read_attempts(fapl, 20);
/* Open the file with non-SWMR access and the non-default file access property list */
fid = H5Fopen(FILE, H5F_ACC_RDONLY, fapl);
/* Get the file's file access roperty list */
file_fapl = H5Fget_access_plist(fid);
/* Retrieve the # of read attempts from the file's file access property list */
H5Pget_metadata_read_attempts(file_fapl, &attempts);
/*
* The value returned in "attempts" will be 1 (default for non-SWMR access).
*/
/* Close the property lists */
H5Pclose(file_fapl);
H5Pclose(fapl);
/* Close the file */
H5Fclose(fid);

41
doxygen/examples/H5Pget_object_flush_cb.c Normal file
View File

@ -0,0 +1,41 @@
hid_t fapl_id;
unsigned counter;
H5F_object_flush_t *ret_cb;
unsigned * ret_counter;
/* Create a copy of the file access property list */
fapl_id = H5Pcreate(H5P_FILE_ACCESS);
/* Set up the object flush property values */
/* flush_cb: callback function to invoke when an object flushes (see below) */
/* counter: user data to pass along to the callback function */
H5Pset_object_flush_cb(fapl_id, flush_cb, &counter);
/* Open the file */
file_id = H5Fopen(FILE, H5F_ACC_RDWR, H5P_DEFAULT);
/* Get the file access property list for the file */
fapl = H5Fget_access_plist(file_id);
/* Retrieve the object flush property values for the file */
H5Pget_object_flush_cb(fapl, &ret_cb, &ret_counter);
/* ret_cb will point to flush_cb() */
/* ret_counter will point to counter */
/*
.
.
.
.
.
.
*/
/* The callback function for the object flush property */
static herr_t
flush_cb(hid_t obj_id, void *_udata)
{
unsigned *flush_ct = (unsigned *)_udata;
++(*flush_ct);
return 0;
}

59
doxygen/examples/H5Pset_metadata_read_attempts.c Normal file
View File

@ -0,0 +1,59 @@
//! [SWMR Access]
/* Create a copy of file access property list */
fapl = H5Pcreate(H5P_FILE_ACCESS);
/* Set the # of read attempts */
H5Pset_metadata_read_attempts(fapl, 20);
/* Open the file with SWMR access and the non-default file access property list */
fid = H5Fopen(FILE, (H5F_ACC_RDONLY | H5F_ACC_SWMR_READ), fapl);
/* Get the file's file access roperty list */
file_fapl = H5Fget_access_plist(fid);
/* Retrieve the # of read attempts from the file's file access property list */
H5Pget_metadata_read_attempts(file_fapl, &attempts);
/*
* The value returned in "attempts" will be 20.
* The library will use 20 as the number of read attempts
* when reading checksummed metadata in the file
*/
/* Close the property list */
H5Pclose(fapl);
H5Pclose(file_fapl);
/* Close the file */
H5Fclose(fid);
//! [SWMR Access]
//! [non-SWMR Access]
/* Create a copy of file access property list */
fapl = H5Pcreate(H5P_FILE_ACCESS);
/* Set the # of read attempts */
H5Pset_metadata_read_attempts(fapl, 20);
/* Open the file with SWMR access and the non-default file access property list */
fid = H5Fopen(FILE, H5F_ACC_RDONLY, fapl);
/* Get the file's file access roperty list */
file_fapl = H5Fget_access_plist(fid);
/* Retrieve the # of read attempts from the file's file access property list */
H5Pget_metadata_read_attempts(file_fapl, &attempts);
/*
* The value returned in "attempts" will be 1 (default for non-SWMR access).
* The library will use 1 as the number of read attempts
* when reading checksummed metadata in the file
*/
/* Close the property lists */
H5Pclose(fapl);
H5Pclose(file_fapl);
/* Close the file */
H5Fclose(fid);
//! [non-SWMR Access]

41
doxygen/examples/H5Pset_object_flush_cb.c Normal file
View File

@ -0,0 +1,41 @@
hid_t file_id, fapl_id;
hid_t dataset_id, dapl_id;
unsigned counter;
/* Create a copy of the file access property list */
fapl_id = H5Pcreate(H5P_FILE_ACCESS);
/* Set up the object flush property values */
/* flush_cb: callback function to invoke when an object flushes (see below) */
/* counter: user data to pass along to the callback function */
H5Pset_object_flush_cb(fapl_id, flush_cb, &counter);
/* Open the file */
file_id = H5Fopen(FILE, H5F_ACC_RDWR, H5P_DEFAULT);
/* Create a group */
gid = H5Gcreate2(fid, “group”, H5P_DEFAULT, H5P_DEFAULT_H5P_DEFAULT);
/* Open a dataset */
dataset_id = H5Dopen2(file_id, DATASET, H5P_DEFAULT);
/* The flush will invoke flush_cb() with counter */
H5Dflush(dataset_id);
/* counter will be equal to 1 */
/* ... */
/* The flush will invoke flush_cb() with counter */
H5Gflush(gid);
/* counter will be equal to 2 */
/* ... */
/* The callback function for object flush property */
static herr_t
flush_cb(hid_t obj_id, void *_udata)
{
unsigned *flush_ct = (unsigned *)_udata;
++(*flush_ct);
return 0;
}

1203
doxygen/examples/ImageSpec.html Normal file
View File

File diff suppressed because it is too large Load Diff

BIN
doxygen/examples/PaletteExample1.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.7 KiB

BIN
doxygen/examples/Palettes.fm.anc.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.6 KiB

193
doxygen/examples/TableSpec.html Normal file
View File

@ -0,0 +1,193 @@
<html>
<head>
<title>HDF5 Table Specification</title>
</head>
The HDF5 specification defines the standard objects and storage for the
standard HDF5 objects. (For information about the HDF5 library, model and
specification, see the HDF documentation.)&nbsp; This document is an additional
specification do define a standard profile for how to store tables in HDF5.
Table data in HDF5 is stored as HDF5 datasets with standard attributes to define
the properties of the tables.
<h2>
1. Overview</h2>
A generic table is a sequence of records, each record has a name and a type.
Table data is stored as an HDF5 one dimensional compound dataset.&nbsp; A table
is defined as a collection of records whose values are stored in fixed-length
fields. All records have the same structure and all values in each field have
the same data type.
<p>The dataset for a table is distinguished from other datasets by giving
it an attribute &quot;CLASS=TABLE&quot;.&nbsp;&nbsp;
Optional attributes allow the storage of a title for the Table and for
each column, and a fill value for each column.
<h2>
2.&nbsp; Table Attributes</h2>
The attributes for the Table are strings.&nbsp;They are written with the <a href="RM_H5LT.html#H5LTset_attribute_string"><code>H5LTset_attribute_string</code></a>
Lite API function.&nbsp; "Required" attributes must always be used. "Optional" attributes
must be used when required.
<br>&nbsp;
<h4>
Attributes</h4>
<dl>
<dt>
Attribute name="<b>CLASS</b>" (Required)</dt>
<dd>
This attribute is type H5T_C_S1, with size 5.</dd>
<dd>
For all Tables, the value of this attribute is &quot;TABLE&quot;.</dd>
<dd>
This attribute identifies this data set as intended to be interpreted as Table that conforms to the specifications on this page.</dd>
</dl>
<dl>
Attribute name="<b>VERSION</b>" (Required)
<dd>
This attribute is of type H5T_C_S1, with size corresponding to the length
of the version string.&nbsp; This attribute identifies the version number
of this specification to which it conforms.&nbsp; The current version number
is &quot;0.2&quot;.</dd>
</dl>
<dl>
<dt>
Attribute name="<b>TITLE</b>" (Optional)</dt>
<dd>
The <b>TITLE</b> is an optional String that is to be used as the
informative title of the whole table.
The <b>TITLE</b> is set with the parameter <code> table_title</code> of the function
<a href="RM_H5TB.html#H5TBmake_table"> <code> H5TBmake_table</code></a>.&nbsp;</dd>
</dl>
<dl>
<dt>
Attribute name="<b>FIELD_(n)_NAME</b>" (Required)</dt>
<dd>
The <b>FIELD_(n)_NAME</b> is an optional String that is to be used as the
informative title of column <b>n</b> of the table.
For each of the fields the word FIELD_ is concatenated with
the zero based field (n) index together with the name of the field.</dd>
</dl>
<dl>
<dt>
Attribute name="<b>FIELD_(n)_FILL</b>" (Optional)</dt>
<dd>
The <b>FIELD_(n)_FILL</b> is an optional String that is the fill value for
column <b>n</b> of the table.
For each of the fields the word FIELD_ is concatenated with
the zero based field (n) index together with the fill value, if present.
This value is written only when a fill value is defined for the table.</dd>
</dl>
<dl>
<br>&nbsp;
<center><table BORDER=2 BGCOLOR="#FFFFFF" >
<caption><b>Table 1. Attributes of an Image Dataset</b></caption>
<tr>
<td><b>Attribute Name</b></td>
<td><b>(R = Required</b>
<br><b>O= Optional)</b></td>
<td><b>Type</b></td>
<td><b>String Size</b></td>
<td><b>Value</b></td>
</tr>
<tr>
<td>CLASS</td>
<td>R</td>
<td>String</td>
<td>5</td>
<td>&quot;TABLE&quot;</td>
</tr>
<tr>
<td>VERSION</td>
<td>R</td>
<td>String</td>
<td>3</td>
<td>&quot;0.2&quot;</td>
</tr>
<tr>
<td>TITLE</td>
<td>O</td>
<td>String</td>
<td>&nbsp;</td>
<td>
<tr>
<td>FIELD_(n)_NAME</td>
<td>R</td>
<td>String</td>
<td>&nbsp;</td>
<td>
&nbsp;
<tr>
<td>FIELD_(n)_FILL</td>
<td>O*</td>
<td>String</td>
<td>&nbsp;</td>
<td>
&nbsp;
</table>
</center>
</dl>
<p>
<center>
&nbsp;
</center>
<i>* </i>The attribute FIELD_(n)_FILL is written to the table if a fill value is
specified on the creation of the Table. Otherwise, it is not.<p>The following
section of code shows the calls necessary to the creation of a table.
<p><code>/* Create a new HDF5 file using default properties. */<br>
file_id = H5Fcreate( &quot;my_table.h5&quot;, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT );</code> </p>
<p><code>/* Call the make table function */<br>
</code> <code>H5TBmake_table( "Table Title", file_id, "Table1", NFIELDS, NRECORDS, dst_size,&nbsp;<br>
field_names, dst_offset, field_type,&nbsp;<br>
chunk_size, fill_data, compress, p_data )&nbsp;</code> </p>
<p><code> /* Close the file. */<br>
status = H5Fclose( file_id );</code> </p>
</body>

787
doxygen/examples/ThreadSafeLibrary.html Normal file
View File

@ -0,0 +1,787 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<html lang="en-US">
<head>
<title>Thread Safe Library</title>
</head>
<h1>1. Library header files and conditional compilation</h1>
<p>
The following code is placed at the beginning of H5private.h:
</p>
<blockquote>
<pre>
#ifdef H5_HAVE_THREADSAFE
#include &lt;pthread.h&gt;
#endif
</pre>
</blockquote>
<p>
<code>H5_HAVE_THREADSAFE</code> is defined when the HDF-5 library is
compiled with the --enable-threadsafe configuration option. In general,
code for the non-threadsafe version of HDF-5 library are placed within
the <code>#else</code> part of the conditional compilation. The exception
to this rule are the changes to the <code>FUNC_ENTER</code> (in
H5private.h), <code>HRETURN</code> and <code>HRETURN_ERROR</code> (in
H5Eprivate.h) macros (see section 3.2).
</p>
<h1>2. Global variables/structures</h1>
<h2>2.1 Global library initialization variable</h2>
<p>
In the threadsafe implementation, the global library initialization
variable <code>H5_libinit_g</code> is changed to a global structure
consisting of the variable with its associated lock (locks are explained
in section 4.1):
</p>
<blockquote>
<pre>
hbool_t H5_libinit_g = FALSE;
</pre>
</blockquote>
<p>
becomes
</p>
<blockquote>
<pre>
H5_api_t H5_g;
</pre>
</blockquote>
<p>
where <code>H5_api_t</code> is
</p>
<blockquote>
<pre>
typedef struct H5_api_struct {
H5_mutex_t init_lock; /* API entrance mutex */
hbool_t H5_libinit_g;
} H5_api_t;
</pre>
</blockquote>
<p>
All former references to <code>H5_libinit_g</code> in the library are now
made using the macro <code>H5_INIT_GLOBAL</code>. If the threadsafe
library is to be used, the macro is set to <code>H5_g.H5_libinit_g</code>
instead.
</p>
<h2>2.2 Global serialization variable</h2>
<p>
A new global boolean variable <code>H5_allow_concurrent_g</code> is used
to determine if multiple threads are allowed to an API call
simultaneously. This is set to <code>FALSE</code>.
</p>
<p>
All APIs that are allowed to do so have their own local variable that
shadows the global variable and is set to <code>TRUE</code>. In phase 1,
no such APIs exist.
</p>
<p>
It is defined in <code>H5.c</code> as follows:
</p>
<blockquote>
<pre>
hbool_t H5_allow_concurrent_g = FALSE;
</pre>
</blockquote>
<h2>2.3 Global thread initialization variable</h2>
<p>
The global variable <code>H5_first_init_g</code> of type
<code>pthread_once_t</code> is used to allow only the first thread in the
application process to call an initialization function using
<code>pthread_once</code>. All subsequent calls to
<code>pthread_once</code> by any thread are disregarded.
</p>
<p>
The call sets up the mutex in the global structure <code>H5_g</code> (see
section 3.1) via an initialization function
<code>H5_first_thread_init</code>. The first thread initialization
function is described in section 4.2.
</p>
<p>
<code>H5_first_init_g</code> is defined in <code>H5.c</code> as follows:
</p>
<blockquote>
<pre>
pthread_once_t H5_first_init_g = PTHREAD_ONCE_INIT;
</pre>
</blockquote>
<h2>2.4 Global key for per-thread error stacks</h2>
<p>
A global pthread-managed key <code>H5_errstk_key_g</code> is used to
allow pthreads to maintain a separate error stack (of type
<code>H5E_t</code>) for each thread. This is defined in <code>H5.c</code>
as:
</p>
<blockquote>
<pre>
pthread_key_t H5_errstk_key_g;
</pre>
</blockquote>
<p>
Error stack management is described in section 4.3.
</p>
<h2>2.5 Global structure and key for thread cancellation prevention</h2>
<p>
We need to preserve the thread cancellation status of each thread
individually by using a key <code>H5_cancel_key_g</code>. The status is
preserved using a structure (of type <code>H5_cancel_t</code>) which
maintains the cancellability state of the thread before it entered the
library and a count (which works very much like the recursive lock
counter) which keeps track of the number of API calls the thread makes
within the library.
</p>
<p>
The structure is defined in <code>H5private.h</code> as:
</p>
<blockquote>
<pre>
/* cancelability structure */
typedef struct H5_cancel_struct {
int previous_state;
unsigned int cancel_count;
} H5_cancel_t;
</pre>
</blockquote>
<p>
Thread cancellation is described in section 4.4.
</p>
<h1>3. Changes to Macro expansions</h1>
<h2>3.1 Changes to FUNC_ENTER</h2>
<p>
The <code>FUNC_ENTER</code> macro is now extended to include macro calls
to initialize first threads, disable cancellability and wraps a lock
operation around the checking of the global initialization flag. It
should be noted that the cancellability should be disabled before
acquiring the lock on the library. Doing so otherwise would allow the
possibility that the thread be cancelled just after it has acquired the
lock on the library and in that scenario, if the cleanup routines are not
properly set, the library would be permanently locked out.
</p>
<p>
The additional macro code and new macro definitions can be found in
Appendix E.1 to E.5. The changes are made in <code>H5private.h</code>.
</p>
<h2>3.2 Changes to HRETURN and HRETURN_ERROR</h2>
<p>
The <code>HRETURN</code> and <code>HRETURN_ERROR</code> macros are the
counterparts to the <code>FUNC_ENTER</code> macro described in section
3.1. <code>FUNC_LEAVE</code> makes a macro call to <code>HRETURN</code>,
so it is also covered here.
</p>
<p>
The basic changes to these two macros involve adding macro calls to call
an unlock operation and re-enable cancellability if necessary. It should
be noted that the cancellability should be re-enabled only after the
thread has released the lock to the library. The consequence of doing
otherwise would be similar to that described in section 3.1.
</p>
<p>
The additional macro code and new macro definitions can be found in
Appendix E.9 to E.9. The changes are made in <code>H5Eprivate.h</code>.
</p>
<h1>4. Implementation of threadsafe functionality</h1>
<h2>4.1 Recursive Locks</h2>
<p>
A recursive mutex lock m allows a thread t1 to successfully lock m more
than once without blocking t1. Another thread t2 will block if t2 tries
to lock m while t1 holds the lock to m. If t1 makes k lock calls on m,
then it also needs to make k unlock calls on m before it releases the
lock.
</p>
<p>
Our implementation of recursive locks is built on top of a pthread mutex
lock (which is not recursive). It makes use of a pthread condition
variable to have unsuccessful threads wait on the mutex. Waiting threads
are awaken by a signal from the final unlock call made by the thread
holding the lock.
</p>
<p>
Recursive locks are defined to be the following type
(<code>H5private.h</code>):
</p>
<blockquote>
<pre>
typedef struct H5_mutex_struct {
pthread_t owner_thread; /* current lock owner */
pthread_mutex_t atomic_lock; /* lock for atomicity of new mechanism */
pthread_cond_t cond_var; /* condition variable */
unsigned int lock_count;
} H5_mutex_t;
</pre>
</blockquote>
<p>
Detailed implementation code can be found in Appendix A. The
implementation changes are made in <code>H5TS.c</code>.
</p>
<h2>4.2 First thread initialization</h2>
<p>
Because the mutex lock associated with a recursive lock cannot be
statically initialized, a mechanism is required to initialize the
recursive lock associated with <code>H5_g</code> so that it can be used
for the first time.
</p>
<p>
The pthreads library allows this through the pthread_once call which as
described in section 3.3 allows only the first thread accessing the
library in an application to initialize <code>H5_g</code>.
</p>
<p>
In addition to initializing <code>H5_g</code>, it also initializes the
key (see section 3.4) for use with per-thread error stacks (see section
4.3).
</p>
<p>
The first thread initialization mechanism is implemented as the function
call <code>H5_first_thread_init()</code> in <code>H5TS.c</code>. This is
described in appendix B.
</p>
<h2>4.3 Per-thread error stack management</h2>
<p>
Pthreads allows individual threads to access dynamic and persistent
per-thread data through the use of keys. Each key is associated with
a table that maps threads to data items. Keys can be initialized by
<code>pthread_key_create()</code> in pthreads (see sections 3.4 and 4.2).
Per-thread data items are accessed using a key through the
<code>pthread_getspecific()</code> and <code>pthread_setspecific()</code>
calls to read and write to the association table respectively.
</p>
<p>
Per-thread error stacks are accessed through the key
<code>H5_errstk_key_g</code> which is initialized by the first thread
initialization call (see section 4.2).
</p>
<p>
In the non-threadsafe version of the library, there is a global stack
variable <code>H5E_stack_g[1]</code> which is no longer defined in the
threadsafe version. At the same time, the macro call to gain access to
the error stack <code>H5E_get_my_stack</code> is changed from:
</p>
<blockquote>
<pre>
#define H5E_get_my_stack() (H5E_stack_g+0)
</pre>
</blockquote>
<p>
to:
</p>
<blockquote>
<pre>
#define H5E_get_my_stack() H5E_get_stack()
</pre>
</blockquote>
<p>
where <code>H5E_get_stack()</code> is a surrogate function that does the
following operations:
</p>
<ol>
<li>if a thread is attempting to get an error stack for the first
time, the error stack is dynamically allocated for the thread and
associated with <code>H5_errstk_key_g</code> using
<code>pthread_setspecific()</code>. The way we detect if it is the
first time is through <code>pthread_getspecific()</code> which
returns <code>NULL</code> if no previous value is associated with
the thread using the key.</li>
<li>if <code>pthread_getspecific()</code> returns a non-null value,
then that is the pointer to the error stack associated with the
thread and the stack can be used as usual.</li>
</ol>
<p>
A final change to the error reporting routines is as follows; the current
implementation reports errors to always be detected at thread 0. In the
threadsafe implementation, this is changed to report the number returned
by a call to <code>pthread_self()</code>.
</p>
<p>
The change in code (reflected in <code>H5Eprint</code> of file
<code>H5E.c</code>) is as follows:
</p>
<blockquote>
<pre>
#ifdef H5_HAVE_THREADSAFE
fprintf (stream, "HDF5-DIAG: Error detected in thread %d."
,pthread_self());
#else
fprintf (stream, "HDF5-DIAG: Error detected in thread 0.");
#endif
</pre>
</blockquote>
<p>
Code for <code>H5E_get_stack()</code> can be found in Appendix C. All the
above changes were made in <code>H5E.c</code>.
</p>
<h2>4.4 Thread Cancellation safety</h2>
<p>
To prevent thread cancellations from killing a thread while it is in the
library, we maintain per-thread information about the cancellability
status of the thread before it entered the library so that we can restore
that same status when the thread leaves the library.
</p>
<p>
By <i>enter</i> and <i>leave</i> the library, we mean the points when a
thread makes an API call from a user application and the time that API
call returns. Other API or callback function calls made from within that
API call are considered <i>within</i> the library.
</p>
<p>
Because other API calls may be made from within the first API call, we
need to maintain a counter to determine which was the first and
correspondingly the last return.
</p>
<p>
When a thread makes an API call, the macro <code>H5_API_SET_CANCEL</code>
calls the worker function <code>H5_cancel_count_inc()</code> which does
the following:
</p>
<ol>
<li>if this is the first time the thread has entered the library,
a new cancellability structure needs to be assigned to it.</li>
<li>if the thread is already within the library when the API call is
made, then cancel_count is simply incremented. Otherwise, we set
the cancellability state to <code>PTHREAD_CANCEL_DISABLE</code>
while storing the previous state into the cancellability structure.
<code>cancel_count</code> is also incremented in this case.</li>
</ol>
<p>
When a thread leaves an API call, the macro
<code>H5_API_UNSET_CANCEL</code> calls the worker function
<code>H5_cancel_count_dec()</code> which does the following:
</p>
<ol>
<li>if <code>cancel_count</code> is greater than 1, indicating that the
thread is not yet about to leave the library, then
<code>cancel_count</code> is simply decremented.</li>
<li>otherwise, we reset the cancellability state back to its original
state before it entered the library and decrement the count (back
to zero).</li>
</ol>
<p>
<code>H5_cancel_count_inc</code> and <code>H5_cancel_count_dec</code> are
described in Appendix D and may be found in <code>H5TS.c</code>.
</p>
<h1>5. Test programs</h1>
<p>
Except where stated, all tests involve 16 simultaneous threads that make
use of HDF-5 API calls without any explicit synchronization typically
required in a non-threadsafe environment.
</p>
<h2>5.1 Data set create and write</h2>
<p>
The test program sets up 16 threads to simultaneously create 16
different datasets named from <i>zero</i> to <i>fifteen</i> for a single
file and then writing an integer value into that dataset equal to the
dataset's named value.
</p>
<p>
The main thread would join with all 16 threads and attempt to match the
resulting HDF-5 file with expected results - that each dataset contains
the correct value (0 for <i>zero</i>, 1 for <i>one</i> etc ...) and all
datasets were correctly created.
</p>
<p>
The test is implemented in the file <code>ttsafe_dcreate.c</code>.
</p>
<h2>5.2 Test on error stack</h2>
<p>
The error stack test is one in which 16 threads simultaneously try to
create datasets with the same name. The result, when properly serialized,
should be equivalent to 16 attempts to create the dataset with the same
name.
</p>
<p>
The error stack implementation runs correctly if it reports 15 instances
of the dataset name conflict error and finally generates a correct HDF-5
containing that single dataset. Each thread should report its own stack
of errors with a thread number associated with it.
</p>
<p>
The test is implemented in the file <code>ttsafe_error.c</code>.
</p>
<h2>5.3 Test on cancellation safety</h2>
<p>
The main idea in thread cancellation safety is as follows; a child thread
is spawned to create and write to a dataset. Following that, it makes a
<code>H5Diterate</code> call on that dataset which activates a callback
function.
</p>
<p>
A deliberate barrier is invoked at the callback function which waits for
both the main and child thread to arrive at that point. After that
happens, the main thread proceeds to make a thread cancel call on the
child thread while the latter sleeps for 3 seconds before proceeding to
write a new value to the dataset.
</p>
<p>
After the iterate call, the child thread logically proceeds to wait
another 3 seconds before writing another newer value to the dataset.
</p>
<p>
The test is correct if the main thread manages to read the second value
at the end of the test. This means that cancellation did not take place
until the end of the iteration call despite of the 3 second wait within
the iteration callback and the extra dataset write operation.
Furthermore, the cancellation should occur before the child can proceed
to write the last value into the dataset.
</p>
<h2>5.4 Test on attribute creation</h2>
<p>
A main thread makes 16 threaded calls to <code>H5Acreate</code> with a
generated name for each attribute. Sixteen attributes should be created
for the single dataset in random (chronological) order and receive values
depending on its generated attribute name (e.g. <i>attrib010</i> would
receive the value 10).
</p>
<p>
After joining with all child threads, the main thread proceeds to read
each attribute by generated name to see if the value tallies. Failure is
detected if the attribute name does not exist (meaning they were never
created) or if the wrong values were read back.
</p>
<h1>A. Recursive Lock implementation code</h1>
<blockquote>
<pre>
void H5_mutex_init(H5_mutex_t *H5_mutex)
{
H5_mutex-&gt;owner_thread = NULL;
pthread_mutex_init(&amp;H5_mutex-&gt;atomic_lock, NULL);
pthread_cond_init(&amp;H5_mutex-&gt;cond_var, NULL);
H5_mutex-&gt;lock_count = 0;
}
void H5_mutex_lock(H5_mutex_t *H5_mutex)
{
pthread_mutex_lock(&amp;H5_mutex-&gt;atomic_lock);
if (pthread_equal(pthread_self(), H5_mutex-&gt;owner_thread)) {
/* already owned by self - increment count */
H5_mutex-&gt;lock_count++;
} else {
if (H5_mutex-&gt;owner_thread == NULL) {
/* no one else has locked it - set owner and grab lock */
H5_mutex-&gt;owner_thread = pthread_self();
H5_mutex-&gt;lock_count = 1;
} else {
/* if already locked by someone else */
while (1) {
pthread_cond_wait(&amp;H5_mutex-&gt;cond_var, &amp;H5_mutex-&gt;atomic_lock);
if (H5_mutex-&gt;owner_thread == NULL) {
H5_mutex-&gt;owner_thread = pthread_self();
H5_mutex-&gt;lock_count = 1;
break;
} /* else do nothing and loop back to wait on condition*/
}
}
}
pthread_mutex_unlock(&amp;H5_mutex-&gt;atomic_lock);
}
void H5_mutex_unlock(H5_mutex_t *H5_mutex)
{
pthread_mutex_lock(&amp;H5_mutex-&gt;atomic_lock);
H5_mutex-&gt;lock_count--;
if (H5_mutex-&gt;lock_count == 0) {
H5_mutex-&gt;owner_thread = NULL;
pthread_cond_signal(&amp;H5_mutex-&gt;cond_var);
}
pthread_mutex_unlock(&amp;H5_mutex-&gt;atomic_lock);
}
</pre>
</blockquote>
<h1>B. First thread initialization</h1>
<blockquote>
<pre>
void H5_first_thread_init(void)
{
/* initialize global API mutex lock */
H5_g.H5_libinit_g = FALSE;
H5_g.init_lock.owner_thread = NULL;
pthread_mutex_init(&amp;H5_g.init_lock.atomic_lock, NULL);
pthread_cond_init(&amp;H5_g.init_lock.cond_var, NULL);
H5_g.init_lock.lock_count = 0;
/* initialize key for thread-specific error stacks */
pthread_key_create(&amp;H5_errstk_key_g, NULL);
/* initialize key for thread cancellability mechanism */
pthread_key_create(&amp;H5_cancel_key_g, NULL);
}
</pre>
</blockquote>
<h1>C. Per-thread error stack acquisition</h1>
<blockquote>
<pre>
H5E_t *H5E_get_stack(void)
{
H5E_t *estack;
if (estack = pthread_getspecific(H5_errstk_key_g)) {
return estack;
} else {
/* no associated value with current thread - create one */
estack = (H5E_t *)malloc(sizeof(H5E_t));
pthread_setspecific(H5_errstk_key_g, (void *)estack);
return estack;
}
}
</pre>
</blockquote>
<h1>D. Thread cancellation mechanisms</h1>
<blockquote>
<pre>
void H5_cancel_count_inc(void)
{
H5_cancel_t *cancel_counter;
if (cancel_counter = pthread_getspecific(H5_cancel_key_g)) {
/* do nothing here */
} else {
/*
* first time thread calls library - create new counter and
* associate with key
*/
cancel_counter = (H5_cancel_t *)malloc(sizeof(H5_cancel_t));
cancel_counter-&gt;cancel_count = 0;
pthread_setspecific(H5_cancel_key_g, (void *)cancel_counter);
}
if (cancel_counter-&gt;cancel_count == 0) {
/* thread entering library */
pthread_setcancelstate(PTHREAD_CANCEL_DISABLE,
&amp;(cancel_counter-&gt;previous_state));
}
cancel_counter-&gt;cancel_count++;
}
void H5_cancel_count_dec(void)
{
H5_cancel_t *cancel_counter = pthread_getspecific(H5_cancel_key_g);
if (cancel_counter-&gt;cancel_count == 1)
pthread_setcancelstate(cancel_counter-&gt;previous_state, NULL);
cancel_counter-&gt;cancel_count--;
}
</pre>
</blockquote>
<h1>E. Macro expansion codes</h1>
<h2>E.1 <code>FUNC_ENTER</code></h2>
<blockquote>
<pre>
/* Initialize the library */ \
H5_FIRST_THREAD_INIT \
H5_API_UNSET_CANCEL \
H5_API_LOCK_BEGIN \
if (!(H5_INIT_GLOBAL)) { \
H5_INIT_GLOBAL = TRUE; \
if (H5_init_library() &lt; 0) { \
HRETURN_ERROR (H5E_FUNC, H5E_CANTINIT, err, \
"library initialization failed"); \
} \
} \
H5_API_LOCK_END \
:
:
:
</pre>
</blockquote>
<h2>E.2 <code>H5_FIRST_THREAD_INIT</code></h2>
<blockquote>
<pre>
/* Macro for first thread initialization */
#define H5_FIRST_THREAD_INIT \
pthread_once(&amp;H5_first_init_g, H5_first_thread_init);
</pre>
</blockquote>
<h2>E.3 <code>H5_API_UNSET_CANCEL</code></h2>
<blockquote>
<pre>
#define H5_API_UNSET_CANCEL \
if (H5_IS_API(FUNC)) { \
H5_cancel_count_inc(); \
}
</pre>
</blockquote>
<h2>E.4 <code>H5_API_LOCK_BEGIN</code></h2>
<blockquote>
<pre>
#define H5_API_LOCK_BEGIN \
if (H5_IS_API(FUNC)) { \
H5_mutex_lock(&amp;H5_g.init_lock);
</pre>
</blockquote>
<h2>E.5 <code>H5_API_LOCK_END</code></h2>
<blockquote>
<pre>
#define H5_API_LOCK_END }
</pre>
</blockquote>
<h2>E.6 <code>HRETURN</code> and <code>HRETURN_ERROR</code></h2>
<blockquote>
<pre>
:
:
H5_API_UNLOCK_BEGIN \
H5_API_UNLOCK_END \
H5_API_SET_CANCEL \
return ret_val; \
}
</pre>
</blockquote>
<h2>E.7 <code>H5_API_UNLOCK_BEGIN</code></h2>
<blockquote>
<pre>
#define H5_API_UNLOCK_BEGIN \
if (H5_IS_API(FUNC)) { \
H5_mutex_unlock(&amp;H5_g.init_lock);
</pre>
</blockquote>
<h2>E.8 <code>H5_API_UNLOCK_END</code></h2>
<blockquote>
<pre>
#define H5_API_UNLOCK_END }
</pre>
</blockquote>
<h2>E.9 <code>H5_API_SET_CANCEL</code></h2>
<blockquote>
<pre>
#define H5_API_SET_CANCEL \
if (H5_IS_API(FUNC)) { \
H5_cancel_count_dec(); \
}
</pre>
</blockquote>
<h2>By Chee Wai Lee</h2>
<h4>By Bill Wendling</h4>
</body>
</html>

1601
doxygen/examples/VFL.html Normal file
View File

File diff suppressed because it is too large Load Diff

21
doxygen/hdf5_footer.html Normal file
View File

@ -0,0 +1,21 @@
<!-- start footer part -->
<!--BEGIN GENERATE_TREEVIEW-->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
$navpath
<li class="footer">$generatedby
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="$relpath^doxygen.png" alt="doxygen"/></a> $doxygenversion </li>
</ul>
</div>
<!--END GENERATE_TREEVIEW-->
<!--BEGIN !GENERATE_TREEVIEW-->
<hr class="footer"/><address class="footer"><small>
$generatedby &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="$relpath^doxygen.png" alt="doxygen"/>
</a> $doxygenversion
</small></address>
<!--END !GENERATE_TREEVIEW-->
</body>
</html>

61
doxygen/hdf5_header.html Normal file
View File

@ -0,0 +1,61 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen $doxygenversion"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
<!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
<link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="$relpath^jquery.js"></script>
<script type="text/javascript" src="$relpath^dynsections.js"></script>
$treeview
$search
$mathjax
<link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
<link href="$relpath$hdf5doxy.css" rel="stylesheet" type="text/css">
<!-- $extrastylesheet -->
<script type="text/javascript" src="$relpath$hdf5_navtree_hacks.js"></script>
</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 id="top"><!-- do not remove this div, it is closed by doxygen! -->
<!--BEGIN TITLEAREA-->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<!--BEGIN PROJECT_LOGO-->
<td id="projectlogo"><img alt="Logo" src="$relpath^$projectlogo"/></td>
<!--END PROJECT_LOGO-->
<!--BEGIN PROJECT_NAME-->
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname"><a href="https://www.hdfgroup.org">$projectname</a>
<!--BEGIN PROJECT_NUMBER-->&#160;<span id="projectnumber">$projectnumber</span><!--END PROJECT_NUMBER-->
</div>
<!--BEGIN PROJECT_BRIEF--><div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF-->
</td>
<!--END PROJECT_NAME-->
<!--BEGIN !PROJECT_NAME-->
<!--BEGIN PROJECT_BRIEF-->
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectbrief">$projectbrief</div>
</td>
<!--END PROJECT_BRIEF-->
<!--END !PROJECT_NAME-->
<!--BEGIN DISABLE_INDEX-->
<!--BEGIN SEARCHENGINE-->
<td>$searchbox</td>
<!--END SEARCHENGINE-->
<!--END DISABLE_INDEX-->
</tr>
</tbody>
</table>
</div>
<!--END TITLEAREA-->
<!-- end header part -->

246
doxygen/hdf5_navtree_hacks.js Normal file
View File

@ -0,0 +1,246 @@
// generate a table of contents in the side-nav based on the h1/h2 tags of the current page.
function generate_autotoc() {
var headers = $("h1, h2");
if(headers.length > 1) {
var toc = $("#side-nav").append('<div id="nav-toc" class="toc"><h3>Table of contents</h3></div>');
toc = $("#nav-toc");
var footer = $("#nav-path");
var footerHeight = footer.height();
toc = toc.append('<ul></ul>');
toc = toc.find('ul');
var indices = new Array();
indices[0] = 0;
indices[1] = 0;
var h1counts = $("h1").length;
headers.each(function(i) {
var current = $(this);
var levelTag = current[0].tagName.charAt(1);
if(h1counts==0)
levelTag--;
var cur_id = current.attr("id");
indices[levelTag-1]+=1;
var prefix = indices[0];
if (levelTag >1) {
prefix+="."+indices[1];
}
// Uncomment to add number prefixes
// current.html(prefix + " " + current.html());
for(var l = levelTag; l < 2; ++l){
indices[l] = 0;
}
if(cur_id == undefined) {
current.attr('id', 'title' + i);
current.addClass('anchor');
toc.append("<li class='level" + levelTag + "'><a id='link" + i + "' href='#title" +
i + "' title='" + current.prop("tagName") + "'>" + current.text() + "</a></li>");
} else {
toc.append("<li class='level" + levelTag + "'><a id='" + cur_id + "' href='#title" +
i + "' title='" + current.prop("tagName") + "'>" + current.text() + "</a></li>");
}
});
resizeHeight();
}
}
var global_navtree_object;
// Overloaded to remove links to sections/subsections
function getNode(o, po)
{
po.childrenVisited = true;
var l = po.childrenData.length-1;
for (var i in po.childrenData) {
var nodeData = po.childrenData[i];
if((!nodeData[1]) || (nodeData[1].indexOf('#')==-1)) // <- we added this line
po.children[i] = newNode(o, po, nodeData[0], nodeData[1], nodeData[2], i==l);
}
}
// Overloaded to adjust the size of the navtree wrt the toc
function resizeHeight()
{
var header = $("#top");
var sidenav = $("#side-nav");
var content = $("#doc-content");
var navtree = $("#nav-tree");
var footer = $("#nav-path");
var toc = $("#nav-toc");
var headerHeight = header.outerHeight();
var footerHeight = footer.outerHeight();
var tocHeight = toc.height();
var windowHeight = $(window).height() - headerHeight - footerHeight;
content.css({height:windowHeight + "px"});
navtree.css({height:(windowHeight-tocHeight) + "px"});
sidenav.css({height:windowHeight + "px"});
}
// Overloaded to save the root node into global_navtree_object
function initNavTree(toroot,relpath)
{
var o = new Object();
global_navtree_object = o; // <- we added this line
o.toroot = toroot;
o.node = new Object();
o.node.li = document.getElementById("nav-tree-contents");
o.node.childrenData = NAVTREE;
o.node.children = new Array();
o.node.childrenUL = document.createElement("ul");
o.node.getChildrenUL = function() { return o.node.childrenUL; };
o.node.li.appendChild(o.node.childrenUL);
o.node.depth = 0;
o.node.relpath = relpath;
o.node.expanded = false;
o.node.isLast = true;
o.node.plus_img = document.createElement("img");
o.node.plus_img.src = relpath+"ftv2pnode.png";
o.node.plus_img.width = 16;
o.node.plus_img.height = 22;
if (localStorageSupported()) {
var navSync = $('#nav-sync');
if (cachedLink()) {
showSyncOff(navSync,relpath);
navSync.removeClass('sync');
} else {
showSyncOn(navSync,relpath);
}
navSync.click(function(){ toggleSyncButton(relpath); });
}
navTo(o,toroot,window.location.hash,relpath);
$(window).bind('hashchange', function(){
if (window.location.hash && window.location.hash.length>1){
var a;
if ($(location).attr('hash')){
var clslink=stripPath($(location).attr('pathname'))+':'+
$(location).attr('hash').substring(1);
a=$('.item a[class$="'+clslink+'"]');
}
if (a==null || !$(a).parent().parent().hasClass('selected')){
$('.item').removeClass('selected');
$('.item').removeAttr('id');
}
var link=stripPath2($(location).attr('pathname'));
navTo(o,link,$(location).attr('hash'),relpath);
} else if (!animationInProgress) {
$('#doc-content').scrollTop(0);
$('.item').removeClass('selected');
$('.item').removeAttr('id');
navTo(o,toroot,window.location.hash,relpath);
}
})
$(window).on("load", showRoot);
}
// return false if the the node has no children at all, or has only section/subsection children
function checkChildrenData(node) {
if (!(typeof(node.childrenData)==='string')) {
for (var i in node.childrenData) {
var url = node.childrenData[i][1];
if(url.indexOf("#")==-1)
return true;
}
return false;
}
return (node.childrenData);
}
// Modified to:
// 1 - remove the root node
// 2 - remove the section/subsection children
function createIndent(o,domNode,node,level)
{
var level=-2; // <- we replaced level=-1 by level=-2
var n = node;
while (n.parentNode) { level++; n=n.parentNode; }
if (checkChildrenData(node)) { // <- we modified this line to use checkChildrenData(node) instead of node.childrenData
var imgNode = document.createElement("span");
imgNode.className = 'arrow';
imgNode.style.paddingLeft=(16*level).toString()+'px';
imgNode.innerHTML=arrowRight;
node.plus_img = imgNode;
node.expandToggle = document.createElement("a");
node.expandToggle.href = "javascript:void(0)";
node.expandToggle.onclick = function() {
if (node.expanded) {
$(node.getChildrenUL()).slideUp("fast");
node.plus_img.innerHTML=arrowRight;
node.expanded = false;
} else {
expandNode(o, node, false, false);
}
}
node.expandToggle.appendChild(imgNode);
domNode.appendChild(node.expandToggle);
} else {
var span = document.createElement("span");
span.className = 'arrow';
span.style.width = 16*(level+1)+'px';
span.innerHTML = '&#160;';
domNode.appendChild(span);
}
}
// Overloaded to automatically expand the selected node
function selectAndHighlight(hash,n)
{
var a;
if (hash) {
var link=stripPath($(location).attr('pathname'))+':'+hash.substring(1);
a=$('.item a[class$="'+link+'"]');
}
if (a && a.length) {
a.parent().parent().addClass('selected');
a.parent().parent().attr('id','selected');
highlightAnchor();
} else if (n) {
$(n.itemDiv).addClass('selected');
$(n.itemDiv).attr('id','selected');
}
if ($('#nav-tree-contents .item:first').hasClass('selected')) {
$('#nav-sync').css('top','30px');
} else {
$('#nav-sync').css('top','5px');
}
expandNode(global_navtree_object, n, true, true); // <- we added this line
showRoot();
}
$(document).ready(function() {
generate_autotoc();
(function (){ // wait until the first "selected" element has been created
try {
// this line will triger an exception if there is no #selected element, i.e., before the tree structure is complete.
document.getElementById("selected").className = "item selected";
// ok, the default tree has been created, we can keep going...
// expand the "Chapters" node
if(window.location.href.indexOf('unsupported')==-1)
expandNode(global_navtree_object, global_navtree_object.node.children[0].children[2], true, true);
else
expandNode(global_navtree_object, global_navtree_object.node.children[0].children[1], true, true);
// Hide the root node "HDF5"
$(document.getElementsByClassName('index.html')[0]).parent().parent().css({display:"none"});
} catch (err) {
setTimeout(arguments.callee, 10);
}
})();
$(window).on("load", resizeHeight);
});

251
doxygen/hdf5doxy.css Normal file
View File

@ -0,0 +1,251 @@
/******** HDF5 specific CSS code ************/
/**** Styles removing elements ****/
/* remove the "modules|classes" link for module pages (they are already in the TOC) */
div.summary {
display:none;
}
/* remove */
div.contents hr {
display:none;
}
/**** ****/
p, dl.warning, dl.attention, dl.note
{
max-width:60em;
text-align:justify;
}
li {
max-width:55em;
text-align:justify;
}
img {
border: 0;
}
div.fragment {
display:table; /* this allows the element to be larger than its parent */
padding: 0pt;
}
pre.fragment {
border: 1px solid #cccccc;
margin: 2px 0px 2px 0px;
padding: 3px 5px 3px 5px;
}
/* Common style for all HDF5's tables */
table.example, table.manual, table.manual-vl, table.manual-hl {
max-width:100%;
border-collapse: collapse;
border-style: solid;
border-width: 1px;
border-color: #cccccc;
font-size: 1em;
box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15);
-moz-box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15);
-webkit-box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15);
}
table.example th, table.manual th, table.manual-vl th, table.manual-hl th {
padding: 0.5em 0.5em 0.5em 0.5em;
text-align: left;
padding-right: 1em;
color: #555555;
background-color: #F4F4E5;
background-image: -webkit-gradient(linear,center top,center bottom,from(#FFFFFF), color-stop(0.3,#FFFFFF), color-stop(0.30,#FFFFFF), color-stop(0.98,#F4F4E5), to(#ECECDE));
background-image: -moz-linear-gradient(center top, #FFFFFF 0%, #FFFFFF 30%, #F4F4E5 98%, #ECECDE);
filter: progid:DXImageTransform.Microsoft.gradient(startColorstr='#FFFFFF', endColorstr='#F4F4E5');
}
table.example td, table.manual td, table.manual-vl td, table.manual-hl td {
vertical-align:top;
border-width: 1px;
border-color: #cccccc;
}
/* header of headers */
table th.meta {
text-align:center;
font-size: 1.2em;
background-color:#FFFFFF;
}
/* intermediate header */
table th.inter {
text-align:left;
background-color:#FFFFFF;
background-image:none;
border-style:solid solid solid solid;
border-width: 1px;
border-color: #cccccc;
}
/** class for example / output tables **/
table.example {
}
table.example th {
}
table.example td {
padding: 0.5em 0.5em 0.5em 0.5em;
vertical-align:top;
}
/* standard class for the manual */
table.manual, table.manual-vl, table.manual-hl {
padding: 0.2em 0em 0.5em 0em;
}
table.manual th, table.manual-vl th, table.manual-hl th {
margin: 0em 0em 0.3em 0em;
}
table.manual td, table.manual-vl td, table.manual-hl td {
padding: 0.3em 0.5em 0.3em 0.5em;
vertical-align:top;
border-width: 1px;
}
table.manual td.alt, table.manual tr.alt, table.manual-vl td.alt, table.manual-vl tr.alt {
background-color: #F4F4E5;
}
table.manual-vl th, table.manual-vl td, table.manual-vl td.alt {
border-color: #cccccc;
border-width: 1px;
border-style: none solid none solid;
}
table.manual-vl th.inter {
border-style: solid solid solid solid;
}
table.manual-hl td {
border-color: #cccccc;
border-width: 1px;
border-style: solid none solid none;
}
table td.code {
font-family: monospace;
}
h2 {
margin-top:2em;
border-style: none none solid none;
border-width: 1px;
border-color: #cccccc;
}
/**** Table of content in the side-nav ****/
div.toc {
margin:0;
padding: 0.3em 0 0 0;
width:100%;
float:none;
position:absolute;
bottom:0;
border-radius:0px;
border-style: solid none none none;
max-height:50%;
overflow-y: scroll;
}
div.toc h3 {
margin-left: 0.5em;
margin-bottom: 0.2em;
}
div.toc ul {
margin: 0.2em 0 0.4em 0.5em;
}
span.cpp11,span.cpp14,span.cpp17 {
color: #119911;
font-weight: bold;
}
.newin3x {
color: #a37c1a;
font-weight: bold;
}
div.warningbox {
max-width:60em;
border-style: solid solid solid solid;
border-color: red;
border-width: 3px;
}
/**** old HDF5's styles ****/
table.tutorial_code td {
border-color: transparent; /* required for Firefox */
padding: 3pt 5pt 3pt 5pt;
vertical-align: top;
}
/* Whenever doxygen meets a '\n' or a '<BR/>', it will put
* the text containing the character into a <p class="starttd">.
* This little hack together with table.tutorial_code td.note
* aims at fixing this issue. */
table.tutorial_code td.note p.starttd {
margin: 0px;
border: none;
padding: 0px;
}
div.eimainmenu {
text-align: center;
}
/* center version number on main page */
h3.version {
text-align: center;
}
td.width20em p.endtd {
width: 20em;
}
/* needed for huge screens */
.ui-resizable-e {
background-repeat: repeat-y;
}
/* Style external links -- nav-tree is different */
#nav-tree .label a {
padding:2px 16px 2px 2px;
}
a {
outline: none;
text-decoration: none;
padding: 2px 1px 0;
}
a[href*="http"] {
background: url('https://mdn.mozillademos.org/files/12982/external-link-52.png') no-repeat 100% 0;
background-size: 12px 12px;
padding-right: 16px;
}

182
doxygen/hdf5doxy_layout.xml Normal file
View File

@ -0,0 +1,182 @@
<?xml version="1.0"?>
<doxygenlayout version="1.0">
<!-- Navigation index tabs for HTML output -->
<navindex>
<tab type="user" url="index.html" title="Overview" />
<tab type="user" url="https://portal.hdfgroup.org/display/HDF5/Learning+HDF5" title="Getting started" />
<tab type="user" url="@ref Cookbook" title="Cookbook" />
<tab type="user" url="https://portal.hdfgroup.org/display/HDF5/HDF5+User+Guides" title="User Guides" />
<tab type="user" url="https://portal.hdfgroup.org/display/HDF5/HDF5+Application+Developer%27s+Guide" title="Application Developer's Guide" />
<tab type="user" url="https://portal.hdfgroup.org/display/HDF5/HDF5+Glossary" title="Glossary" />
<tab type="user" url="@ref 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 About" title="About" />
</navindex>
<!-- Layout definition for a class page -->
<class>
<briefdescription visible="no"/>
<includes visible="$SHOW_INCLUDE_FILES"/>
<detaileddescription title=""/>
<inheritancegraph visible="$CLASS_GRAPH"/>
<collaborationgraph visible="$COLLABORATION_GRAPH"/>
<allmemberslink visible="yes"/>
<memberdecl>
<nestedclasses visible="yes" title=""/>
<publictypes title=""/>
<publicslots title=""/>
<signals title=""/>
<publicmethods title=""/>
<publicstaticmethods title=""/>
<publicattributes title=""/>
<publicstaticattributes title=""/>
<protectedtypes title=""/>
<protectedslots title=""/>
<protectedmethods title=""/>
<protectedstaticmethods title=""/>
<protectedattributes title=""/>
<protectedstaticattributes title=""/>
<packagetypes title=""/>
<packagemethods title=""/>
<packagestaticmethods title=""/>
<packageattributes title=""/>
<packagestaticattributes title=""/>
<properties title=""/>
<events title=""/>
<privatetypes title=""/>
<privateslots title=""/>
<privatemethods title=""/>
<privatestaticmethods title=""/>
<privateattributes title=""/>
<privatestaticattributes title=""/>
<friends title=""/>
<related title="" subtitle=""/>
<membergroups visible="yes"/>
</memberdecl>
<memberdef>
<inlineclasses title=""/>
<typedefs title=""/>
<enums title=""/>
<constructors title=""/>
<functions title=""/>
<related title=""/>
<variables title=""/>
<properties title=""/>
<events title=""/>
</memberdef>
<usedfiles visible="$SHOW_USED_FILES"/>
<authorsection visible="yes"/>
</class>
<!-- Layout definition for a namespace page -->
<namespace>
<briefdescription visible="yes"/>
<memberdecl>
<nestednamespaces visible="yes" title=""/>
<classes visible="yes" title=""/>
<typedefs title=""/>
<enums title=""/>
<functions title=""/>
<variables title=""/>
<membergroups visible="yes"/>
</memberdecl>
<detaileddescription title=""/>
<memberdef>
<inlineclasses title=""/>
<typedefs title=""/>
<enums title=""/>
<functions title=""/>
<variables title=""/>
</memberdef>
<authorsection visible="yes"/>
</namespace>
<!-- Layout definition for a file page -->
<file>
<briefdescription visible="yes"/>
<includes visible="$SHOW_INCLUDE_FILES"/>
<includegraph visible="$INCLUDE_GRAPH"/>
<includedbygraph visible="$INCLUDED_BY_GRAPH"/>
<sourcelink visible="yes"/>
<memberdecl>
<classes visible="yes" title=""/>
<namespaces visible="yes" title=""/>
<defines title=""/>
<typedefs title=""/>
<enums title=""/>
<functions title=""/>
<variables title=""/>
<membergroups visible="yes"/>
</memberdecl>
<detaileddescription title=""/>
<memberdef>
<inlineclasses title=""/>
<defines title=""/>
<typedefs title=""/>
<enums title=""/>
<functions title=""/>
<variables title=""/>
</memberdef>
<authorsection/>
</file>
<!-- Layout definition for a group page -->
<group>
<briefdescription visible="no"/>
<detaileddescription title=""/>
<groupgraph visible="$GROUP_GRAPHS"/>
<memberdecl>
<nestedgroups visible="yes" title=""/>
<dirs visible="yes" title=""/>
<files visible="yes" title=""/>
<namespaces visible="yes" title=""/>
<classes visible="yes" title=""/>
<defines title=""/>
<typedefs title=""/>
<enums title=""/>
<enumvalues title=""/>
<functions title=""/>
<variables title=""/>
<signals title=""/>
<publicslots title=""/>
<protectedslots title=""/>
<privateslots title=""/>
<events title=""/>
<properties title=""/>
<friends title=""/>
<membergroups visible="yes"/>
</memberdecl>
<memberdef>
<pagedocs/>
<inlineclasses title=""/>
<defines title=""/>
<typedefs title=""/>
<enums title=""/>
<enumvalues title=""/>
<functions title=""/>
<variables title=""/>
<signals title=""/>
<publicslots title=""/>
<protectedslots title=""/>
<privateslots title=""/>
<events title=""/>
<properties title=""/>
<friends title=""/>
</memberdef>
<authorsection visible="yes"/>
</group>
<!-- Layout definition for a directory page -->
<directory>
<briefdescription visible="yes"/>
<directorygraph visible="yes"/>
<memberdecl>
<dirs visible="yes"/>
<files visible="yes"/>
</memberdecl>
<detaileddescription title=""/>
</directory>
</doxygenlayout>

BIN
doxygen/img/FF-IH_FileGroup.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.3 KiB

BIN
doxygen/img/FF-IH_FileObject.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.1 KiB

BIN
doxygen/img/FileFormatSpecChunkDiagram.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 29 KiB

BIN
doxygen/img/HDFG-logo.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 4.4 KiB

After

Width:  |  Height:  |  Size: 1.6 KiB

BIN
doxygen/img/PaletteExample1.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.7 KiB

BIN
doxygen/img/Palettes.fm.anc.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.6 KiB

BIN
doxygen/img/ftv2node.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 86 B

BIN
doxygen/img/ftv2pnode.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 229 B

1
src/CMakeLists.txt
View File

@ -1378,6 +1378,7 @@ if (DOXYGEN_FOUND)
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}/examples)
# This configure and custom target work together
# Replace variables inside @@ with the current values

341
src/H5ACpublic.h
View File

@ -442,124 +442,347 @@ extern "C" {
#define H5AC_METADATA_WRITE_STRATEGY__PROCESS_0_ONLY 0
#define H5AC_METADATA_WRITE_STRATEGY__DISTRIBUTED 1
/**
* H5AC_cache_config_t is a public structure intended for use in public APIs.
* At least in its initial incarnation, it is basically a copy of \c struct
* \c H5C_auto_size_ctl_t, minus the \c report_fcn field, and plus the
* \c dirty_bytes_threshold field.
*
* The \c report_fcn field is omitted, as including it would require us to make
* \c H5C_t structure public.
*
* The \c dirty_bytes_threshold field does not appear in \c H5C_auto_size_ctl_t,
* as synchronization between caches on different processes is handled at the \c
* H5AC level, not at the level of \c H5C. Note however that there is
* considerable interaction between this value and the other fields in this
* structure.
*
* Similarly, the \c open_trace_file, \c close_trace_file, and \c
* trace_file_name fields do not appear in \c H5C_auto_size_ctl_t, as most trace
* file issues are handled at the \c H5AC level. The one exception is storage
* of the pointer to the trace file, which is handled by \c H5C.
*
* The structure is in H5ACpublic.h as we may wish to allow different
* configuration options for metadata and raw data caches.
*/
//! <!-- [H5AC_cache_config_t_snip] -->
typedef struct H5AC_cache_config_t {
/* general configuration fields: */
//! <!-- [H5AC_cache_config_t_general_snip] -->
int version;
/**< Integer field indicating the the version of the H5AC_cache_config_t
* in use. This field should be set to #H5AC__CURR_CACHE_CONFIG_VERSION
* (defined in H5ACpublic.h). */
hbool_t rpt_fcn_enabled;
/**< Boolean flag indicating whether the adaptive cache resize report
* function is enabled. This field should almost always be set to disabled
* (0). Since resize algorithm activity is reported via stdout, it MUST be
* set to disabled (0) on Windows machines.\n
* The report function is not supported code, and can be expected to change
* between versions of the library. Use it at your own risk. */
hbool_t open_trace_file;
/**< Boolean field indicating whether the
* \ref H5AC_cache_config_t.trace_file_name "trace_file_name"
* field should be used to open a trace file for the cache.\n
* The trace file is a debugging feature that allows the capture
* of top level metadata cache requests for purposes of debugging
* and/or optimization. This field should normally be set to 0, as
* trace file collection imposes considerable overhead.\n
* This field should only be set to 1 when the
* \ref H5AC_cache_config_t.trace_file_name "trace_file_name"
* contains the full path of the desired trace file, and either
* there is no open trace file on the cache, or the
* \ref H5AC_cache_config_t.close_trace_file "close_trace_file"
* field is also 1.\n
* The trace file feature is unsupported unless used at the
* direction of The HDF Group. It is intended to allow The HDF
* Group to collect a trace of cache activity in cases of occult
* failures and/or poor performance seen in the field, so as to aid
* in reproduction in the lab. If you use it absent the direction
* of The HDF Group, you are on your own. */
hbool_t close_trace_file;
char trace_file_name[H5AC__MAX_TRACE_FILE_NAME_LEN + 1];
/**< Boolean field indicating whether the current trace file
*(if any) should be closed.\n
* See the above comments on the \ref H5AC_cache_config_t.open_trace_file
* "open_trace_file" field. This field should be set to 0 unless there is
* an open trace file on the cache that you wish to close.\n
* The trace file feature is unsupported unless used at the direction of
* The HDF Group. It is intended to allow The HDF Group to collect a trace
* of cache activity in cases of occult failures and/or poor performance
* seen in the field, so as to aid in reproduction in the lab. If you use
* it absent the direction of The HDF Group, you are on your own. */
char trace_file_name[H5AC__MAX_TRACE_FILE_NAME_LEN + 1];
/**< Full path of the trace file to be opened if the
* \ref H5AC_cache_config_t.open_trace_file "open_trace_file" field is set
* to 1.\n
* In the parallel case, an ascii representation of the MPI rank of the
* process will be appended to the file name to yield a unique trace file
* name for each process.\n
* The length of the path must not exceed #H5AC__MAX_TRACE_FILE_NAME_LEN
* characters.\n
* The trace file feature is unsupported unless used at the direction of
* The HDF Group. It is intended to allow The HDF Group to collect a trace
* of cache activity in cases of occult failures and/or poor performance
* seen in the field, so as to aid in reproduction in the lab. If you use
* it absent the direction of The HDF Group, you are on your own. */
hbool_t evictions_enabled;
/**< A boolean flag indicating whether evictions from the metadata cache
* are enabled. This flag is initially set to enabled (1).\n
* In rare circumstances, the raw data throughput quirements may be so high
* that the user wishes to postpone metadata writes so as to reserve I/O
* throughput for raw data. The \p evictions_enabled field exists to allow
* this. However, this is an extreme step, and you have no business doing
* it unless you have read the User Guide section on metadata caching, and
* have considered all other options carefully.\n
* The \p evictions_enabled field may not be set to disabled (0)
* unless all adaptive cache resizing code is disabled via the
* \ref H5AC_cache_config_t.incr_mode "incr_mode",
* \ref H5AC_cache_config_t.flash_incr_mode "flash_incr_mode",
* \ref H5AC_cache_config_t.decr_mode "decr_mode" fields.\n
* When this flag is set to disabled (\c 0), the metadata cache will not
* attempt to evict entries to make space for new entries, and thus will
* grow without bound.\n
* Evictions will be re-enabled when this field is set back to \c 1.
* This should be done as soon as possible. */
hbool_t set_initial_size;
size_t initial_size;
/**< Boolean flag indicating whether the cache should be created
* with a user specified initial size. */
size_t initial_size;
/**< If \ref H5AC_cache_config_t.set_initial_size "set_initial_size"
* is set to 1, \p initial_size must contain he desired initial size in
* bytes. This value must lie in the closed interval
* [ \p min_size, \p max_size ]. (see below) */
double min_clean_fraction;
/**< This field specifies the minimum fraction of the cache
* that must be kept either clean or empty.\n
* The value must lie in the interval [0.0, 1.0]. 0.01 is a good place to
* start in the serial case. In the parallel case, a larger value is needed
* -- see the overview of the metadata cache in the
* “Metadata Caching in HDF5” section of the -- <em>HDF5 User’s Guide</em>
* for details. */
size_t max_size;
/**< Upper bound (in bytes) on the range of values that the
* adaptive cache resize code can select as the maximum cache size. */
size_t min_size;
/**< Lower bound (in bytes) on the range of values that the
* adaptive cache resize code can select as the mininum cache * size. */
long int epoch_length;
/**< Number of cache accesses between runs of the adaptive cache resize
* code. 50,000 is a good starting number. */
//! <!-- [H5AC_cache_config_t_general_snip] -->
/* size increase control fields: */
//! <!-- [H5AC_cache_config_t_incr_snip] -->
enum H5C_cache_incr_mode incr_mode;
/**< Enumerated value indicating the operational mode of the automatic
* cache size increase code. At present, only two values listed in
* #H5C_cache_incr_mode are legal. */
double lower_hr_threshold;
/**< Hit rate threshold used by the hit rate threshold cache size
* increment algorithm.\n
* When the hit rate over an epoch is below this threshold and the cache
* is full, the maximum size of the cache is multiplied by increment
* (below), and then clipped as necessary to stay within \p max_size, and
* possibly \p max_increment.\n
* This field must lie in the interval [0.0, 1.0]. 0.8 or 0.9 is a good
* place to start. */
double increment;
/**< Factor by which the hit rate threshold cache size increment
* algorithm multiplies the current cache max size to obtain a tentative
* new cache size.\n
* The actual cache size increase will be clipped to satisfy the \p max_size
* specified in the general configuration, and possibly max_increment
* below.\n
* The parameter must be greater than or equal to 1.0 -- 2.0 is a reasonable
* value.\n
* If you set it to 1.0, you will effectively disable cache size increases.
*/
hbool_t apply_max_increment;
size_t max_increment;
/**< Boolean flag indicating whether an upper limit should be applied to
* the size of cache size increases. */
size_t max_increment;
/**< Maximum number of bytes by which cache size can be increased in a
* single step -- if applicable. */
enum H5C_cache_flash_incr_mode flash_incr_mode;
double flash_multiple;
double flash_threshold;
/**< Enumerated value indicating the operational mode of the flash cache
* size increase code. At present, only two listed values in
* #H5C_cache_flash_incr_mode are legal.*/
double flash_multiple;
/**< The factor by which the size of the triggering entry / entry size
* increase is multiplied to obtain the initial cache size increment. This
* increment may be reduced to reflect existing free space in the cache and
* the \p max_size field above.\n
* The parameter must lie in the interval [0.0, 1.0]. 0.1 or 0.05 is a good
* place to start.\n
* At present, this field must lie in the range [0.1, 10.0]. */
double flash_threshold;
/**< The factor by which the current maximum cache size is multiplied to
* obtain the minimum size entry / entry size increase which may trigger a
* flash cache size increase. \n
* At present, this value must lie in the range [0.1, 1.0]. */
//! <!-- [H5AC_cache_config_t_incr_snip] -->
/* size decrease control fields: */
//! <!-- [H5AC_cache_config_t_decr_snip] -->
enum H5C_cache_decr_mode decr_mode;
/**< Enumerated value indicating the operational mode of the tomatic
* cache size decrease code. At present, the values listed in
* #H5C_cache_decr_mode are legal.*/
double upper_hr_threshold;
/**< Hit rate threshold for the hit rate threshold and ageout with hit
* rate threshold cache size decrement algorithms.\n
* When \p decr_mode is #H5C_decr__threshold, and the hit rate over a given
* epoch exceeds the supplied threshold, the current maximum cache
* size is multiplied by decrement to obtain a tentative new (and smaller)
* maximum cache size.\n
* When \p decr_mode is #H5C_decr__age_out_with_threshold, there is
* no attempt to find and evict aged out entries unless the hit rate in
* the previous epoch exceeded the supplied threshold.\n
* This field must lie in the interval [0.0, 1.0].\n
* For #H5C_incr__threshold, .9995 or .99995 is a good place to start.\n
* For #H5C_decr__age_out_with_threshold, .999 might be more useful.*/
double decrement;
/**< In the hit rate threshold cache size decrease algorithm, this
* parameter contains the factor by which the current max cache size is
* multiplied to produce a tentative new cache size.\n
* The actual cache size decrease will be clipped to satisfy the
* \ref H5AC_cache_config_t.min_size "min_size" specified in the general
* configuration, and possibly \ref H5AC_cache_config_t.max_decrement
* "max_decrement".\n
* The parameter must be be in the interval [0.0, 1.0].\n
* If you set it to 1.0, you will effectively
* disable cache size decreases. 0.9 is a reasonable starting point. */
hbool_t apply_max_decrement;
size_t max_decrement;
/**< Boolean flag indicating ether an upper limit should be applied to
* the size of cache size decreases. */
size_t max_decrement;
/**< Maximum number of bytes by which the maximum cache size can be
* decreased in any single step -- if applicable.*/
int epochs_before_eviction;
/**< In the ageout based cache size reduction algorithms, this field
* contains the minimum number of epochs an entry must remain unaccessed in
* cache before the cache size reduction algorithm tries to evict it. 3 is a
* reasonable value. */
hbool_t apply_empty_reserve;
double empty_reserve;
/**< Boolean flag indicating whether the ageout based decrement
* algorithms will maintain a empty reserve when decreasing cache size. */
double empty_reserve;
/**< Empty reserve as a fraction maximum cache size if applicable.\n When
* so directed, the ageout based algorithms will not decrease the maximum
* cache size unless the empty reserve can be met.\n The parameter must lie
* in the interval [0.0, 1.0]. 0.1 or 0.05 is a good place to start. */
//! <!-- [H5AC_cache_config_t_decr_snip] -->
/* parallel configuration fields: */
//! <!-- [H5AC_cache_config_t_parallel_snip] -->
size_t dirty_bytes_threshold;
int metadata_write_strategy;
/**< Threshold number of bytes of dirty metadata generation for
* triggering synchronizations of the metadata caches serving the target
* file in the parallel case.\n Synchronization occurs whenever the number
* of bytes of dirty metadata created since the last synchronization exceeds
* this limit.\n This field only applies to the parallel case. While it is
* ignored elsewhere, it can still draw a value out of bounds error.\n It
* must be consistant across all caches on any given file.\n By default,
* this field is set to 256 KB. It shouldn't be more than half the current
* max cache size times the min clean fraction. */
int metadata_write_strategy;
/**< Desired metadata write strategy. The valid values for this field
* are:\n #H5AC_METADATA_WRITE_STRATEGY__PROCESS_0_ONLY: Specifies tha only
* process zero is allowed to write dirty metadata to disk.\n
* #H5AC_METADATA_WRITE_STRATEGY__DISTRIBUTED: Specifies that process zero
* still makes the decisions as to what entries should be flushed, but the
* actual flushes are distributed across the processes in the computation to
* the extent possible.\n The src/H5ACpublic.h include file in the HDF5
* library has detailed information on each strategy. */
//! <!-- [H5AC_cache_config_t_parallel_snip] -->
} H5AC_cache_config_t;
/****************************************************************************
*
* structure H5AC_cache_image_config_t
*
* H5AC_cache_image_ctl_t is a public structure intended for use in public
* APIs. At least in its initial incarnation, it is a copy of struct
* H5C_cache_image_ctl_t.
*
* The fields of the structure are discussed individually below:
*
* version: Integer field containing the version number of this version
* of the H5C_image_ctl_t structure. Any instance of
* H5C_image_ctl_t passed to the cache must have a known
* version number, or an error will be flagged.
*
* generate_image: Boolean flag indicating whether a cache image should
* be created on file close.
*
* save_resize_status: Boolean flag indicating whether the cache image
* should include the adaptive cache resize configuration and status.
* Note that this field is ignored at present.
*
* entry_ageout: Integer field indicating the maximum number of
* times a prefetched entry can appear in subsequent cache images.
* This field exists to allow the user to avoid the buildup of
* infrequently used entries in long sequences of cache images.
*
* The value of this field must lie in the range
* H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE (-1) to
* H5AC__CACHE_IMAGE__ENTRY_AGEOUT__MAX (100).
*
* H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE means that no limit
* is imposed on number of times a prefeteched entry can appear
* in subsequent cache images.
*
* A value of 0 prevents prefetched entries from being included
* in cache images.
*
* Positive integers restrict prefetched entries to the specified
* number of appearances.
*
* Note that the number of subsequent cache images that a prefetched
* entry has appeared in is tracked in an 8 bit field. Thus, while
* H5AC__CACHE_IMAGE__ENTRY_AGEOUT__MAX can be increased from its
* current value, any value in excess of 255 will be the functional
* equivalent of H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE.
*
****************************************************************************/
//! <!-- [H5AC_cache_config_t_snip] -->
#define H5AC__CURR_CACHE_IMAGE_CONFIG_VERSION 1
#define H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE -1
#define H5AC__CACHE_IMAGE__ENTRY_AGEOUT__MAX 100
//! <!-- [H5AC_cache_image_config_t_snip] -->
/**
* H5AC_cache_image_config_t is a public structure intended for use in public
* APIs. At least in its initial incarnation, it is a copy of \c struct \c
* H5C_cache_image_ctl_t.
*/
typedef struct H5AC_cache_image_config_t {
int version;
int version;
/**< Integer field containing the version number of this version of the \c
* H5C_image_ctl_t structure. Any instance of \c H5C_image_ctl_t passed
* to the cache must have a known version number, or an error will be
* flagged.
*/
hbool_t generate_image;
/**< Boolean flag indicating whether a cache image should be created on file
* close.
*/
hbool_t save_resize_status;
int entry_ageout;
/**< Boolean flag indicating whether the cache image should include the
* adaptive cache resize configuration and status. Note that this field
* is ignored at present.
*/
int entry_ageout;
/**< Integer field indicating the maximum number of times a
* prefetched entry can appear in subsequent cache images. This field
* exists to allow the user to avoid the buildup of infrequently used
* entries in long sequences of cache images.
*
* The value of this field must lie in the range \ref
* H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE (-1) to \ref
* H5AC__CACHE_IMAGE__ENTRY_AGEOUT__MAX (100).
*
* \ref H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE means that no limit is
* imposed on number of times a prefeteched entry can appear in subsequent
* cache images.
*
* A value of 0 prevents prefetched entries from being included in cache
* images.
*
* Positive integers restrict prefetched entries to the specified number
* of appearances.
*
* Note that the number of subsequent cache images that a prefetched entry
* has appeared in is tracked in an 8 bit field. Thus, while \ref
* H5AC__CACHE_IMAGE__ENTRY_AGEOUT__MAX can be increased from its current
* value, any value in excess of 255 will be the functional equivalent of
* \ref H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE.
*/
} H5AC_cache_image_config_t;
//! <!-- [H5AC_cache_image_config_t_snip] -->
#ifdef __cplusplus
}
#endif

40
src/H5Amodule.h
View File

@ -30,19 +30,39 @@
#define H5_MY_PKG_INIT YES
/**\defgroup H5A H5A
* \brief Attribute Interface
*
* \details The Attribute Interface, H5A, provides a mechanism for attaching
* additional information to a dataset, group, or named datatype.
* Use the functions in this module to manage HDF5 attributes.
*
* Attributes are accessed by opening the object that they are
* attached to and are not independent objects. Typically an
* attribute is small in size and contains user metadata about the
* object that it is attached to.
* The Attribute Interface, H5A, provides a mechanism for attaching additional
* information to a dataset, group, or named datatype.
*
* Attributes look similar to HDF5 datasets in that they have a
* datatype and dataspace. However, they do not support partial
* I/O operations and cannot be compressed or extended.
* Attributes are accessed by opening the object that they are attached to and
* are not independent objects. Typically an attribute is small in size and
* contains user metadata about the object that it is attached to.
*
* Attributes look similar to HDF5 datasets in that they have a datatype and
* dataspace. However, they do not support partial I/O operations and cannot be
* compressed or extended.
*
* <table>
* <tr><th>Create</th><th>Read</th></tr>
* <tr valign="top">
* <td>
* \snippet H5A_examples.c create
* </td>
* <td>
* \snippet H5A_examples.c read
* </td>
* <tr><th>Update</th><th>Delete</th></tr>
* <tr valign="top">
* <td>
* \snippet H5A_examples.c update
* </td>
* <td>
* \snippet H5A_examples.c delete
* </td>
* </tr>
* </table>
*
*/

193
src/H5Apublic.h
View File

@ -22,19 +22,40 @@
#include "H5Opublic.h" /* Object Headers */
#include "H5Tpublic.h" /* Datatypes */
/* Information struct for attribute (for H5Aget_info/H5Aget_info_by_idx) */
//! [H5A_info_t_snip]
//! <!-- [H5A_info_t_snip] -->
/**
* Information struct for H5Aget_info() / H5Aget_info_by_idx()
*/
typedef struct {
hbool_t corder_valid; /* Indicate if creation order is valid */
H5O_msg_crt_idx_t corder; /* Creation order */
H5T_cset_t cset; /* Character set of attribute name */
hsize_t data_size; /* Size of raw data */
hbool_t corder_valid; /**< Indicate if creation order is valid */
H5O_msg_crt_idx_t corder; /**< Creation order */
H5T_cset_t cset; /**< Character set of attribute name */
hsize_t data_size; /**< Size of raw data */
} H5A_info_t;
//! [H5A_info_t_snip]
//! <!-- [H5A_info_t_snip] -->
/* Typedef for H5Aiterate2() callbacks */
//! <!-- [H5A_operator2_t_snip] -->
/**
* Typedef for H5Aiterate2() / H5Aiterate_by_name() callbacks
* \param[in] location_id The identifier for the group, dataset
* or named datatype being iterated over
* \param[in] attr_name The name of the current object attribute
* \param[in] ainfo The attribute’s info struct
* \param[in,out] op_data A pointer to the operator data passed in to
* H5Aiterate2() or H5Aiterate_by_name()
* \returns The return values from an operator are:
* \li Zero causes the iterator to continue, returning zero when
* all attributes have been processed.
* \li Positive causes the iterator to immediately return that
* positive value, indicating short-circuit success. The
* iterator can be restarted at the next attribute.
* \li Negative causes the iterator to immediately return that value,
* indicating failure. The iterator can be restarted at the next
* attribute.
*/
typedef herr_t (*H5A_operator2_t)(hid_t location_id /*in*/, const char *attr_name /*in*/,
const H5A_info_t *ainfo /*in*/, void *op_data /*in,out*/);
//! <!-- [H5A_operator2_t_snip] -->
/********************/
/* Public Variables */
@ -105,8 +126,8 @@ H5_DLL herr_t H5Aclose(hid_t attr_id);
* The attribute identifier returned by this function must be released
* with H5Aclose() resource leaks will develop.
*
* \note The \p acpl and \p aapl parameters are currently not used; specify
* #H5P_DEFAULT.
* \note The \p aapl parameter is currently not used; specify #H5P_DEFAULT.
*
* \note If \p loc_id is a file identifier, the attribute will be attached
* that file’s root group.
*
@ -117,6 +138,11 @@ H5_DLL herr_t H5Aclose(hid_t attr_id);
*/
H5_DLL hid_t H5Acreate2(hid_t loc_id, const char *attr_name, hid_t type_id, hid_t space_id, hid_t acpl_id,
hid_t aapl_id);
/*--------------------------------------------------------------------------*/
/**
* \ingroup ASYNC
* \async_variant_of{H5Acreate}
*/
H5_DLL hid_t H5Acreate_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
const char *attr_name, hid_t type_id, hid_t space_id, hid_t acpl_id,
hid_t aapl_id, hid_t es_id);
@ -659,30 +685,12 @@ H5_DLL hid_t H5Aget_type(hid_t attr_id);
* the value returned identifies the parameter to be operated on
* in the next step of the iteration.
*
* The #H5A_operator2_t prototype for the \p op parameter is a
* user defined function where:
* The operation receives the location identifier for the group or
* dataset being iterated over, \p location_id; the name of the
* current object attribute, \p attr_name; the attribute’s info
* struct, \p ainfo; and a pointer to the operator data passed
* into H5Aiterate2(), \p op_data.
*
* Valid return values from an operator and the resulting
* H5Aiterate2() and \p op behavior are as follows:
*
* \li Zero causes the iterator to continue, returning zero when
* all attributes have been processed.
* \li A positive value causes the iterator to immediately return
* that positive value, indicating short-circuit success. The
* iterator can be restarted at the next attribute, as
* indicated by the return value of \p idx.
* \li A negative value causes the iterator to immediately return
* that value, indicating failure. The iterator can be
* restarted at the next attribute, as indicated by the return
* value of \p idx.
* \p op is a user-defined function whose prototype is defined
* as follows:
* \snippet this H5A_operator2_t_snip
* \click4more
*
* \note This function is also available through the H5Aiterate() macro.
* \todo Add snippet for H5A_operator2_t
*
* \since 1.8.0
*
@ -751,13 +759,10 @@ H5_DLL herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t ord
* the value returned identifies the parameter to be operated on in
* the next step of the iteration.
*
* The #H5A_operator2_t prototype for the \p op parameter is a
* user defined function where:
* The operation receives the location identifier for the group or
* dataset being iterated over, \p location_id; the name of the
* current object attribute, \p attr_name; the attribute’s info
* struct, \p ainfo; and a pointer to the operator data passed
* into H5Aiterate_by_name(), \p op_data.
* \p op is a user-defined function whose prototype is defined
* as follows:
* \snippet this H5A_operator2_t_snip
* \click4more
*
* Valid return values from an operator and the resulting
* H5Aiterate_by_name() and \p op behavior are as follows:
@ -777,17 +782,21 @@ H5_DLL herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t ord
* information regarding the properties of links required to access
* the object, \p obj_name.
*
* \todo Add snippet to show H5Aoperator2_t.
* \since 1.8.0
*
*/
H5_DLL herr_t H5Aiterate_by_name(hid_t loc_id, const char *obj_name, H5_index_t idx_type,
H5_iter_order_t order, hsize_t *idx, H5A_operator2_t op, void *op_data,
hid_t lapl_id);
H5_DLL hid_t H5Acreate_by_name_async(const char *app_file, const char *app_func, unsigned app_line,
hid_t loc_id, const char *obj_name, const char *attr_name, hid_t type_id,
hid_t space_id, hid_t acpl_id, hid_t aapl_id, hid_t lapl_id,
hid_t es_id);
/*--------------------------------------------------------------------------*/
/**
* \ingroup ASYNC
* \async_variant_of{H5Acreate_by_name}
*/
H5_DLL hid_t H5Acreate_by_name_async(const char *app_file, const char *app_func, unsigned app_line,
hid_t loc_id, const char *obj_name, const char *attr_name, hid_t type_id,
hid_t space_id, hid_t acpl_id, hid_t aapl_id, hid_t lapl_id,
hid_t es_id);
/*--------------------------------------------------------------------------*/
/**
* \ingroup H5A
@ -819,6 +828,11 @@ H5_DLL hid_t H5Acreate_by_name_async(const char *app_file, const char *app_func
* \see H5Aclose(), H5Acreate()
*/
H5_DLL hid_t H5Aopen(hid_t obj_id, const char *attr_name, hid_t aapl_id);
/*--------------------------------------------------------------------------*/
/**
* \ingroup ASYNC
* \async_variant_of{H5Aopen}
*/
H5_DLL hid_t H5Aopen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t obj_id,
const char *attr_name, hid_t aapl_id, hid_t es_id);
/*--------------------------------------------------------------------------*/
@ -868,6 +882,11 @@ H5_DLL hid_t H5Aopen_async(const char *app_file, const char *app_func, unsigned
*/
H5_DLL hid_t H5Aopen_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order,
hsize_t n, hid_t aapl_id, hid_t lapl_id);
/*--------------------------------------------------------------------------*/
/**
* \ingroup ASYNC
* \async_variant_of{H5Aopen_by_idx}
*/
H5_DLL hid_t H5Aopen_by_idx_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n,
hid_t aapl_id, hid_t lapl_id, hid_t es_id);
@ -914,6 +933,11 @@ H5_DLL hid_t H5Aopen_by_idx_async(const char *app_file, const char *app_func, un
*/
H5_DLL hid_t H5Aopen_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t aapl_id,
hid_t lapl_id);
/*--------------------------------------------------------------------------*/
/**
* \ingroup ASYNC
* \async_variant_of{H5Aopen_by_name}
*/
H5_DLL hid_t H5Aopen_by_name_async(const char *app_file, const char *app_func, unsigned app_line,
hid_t loc_id, const char *obj_name, const char *attr_name, hid_t aapl_id,
hid_t lapl_id, hid_t es_id);
@ -967,6 +991,11 @@ H5_DLL herr_t H5Aread(hid_t attr_id, hid_t type_id, void *buf);
*
*/
H5_DLL herr_t H5Arename(hid_t loc_id, const char *old_name, const char *new_name);
/*--------------------------------------------------------------------------*/
/**
* \ingroup ASYNC
* \async_variant_of{H5Aread}
*/
H5_DLL herr_t H5Aread_async(const char *app_file, const char *app_func, unsigned app_line, hid_t attr_id,
hid_t dtype_id, void *buf, hid_t es_id);
/*--------------------------------------------------------------------------*/
@ -1001,15 +1030,40 @@ H5_DLL herr_t H5Aread_async(const char *app_file, const char *app_func, unsigned
*
*/
H5_DLL herr_t H5Awrite(hid_t attr_id, hid_t type_id, const void *buf);
/*--------------------------------------------------------------------------*/
/**
* \ingroup ASYNC
* \async_variant_of{H5Awrite}
*/
H5_DLL herr_t H5Awrite_async(const char *app_file, const char *app_func, unsigned app_line, hid_t attr_id,
hid_t type_id, const void *buf, hid_t es_id);
/*--------------------------------------------------------------------------*/
/**
* \ingroup ASYNC
* \async_variant_of{H5Arename}
*/
H5_DLL herr_t H5Arename_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
const char *old_name, const char *new_name, hid_t es_id);
/*--------------------------------------------------------------------------*/
/**
* \ingroup ASYNC
* \async_variant_of{H5Arename_by_name}
*/
H5_DLL herr_t H5Arename_by_name_async(const char *app_file, const char *app_func, unsigned app_line,
hid_t loc_id, const char *obj_name, const char *old_attr_name,
const char *new_attr_name, hid_t lapl_id, hid_t es_id);
/*--------------------------------------------------------------------------*/
/**
* \ingroup ASYNC
* \async_variant_of{H5Aexists}
*/
H5_DLL herr_t H5Aexists_async(const char *app_file, const char *app_func, unsigned app_line, hid_t obj_id,
const char *attr_name, hbool_t *exists, hid_t es_id);
/*--------------------------------------------------------------------------*/
/**
* \ingroup ASYNC
* \async_variant_of{H5Aexists_by_name}
*/
H5_DLL herr_t H5Aexists_by_name_async(const char *app_file, const char *app_func, unsigned app_line,
hid_t loc_id, const char *obj_name, const char *attr_name,
hbool_t *exists, hid_t lapl_id, hid_t es_id);
@ -1038,6 +1092,11 @@ H5_DLL herr_t H5Aexists_by_name_async(const char *app_file, const char *app_func
*/
H5_DLL herr_t H5Arename_by_name(hid_t loc_id, const char *obj_name, const char *old_attr_name,
const char *new_attr_name, hid_t lapl_id);
/*--------------------------------------------------------------------------*/
/**
* \ingroup ASYNC
* \async_variant_of{H5Aclose}
*/
H5_DLL herr_t H5Aclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t attr_id,
hid_t es_id);
@ -1085,9 +1144,28 @@ H5_DLL herr_t H5Aclose_async(const char *app_file, const char *app_func, unsigne
/* Typedefs */
/* Typedef for H5Aiterate1() callbacks */
//! <!-- [H5A_operator1_t_snip] -->
/**
* \brief Typedef for H5Aiterate1() callbacks
*
* \param[in] location_id The identifier for the group, dataset
* or named datatype being iterated over
* \param[in] attr_name The name of the current object attribute
* \param[in,out] operator_data A pointer to the operator data passed in to
* H5Aiterate1()
* \returns The return values from an operator are:
* \li Zero causes the iterator to continue, returning zero when
* all attributes have been processed.
* \li Positive causes the iterator to immediately return that
* positive value, indicating short-circuit success. The
* iterator can be restarted at the next attribute.
* \li Negative causes the iterator to immediately return that value,
* indicating failure. The iterator can be restarted at the next
* attribute.
*/
typedef herr_t (*H5A_operator1_t)(hid_t location_id /*in*/, const char *attr_name /*in*/,
void *operator_data /*in,out*/);
//! <!-- [H5A_operator1_t_snip] -->
/* Function prototypes */
/* --------------------------------------------------------------------------*/
@ -1163,8 +1241,6 @@ H5_DLL int H5Aget_num_attrs(hid_t loc_id);
*
* \brief Calls a user’s function for each attribute on an object
*
* \todo make prototype parameter match function (idx vs attr_num)
*
* \loc_id
* \param[in,out] idx Starting (in) and ending (out) attribute index
* \param[in] op User's function to pass each attribute to
@ -1186,29 +1262,12 @@ H5_DLL int H5Aget_num_attrs(hid_t loc_id);
* \p op, is returned in \p idx. If \p idx is the null pointer,
* then all attributes are processed.
*
* The prototype for #H5A_operator1_t is a user defined function
* where:
* The operation receives the identifier for the group, dataset
* or named datatype being iterated over, \p loc_id, the name of
* the current object attribute, \p attr_name, and the pointer to
* the operator data passed in to H5Aiterate1(), \p op_data.
*
* The return values from an operator are:
*
* \li Zero causes the iterator to continue, returning zero when
* all attributes have been processed.
* \li Positive causes the iterator to immediately return that
* positive value, indicating short-circuit success. The
* iterator can be restarted at the next attribute.
* \li Negative causes the iterator to immediately return that value,
* indicating failure. The iterator can be restarted at the next
* attribute.
*
* \todo Add snippet to show H5A_operator1_t.
* \p op is a user-defined function whose prototype is defined as follows:
* \snippet this H5A_operator1_t_snip
* \click4more
*
* \version 1.8.0 The function \p H5Aiterate was renamed to H5Aiterate1()
* and deprecated in this release.
*
* \since 1.0.0
*
*/

23
src/H5Cpublic.h
View File

@ -31,15 +31,34 @@
extern "C" {
#endif
enum H5C_cache_incr_mode { H5C_incr__off, H5C_incr__threshold };
enum H5C_cache_incr_mode {
H5C_incr__off,
/**<Automatic cache size increase is disabled, and the remaining increment fields are ignored.*/
enum H5C_cache_flash_incr_mode { H5C_flash_incr__off, H5C_flash_incr__add_space };
H5C_incr__threshold
/**<Automatic cache size increase is enabled using the hit rate threshold algorithm.*/
};
enum H5C_cache_flash_incr_mode {
H5C_flash_incr__off,
/**<Flash cache size increase is disabled.*/
H5C_flash_incr__add_space
/**<Flash cache size increase is enabled using the add space algorithm.*/
};
enum H5C_cache_decr_mode {
H5C_decr__off,
/**<Automatic cache size decrease is disabled.*/
H5C_decr__threshold,
/**<Automatic cache size decrease is enabled using the hit rate threshold algorithm.*/
H5C_decr__age_out,
/**<Automatic cache size decrease is enabled using the ageout algorithm. */
H5C_decr__age_out_with_threshold
/**<Automatic cache size decrease is enabled using the ageout with hit rate threshold algorithm.*/
};
#ifdef __cplusplus

38
src/H5Dmodule.h
View File

@ -29,15 +29,37 @@
#define H5_MY_PKG_ERR H5E_DATASET
#define H5_MY_PKG_INIT YES
/**
* \defgroup H5D H5D
* \brief Group Interface
* \details The HDF5 Dataset Interface, H5D, provides a mechanism for managing
* HDF5 datasets, including the transfer of data between memory and
* disk and the description of dataset properties.
/**\defgroup H5D H5D
*
* Use the functions in this module to manage HDF5 datasets, including the
* transfer of data between memory and disk and the description of dataset
* properties. Datasets are used by other HDF5 APIs and referenced either by
* name or by a handle. Such handles can be obtained by either creating or
* opening the dataset.
*
* Typical stages in the HDF5 dataset life cycle are shown below in introductory
* examples.
*
* <table>
* <tr><th>Create</th><th>Read</th></tr>
* <tr valign="top">
* <td>
* \snippet H5D_examples.c create
* </td>
* <td>
* \snippet H5D_examples.c read
* </td>
* <tr><th>Update</th><th>Delete</th></tr>
* <tr valign="top">
* <td>
* \snippet H5D_examples.c update
* </td>
* <td>
* \snippet H5D_examples.c delete
* </td>
* </tr>
* </table>
*
* A Dataset is used by other HDF5 APIs, either by name or by a handle,
* which is obtained by either creating or opening the dataset.
*/
#endif /* H5Dmodule_H */

415
src/H5Dpublic.h
View File

@ -39,30 +39,41 @@
/* Public Typedefs */
/*******************/
/* Values for the H5D_LAYOUT property */
//! <!-- [H5D_layout_t_snip] -->
/**
* Values for the H5D_LAYOUT property
*/
typedef enum H5D_layout_t {
H5D_LAYOUT_ERROR = -1,
H5D_COMPACT = 0, /*raw data is very small */
H5D_CONTIGUOUS = 1, /*the default */
H5D_CHUNKED = 2, /*slow and fancy */
H5D_VIRTUAL = 3, /*actual data is stored in other datasets */
H5D_NLAYOUTS = 4 /*this one must be last! */
H5D_COMPACT = 0, /**< raw data is very small */
H5D_CONTIGUOUS = 1, /**< the default */
H5D_CHUNKED = 2, /**< slow and fancy */
H5D_VIRTUAL = 3, /**< actual data is stored in other datasets */
H5D_NLAYOUTS = 4 /**< this one must be last! */
} H5D_layout_t;
//! <!-- [H5D_layout_t_snip] -->
/* Types of chunk index data structures */
//! <!-- [H5D_chunk_index_t_snip] -->
/**
* Types of chunk index data structures
*/
typedef enum H5D_chunk_index_t {
H5D_CHUNK_IDX_BTREE = 0, /* v1 B-tree index (default) */
H5D_CHUNK_IDX_BTREE = 0, /**< v1 B-tree index (default) */
H5D_CHUNK_IDX_SINGLE =
1, /* Single Chunk index (cur dims[]=max dims[]=chunk dims[]; filtered & non-filtered) */
H5D_CHUNK_IDX_NONE = 2, /* Implicit: No Index (H5D_ALLOC_TIME_EARLY, non-filtered, fixed dims) */
H5D_CHUNK_IDX_FARRAY = 3, /* Fixed array (for 0 unlimited dims) */
H5D_CHUNK_IDX_EARRAY = 4, /* Extensible array (for 1 unlimited dim) */
H5D_CHUNK_IDX_BT2 = 5, /* v2 B-tree index (for >1 unlimited dims) */
H5D_CHUNK_IDX_NTYPES /* This one must be last! */
1, /**< Single Chunk index (cur dims[]=max dims[]=chunk dims[]; filtered & non-filtered) */
H5D_CHUNK_IDX_NONE = 2, /**< Implicit: No Index (#H5D_ALLOC_TIME_EARLY, non-filtered, fixed dims) */
H5D_CHUNK_IDX_FARRAY = 3, /**< Fixed array (for 0 unlimited dims) */
H5D_CHUNK_IDX_EARRAY = 4, /**< Extensible array (for 1 unlimited dim) */
H5D_CHUNK_IDX_BT2 = 5, /**< v2 B-tree index (for >1 unlimited dims) */
H5D_CHUNK_IDX_NTYPES /**< This one must be last! */
} H5D_chunk_index_t;
//! <!-- [H5D_chunk_index_t_snip] -->
/* Values for the space allocation time property */
//! <!-- [H5D_alloc_time_t_snip] -->
/**
* Values for the space allocation time property
*/
typedef enum H5D_alloc_time_t {
H5D_ALLOC_TIME_ERROR = -1,
H5D_ALLOC_TIME_DEFAULT = 0,
@ -70,57 +81,84 @@ typedef enum H5D_alloc_time_t {
H5D_ALLOC_TIME_LATE = 2,
H5D_ALLOC_TIME_INCR = 3
} H5D_alloc_time_t;
//! <!-- [H5D_alloc_time_t_snip] -->
/* Values for the status of space allocation */
//! <!-- [H5D_space_status_t_snip] -->
/**
* Values for the status of space allocation
*/
typedef enum H5D_space_status_t {
H5D_SPACE_STATUS_ERROR = -1,
H5D_SPACE_STATUS_NOT_ALLOCATED = 0,
H5D_SPACE_STATUS_PART_ALLOCATED = 1,
H5D_SPACE_STATUS_ALLOCATED = 2
} H5D_space_status_t;
//! <!-- [H5D_space_status_t_snip] -->
/* Values for time of writing fill value property */
//! <!-- [H5D_fill_time_t_snip] -->
/**
* Values for time of writing fill value property
*/
typedef enum H5D_fill_time_t {
H5D_FILL_TIME_ERROR = -1,
H5D_FILL_TIME_ALLOC = 0,
H5D_FILL_TIME_NEVER = 1,
H5D_FILL_TIME_IFSET = 2
} H5D_fill_time_t;
//! <!-- [H5D_fill_time_t_snip] -->
/* Values for fill value status */
//! <!-- [H5D_fill_value_t_snip] -->
/**
* Values for fill value status
*/
typedef enum H5D_fill_value_t {
H5D_FILL_VALUE_ERROR = -1,
H5D_FILL_VALUE_UNDEFINED = 0,
H5D_FILL_VALUE_DEFAULT = 1,
H5D_FILL_VALUE_USER_DEFINED = 2
} H5D_fill_value_t;
//! <!-- [H5D_fill_value_t_snip] -->
/* Values for VDS bounds option */
//! <!-- [H5D_vds_view_t_snip] -->
/**
* Values for VDS bounds option
*/
typedef enum H5D_vds_view_t {
H5D_VDS_ERROR = -1,
H5D_VDS_FIRST_MISSING = 0,
H5D_VDS_LAST_AVAILABLE = 1
} H5D_vds_view_t;
//! <!-- [H5D_vds_view_t_snip] -->
/* Callback for H5Pset_append_flush() in a dataset access property list */
//! <!-- [H5D_append_cb_t_snip] -->
/**
* Callback for H5Pset_append_flush() in a dataset access property list
*/
typedef herr_t (*H5D_append_cb_t)(hid_t dataset_id, hsize_t *cur_dims, void *op_data);
//! <!-- [H5D_append_cb_t_snip] -->
/** Define the operator function pointer for H5Diterate() */
//! [H5D_operator_t_snip]
//! <!-- [H5D_operator_t_snip] -->
/**
* Define the operator function pointer for H5Diterate()
*/
typedef herr_t (*H5D_operator_t)(void *elem, hid_t type_id, unsigned ndim, const hsize_t *point,
void *operator_data);
//! [H5D_operator_t_snip]
//! <!-- [H5D_operator_t_snip] -->
/** Define the operator function pointer for H5Dscatter() */
//! [H5D_scatter_func_t_snip]
//! <!-- [H5D_scatter_func_t_snip] -->
/**
* Define the operator function pointer for H5Dscatter()
*/
typedef herr_t (*H5D_scatter_func_t)(const void **src_buf /*out*/, size_t *src_buf_bytes_used /*out*/,
void *op_data);
//! [H5D_scatter_func_t_snip]
//! <!-- [H5D_scatter_func_t_snip] -->
/** Define the operator function pointer for H5Dgather() */
//! [H5D_gather_func_t_snip]
//! <!-- [H5D_gather_func_t_snip] -->
/**
* Define the operator function pointer for H5Dgather()
*/
typedef herr_t (*H5D_gather_func_t)(const void *dst_buf, size_t dst_buf_bytes_used, void *op_data);
//! [H5D_gather_func_t_snip]
//! <!-- [H5D_gather_func_t_snip] -->
/********************/
/* Public Variables */
@ -203,26 +241,8 @@ H5_DLL hid_t H5Dcreate2(hid_t loc_id, const char *name, hid_t type_id, hid_t spa
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Asynchronous version of H5Dcreate2()
*
* \app_file
* \app_func
* \app_line
* \fgdta_loc_id
* \param[in] name Name of the dataset to create
* \type_id
* \space_id
* \lcpl_id
* \dcpl_id
* \dapl_id
* \es_id
*
* \return \hid_t{dataset}
*
* \see H5Dcreate2()
*
* \ingroup ASYNC
* \async_variant_of{H5Dcreate}
*/
H5_DLL hid_t H5Dcreate_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
const char *name, hid_t type_id, hid_t space_id, hid_t lcpl_id, hid_t dcpl_id,
@ -325,22 +345,8 @@ H5_DLL hid_t H5Dopen2(hid_t loc_id, const char *name, hid_t dapl_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Asynchronous version of H5Dopen2()
*
* \app_file
* \app_func
* \app_line
* \fgdta_loc_id
* \param[in] name Name of the dataset to open
* \dapl_id
* \es_id
*
* \return \hid_t{dataset}
*
* \see H5Dopen2()
*
* \ingroup ASYNC
* \async_variant_of{H5Dopen}
*/
H5_DLL hid_t H5Dopen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
const char *name, hid_t dapl_id, hid_t es_id);
@ -370,24 +376,17 @@ H5_DLL hid_t H5Dget_space(hid_t dset_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Asynchronous version of H5Dget_space()
*
* \app_file
* \app_func
* \app_line
* \dset_id
* \es_id
*
* \return \hid_t{dataspace}
*
* \see H5Dget_space()
*
* \ingroup ASYNC
* \async_variant_of{H5Dget_space}
*/
H5_DLL hid_t H5Dget_space_async(const char *app_file, const char *app_func, unsigned app_line, hid_t dset_id,
hid_t es_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
* \todo Document this function!
*/
H5_DLL herr_t H5Dget_space_status(hid_t dset_id, H5D_space_status_t *allocation);
/**
@ -614,7 +613,7 @@ H5_DLL herr_t H5Dget_num_chunks(hid_t dset_id, hid_t fspace_id, hsize_t *nchunks
* using the coordinates specified by \p offset.
*
* If the queried chunk does not exist in the file, \p size will
* be set to 0, \p addr to #HADDR_UNDEF, and the buffer \p
* be set to 0, \p addr to \c HADDR_UNDEF, and the buffer \p
* filter_mask will not be modified.
*
* \p offset is a pointer to a one-dimensional array with a size
@ -649,7 +648,7 @@ H5_DLL herr_t H5Dget_chunk_info_by_coord(hid_t dset_id, const hsize_t *offset, u
* specified by the index index. The chunk belongs to a set of
* chunks in the selection specified by fspace_id. If the queried
* chunk does not exist in the file, the size will be set to 0 and
* address to #HADDR_UNDEF. The value pointed to by filter_mask will
* address to \c HADDR_UNDEF. The value pointed to by filter_mask will
* not be modified. NULL can be passed in for any \p out parameters.
*
* \p chk_idx is the chunk index in the selection. Index value
@ -684,7 +683,7 @@ H5_DLL herr_t H5Dget_chunk_info(hid_t dset_id, hid_t fspace_id, hsize_t chk_idx,
*
* \dset_id
*
* \return Returns the offset in bytes; otherwise, returns #HADDR_UNDEF,
* \return Returns the offset in bytes; otherwise, returns \c HADDR_UNDEF,
* a negative value.
*
* \details H5Dget_offset() returns the address in the file of
@ -795,25 +794,8 @@ H5_DLL herr_t H5Dread(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Asynchronous version of H5Dread()
*
* \app_file
* \app_func
* \app_line
* \dset_id Identifier of the dataset to read from
* \param[in] mem_type_id Identifier of the memory datatype
* \param[in] mem_space_id Identifier of the memory dataspace
* \param[in] file_space_id Identifier of the dataset's dataspace in the file
* \param[in] dxpl_id Identifier of a transfer property list
* \param[out] buf Buffer to receive data read from file
* \es_id
*
* \return \herr_t
*
* \see H5Dread()
*
* \ingroup ASYNC
* \async_variant_of{H5Dread}
*/
H5_DLL herr_t H5Dread_async(const char *app_file, const char *app_func, unsigned app_line, hid_t dset_id,
hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t dxpl_id,
@ -932,25 +914,8 @@ H5_DLL herr_t H5Dwrite(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Asynchronous version of H5Dwrite()
*
* \app_file
* \app_func
* \app_line
* \param[in] dset_id Identifier of the dataset to read from
* \param[in] mem_type_id Identifier of the memory datatype
* \param[in] mem_space_id Identifier of the memory dataspace
* \param[in] file_space_id Identifier of the dataset's dataspace in the file
* \dxpl_id
* \param[out] buf Buffer with data to be written to the file
* \es_id
*
* \return \herr_t
*
* \see H5Dwrite()
*
* \ingroup ASYNC
* \async_variant_of{H5Dwrite}
*/
H5_DLL herr_t H5Dwrite_async(const char *app_file, const char *app_func, unsigned app_line, hid_t dset_id,
hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t dxpl_id,
@ -1292,22 +1257,8 @@ H5_DLL herr_t H5Dset_extent(hid_t dset_id, const hsize_t size[]);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Asynchronous version of H5Dset_extent()
*
* \app_file
* \app_func
* \app_line
* \dset_id
* \param[in] size[] Array containing the new magnitude of each dimension
* of the dataset
* \es_id
*
* \return \herr_t
*
* \see H5Dset_extent()
*
* \ingroup ASYNC
* \async_variant_of{H5Dset_extent}
*/
H5_DLL herr_t H5Dset_extent_async(const char *app_file, const char *app_func, unsigned app_line,
hid_t dset_id, const hsize_t size[], hid_t es_id);
@ -1536,20 +1487,8 @@ H5_DLL herr_t H5Dclose(hid_t dset_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Asynchronous version of H5Dclose()
*
* \app_file
* \app_func
* \app_line
* \dset_id
* \es_id
*
* \return \herr_t
*
* \see H5Dclose()
*
* \ingroup ASYNC
* \async_variant_of{H5Dclose}
*/
H5_DLL herr_t H5Dclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t dset_id,
hid_t es_id);
@ -1608,9 +1547,181 @@ H5_DLL herr_t H5Dget_chunk_index_type(hid_t did, H5D_chunk_index_t *idx_type);
/* Typedefs */
/* Function prototypes */
H5_DLL hid_t H5Dcreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t dcpl_id);
H5_DLL hid_t H5Dopen1(hid_t loc_id, const char *name);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Creates a dataset at the specified location
*
* \fgdta_loc_id
* \param[in] name Name of the dataset to create
* \type_id
* \space_id
* \dcpl_id
*
* \return \hid_t{dataset}
*
* \deprecated This function is deprecated in favor of the function H5Dcreate2()
* or the macro H5Dcreate().
*
* \details H5Dcreate1() creates a data set with a name, \p name, in the
* location specified by the identifier \p loc_id. \p loc_id may be a
* file, group, dataset, named datatype or attribute. If an attribute,
* dataset, or named datatype is specified for \p loc_id then the
* dataset will be created at the location where the attribute,
* dataset, or named datatype is attached.
*
* \p name can be a relative path based at \p loc_id or an absolute
* path from the root of the file. Use of this function requires that
* any intermediate groups specified in the path already exist.
*
* The dataset’s datatype and dataspace are specified by \p type_id and
* \p space_id, respectively. These are the datatype and dataspace of
* the dataset as it will exist in the file, which may differ from the
* datatype and dataspace in application memory.
*
* Names within a group are unique: H5Dcreate1() will return an error
* if a link with the name specified in name already exists at the
* location specified in \p loc_id.
*
* As is the case for any object in a group, the length of a dataset
* name is not limited.
*
* \p dcpl_id is an #H5P_DATASET_CREATE property list created with \p
* H5reate1() and initialized with various property list functions
* described in Property List Interface.
*
* H5Dcreate() and H5Dcreate_anon() return an error if the dataset’s
* datatype includes a variable-length (VL) datatype and the fill value
* is undefined, i.e., set to \c NULL in the dataset creation property
* list. Such a VL datatype may be directly included, indirectly
* included as part of a compound or array datatype, or indirectly
* included as part of a nested compound or array datatype.
*
* H5Dcreate() and H5Dcreate_anon() return a dataset identifier for
* success or a negative value for failure. The dataset identifier
* should eventually be closed by calling H5Dclose() to release
* resources it uses.
*
* See H5Dcreate_anon() for discussion of the differences between
* H5Dcreate() and H5Dcreate_anon().
*
* The HDF5 library provides flexible means of specifying a fill value,
* of specifying when space will be allocated for a dataset, and of
* specifying when fill values will be written to a dataset.
*
* \version 1.8.0 Function H5Dcreate() renamed to H5Dcreate1() and deprecated in this release.
* \since 1.0.0
*
* \see H5Dopen2(), H5Dclose(), H5Tset_size()
*
*/
H5_DLL hid_t H5Dcreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t dcpl_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Opens an existing dataset
*
* \fgdta_loc_id
* \param[in] name Name of the dataset to access
*
* \return \hid_t{dataset}
*
* \deprecated This function is deprecated in favor of the function H5Dopen2()
* or the macro H5Dopen().
*
* \details H5Dopen1() opens an existing dataset for access at the location
* specified by \p loc_id. \p loc_id may be a file, group, dataset,
* named datatype or attribute. If an attribute, dataset, or named
* datatype is specified for loc_id then the dataset will be opened at
* the location where the attribute, dataset, or named datatype is
* attached. name is a dataset name and is used to identify the dataset
* in the file.
*
* A dataset opened with this function should be closed with H5Dclose()
* when the dataset is no longer needed so that resource leaks will not
* develop.
*
* \version 1.8.0 Function H5Dopen() renamed to H5Dopen1() and deprecated in this release.
* \since 1.0.0
*
*/
H5_DLL hid_t H5Dopen1(hid_t loc_id, const char *name);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Extends a dataset
*
* \dset_id
* \param[in] size Array containing the new size of each dimension
*
* \return \herr_t
*
* \deprecated This function is deprecated in favor of the function H5Dset_extent().
*
* \details H5Dextend() verifies that the dataset is at least of size \p size,
* extending it if necessary. The dimensionality of size is the same as
* that of the dataspace of the dataset being changed.
*
* This function can be applied to the following datasets:
* \li Any dataset with unlimited dimensions
* \li A dataset with fixed dimensions if the current dimension sizes
* are less than the maximum sizes set with \c maxdims
* (see H5Screate_simple())
*
* Space on disk is immediately allocated for the new dataset extent if
* the dataset’s space allocation time is set to
* #H5D_ALLOC_TIME_EARLY. Fill values will be written to the dataset if
* the dataset’s fill time is set to #H5D_FILL_TIME_IFSET or
* #H5D_FILL_TIME_ALLOC. (See H5Pset_fill_time() and
* H5Pset_alloc_time().)
*
* This function ensures that the dataset dimensions are of at least
* the sizes specified in size. The function H5Dset_extent() must be
* used if the dataset dimension sizes are are to be reduced.
*
* \version 1.8.0 Function Function deprecated in this release. Parameter size
* syntax changed to \Code{const hsize_t size[]} in this release.
*
*/
H5_DLL herr_t H5Dextend(hid_t dset_id, const hsize_t size[]);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Reclaims variable-length (VL) datatype memory buffers
*
* \type_id
* \space_id
* \dxpl_id
* \param[in] buf Pointer to the buffer to be reclaimed
*
* \return \herr_t
*
* \deprecated This function has been deprecated in HDF5-1.12 in favor of the
* function H5Treclaim().
*
* \details H5Dvlen_reclaim() reclaims memory buffers created to store VL
* datatypes.
*
* The \p type_id must be the datatype stored in the buffer. The \p
* space_id describes the selection for the memory buffer to free the
* VL datatypes within. The \p dxpl_id is the dataset transfer property
* list which was used for the I/O transfer to create the buffer. And
* \p buf is the pointer to the buffer to be reclaimed.
*
* The VL structures (\ref hvl_t) in the user's buffer are modified to
* zero out the VL information after the memory has been reclaimed.
*
* If nested VL datatypes were used to create the buffer, this routine
* frees them from the bottom up, releasing all the memory without
* creating memory leaks.
*
* \version 1.12.0 Routine was deprecated
*
*/
H5_DLL herr_t H5Dvlen_reclaim(hid_t type_id, hid_t space_id, hid_t dxpl_id, void *buf);
#endif /* H5_NO_DEPRECATED_SYMBOLS */

33
src/H5ESmodule.h
View File

@ -29,4 +29,37 @@
#define H5_MY_PKG_ERR H5E_EVENTSET
#define H5_MY_PKG_INIT YES
/**
* \defgroup H5ES H5ES
* \brief Event Set Interface
*
* \details \Bold{This interface can be only used with the HDF5 VOL connectors that
* enable the asynchronous feature in HDF5.} The native HDF5 library has
* only synchronous operations.
*
* HDF5 VOL connectors with support for asynchronous operations:
* - ASYNC
* - DAOS
*
* \par Example:
* \code
* fid = H5Fopen(..);
* gid = H5Gopen(fid, ..); //Starts when H5Fopen completes
* did = H5Dopen(gid, ..); //Starts when H5Gopen completes
*
* es_id = H5EScreate(); // Create event set for tracking async operations
* status = H5Dwrite_async(did, .., es_id); //Asynchronous, starts when H5Dopen completes,
* // may run concurrently with other H5Dwrite_async
* // in event set.
* status = H5Dwrite_async(did, .., es_id); //Asynchronous, starts when H5Dopen completes,
* // may run concurrently with other H5Dwrite_async
* // in event set....
* <other user code>
* ...
* H5ESwait(es_id); // Wait for operations in event set to complete, buffers
* // used for H5Dwrite_async must only be changed after wait
* // returns.
* \endcode
*/
#endif /* H5ESmodule_H */

167
src/H5ESpublic.h
View File

@ -47,20 +47,24 @@ typedef enum H5ES_status_t {
H5ES_STATUS_FAIL /* An operation has completed, but failed */
} H5ES_status_t;
/* Information about failed operations in event set */
//! <!-- [H5ES_err_info_t_snip] -->
/**
* Information about failed operations in event set
*/
typedef struct H5ES_err_info_t {
/* Operation info */
char * api_name; /* Name of HDF5 API routine called */
char * api_args; /* "Argument string" for arguments to HDF5 API routine called */
char * app_file_name; /* Name of source file where the HDF5 API routine was called */
char * app_func_name; /* Name of function where the HDF5 API routine was called */
unsigned app_line_num; /* Line # of source file where the HDF5 API routine was called */
uint64_t op_ins_count; /* Counter of operation's insertion into event set */
uint64_t op_ins_ts; /* Timestamp for when the operation was inserted into the event set */
char * api_name; /**< Name of HDF5 API routine called */
char * api_args; /**< "Argument string" for arguments to HDF5 API routine called */
char * app_file_name; /**< Name of source file where the HDF5 API routine was called */
char * app_func_name; /**< Name of function where the HDF5 API routine was called */
unsigned app_line_num; /**< Line # of source file where the HDF5 API routine was called */
uint64_t op_ins_count; /**< Counter of operation's insertion into event set */
uint64_t op_ins_ts; /**< Timestamp for when the operation was inserted into the event set */
/* Error info */
hid_t err_stack_id; /* ID for error stack from failed operation */
hid_t err_stack_id; /**< ID for error stack from failed operation */
} H5ES_err_info_t;
//! <!-- [H5ES_err_info_t_snip] -->
/*
H5ES_op_info_t:
@ -119,14 +123,157 @@ How to Trace Async Operations?
extern "C" {
#endif
H5_DLL hid_t H5EScreate(void);
/**
* \ingroup H5ES
*
* \brief Creates an event set
*
* \returns \hid_ti{event set}
*
* \details H5EScreate() creates a new event set and returns a corresponding
* event set identifier.
*
* \since 1.13.0
*
*/
H5_DLL hid_t H5EScreate(void);
/**
* \ingroup H5ES
*
* \brief Waits for operations in event set to complete
*
* \es_id
* \param[in] timeout Total time in nanoseconds to wait for all operations in
* the event set to complete
* \param[out] num_in_progress The number of operations still in progress
* \param[out] err_occurred Flag if an operation in the event set failed
* \returns \herr_t
*
* \details H5ESwait() waits for operations in an event set \p es_id to wait
* with \p timeout.
*
* Timeout value is in nanoseconds, and is for the H5ESwait() call and
* not for each individual operation in the event set. For example, if
* "10" is passed as a timeout value and the event set waited 4
* nanoseconds for the first operation to complete, the remaining
* operations would be allowed to wait for at most 6 nanoseconds more,
* i.e., the timeout value used across all operations in the event set
* until it reaches 0, then any remaining operations are only checked
* for completion, not waited on.
*
* This call will stop waiting on operations and will return
* immediately if an operation fails. If a failure occurs, the value
* returned for the number of operations in progress may be inaccurate.
*
* \since 1.13.0
*
*/
H5_DLL herr_t H5ESwait(hid_t es_id, uint64_t timeout, size_t *num_in_progress, hbool_t *err_occurred);
/**
* \ingroup H5ES
*
* \brief Retrieves number of events in an event set
*
* \es_id
* \param[out] count The number of events in the event set
* \returns \herr_t
*
* \details H5ESget_count() retrieves number of events in an event set specified
* by \p es_id.
*
* \since 1.13.0
*
*/
H5_DLL herr_t H5ESget_count(hid_t es_id, size_t *count);
/**
* \ingroup H5ES
*
* \todo Fill in the blanks!
*
* \since 1.13.0
*
*/
H5_DLL herr_t H5ESget_op_counter(hid_t es_id, uint64_t *counter);
/**
* \ingroup H5ES
*
* \brief Checks for failed operations
*
* \es_id
* \param[out] err_occurred Status indicating if error is present in the event
* set
* \returns \herr_t
*
* \details H5ESget_err_status() checks if event set specified by es_id has
* failed operations.
*
* \since 1.13.0
*
*/
H5_DLL herr_t H5ESget_err_status(hid_t es_id, hbool_t *err_occurred);
/**
* \ingroup H5ES
*
* \brief Retrieves the number of failed operations
*
* \es_id
* \param[out] num_errs Number of errors
* \returns \herr_t
*
* \details H5ESget_err_count() retrieves the number of failed operations in an
* event set specified by \p es_id.
*
* The function does not wait for active operations to complete, so
* count may not include all failures.
*
* \since 1.13.0
*
*/
H5_DLL herr_t H5ESget_err_count(hid_t es_id, size_t *num_errs);
/**
* \ingroup H5ES
*
* \brief Retrieves information about failed operations
*
* \es_id
* \param[in] num_err_info The number of elements in \p err_info array
* \param[out] err_info Array of structures
* \param[out] err_cleared Number of cleared errors
* \returns \herr_t
*
* \details H5ESget_err_info() retrieves information about failed operations in
* an event set specified by \p es_id. The strings retrieved for each
* error info must be released by calling H5free_memory().
*
* Below is the description of the \ref H5ES_err_info_t structure:
* \snippet this H5ES_err_info_t_snip
* \click4more
*
* \since 1.13.0
*
*/
H5_DLL herr_t H5ESget_err_info(hid_t es_id, size_t num_err_info, H5ES_err_info_t err_info[],
size_t *err_cleared);
/**
* \ingroup H5ES
*
* \brief Terminates access to an event set
*
* \es_id
* \returns \herr_t
*
* \details H5ESclose() terminates access to an event set specified by \p es_id.
*
* \since 1.13.0
*
*/
H5_DLL herr_t H5ESclose(hid_t es_id);
#ifdef __cplusplus

29
src/H5Emodule.h
View File

@ -29,4 +29,33 @@
#define H5_MY_PKG_ERR H5E_ERROR
#define H5_MY_PKG_INIT YES
/**
* \defgroup H5E H5E
* \brief Error Handling Interface
*
* \details The Error interface provides error handling in the form of a stack.
* The \Code{FUNC_ENTER} macro clears the error stack whenever an
* interface function is entered. When an error is detected, an entry
* is pushed onto the stack. As the functions unwind, additional
* entries are pushed onto the stack. The API function will return some
* indication that an error occurred and the application can print the
* error stack.
*
* Certain API functions in the \c H5E package, such as H5Eprint1(), do
* not clear the error stack. Otherwise, any function which does not
* have an underscore immediately after the package name will clear the
* error stack. For instance, H5Fopen() clears the error stack while
* \Code{H5F_open} does not.
*
* An error stack has a fixed maximum size. If this size is exceeded
* then the stack will be truncated and only the inner-most functions
* will have entries on the stack. This is expected to be a rare
* condition.
*
* Each thread has its own error stack, but since multi-threading has
* not been added to the library yet, this package maintains a single
* error stack. The error stack is statically allocated to reduce the
* complexity of handling errors within the \c H5E package.
*/
#endif /* H5Emodule_H */

788
src/H5Epublic.h
View File

@ -26,18 +26,29 @@
/* Value for the default error stack */
#define H5E_DEFAULT (hid_t)0
/* Different kinds of error information */
/**
* Different kinds of error information
*/
typedef enum H5E_type_t { H5E_MAJOR, H5E_MINOR } H5E_type_t;
/* Information about an error; element of error stack */
/**
* Information about an error; element of error stack
*/
typedef struct H5E_error2_t {
hid_t cls_id; /*class ID */
hid_t maj_num; /*major error ID */
hid_t min_num; /*minor error number */
unsigned line; /*line in file where error occurs */
const char *func_name; /*function in which error occurred */
const char *file_name; /*file in which error occurred */
const char *desc; /*optional supplied description */
hid_t cls_id;
/**< Class ID */
hid_t maj_num;
/**< Major error ID */
hid_t min_num;
/**< Minor error number */
unsigned line;
/**< Line in file where error occurs */
const char *func_name;
/**< Function in which error occurred */
const char *file_name;
/**< File in which error occurred */
const char *desc;
/**< Optional supplied description */
} H5E_error2_t;
/* When this header is included from a private header, don't make calls to H5open() */
@ -138,10 +149,12 @@ H5_DLLVAR hid_t H5E_ERR_CLS_g;
goto label; \
}
/* Error stack traversal direction */
/**
* Error stack traversal direction
*/
typedef enum H5E_direction_t {
H5E_WALK_UPWARD = 0, /*begin deep, end at API function */
H5E_WALK_DOWNWARD = 1 /*begin at API function, end deep */
H5E_WALK_UPWARD = 0, /**< begin w/ most specific error, end at API function */
H5E_WALK_DOWNWARD = 1 /**< begin at API function, end w/ most specific error */
} H5E_direction_t;
#ifdef __cplusplus
@ -149,30 +162,498 @@ extern "C" {
#endif
/* Error stack traversal callback function pointers */
//! <!-- [H5E_walk2_t_snip] -->
/**
* \brief Callback function for H5Ewalk2()
*
* \param[in] n Indexed error position in the stack
* \param[in] err_desc Pointer to a data structure describing the error
* \param[in] client_data Pointer to client data in the format expected by the
* user-defined function
* \return \herr_t
*/
typedef herr_t (*H5E_walk2_t)(unsigned n, const H5E_error2_t *err_desc, void *client_data);
//! <!-- [H5E_walk2_t_snip] -->
//! <!-- [H5E_auto2_t_snip] -->
/**
* \brief Callback function for H5Eset_auto2()
*
* \estack_id{estack}
* \param[in] client_data Pointer to client data in the format expected by the
* user-defined function
* \return \herr_t
*/
typedef herr_t (*H5E_auto2_t)(hid_t estack, void *client_data);
//! <!-- [H5E_auto2_t_snip] -->
/* Public API functions */
H5_DLL hid_t H5Eregister_class(const char *cls_name, const char *lib_name, const char *version);
H5_DLL herr_t H5Eunregister_class(hid_t class_id);
H5_DLL herr_t H5Eclose_msg(hid_t err_id);
H5_DLL hid_t H5Ecreate_msg(hid_t cls, H5E_type_t msg_type, const char *msg);
H5_DLL hid_t H5Ecreate_stack(void);
H5_DLL hid_t H5Eget_current_stack(void);
H5_DLL herr_t H5Eappend_stack(hid_t dst_stack_id, hid_t src_stack_id, hbool_t close_source_stack);
H5_DLL herr_t H5Eclose_stack(hid_t stack_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5E
*
* \brief Registers a client library or application program to the HDF5 error API
*
* \param[in] cls_name Name of the error class
* \param[in] lib_name Name of the client library or application to which the error class belongs
* \param[in] version Version of the client library or application to which the
error class belongs. Can be \c NULL.
* \return Returns a class identifier on success; otherwise returns H5I_INVALID_ID.
*
* \details H5Eregister_class() registers a client library or application
* program to the HDF5 error API so that the client library or
* application program can report errors together with the HDF5
* library. It receives an identifier for this error class for further
* error operations. The library name and version number will be
* printed out in the error message as a preamble.
*
* \since 1.8.0
*/
H5_DLL hid_t H5Eregister_class(const char *cls_name, const char *lib_name, const char *version);
/**
* --------------------------------------------------------------------------
* \ingroup H5E
*
* \brief Removes an error class
*
* \param[in] class_id Error class identifier.
* \return \herr_t
*
* \details H5Eunregister_class() removes the error class specified by \p
* class_id. All the major and minor errors in this class will also be
* closed.
*
* \since 1.8.0
*/
H5_DLL herr_t H5Eunregister_class(hid_t class_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5E
*
* \brief Closes an error message
*
* \param[in] err_id An error message identifier
* \return \herr_t
*
* \details H5Eclose_msg() closes an error message identifier, which can be
* either a major or minor message.
*
* \since 1.8.0
*/
H5_DLL herr_t H5Eclose_msg(hid_t err_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5E
*
* \brief Adds a major error message to an error class
*
* \param[in] cls An error class identifier
* \param[in] msg_type The type of the error message
* \param[in] msg Major error message
* \return \herr_t
*
* \details H5Ecreate_msg() adds an error message to an error class defined by
* client library or application program. The error message can be
* either major or minor as indicated by the parameter \p msg_type.
*
* Use H5Eclose_msg() to close the message identifier returned by this
* function.
*
* \since 1.8.0
*/
H5_DLL hid_t H5Ecreate_msg(hid_t cls, H5E_type_t msg_type, const char *msg);
/**
* --------------------------------------------------------------------------
* \ingroup H5E
*
* \brief Creates a new, empty error stack
*
* \return \hid_ti{error stack}
*
* \details H5Ecreate_stack() creates a new empty error stack and returns the
* new stack’s identifier. Use H5Eclose_stack() to close the error stack
* identifier returned by this function.
*
* \since 1.8.0
*/
H5_DLL hid_t H5Ecreate_stack(void);
/**
* --------------------------------------------------------------------------
* \ingroup H5E
*
* \brief Returns a copy of the current error stack
*
* \return \hid_ti{error stack}
*
* \details H5Eget_current_stack() copies the current error stack and returns an
* error stack identifier for the new copy.
*
* \since 1.8.0
*/
H5_DLL hid_t H5Eget_current_stack(void);
/**
* --------------------------------------------------------------------------
* \ingroup H5E
*
* \brief Appends one error stack to another, optionally closing the source
* stack.
*
* \estack_id{dst_stack_id}
* \estack_id{src_stack_id}
* \param[in] close_source_stack Flag to indicate whether to close the source stack
* \return \herr_t
*
* \details H5Eappend_stack() appends the messages from error stack
* \p src_stack_id to the error stack \p dst_stack_id.
* If \p close_source_stack is \c TRUE, the source error stack
* will be closed.
*
* \since 1.8.0
*/
H5_DLL herr_t H5Eappend_stack(hid_t dst_stack_id, hid_t src_stack_id, hbool_t close_source_stack);
/**
* --------------------------------------------------------------------------
* \ingroup H5E
*
* \brief Closes an error stack handle
*
* \estack_id{stack_id}
*
* \return \herr_t
*
* \details H5Eclose_stack() closes the error stack handle \p stack_id
* and releases its resources. #H5E_DEFAULT cannot be closed.
*
* \since 1.8.0
*/
H5_DLL herr_t H5Eclose_stack(hid_t stack_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5E
*
* \brief Retrieves error class name
*
* \param[in] class_id Error class identifier
* \param[out] name Buffer for the error class name
* \param[in] size The maximum number of characters the class name to be returned
* by this function in\p name.
* \return Returns non-negative value as on success; otherwise returns negative value.
*
* \details H5Eget_class_name() retrieves the name of the error class specified
* by the class identifier. If non-NULL pointer is passed in for \p
* name and \p size is greater than zero, the class name of \p size
* long is returned. The length of the error class name is also
* returned. If NULL is passed in as \p name, only the length of class
* name is returned. If zero is returned, it means no name. The user is
* responsible for allocating sufficient buffer space for the name.
*
* \since 1.8.0
*/
H5_DLL ssize_t H5Eget_class_name(hid_t class_id, char *name, size_t size);
H5_DLL herr_t H5Eset_current_stack(hid_t err_stack_id);
H5_DLL herr_t H5Epush2(hid_t err_stack, const char *file, const char *func, unsigned line, hid_t cls_id,
hid_t maj_id, hid_t min_id, const char *msg, ...);
H5_DLL herr_t H5Epop(hid_t err_stack, size_t count);
H5_DLL herr_t H5Eprint2(hid_t err_stack, FILE *stream);
H5_DLL herr_t H5Ewalk2(hid_t err_stack, H5E_direction_t direction, H5E_walk2_t func, void *client_data);
H5_DLL herr_t H5Eget_auto2(hid_t estack_id, H5E_auto2_t *func, void **client_data);
H5_DLL herr_t H5Eset_auto2(hid_t estack_id, H5E_auto2_t func, void *client_data);
H5_DLL herr_t H5Eclear2(hid_t err_stack);
H5_DLL herr_t H5Eauto_is_v2(hid_t err_stack, unsigned *is_stack);
/**
* --------------------------------------------------------------------------
* \ingroup H5E
*
* \brief Replaces the current error stack
*
* \estack_id{err_stack_id}
*
* \return \herr_t
*
* \details H5Eset_current_stack() replaces the content of the current error
* stack with a copy of the content of the error stack specified by
* \p err_stack_id, and it closes the error stack specified by
* \p err_stack_id.
*
* \since 1.8.0
*/
H5_DLL herr_t H5Eset_current_stack(hid_t err_stack_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5E
*
* \brief Pushes a new error record onto an error stack
*
* \estack_id{err_stack}. If the identifier is #H5E_DEFAULT, the error record
* will be pushed to the current stack.
* \param[in] file Name of the file in which the error was detected
* \param[in] func Name of the function in which the error was detected
* \param[in] line Line number in the file where the error was detected
* \param[in] cls_id Error class identifier
* \param[in] maj_id Major error identifier
* \param[in] min_id Minor error identifier
* \param[in] msg Error description string
* \return \herr_t
*
* \details H5Epush2() pushes a new error record onto the error stack specified
* by \p err_stack.\n
* The error record contains the error class identifier \p cls_id, the
* major and minor message identifiers \p maj_id and \p min_id, the
* function name \p func where the error was detected, the file name \p
* file and line number \p line in the file where the error was
* detected, and an error description \p msg.\n
* The major and minor errors must be in the same error class.\n
* The function name, filename, and error description strings must be
* statically allocated.\n
* \p msg can be a format control string with additional
* arguments. This design of appending additional arguments is similar
* to the system and C functions printf() and fprintf().
*
* \since 1.8.0
*/
H5_DLL herr_t H5Epush2(hid_t err_stack, const char *file, const char *func, unsigned line, hid_t cls_id,
hid_t maj_id, hid_t min_id, const char *msg, ...);
/**
* --------------------------------------------------------------------------
* \ingroup H5E
*
* \brief Deletes specified number of error messages from the error stack
*
* \estack_id{err_stack}
* \param[in] count The number of error messages to be deleted from the top
* of error stack
* \return \herr_t
*
* \details H5Epop() deletes the number of error records specified in \p count
* from the top of the error stack specified by \p err_stack (including
* major, minor messages and description). The number of error messages
* to be deleted is specified by \p count.
*
* \since 1.8.0
*/
H5_DLL herr_t H5Epop(hid_t err_stack, size_t count);
/**
* --------------------------------------------------------------------------
* \ingroup H5E
*
* \brief Prints the specified error stack in a default manner
*
* \estack_id{err_stack}
* \param[in] stream File pointer, or \c NULL for \c stderr
* \return \herr_t
*
* \details H5Eprint2() prints the error stack specified by \p err_stack on the
* specified stream, \p stream. Even if the error stack is empty, a
* one-line message of the following form will be printed:
* \code{.unparsed}
* HDF5-DIAG: Error detected in HDF5 library version: 1.5.62 thread 0.
* \endcode
*
* A similar line will appear before the error messages of each error
* class stating the library name, library version number, and thread
* identifier.
*
* If \p err_stack is #H5E_DEFAULT, the current error stack will be
* printed.
*
* H5Eprint2() is a convenience function for H5Ewalk2() with a function
* that prints error messages. Users are encouraged to write their own
* more specific error handlers.
*
* \since 1.8.0
*/
H5_DLL herr_t H5Eprint2(hid_t err_stack, FILE *stream);
/**
* --------------------------------------------------------------------------
* \ingroup H5E
*
* \brief Walks the specified error stack, calling the specified function
*
* \estack_id{err_stack}
* \param[in] direction Direction in which the error stack is to be walked
* \param[in] func Function to be called for each error encountered
* \param[in] client_data Data to be passed to \p func
* \return \herr_t
*
* \details H5Ewalk2() walks the error stack specified by err_stack for the
* current thread and calls the function specified in \p func for each
* error along the way.
*
* If the value of \p err_stack is #H5E_DEFAULT, then H5Ewalk2() walks
* the current error stack.
*
* \p direction specifies whether the stack is walked from the inside
* out or the outside in. A value of #H5E_WALK_UPWARD means to begin
* with the most specific error and end at the API; a value of
* #H5E_WALK_DOWNWARD means to start at the API and end at the
* innermost function where the error was first detected.
*
* \p func, a function conforming to the #H5E_walk2_t prototype, will
* be called for each error in the error stack. Its arguments will
* include an index number \c n (beginning at zero regardless of stack
* traversal direction), an error stack entry \c err_desc, and the \c
* client_data pointer passed to H5Eprint(). The #H5E_walk2_t prototype
* is as follows:
* \snippet this H5E_walk2_t_snip
*
* \since 1.8.0
*/
H5_DLL herr_t H5Ewalk2(hid_t err_stack, H5E_direction_t direction, H5E_walk2_t func, void *client_data);
/**
* --------------------------------------------------------------------------
* \ingroup H5E
*
* \brief Returns the settings for the automatic error stack traversal
* function and its data
*
* \estack_id
* \param[out] func The function currently set to be called upon an error condition
* \param[out] client_data Data currently set to be passed to the error function
* \return \herr_t
*
* \details H5Eget_auto2() returns the settings for the automatic error stack
* traversal function, \p func, and its data, \p client_data, that are
* associated with the error stack specified by \p estack_id.
*
* Either or both of the \p func and \p client_data arguments may be
* \c NULL, in which case the value is not returned.
*
* The library initializes its default error stack traversal functions
* to H5Eprint1() and H5Eprint2(). A call to H5Eget_auto2() returns
* H5Eprint2() or the user-defined function passed in through
* H5Eset_auto2(). A call to H5Eget_auto1() returns H5Eprint1() or the
* user-defined function passed in through H5Eset_auto1(). However, if
* the application passes in a user-defined function through
* H5Eset_auto1(), it should call H5Eget_auto1() to query the traversal
* function. If the application passes in a user-defined function
* through H5Eset_auto2(), it should call H5Eget_auto2() to query the
* traversal function.
*
* Mixing the new style and the old style functions will cause a
* failure. For example, if the application sets a user-defined
* old-style traversal function through H5Eset_auto1(), a call to
* H5Eget_auto2() will fail and will indicate that the application has
* mixed H5Eset_auto1() and H5Eget_auto2(). On the other hand, mixing
* H5Eset_auto2() and H5Eget_auto1() will also cause a failure. But if
* the traversal functions are the library’s default H5Eprint1() or
* H5Eprint2(), mixing H5Eset_auto1() and H5Eget_auto2() or mixing
* H5Eset_auto2() and H5Eget_auto1() does not fail.
*
* \since 1.8.0
*/
H5_DLL herr_t H5Eget_auto2(hid_t estack_id, H5E_auto2_t *func, void **client_data);
/**
* --------------------------------------------------------------------------
* \ingroup H5E
*
* \brief Turns automatic error printing on or off
*
* \estack_id
* \param[in] func Function to be called upon an error condition
* \param[in] client_data Data passed to the error function
* \return \herr_t
*
* \details H5Eset_auto2() turns on or off automatic printing of errors for the
* error stack specified with \p estack_id. An \p estack_id value of
* #H5E_DEFAULT indicates the current stack.
*
* When automatic printing is turned on, by the use of a non-null \p func
* pointer, any API function which returns an error indication will
* first call \p func, passing it \p client_data as an argument.
*
* \p func, a function compliant with the #H5E_auto2_t prototype, is
* defined in the H5Epublic.h source code file as:
* \snippet this H5E_auto2_t_snip
*
* When the library is first initialized, the auto printing function is
* set to H5Eprint2() (cast appropriately) and \p client_data is the
* standard error stream pointer, \c stderr.
*
* Automatic stack traversal is always in the #H5E_WALK_DOWNWARD
* direction.
*
* Automatic error printing is turned off with a H5Eset_auto2() call
* with a \c NULL \p func pointer.
*
* \since 1.8.0
*/
H5_DLL herr_t H5Eset_auto2(hid_t estack_id, H5E_auto2_t func, void *client_data);
/**
* --------------------------------------------------------------------------
* \ingroup H5E
*
* \brief Clears the specified error stack or the error stack for the current thread
*
* \estack_id{err_stack}
* \return \herr_t
*
* \details H5Eclear2() clears the error stack specified by \p err_stack, or, if
* \p err_stack is set to #H5E_DEFAULT, the error stack for the current
* thread.
*
* \p err_stack is an error stack identifier, such as that returned by
* H5Eget_current_stack().
*
* The current error stack is also cleared whenever an API function is
* called, with certain exceptions (for instance, H5Eprint1() or
* H5Eprint2()).
*
* \since 1.8.0
*/
H5_DLL herr_t H5Eclear2(hid_t err_stack);
/**
* --------------------------------------------------------------------------
* \ingroup H5E
*
* \brief Determines the type of error stack
*
* \estack_id{err_stack}
* \param[out] is_stack A flag indicating which error stack \c typedef the
* specified error stack conforms to
*
* \return \herr_t
*
* \details H5Eauto_is_v2() determines whether the error auto reporting function
* for an error stack conforms to the #H5E_auto2_t \c typedef or the
* #H5E_auto1_t \c typedef.
*
* The \p is_stack parameter is set to 1 if the error stack conforms to
* #H5E_auto2_t and 0 if it conforms to #H5E_auto1_t.
*
* \since 1.8.0
*/
H5_DLL herr_t H5Eauto_is_v2(hid_t err_stack, unsigned *is_stack);
/**
* --------------------------------------------------------------------------
* \ingroup H5E
*
* \brief Retrieves an error message
*
* \param[in] msg_id Error message identifier
* \param[out] type The type of the error message Valid values are #H5E_MAJOR
* and #H5E_MINOR.
* \param[out] msg Error message buffer
* \param[in] size The length of error message to be returned by this function
* \return Returns the size of the error message in bytes on success; otherwise
* returns a negative value.
*
* \details H5Eget_msg() retrieves the error message including its length and
* type. The error message is specified by \p msg_id. The user is
* responsible for passing in sufficient buffer space for the
* message. If \p msg is not NULL and \p size is greater than zero, the
* error message of \p size long is returned. The length of the message
* is also returned. If NULL is passed in as \p msg, only the length
* and type of the message is returned. If the return value is zero, it
* means there is no message.
*
* \since 1.8.0
*/
H5_DLL ssize_t H5Eget_msg(hid_t msg_id, H5E_type_t *type, char *msg, size_t size);
/**
* --------------------------------------------------------------------------
* \ingroup H5E
*
* \brief Retrieves the number of error messages in an error stack
*
* \estack_id{error_stack_id}
* \return Returns a non-negative value on success; otherwise returns a negative value.
*
* \details H5Eget_num() retrieves the number of error records in the error
* stack specified by \p error_stack_id (including major, minor
* messages and description).
*
* \since 1.8.0
*/
H5_DLL ssize_t H5Eget_num(hid_t error_stack_id);
/* Symbols defined for compatibility with previous versions of the HDF5 API.
@ -189,30 +670,259 @@ H5_DLL ssize_t H5Eget_num(hid_t error_stack_id);
typedef hid_t H5E_major_t;
typedef hid_t H5E_minor_t;
/* Information about an error element of error stack. */
/**
* Information about an error element of error stack.
*/
typedef struct H5E_error1_t {
H5E_major_t maj_num; /*major error number */
H5E_minor_t min_num; /*minor error number */
const char *func_name; /*function in which error occurred */
const char *file_name; /*file in which error occurred */
unsigned line; /*line in file where error occurs */
const char *desc; /*optional supplied description */
H5E_major_t maj_num; /**< major error number */
H5E_minor_t min_num; /**< minor error number */
const char *func_name; /**< function in which error occurred */
const char *file_name; /**< file in which error occurred */
unsigned line; /**< line in file where error occurs */
const char *desc; /**< optional supplied description */
} H5E_error1_t;
/* Error stack traversal callback function pointers */
//! <!-- [H5E_walk1_t_snip] -->
/**
* \brief Callback function for H5Ewalk1()
*
* \param[in] n Indexed error position in the stack
* \param[in] err_desc Pointer to a data structure describing the error
* \param[in] client_data Pointer to client data in the format expected by the
* user-defined function
* \return \herr_t
*/
typedef herr_t (*H5E_walk1_t)(int n, H5E_error1_t *err_desc, void *client_data);
//! <!-- [H5E_walk1_t_snip] -->
//! <!-- [H5E_auto1_t_snip] -->
/**
* \brief Callback function for H5Eset_auto1()
*
* \param[in] client_data Pointer to client data in the format expected by the
* user-defined function
* \return \herr_t
*/
typedef herr_t (*H5E_auto1_t)(void *client_data);
//! <!-- [H5E_auto1_t_snip] -->
/* Function prototypes */
/**
* --------------------------------------------------------------------------
* \ingroup H5E
*
* \brief Clears the error stack for the current thread
*
* \return \herr_t
*
* \details H5Eclear1() clears the error stack for the current thread.\n
* The stack is also cleared whenever an API function is called, with
* certain exceptions (for instance, H5Eprint1()).
*
* \deprecated 1.8.0 Function H5Eclear() renamed to H5Eclear1() and deprecated
* in this release.
*/
H5_DLL herr_t H5Eclear1(void);
/**
* --------------------------------------------------------------------------
* \ingroup H5E
*
* \brief Returns the current settings for the automatic error stack traversal
* function and its data
*
* \param[out] func Current setting for the function to be called upon an error
* condition
* \param[out] client_data Current setting for the data passed to the error
* function
* \return \herr_t
*
* \details H5Eget_auto1() returns the current settings for the automatic error
* stack traversal function, \p func, and its data,
* \p client_data. Either or both arguments may be \c NULL, in which case the
* value is not returned.
*
* The library initializes its default error stack traversal functions
* to H5Eprint1() and H5Eprint2(). A call to H5Eget_auto2() returns
* H5Eprint2() or the user-defined function passed in through
* H5Eset_auto2(). A call to H5Eget_auto1() returns H5Eprint1() or the
* user-defined function passed in through H5Eset_auto1(). However, if
* the application passes in a user-defined function through
* H5Eset_auto1(), it should call H5Eget_auto1() to query the traversal
* function. If the application passes in a user-defined function
* through H5Eset_auto2(), it should call H5Eget_auto2() to query the
* traversal function.
*
* Mixing the new style and the old style functions will cause a
* failure. For example, if the application sets a user-defined
* old-style traversal function through H5Eset_auto1(), a call to
* H5Eget_auto2() will fail and will indicate that the application has
* mixed H5Eset_auto1() and H5Eget_auto2(). On the other hand, mixing
* H5Eset_auto2() and H5Eget_auto1() will also cause a failure. But if
* the traversal functions are the library’s default H5Eprint1() or
* H5Eprint2(), mixing H5Eset_auto1() and H5Eget_auto2() or mixing
* H5Eset_auto2() and H5Eget_auto1() does not fail.
*
* \deprecated 1.8.0 Function H5Eget_auto() renamed to H5Eget_auto1() and
* deprecated in this release.
*/
H5_DLL herr_t H5Eget_auto1(H5E_auto1_t *func, void **client_data);
/**
* --------------------------------------------------------------------------
* \ingroup H5E
*
* \brief Pushes a new error record onto the error stack
*
* \param[in] file Name of the file in which the error was detected
* \param[in] func Name of the function in which the error was detected
* \param[in] line Line number in the file where the error was detected
* \param[in] maj Major error identifier
* \param[in] min Minor error identifier
* \param[in] str Error description string
* \return \herr_t
*
* \details H5Epush1() pushes a new error record onto the error stack for the
* current thread.\n
* The error has major and minor numbers \p maj_num
* and \p min_num, the function \p func where the error was detected, the
* name of the file \p file where the error was detected, the line \p line
* within that file, and an error description string \p str.\n
* The function name, filename, and error description strings must be statically
* allocated.
*
* \since 1.4.0
* \deprecated 1.8.0 Function H5Epush() renamed to H5Epush1() and
* deprecated in this release.
*/
H5_DLL herr_t H5Epush1(const char *file, const char *func, unsigned line, H5E_major_t maj, H5E_minor_t min,
const char *str);
/**
* --------------------------------------------------------------------------
* \ingroup H5E
*
* \brief Prints the current error stack in a default manner
*
* \param[in] stream File pointer, or \c NULL for \c stderr
* \return \herr_t
*
* \details H5Eprint1() prints prints the error stack for the current thread
* on the specified stream, \p stream. Even if the error stack is empty, a
* one-line message of the following form will be printed:
* \code{.unparsed}
* HDF5-DIAG: Error detected in thread 0.
* \endcode
* H5Eprint1() is a convenience function for H5Ewalk1() with a function
* that prints error messages. Users are encouraged to write their own
* more specific error handlers.
*
* \deprecated 1.8.0 Function H5Eprint() renamed to H5Eprint1() and
* deprecated in this release.
*/
H5_DLL herr_t H5Eprint1(FILE *stream);
/**
* --------------------------------------------------------------------------
* \ingroup H5E
*
* \brief Turns automatic error printing on or off
*
* \param[in] func Function to be called upon an error condition
* \param[in] client_data Data passed to the error function
* \return \herr_t
*
* \details H5Eset_auto1() turns on or off automatic printing of errors. When
* turned on (non-null \p func pointer), any API function which returns
* an error indication will first call \p func, passing it \p
* client_data as an argument.
*
* \p func, a function conforming to the #H5E_auto1_t prototype, is
* defined in the H5Epublic.h source code file as:
* \snippet this H5E_auto1_t_snip
*
* When the library is first initialized, the auto printing function is
* set to H5Eprint1() (cast appropriately) and \p client_data is the
* standard error stream pointer, \c stderr.
*
* Automatic stack traversal is always in the #H5E_WALK_DOWNWARD
* direction.
*
* \deprecated 1.8.0 Function H5Eset_auto() renamed to H5Eset_auto1() and
* deprecated in this release.
*/
H5_DLL herr_t H5Eset_auto1(H5E_auto1_t func, void *client_data);
/**
* --------------------------------------------------------------------------
* \ingroup H5E
*
* \brief Walks the current error stack, calling the specified function
*
* \param[in] direction Direction in which the error stack is to be walked
* \param[in] func Function to be called for each error encountered
* \param[in] client_data Data to be passed to \p func
* \return \herr_t
*
* \details H5Ewalk1() walks the error stack for the current thread and calls
* the function specified in \p func for each error along the way.
*
* \p direction specifies whether the stack is walked from the inside
* out or the outside in. A value of #H5E_WALK_UPWARD means to begin
* with the most specific error and end at the API; a value of
* #H5E_WALK_DOWNWARD means to start at the API and end at the
* innermost function where the error was first detected.
*
* \p func, a function conforming to the #H5E_walk1_t prototype, will
* be called for each error in the error stack. Its arguments will
* include an index number \c n (beginning at zero regardless of stack
* traversal direction), an error stack entry \c err_desc, and the \c
* client_data pointer passed to H5Eprint(). The #H5E_walk1_t prototype
* is as follows:
* \snippet this H5E_walk1_t_snip
*
* \deprecated 1.8.0 Function H5Ewalk() renamed to H5Ewalk1() and
* deprecated in this release.
*/
H5_DLL herr_t H5Ewalk1(H5E_direction_t direction, H5E_walk1_t func, void *client_data);
H5_DLL char * H5Eget_major(H5E_major_t maj);
H5_DLL char * H5Eget_minor(H5E_minor_t min);
/**
* --------------------------------------------------------------------------
* \ingroup H5E
*
* \brief Returns a character string describing an error specified by a major
* error number
*
* \param[in] maj Major error number
* \return \herr_t
*
* \details Given a major error number, H5Eget_major() returns a constant
* character string that describes the error.
*
* \attention This function returns a dynamically allocated string (\c char
* array). An application calling this function must free the memory
* associated with the return value to prevent a memory leak.
*
* \deprecated 1.8.0 Function deprecated in this release.
*/
H5_DLL char *H5Eget_major(H5E_major_t maj);
/**
* --------------------------------------------------------------------------
* \ingroup H5E
*
* \brief Returns a character string describing an error specified by a minor
* error number
*
* \param[in] min Minor error number
* \return \herr_t
*
* \details Given a minor error number, H5Eget_minor() returns a constant
* character string that describes the error.
*
* \attention In the Release 1.8.x series, H5Eget_minor() returns a string of
* dynamic allocated \c char array. An application calling this
* function from an HDF5 library of Release 1.8.0 or later must free
* the memory associated with the return value to prevent a memory
* leak. This is a change from the 1.6.x release series.
*
* \deprecated 1.8.0 Function deprecated and return type changed in this release.
*/
H5_DLL char *H5Eget_minor(H5E_minor_t min);
#endif /* H5_NO_DEPRECATED_SYMBOLS */
#ifdef __cplusplus

64
src/H5FDcore.h
View File

@ -25,8 +25,70 @@
#ifdef __cplusplus
extern "C" {
#endif
H5_DLL hid_t H5FD_core_init(void);
H5_DLL hid_t H5FD_core_init(void);
/**
* \ingroup FAPL
*
* \brief Modifies the file access property list to use the #H5FD_CORE driver
*
* \fapl_id
* \param[in] increment Size, in bytes, of memory increments
* \param[in] backing_store Boolean flag indicating whether to write the file
* contents to disk when the file is closed
* \returns \herr_t
*
* \details H5Pset_fapl_core() modifies the file access property list to use the
* #H5FD_CORE driver.
*
* The #H5FD_CORE driver enables an application to work with a file in
* memory, speeding reads and writes as no disk access is made. File
* contents are stored only in memory until the file is closed. The \p
* backing_store parameter determines whether file contents are ever
* written to disk.
*
* \p increment specifies the increment by which allocated memory is to
* be increased each time more memory is required.
*
* While using H5Fcreate() to create a core file, if the \p
* backing_store is set to 1 (TRUE), the file contents are flushed to a
* file with the same name as this core file when the file is closed or
* access to the file is terminated in memory.
*
* The application is allowed to open an existing file with #H5FD_CORE
* driver. While using H5Fopen() to open an existing file, if the \p
* backing_store is set to 1 (TRUE) and the \c flags for H5Fopen() is set to
* #H5F_ACC_RDWR, any change to the file contents are saved to the file
* when the file is closed. If \p backing_store is set to 0 (FALSE) and the \c
* flags for H5Fopen() is set to #H5F_ACC_RDWR, any change to the file
* contents will be lost when the file is closed. If the flags for
* H5Fopen() is set to #H5F_ACC_RDONLY, no change to the file is
* allowed either in memory or on file.
*
* \note Currently this driver cannot create or open family or multi files.
*
* \since 1.4.0
*
*/
H5_DLL herr_t H5Pset_fapl_core(hid_t fapl_id, size_t increment, hbool_t backing_store);
/**
* \ingroup FAPL
*
* \brief Queries core file driver properties
*
* \fapl_id
* \param[out] increment Size, in bytes, of memory increments
* \param[out] backing_store Boolean flag indicating whether to write the file
* contents to disk when the file is closed
* \returns \herr_t
*
* \details H5Pget_fapl_core() queries the #H5FD_CORE driver properties as set
* by H5Pset_fapl_core().
*
* \since 1.4.0
*
*/
H5_DLL herr_t H5Pget_fapl_core(hid_t fapl_id, size_t *increment /*out*/, hbool_t *backing_store /*out*/);
#ifdef __cplusplus
}

63
src/H5FDdirect.h
View File

@ -37,8 +37,69 @@ extern "C" {
#define FBSIZE_DEF 4096
#define CBSIZE_DEF 16 * 1024 * 1024
H5_DLL hid_t H5FD_direct_init(void);
H5_DLL hid_t H5FD_direct_init(void);
/**
* \ingroup FAPL
*
* \brief Sets up use of the direct I/O driver
*
* \fapl_id
* \param[in] alignment Required memory alignment boundary
* \param[in] block_size File system block size
* \param[in] cbuf_size Copy buffer size
* \returns \herr_t
*
* \details H5Pset_fapl_direct() sets the file access property list, \p fapl_id,
* to use the direct I/O driver, #H5FD_DIRECT. With this driver, data
* is written to or read from the file synchronously without being
* cached by the system.
*
* File systems usually require the data address in memory, the file
* address, and the size of the data to be aligned. The HDF5 library’s
* direct I/O driver is able to handle unaligned data, though that will
* consume some additional memory resources and may slow
* performance. To get better performance, use the system function \p
* posix_memalign to align the data buffer in memory and the HDF5
* function H5Pset_alignment() to align the data in the file. Be aware,
* however, that aligned data I/O may cause the HDF5 file to be bigger
* than the actual data size would otherwise require because the
* alignment may leave some holes in the file.
*
* \p alignment specifies the required alignment boundary in memory.
*
* \p block_size specifies the file system block size. A value of 0
* (zero) means to use HDF5 library’s default value of 4KB.
*
* \p cbuf_size specifies the copy buffer size.
*
* \since 1.8.0
*
*/
H5_DLL herr_t H5Pset_fapl_direct(hid_t fapl_id, size_t alignment, size_t block_size, size_t cbuf_size);
/**
* \ingroup FAPL
*
* \brief Retrieves direct I/O driver settings
*
* \fapl_id
* \param[out] boundary Required memory alignment boundary
* \param[out] block_size File system block size
* \param[out] cbuf_size Copy buffer size
* \returns \herr_t
*
* \details H5Pget_fapl_direct() retrieves the required memory alignment (\p
* alignment), file system block size (\p block_size), and copy buffer
* size (\p cbuf_size) settings for the direct I/O driver, #H5FD_DIRECT,
* from the file access property list \p fapl_id.
*
* See H5Pset_fapl_direct() for discussion of these values,
* requirements, and important considerations.
*
* \since 1.8.0
*
*/
H5_DLL herr_t H5Pget_fapl_direct(hid_t fapl_id, size_t *boundary /*out*/, size_t *block_size /*out*/,
size_t *cbuf_size /*out*/);

52
src/H5FDfamily.h
View File

@ -26,8 +26,58 @@
extern "C" {
#endif
H5_DLL hid_t H5FD_family_init(void);
H5_DLL hid_t H5FD_family_init(void);
/**
* \ingroup FAPL
*
* \brief Sets the file access property list to use the family driver
*
* \fapl_id
* \param[in] memb_size Size in bytes of each file member
* \param[in] memb_fapl_id Identifier of file access property list for
* each family member
* \returns \herr_t
*
* \details H5Pset_fapl_family() sets the file access property list identifier,
* \p fapl_id, to use the family driver.
*
* \p memb_size is the size in bytes of each file member. This size
* will be saved in file when the property list \p fapl_id is used to
* create a new file. If \p fapl_id is used to open an existing file,
* \p memb_size has to be equal to the original size saved in file. A
* failure with an error message indicating the correct member size
* will be returned if \p memb_size does not match the size saved. If
* any user does not know the original size, #H5F_FAMILY_DEFAULT can be
* passed in. The library will retrieve the saved size.
*
* \p memb_fapl_id is the identifier of the file access property list
* to be used for each family member.
*
* \version 1.8.0 Behavior of the \p memb_size parameter was changed.
* \since 1.4.0
*
*/
H5_DLL herr_t H5Pset_fapl_family(hid_t fapl_id, hsize_t memb_size, hid_t memb_fapl_id);
/**
* \ingroup FAPL
*
* \brief Returns file access property list information
*
* \fapl_id
* \param[out] memb_size Size in bytes of each file member
* \param[out] memb_fapl_id Identifier of file access property list for
* each family member
* \returns \herr_t
*
* \details H5Pget_fapl_family() returns file access property list for use with
* the family driver. This information is returned through the output
* parameters.
*
* \since 1.4.0
*
*/
H5_DLL herr_t H5Pget_fapl_family(hid_t fapl_id, hsize_t *memb_size /*out*/, hid_t *memb_fapl_id /*out*/);
#ifdef __cplusplus

14
src/H5FDhdfs.h
View File

@ -112,8 +112,20 @@ typedef struct H5FD_hdfs_fapl_t {
int32_t stream_buffer_size;
} H5FD_hdfs_fapl_t;
H5_DLL hid_t H5FD_hdfs_init(void);
H5_DLL hid_t H5FD_hdfs_init(void);
/**
* \ingroup FAPL
*
* \todo Add missing documentation
*/
H5_DLL herr_t H5Pget_fapl_hdfs(hid_t fapl_id, H5FD_hdfs_fapl_t *fa_out);
/**
* \ingroup FAPL
*
* \todo Add missing documentation
*/
H5_DLL herr_t H5Pset_fapl_hdfs(hid_t fapl_id, H5FD_hdfs_fapl_t *fa);
#ifdef __cplusplus

405
src/H5FDlog.h
View File

@ -65,7 +65,410 @@
extern "C" {
#endif
H5_DLL hid_t H5FD_log_init(void);
H5_DLL hid_t H5FD_log_init(void);
/**
* \ingroup FAPL
*
* \brief Sets up the logging virtual file driver (#H5FD_LOG) for use
*
* \fapl_id
* \param[in] logfile Name of the log file
* \param[in] flags Flags specifying the types of logging activity
* \param[in] buf_size The size of the logging buffers, in bytes (see description)
* \returns \herr_t
*
* \details H5Pset_fapl_log() modifies the file access property list to use the
* logging driver, #H5FD_LOG. The logging virtual file driver (VFD) is
* a clone of the standard SEC2 (#H5FD_SEC2) driver with additional
* facilities for logging VFD metrics and activity to a file.
*
* \p logfile is the name of the file in which the logging entries are
* to be recorded.
*
* The actions to be logged are specified in the parameter \p flags
* using the pre-defined constants described in the following
* table. Multiple flags can be set through the use of a logical \c OR
* contained in parentheses. For example, logging read and write
* locations would be specified as
* \Code{(H5FD_LOG_LOC_READ|H5FD_LOG_LOC_WRITE)}.
*
* <table>
* <caption>Table1: Logging Flags</caption>
* <tr>
* <td>
* #H5FD_LOG_LOC_READ
* </td>
* <td rowspan="3">
* Track the location and length of every read, write, or seek operation.
* </td>
* </tr>
* <tr><td>#H5FD_LOG_LOC_WRITE</td></tr>
* <tr><td>#H5FD_LOG_LOC_SEEK</td></tr>
* <tr>
* <td>
* #H5FD_LOG_LOC_IO
* </td>
* <td>
* Track all I/O locations and lengths. The logical equivalent of the following:
* \Code{(#H5FD_LOG_LOC_READ | #H5FD_LOG_LOC_WRITE | #H5FD_LOG_LOC_SEEK)}
* </td>
* </tr>
* <tr>
* <td>
* #H5FD_LOG_FILE_READ
* </td>
* <td rowspan="2">
* Track the number of times each byte is read or written.
* </td>
* </tr>
* <tr><td>#H5FD_LOG_FILE_WRITE</td></tr>
* <tr>
* <td>
* #H5FD_LOG_FILE_IO
* </td>
* <td>
* Track the number of times each byte is read and written. The logical
* equivalent of the following:
* \Code{(#H5FD_LOG_FILE_READ | #H5FD_LOG_FILE_WRITE)}
* </td>
* </tr>
* <tr>
* <td>
* #H5FD_LOG_FLAVOR
* </td>
* <td>
* Track the type, or flavor, of information stored at each byte.
* </td>
* </tr>
* <tr>
* <td>
* #H5FD_LOG_NUM_READ
* </td>
* <td rowspan="4">
* Track the total number of read, write, seek, or truncate operations that occur.
* </td>
* </tr>
* <tr><td>#H5FD_LOG_NUM_WRITE</td></tr>
* <tr><td>#H5FD_LOG_NUM_SEEK</td></tr>
* <tr><td>#H5FD_LOG_NUM_TRUNCATE</td></tr>
* <tr>
* <td>
* #H5FD_LOG_NUM_IO
* </td>
* <td>
* Track the total number of all types of I/O operations. The logical equivalent
* of the following:
* \Code{(#H5FD_LOG_NUM_READ | #H5FD_LOG_NUM_WRITE | #H5FD_LOG_NUM_SEEK | #H5FD_LOG_NUM_TRUNCATE)}
* </td>
* </tr>
* <tr>
* <td>
* #H5FD_LOG_TIME_OPEN
* </td>
* <td rowspan="6">
* Track the time spent in open, stat, read, write, seek, or close operations.
* </td>
* </tr>
* <tr><td>#H5FD_LOG_TIME_STAT</td></tr>
* <tr><td>#H5FD_LOG_TIME_READ</td></tr>
* <tr><td>#H5FD_LOG_TIME_WRITE</td></tr>
* <tr><td>#H5FD_LOG_TIME_SEEK</td></tr>
* <tr><td>#H5FD_LOG_TIME_CLOSE</td></tr>
* <tr>
* <td>
* #H5FD_LOG_TIME_IO
* </td>
* <td>
* Track the time spent in each of the above operations. The logical equivalent
* of the following:
* \Code{(#H5FD_LOG_TIME_OPEN | #H5FD_LOG_TIME_STAT | #H5FD_LOG_TIME_READ | #H5FD_LOG_TIME_WRITE |
* #H5FD_LOG_TIME_SEEK | #H5FD_LOG_TIME_CLOSE)}
* </td>
* </tr>
* <tr>
* <td>
* #H5FD_LOG_ALLOC
* </td>
* <td>
* Track the allocation of space in the file.
* </td>
* </tr>
* <tr>
* <td>
* #H5FD_LOG_ALL
* </td>
* <td>
* Track everything. The logical equivalent of the following:
* \Code{(#H5FD_LOG_ALLOC | #H5FD_LOG_TIME_IO | #H5FD_LOG_NUM_IO | #H5FD_LOG_FLAVOR | #H5FD_LOG_FILE_IO |
* #H5FD_LOG_LOC_IO)}
* </td>
* </tr>
* </table>
* The logging driver can track the number of times each byte in the file is
* read from or written to (using #H5FD_LOG_FILE_READ and #H5FD_LOG_FILE_WRITE)
* and what kind of data is at that location (e.g., metadata, raw data; using
* #H5FD_LOG_FLAVOR). This information is tracked in internal buffers of size
* buf_size, which must be at least the maximum size in bytes of the file to be
* logged while the log driver is in use.\n
* One buffer of size buf_size will be created for each of #H5FD_LOG_FILE_READ,
* #H5FD_LOG_FILE_WRITE and #H5FD_LOG_FLAVOR when those flags are set; these
* buffers will not grow as the file increases in size.
*
* \par Output:
* This section describes the logging driver (LOG VFD) output.\n
* The table, immediately below, describes output of the various logging driver
* flags and function calls. A list of valid flavor values, describing the type
* of data stored, follows the table.
* <table>
* <caption>Table2: Logging Output</caption>
* <tr>
* <th>Flag</th><th>VFD Call</th><th>Output and Comments</th>
* </th>
* </tr>
* <tr>
* <td>#H5FD_LOG_LOC_READ</td>
* <td>Read</td>
* <td>
* \Code{%10a-%10a (%10Zu bytes) (%s) Read}\n\n
* Start position\n
* End position\n
* Number of bytes\n
* Flavor of read\n\n
* Adds \Code{(\%f s)} and seek time if #H5FD_LOG_TIME_SEEK is also set.
* </td>
* </tr>
* <tr>
* <td>#H5FD_LOG_LOC_READ</td>
* <td>Read Error</td>
* <td>
* \Code{Error! Reading: %10a-%10a (%10Zu bytes)}\n\n
* Same parameters as non-error entry.
* </td>
* </tr>
* <tr>
* <td>#H5FD_LOG_LOC_WRITE</td>
* <td>Write</td>
* <td>
* \Code{%10a-%10a (%10Zu bytes) (%s) Written}\n\n
* Start position\n
* End position\n
* Number of bytes\n
* Flavor of write\n\n
* Adds \Code{(\%f s)} and seek time if #H5FD_LOG_TIME_SEEK is also set.
* </td>
* </tr>
* <tr>
* <td>#H5FD_LOG_LOC_WRITE</td>
* <td>Write Error</td>
* <td>
* \Code{Error! Writing: %10a-%10a (%10Zu bytes)}\n\n
* Same parameters as non-error entry.
* </td>
* </tr>
* <tr>
* <td>#H5FD_LOG_LOC_SEEK</td>
* <td>Read, Write</td>
* <td>
* \Code{Seek: From %10a-%10a}\n\n
* Start position\n
* End position\n\n
* Adds \Code{(\%f s)} and seek time if #H5FD_LOG_TIME_SEEK is also set.
* </td>
* </tr>
* <tr>
* <td>#H5FD_LOG_FILE_READ</td>
* <td>Close</td>
* <td>
* Begins with:\n
* Dumping read I/O information\n\n
* Then, for each range of identical values, there is this line:\n
* \Code{Addr %10-%10 (%10lu bytes) read from %3d times}\n\n
* Start address\n
* End address\n
* Number of bytes\n
* Number of times read\n\n
* Note: The data buffer is scanned and each range of identical values
* gets one entry in the log file to save space and make it easier to read.
* </td>
* </tr>
* <tr>
* <td>#H5FD_LOG_FILE_WRITE</td>
* <td>Close</td>
* <td>
* Begins with:\n
* Dumping read I/O information\n\n
* Then, for each range of identical values, there is this line:\n
* \Code{Addr %10-%10 (%10lu bytes) written to %3d times}\n\n
* Start address\n
* End address\n
* Number of bytes\n
* Number of times written\n\n
* Note: The data buffer is scanned and each range of identical values
* gets one entry in the log file to save space and make it easier to read.
* </td>
* </tr>
* <tr>
* <td>#H5FD_LOG_FLAVOR</td>
* <td>Close</td>
* <td>
* Begins with:\n
* Dumping I/O flavor information\n\n
* Then, for each range of identical values, there is this line:\n
* \Code{Addr %10-%10 (%10lu bytes) flavor is %s}\n\n
* Start address\n
* End address\n
* Number of bytes\n
* Flavor\n\n
* Note: The data buffer is scanned and each range of identical values
* gets one entry in the log file to save space and make it easier to read.
* </td>
* </tr>
* <tr>
* <td>#H5FD_LOG_NUM_READ</td>
* <td>Close</td>
* <td>
* Total number of read operations: \Code{%11u}
* </td>
* </tr>
* <tr>
* <td>#H5FD_LOG_NUM_WRITE</td>
* <td>Close</td>
* <td>
* Total number of write operations: \Code{%11u}
* </td>
* </tr>
* <tr>
* <td>#H5FD_LOG_NUM_SEEK</td>
* <td>Close</td>
* <td>
* Total number of seek operations: \Code{%11u}
* </td>
* </tr>
* <tr>
* <td>#H5FD_LOG_NUM_TRUNCATE</td>
* <td>Close</td>
* <td>
* Total number of truncate operations: \Code{%11u}
* </td>
* </tr>
* <tr>
* <td>#H5FD_LOG_TIME_OPEN</td>
* <td>Open</td>
* <td>
* Open took: \Code{(\%f s)}
* </td>
* </tr>
* <tr>
* <td>#H5FD_LOG_TIME_READ</td>
* <td>Close, Read</td>
* <td>
* Total time in read operations: \Code{\%f s}\n\n
* See also: #H5FD_LOG_LOC_READ
* </td>
* </tr>
* </tr>
* <tr>
* <td>#H5FD_LOG_TIME_WRITE</td>
* <td>Close, Write</td>
* <td>
* Total time in write operations: \Code{\%f s}\n\n
* See also: #H5FD_LOG_LOC_WRITE
* </td>
* </tr>
* <tr>
* <td>#H5FD_LOG_TIME_SEEK</td>
* <td>Close, Read, Write</td>
* <td>
* Total time in write operations: \Code{\%f s}\n\n
* See also: #H5FD_LOG_LOC_SEEK or #H5FD_LOG_LOC_WRITE
* </td>
* </tr>
* <tr>
* <td>#H5FD_LOG_TIME_CLOSE</td>
* <td>Close</td>
* <td>
* Close took: \Code{(\%f s)}
* </td>
* </tr>
* <tr>
* <td>#H5FD_LOG_TIME_STAT</td>
* <td>Open</td>
* <td>
* Stat took: \Code{(\%f s)}
* </td>
* </tr>
* <tr>
* <td>#H5FD_LOG_ALLOC</td>
* <td>Alloc</td>
* <td>
* \Code{%10-%10 (%10Hu bytes) (\%s) Allocated}\n\n
* Start of address space\n
* End of address space\n
* Total size allocation\n
* Flavor of allocation
* </td>
* </tr>
* </table>
*
* \par Flavors:
* The \Emph{flavor} describes the type of stored information. The following
* table lists the flavors that appear in log output and briefly describes each.
* These terms are provided here to aid in the construction of log message
* parsers; a full description is beyond the scope of this document.
* <table>
* <caption>Table3: Flavors of logged data</caption>
* <tr>
* <th>Flavor</th><th>Description</th>
* </th>
* </tr>
* <tr>
* <td>#H5FD_MEM_NOLIST</td>
* <td>Error value</td>
* </tr>
* <tr>
* <td>#H5FD_MEM_DEFAULT</td>
* <td>Value not yet set.\n
* May also be a datatype set in a larger allocation that will be
* suballocated by the library.</td>
* </tr>
* <tr>
* <td>#H5FD_MEM_SUPER</td>
* <td>Superblock data</td>
* </tr>
* <tr>
* <td>#H5FD_MEM_BTREE</td>
* <td>B-tree data</td>
* </tr>
* <tr>
* <td>#H5FD_MEM_DRAW</td>
* <td>Raw data (for example, contents of a dataset)</td>
* </tr>
* <tr>
* <td>#H5FD_MEM_GHEAP</td>
* <td>Global heap data</td>
* </tr>
* <tr>
* <td>#H5FD_MEM_LHEAP</td>
* <td>Local heap data</td>
* </tr>
* <tr>
* <td>#H5FD_MEM_OHDR</td>
* <td>Object header data</td>
* </tr>
* </table>
*
* \version 1.8.7 The flags parameter has been changed from \Code{unsigned int}
* to \Code{unsigned long long}.
* The implementation of the #H5FD_LOG_TIME_OPEN, #H5FD_LOG_TIME_READ,
* #H5FD_LOG_TIME_WRITE, and #H5FD_LOG_TIME_SEEK flags has been finished.
* New flags were added: #H5FD_LOG_NUM_TRUNCATE and #H5FD_LOG_TIME_STAT.
* \version 1.6.0 The \c verbosity parameter has been removed.
* Two new parameters have been added: \p flags of type \Code{unsigned} and
* \p buf_size of type \Code{size_t}.
* \since 1.4.0
*
*/
H5_DLL herr_t H5Pset_fapl_log(hid_t fapl_id, const char *logfile, unsigned long long flags, size_t buf_size);
#ifdef __cplusplus

14
src/H5FDmirror.h
View File

@ -61,8 +61,20 @@ typedef struct H5FD_mirror_fapl_t {
char remote_ip[H5FD_MIRROR_MAX_IP_LEN + 1];
} H5FD_mirror_fapl_t;
H5_DLL hid_t H5FD_mirror_init(void);
H5_DLL hid_t H5FD_mirror_init(void);
/**
* \ingroup FAPL
*
* \todo Add missing documentation
*/
H5_DLL herr_t H5Pget_fapl_mirror(hid_t fapl_id, H5FD_mirror_fapl_t *fa_out);
/**
* \ingroup FAPL
*
* \todo Add missing documentation
*/
H5_DLL herr_t H5Pset_fapl_mirror(hid_t fapl_id, H5FD_mirror_fapl_t *fa);
#ifdef __cplusplus

8
src/H5FDmpi.h
View File

@ -34,10 +34,12 @@
*/
#define H5D_MULTI_CHUNK_IO_COL_THRESHOLD 60
/* Type of I/O for data transfer properties */
/**
* Type of I/O for data transfer properties
*/
typedef enum H5FD_mpio_xfer_t {
H5FD_MPIO_INDEPENDENT = 0, /*zero is the default*/
H5FD_MPIO_COLLECTIVE
H5FD_MPIO_INDEPENDENT = 0, /**< Use independent I/O access */
H5FD_MPIO_COLLECTIVE /**< Use collective I/O access */
} H5FD_mpio_xfer_t;
/* Type of chunked dataset I/O */

225
src/H5FDmpio.h
View File

@ -44,14 +44,237 @@ H5_DLLVAR hbool_t H5FD_mpi_opt_types_g;
#ifdef __cplusplus
extern "C" {
#endif
H5_DLL hid_t H5FD_mpio_init(void);
H5_DLL hid_t H5FD_mpio_init(void);
/**
* \ingroup FAPL
*
* \brief Stores MPI IO communicator information to the file access property list
*
* \fapl_id
* \param[in] comm MPI-2 communicator
* \param[in] info MPI-2 info object
* \returns \herr_t
*
* \details H5Pset_fapl_mpio() stores the user-supplied MPI IO parameters \p
* comm, for communicator, and \p info, for information, in the file
* access property list \p fapl_id. That property list can then be used
* to create and/or open a file.
*
* H5Pset_fapl_mpio() is available only in the parallel HDF5 library
* and is not a collective function.
*
* \p comm is the MPI communicator to be used for file open, as defined
* in \c MPI_File_open of MPI-2. This function makes a duplicate of the
* communicator, so modifications to \p comm after this function call
* returns have no effect on the file access property list.
*
* \p info is the MPI Info object to be used for file open, as defined
* in MPI_File_open() of MPI-2. This function makes a duplicate copy of
* the Info object, so modifications to the Info object after this
* function call returns will have no effect on the file access
* property list.
*
* If the file access property list already contains previously-set
* communicator and Info values, those values will be replaced and the
* old communicator and Info object will be freed.
*
* \note Raw dataset chunk caching is not currently supported when using this
* file driver in read/write mode. All calls to H5Dread() and H5Dwrite()
* will access the disk directly, and H5Pset_cache() and
* H5Pset_chunk_cache() will have no effect on performance.\n
* Raw dataset chunk caching is supported when this driver is used in
* read-only mode.
*
* \version 1.4.5 Handling of the MPI Communicator and Info object changed at
* this release. A duplicate of each of these is now stored in the property
* list instead of pointers to each.
* \since 1.4.0
*
*/
H5_DLL herr_t H5Pset_fapl_mpio(hid_t fapl_id, MPI_Comm comm, MPI_Info info);
/**
* \ingroup FAPL
*
* \brief Returns MPI IO communicator information
*
* \fapl_id
* \param[out] comm MPI-2 communicator
* \param[out] info MPI-2 info object
* \returns \herr_t
*
* \details If the file access property list is set to the #H5FD_MPIO driver,
* H5Pget_fapl_mpio() returns duplicates of the stored MPI communicator
* and Info object through the \p comm and \p info pointers, if those
* values are non-null.
*
* Since the MPI communicator and Info object are duplicates of the
* stored information, future modifications to the access property list
* will not affect them. It is the responsibility of the application to
* free these objects.
*
* \version 1.4.5 Handling of the MPI Communicator and Info object changed at
* this release. A duplicate of each of these is now stored in the
* property list instead of pointers to each.
* \since 1.4.0
*
*/
H5_DLL herr_t H5Pget_fapl_mpio(hid_t fapl_id, MPI_Comm *comm /*out*/, MPI_Info *info /*out*/);
/**
* \ingroup DXPL
*
* \brief Sets data transfer mode
*
* \dxpl_id
* \param[in] xfer_mode Transfer mode
* \returns \herr_t
*
* \details H5Pset_dxpl_mpio() sets the data transfer property list \p dxpl_id
* to use transfer mode \p xfer_mode. The property list can then be
* used to control the I/O transfer mode during data I/O operations.
*
* Valid transfer modes are #H5FD_MPIO_INDEPENDENT (default) and
* #H5FD_MPIO_COLLECTIVE.
*
* \since 1.4.0
*
*/
H5_DLL herr_t H5Pset_dxpl_mpio(hid_t dxpl_id, H5FD_mpio_xfer_t xfer_mode);
/**
* \ingroup DXPL
*
* \brief Returns the data transfer mode
*
* \dxpl_id
* \param[out] xfer_mode Transfer mode
* \returns \herr_t
*
* \details H5Pget_dxpl_mpio() queries the data transfer mode currently set in
* the data transfer property list \p dxpl_id.
*
* Upon return, \p xfer_mode contains the data transfer mode, if it is
* non-null.
*
* H5Pget_dxpl_mpio() is not a collective function.
*
* \since 1.4.0
*
*/
H5_DLL herr_t H5Pget_dxpl_mpio(hid_t dxpl_id, H5FD_mpio_xfer_t *xfer_mode /*out*/);
/**
* \ingroup DXPL
*
* \brief Sets data transfer mode
*
* \dxpl_id
* \param[in] opt_mode Transfer mode
* \returns \herr_t
*
* \details H5Pset_dxpl_mpio() sets the data transfer property list \p dxpl_id
* to use transfer mode xfer_mode. The property list can then be used
* to control the I/O transfer mode during data I/O operations.
*
* Valid transfer modes are #H5FD_MPIO_INDEPENDENT (default) and
* #H5FD_MPIO_COLLECTIVE.
*
* \since 1.4.0
*
*/
H5_DLL herr_t H5Pset_dxpl_mpio_collective_opt(hid_t dxpl_id, H5FD_mpio_collective_opt_t opt_mode);
/**
* \ingroup DXPL
*
* \brief Sets a flag specifying linked-chunk I/O or multi-chunk I/O
*
* \dxpl_id
* \param[in] opt_mode Transfer mode
* \returns \herr_t
*
* \details H5Pset_dxpl_mpio_chunk_opt() specifies whether I/O is to be
* performed as linked-chunk I/O or as multi-chunk I/O. This function
* overrides the HDF5 library's internal algorithm for determining
* which mechanism to use.
*
* When an application uses collective I/O with chunked storage, the
* HDF5 library normally uses an internal algorithm to determine
* whether that I/O activity should be conducted as one linked-chunk
* I/O or as multi-chunk I/O. H5Pset_dxpl_mpio_chunk_opt() is provided
* so that an application can override the library's algorithm in
* circumstances where the library might lack the information needed to
* make an optimal decision.
*
* H5Pset_dxpl_mpio_chunk_opt() works by setting one of the following
* flags in the parameter \p opt_mode:
* - #H5FD_MPIO_CHUNK_ONE_IO - Do one-link chunked I/O
* - #H5FD_MPIO_CHUNK_MULTI_IO - Do multi-chunked I/O
*
* This function works by setting a corresponding property in the
* dataset transfer property list \p dxpl_id.
*
* The library performs I/O in the specified manner unless it
* determines that the low-level MPI IO package does not support the
* requested behavior; in such cases, the HDF5 library will internally
* use independent I/O.
*
* Use of this function is optional.
*
* \todo Add missing version information
*
*/
H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt(hid_t dxpl_id, H5FD_mpio_chunk_opt_t opt_mode);
/**
* \ingroup DXPL
*
* \brief Sets a numeric threshold for linked-chunk I/O
*
* \dxpl_id
* \param[in] num_chunk_per_proc
* \returns \herr_t
*
* \details H5Pset_dxpl_mpio_chunk_opt_num() sets a numeric threshold for the
* use of linked-chunk I/O.
*
* The library will calculate the average number of chunks selected by
* each process when doing collective access with chunked storage. If
* the number is greater than the threshold set in \p
* num_chunk_per_proc, the library will use linked-chunk I/O;
* otherwise, a separate I/O process will be invoked for each chunk
* (multi-chunk I/O).
*
* \todo Add missing version information
*
*/
H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt_num(hid_t dxpl_id, unsigned num_chunk_per_proc);
/**
* \ingroup DXPL
*
* \brief Sets a ratio threshold for collective I/O
*
* \dxpl_id
* \param[in] percent_num_proc_per_chunk
* \returns \herr_t
*
* \details H5Pset_dxpl_mpio_chunk_opt_ratio() sets a threshold for the use of
* collective I/O based on the ratio of processes with collective
* access to a dataset with chunked storage. The decision whether to
* use collective I/O is made on a per-chunk basis.
*
* The library will calculate the percentage of the total number of
* processes, the ratio, that hold selections in each chunk. If that
* percentage is greater than the threshold set in \p
* percent_proc_per_chunk, the library will do collective I/O for this
* chunk; otherwise, independent I/O will be done for the chunk.
*
* \todo Add missing version information
*
*/
H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt_ratio(hid_t dxpl_id, unsigned percent_num_proc_per_chunk);
#ifdef __cplusplus
}

219
src/H5FDmulti.h
View File

@ -25,11 +25,228 @@
#ifdef __cplusplus
extern "C" {
#endif
H5_DLL hid_t H5FD_multi_init(void);
H5_DLL hid_t H5FD_multi_init(void);
/**
* \ingroup FAPL
*
* \brief Sets up use of the multi-file driver
*
* \fapl_id
* \param[in] memb_map Maps memory usage types to other memory usage types
* \param[in] memb_fapl Property list for each memory usage type
* \param[in] memb_name Name generator for names of member files
* \param[in] memb_addr The offsets within the virtual address space, from 0
* (zero) to #HADDR_MAX, at which each type of data storage begins
* \param[in] relax Allows read-only access to incomplete file sets when \c TRUE
* \returns \herr_t
*
* \details H5Pset_fapl_multi() sets the file access property list \p fapl_id to
* use the multi-file driver.
*
* The multi-file driver enables different types of HDF5 data and
* metadata to be written to separate files. These files are viewed by
* the HDF5 library and the application as a single virtual HDF5 file
* with a single HDF5 file address space. The types of data that can be
* broken out into separate files include raw data, the superblock,
* B-tree data, global heap data, local heap data, and object
* headers. At the programmer's discretion, two or more types of data
* can be written to the same file while other types of data are
* written to separate files.
*
* The array \p memb_map maps memory usage types to other memory usage
* types and is the mechanism that allows the caller to specify how
* many files are created. The array contains #H5FD_MEM_NTYPES entries,
* which are either the value #H5FD_MEM_DEFAULT or a memory usage
* type. The number of unique values determines the number of files
* that are opened.
*
* The array \p memb_fapl contains a property list for each memory
* usage type that will be associated with a file.
*
* The array \p memb_name should be a name generator (a
* \Code{printf}-style format with a \Code{%s} which will be replaced
* with the name passed to H5FDopen(), usually from H5Fcreate() or
* H5Fopen()).
*
* The array \p memb_addr specifies the offsets within the virtual
* address space, from 0 (zero) to #HADDR_MAX, at which each type of
* data storage begins.
*
* If \p relax is set to 1 (TRUE), then opening an existing file for
* read-only access will not fail if some file members are
* missing. This allows a file to be accessed in a limited sense if
* just the meta data is available.
*
* Default values for each of the optional arguments are as follows:
* <table>
* <tr>
* <td>\p memb_map</td>
* <td>The default member map contains the value #H5FD_MEM_DEFAULT for each element.</td>
* </tr>
* <tr>
* <td>
* \p memb_fapl
* </td>
* <td>
* The default value is #H5P_DEFAULT for each element.
* </td>
* </tr>
* <tr>
* <td>
* \p memb_name
* </td>
* <td>
* The default string is \Code{%s-X.h5} where \c X is one of the following letters:
* - \c s for #H5FD_MEM_SUPER
* - \c b for #H5FD_MEM_BTREE
* - \c r for #H5FD_MEM_DRAW
* - \c g for #H5FD_MEM_GHEAP
* - \c l for #H5FD_MEM_LHEAP
* - \c o for #H5FD_MEM_OHDR
* </td>
* </tr>
* <tr>
* <td>
* \p memb_addr
* </td>
* <td>
* The default setting is that the address space is equally divided
* among all of the elements:
* - #H5FD_MEM_SUPER \Code{-> 0 * (HADDR_MAX/6)}
* - #H5FD_MEM_BTREE \Code{-> 1 * (HADDR_MAX/6)}
* - #H5FD_MEM_DRAW \Code{-> 2 * (HADDR_MAX/6)}
* - #H5FD_MEM_GHEAP \Code{-> 3 * (HADDR_MAX/6)}
* - #H5FD_MEM_LHEAP \Code{-> 4 * (HADDR_MAX/6)}
* - #H5FD_MEM_OHDR \Code{-> 5 * (HADDR_MAX/6)}
* </td>
* </tr>
* </table>
*
* \par Example:
* The following code sample sets up a multi-file access property list that
* partitions data into meta and raw files, each being one-half of the address:\n
* \code
* H5FD_mem_t mt, memb_map[H5FD_MEM_NTYPES];
* hid_t memb_fapl[H5FD_MEM_NTYPES];
* const char *memb[H5FD_MEM_NTYPES];
* haddr_t memb_addr[H5FD_MEM_NTYPES];
*
* // The mapping...
* for (mt=0; mt<H5FD_MEM_NTYPES; mt++) {
* memb_map[mt] = H5FD_MEM_SUPER;
* }
* memb_map[H5FD_MEM_DRAW] = H5FD_MEM_DRAW;
*
* // Member information
* memb_fapl[H5FD_MEM_SUPER] = H5P_DEFAULT;
* memb_name[H5FD_MEM_SUPER] = "%s.meta";
* memb_addr[H5FD_MEM_SUPER] = 0;
*
* memb_fapl[H5FD_MEM_DRAW] = H5P_DEFAULT;
* memb_name[H5FD_MEM_DRAW] = "%s.raw";
* memb_addr[H5FD_MEM_DRAW] = HADDR_MAX/2;
*
* hid_t fapl = H5Pcreate(H5P_FILE_ACCESS);
* H5Pset_fapl_multi(fapl, memb_map, memb_fapl,
* memb_name, memb_addr, TRUE);
* \endcode
*
* \version 1.6.3 \p memb_name parameter type changed to \Code{const char* const*}.
* \since 1.4.0
*/
H5_DLL herr_t H5Pset_fapl_multi(hid_t fapl_id, const H5FD_mem_t *memb_map, const hid_t *memb_fapl,
const char *const *memb_name, const haddr_t *memb_addr, hbool_t relax);
/**
* \ingroup FAPL
*
* \brief Returns information about the multi-file access property list
*
* \fapl_id
* \param[out] memb_map Maps memory usage types to other memory usage types
* \param[out] memb_fapl Property list for each memory usage type
* \param[out] memb_name Name generator for names of member files
* \param[out] memb_addr The offsets within the virtual address space, from 0
* (zero) to #HADDR_MAX, at which each type of data storage begins
* \param[out] relax Allows read-only access to incomplete file sets when \c TRUE
* \returns \herr_t
*
* \details H5Pget_fapl_multi() returns information about the multi-file access
* property list.
*
* \since 1.4.0
*
*/
H5_DLL herr_t H5Pget_fapl_multi(hid_t fapl_id, H5FD_mem_t *memb_map /*out*/, hid_t *memb_fapl /*out*/,
char **memb_name /*out*/, haddr_t *memb_addr /*out*/, hbool_t *relax /*out*/);
/**
* \ingroup FAPL
*
* \brief Emulates the old split file driver
*
* \fapl_id{fapl}
* \param[in] meta_ext Metadata filename extension
* \param[in] meta_plist_id File access property list identifier for the metadata file
* \param[in] raw_ext Raw data filename extension
* \param[in] raw_plist_id
* \returns \herr_t
*
* \details H5Pset_fapl_split() is a compatibility function that enables the
* multi-file driver to emulate the split driver from HDF5 Releases 1.0
* and 1.2. The split file driver stored metadata and raw data in
* separate files but provided no mechanism for separating types of
* metadata.
*
* \p fapl is a file access property list identifier.
*
* \p meta_ext is the filename extension for the metadata file. The
* extension is appended to the name passed to H5FDopen(), usually from
* H5Fcreate() or H5Fopen(), to form the name of the metadata file. If
* the string \Code{%s} is used in the extension, it works like the
* name generator as in H5Pset_fapl_multi().
*
* \p meta_plist_id is the file access property list identifier for the
* metadata file.
*
* \p raw_ext is the filename extension for the raw data file. The
* extension is appended to the name passed to H5FDopen(), usually from
* H5Fcreate() or H5Fopen(), to form the name of the raw data file. If
* the string \Code{%s} is used in the extension, it works like the
* name generator as in H5Pset_fapl_multi().
*
* \p raw_plist_id is the file access property list identifier for the
* raw data file.
*
* If a user wishes to check to see whether this driver is in use, the
* user must call H5Pget_driver() and compare the returned value to the
* string #H5FD_MULTI. A positive match will confirm that the multi
* driver is in use; HDF5 provides no mechanism to determine whether it
* was called as the special case invoked by H5Pset_fapl_split().
*
* \par Example:
* \code
* // Example 1: Both metadata and rawdata files are in the same
* // directory. Use Station1-m.h5 and Station1-r.h5 as
* // the metadata and rawdata files.
* hid_t fapl, fid;
* fapl = H5Pcreate(H5P_FILE_ACCESS);
* H5Pset_fapl_split(fapl, "-m.h5", H5P_DEFAULT, "-r.h5", H5P_DEFAULT);
* fid=H5Fcreate("Station1",H5F_ACC_TRUNC,H5P_DEFAULT,fapl);
*
* // Example 2: metadata and rawdata files are in different
* // directories. Use PointA-m.h5 and /pfs/PointA-r.h5 as
* // the metadata and rawdata files.
* hid_t fapl, fid;
* fapl = H5Pcreate(H5P_FILE_ACCESS);
* H5Pset_fapl_split(fapl, "-m.h5", H5P_DEFAULT, "/pfs/%s-r.h5", H5P_DEFAULT);
* fid=H5Fcreate("PointA",H5F_ACC_TRUNC,H5P_DEFAULT,fapl);
* \endcode
*
* \since 1.4.0
*
*/
H5_DLL herr_t H5Pset_fapl_split(hid_t fapl, const char *meta_ext, hid_t meta_plist_id, const char *raw_ext,
hid_t raw_plist_id);
#ifdef __cplusplus

88
src/H5FDpublic.h
View File

@ -329,29 +329,113 @@ struct H5FD_t {
hbool_t paged_aggr; /* Paged aggregation for file space is enabled or not */
};
/* Define enum for the source of file image callbacks */
/**
* Define enum for the source of file image callbacks
*/
//! <!-- [H5FD_file_image_op_t_snip] -->
typedef enum {
H5FD_FILE_IMAGE_OP_NO_OP,
H5FD_FILE_IMAGE_OP_PROPERTY_LIST_SET,
/**< Passed to the \p image_malloc and \p image_memcpy callbacks when a
* file image buffer is to be copied while being set in a file access
* property list (FAPL)*/
H5FD_FILE_IMAGE_OP_PROPERTY_LIST_COPY,
/**< Passed to the \p image_malloc and \p image_memcpy callbacks
* when a file image buffer is to be copied when a FAPL is copied*/
H5FD_FILE_IMAGE_OP_PROPERTY_LIST_GET,
/**<Passed to the \p image_malloc and \p image_memcpy callbacks when
* a file image buffer is to be copied while being retrieved from a FAPL*/
H5FD_FILE_IMAGE_OP_PROPERTY_LIST_CLOSE,
/**<Passed to the \p image_free callback when a file image
* buffer is to be released during a FAPL close operation*/
H5FD_FILE_IMAGE_OP_FILE_OPEN,
/**<Passed to the \p image_malloc and
* \p image_memcpy callbackswhen a
* file image buffer is to be copied during a file open operation \n
* While the file image being opened will typically be copied from a
* FAPL, this need not always be the case. For example, the core file
* driver, also known as the memory file driver, takes its initial
* image from a file.*/
H5FD_FILE_IMAGE_OP_FILE_RESIZE,
/**<Passed to the \p image_realloc callback when a file driver needs
* to resize an image buffer*/
H5FD_FILE_IMAGE_OP_FILE_CLOSE
/**<Passed to the \p image_free callback when an image buffer is to
* be released during a file close operation*/
} H5FD_file_image_op_t;
//! <!-- [H5FD_file_image_op_t_snip] -->
/* Define structure to hold file image callbacks */
/**
* Define structure to hold file image callbacks
*/
//! <!-- [H5FD_file_image_callbacks_t_snip] -->
typedef struct {
/**
* \param[in] size Size in bytes of the file image buffer to allocate
* \param[in] file_image_op A value from H5FD_file_image_op_t indicating
* the operation being performed on the file image
* when this callback is invoked
* \param[in] udata Value passed in in the H5Pset_file_image_callbacks
* parameter \p udata
*/
//! <!-- [image_malloc_snip] -->
void *(*image_malloc)(size_t size, H5FD_file_image_op_t file_image_op, void *udata);
//! <!-- [image_malloc_snip] -->
/**
* \param[in] dest Address of the destination buffer
* \param[in] src Address of the source buffer
* \param[in] file_image_op A value from #H5FD_file_image_op_t indicating
* the operation being performed on the file image
* when this callback is invoked
* \param[in] udata Value passed in in the H5Pset_file_image_callbacks
* parameter \p udata
*/
//! <!-- [image_memcpy_snip] -->
void *(*image_memcpy)(void *dest, const void *src, size_t size, H5FD_file_image_op_t file_image_op,
void *udata);
//! <!-- [image_memcpy_snip] -->
/**
* \param[in] ptr Pointer to the buffer being reallocated
* \param[in] file_image_op A value from #H5FD_file_image_op_t indicating
* the operation being performed on the file image
* when this callback is invoked
* \param[in] udata Value passed in in the H5Pset_file_image_callbacks
* parameter \p udata
*/
//! <!-- [image_realloc_snip] -->
void *(*image_realloc)(void *ptr, size_t size, H5FD_file_image_op_t file_image_op, void *udata);
//! <!-- [image_realloc_snip] -->
/**
* \param[in] udata Value passed in in the H5Pset_file_image_callbacks
* parameter \p udata
*/
//! <!-- [image_free_snip] -->
herr_t (*image_free)(void *ptr, H5FD_file_image_op_t file_image_op, void *udata);
//! <!-- [image_free_snip] -->
/**
* \param[in] udata Value passed in in the H5Pset_file_image_callbacks
* parameter \p udata
*/
//! <!-- [udata_copy_snip] -->
void *(*udata_copy)(void *udata);
//! <!-- [udata_copy_snip] -->
/**
* \param[in] udata Value passed in in the H5Pset_file_image_callbacks
* parameter \p udata
*/
//! <!-- [udata_free_snip] -->
herr_t (*udata_free)(void *udata);
//! <!-- [udata_free_snip] -->
/**
* \brief The final field in the #H5FD_file_image_callbacks_t struct,
* provides a pointer to user-defined data. This pointer will be
* passed to the image_malloc, image_memcpy, image_realloc, and
* image_free callbacks. Define udata as NULL if no user-defined
* data is provided.
*/
void *udata;
} H5FD_file_image_callbacks_t;
//! <!-- [H5FD_file_image_callbacks_t_snip] -->
#ifdef __cplusplus
extern "C" {

14
src/H5FDros3.h
View File

@ -89,8 +89,20 @@ typedef struct H5FD_ros3_fapl_t {
extern "C" {
#endif
H5_DLL hid_t H5FD_ros3_init(void);
H5_DLL hid_t H5FD_ros3_init(void);
/**
* \ingroup FAPL
*
* \todo Add missing documentation
*/
H5_DLL herr_t H5Pget_fapl_ros3(hid_t fapl_id, H5FD_ros3_fapl_t *fa_out);
/**
* \ingroup FAPL
*
* \todo Add missing documentation
*/
H5_DLL herr_t H5Pset_fapl_ros3(hid_t fapl_id, H5FD_ros3_fapl_t *fa);
#ifdef __cplusplus

14
src/H5FDsplitter.h
View File

@ -87,8 +87,20 @@ typedef struct H5FD_splitter_vfd_config_t {
#ifdef __cplusplus
extern "C" {
#endif
H5_DLL hid_t H5FD_splitter_init(void);
H5_DLL hid_t H5FD_splitter_init(void);
/**
* \ingroup FAPL
*
* \todo Add missing documentation
*/
H5_DLL herr_t H5Pset_fapl_splitter(hid_t fapl_id, H5FD_splitter_vfd_config_t *config_ptr);
/**
* \ingroup FAPL
*
* \todo Add missing documentation
*/
H5_DLL herr_t H5Pget_fapl_splitter(hid_t fapl_id, H5FD_splitter_vfd_config_t *config_ptr);
#ifdef __cplusplus

16
src/H5FDstdio.h
View File

@ -28,7 +28,21 @@
extern "C" {
#endif
H5_DLL hid_t H5FD_stdio_init(void);
H5_DLL hid_t H5FD_stdio_init(void);
/**
* \ingroup FAPL
*
* \brief Sets the standard I/O driver
*
* \fapl_id
* \returns \herr_t
*
* \details H5Pset_fapl_stdio() modifies the file access property list to use
* the standard I/O driver, H5FDstdio().
*
* \since 1.4.0
*
*/
H5_DLL herr_t H5Pset_fapl_stdio(hid_t fapl_id);
#ifdef __cplusplus

30
src/H5FDwindows.h
View File

@ -27,6 +27,36 @@
extern "C" {
#endif /* __cplusplus */
/**
* \ingroup FAPL
*
* \brief Sets the Windows I/O driver
*
* \fapl_id
* \returns \herr_t
*
* \details H5Pset_fapl_windows() sets the default HDF5 Windows I/O driver on
* Windows systems.
*
* Since the HDF5 library uses this driver, #H5FD_WINDOWS, by default
* on Windows systems, it is not normally necessary for a user
* application to call H5Pset_fapl_windows(). While it is not
* recommended, there may be times when a user chooses to set a
* different HDF5 driver, such as the standard I/O driver (#H5FD_STDIO)
* or the sec2 driver (#H5FD_SEC2), in a Windows
* application. H5Pset_fapl_windows() is provided so that the
* application can return to the Windows I/O driver when the time
* comes.
*
* Only the Windows driver is tested on Windows systems; other drivers
* are used at the application’s and the user’s risk.
*
* Furthermore, the Windows driver is tested and available only on
* Windows systems; it is not available on non-Windows systems.
*
* \since 1.8.0
*
*/
H5_DLL herr_t H5Pset_fapl_windows(hid_t fapl_id);
#ifdef __cplusplus

30
src/H5Fmodule.h
View File

@ -31,8 +31,34 @@
/**
* \defgroup H5F H5F
* \brief File Interface
* \todo Describe concisely what the functions in this module are about.
*
* Use the functions in this module to manage HDF5 files.
*
* In the code snippets below, we show the skeletal life cycle of an HDF5 file,
* when creating a new file (left) or when opening an existing file (right).
* File creation is essentially controlled through \ref FCPL, and file access to
* new and existing files is controlled through \ref FAPL. The file \c name and
* creation or access \c mode control the interaction with the underlying
* storage such as file systems.
*
* \Emph{Proper error handling is part of the life cycle.}
* <table>
* <tr><th>Create</th><th>Open</th></tr>
* <tr valign="top">
* <td>
* \snippet H5F_examples.c life_cycle
* </td>
* <td>
* \snippet H5F_examples.c life_cycle_w_open
* </td>
* </tr>
* </table>
*
* In addition to general file management functions, there are three categories
* of functions that deal with advanced file management tasks and use cases:
* 1. The control of the HDF5 \ref MDC
* 2. The use of (MPI-) \ref PH5F HDF5
* 3. The \ref SWMR pattern
*
* \defgroup MDC Metadata Cache
* \ingroup H5F

588
src/H5Fpublic.h
View File

@ -47,27 +47,23 @@
* We're assuming that these constants are used rather early in the hdf5
* session.
*/
#define H5F_ACC_RDONLY (H5CHECK H5OPEN 0x0000u) /**< absence of rdwr => rd-only */
#define H5F_ACC_RDWR (H5CHECK H5OPEN 0x0001u) /**< open for read and write */
#define H5F_ACC_TRUNC (H5CHECK H5OPEN 0x0002u) /**< overwrite existing files */
#define H5F_ACC_EXCL (H5CHECK H5OPEN 0x0004u) /**< fail if file already exists*/
#define H5F_ACC_RDONLY (H5CHECK H5OPEN 0x0000u) /**< Absence of RDWR: read-only */
#define H5F_ACC_RDWR (H5CHECK H5OPEN 0x0001u) /**< Open for read and write */
#define H5F_ACC_TRUNC (H5CHECK H5OPEN 0x0002u) /**< Overwrite existing files */
#define H5F_ACC_EXCL (H5CHECK H5OPEN 0x0004u) /**< Fail if file already exists*/
/* NOTE: 0x0008u was H5F_ACC_DEBUG, now deprecated */
#define H5F_ACC_CREAT (H5CHECK H5OPEN 0x0010u) /**< create non-existing files */
#define H5F_ACC_CREAT (H5CHECK H5OPEN 0x0010u) /**< Create non-existing files */
#define H5F_ACC_SWMR_WRITE \
(H5CHECK 0x0020u) /**< indicate that this file is open for writing in a \
single-writer/multi-reader (SWMR) scenario. \
Note that the process(es) opening the file for reading must \
open the file with RDONLY access, and use the special "SWMR_READ" \
access flag. */
(H5CHECK 0x0020u) /**< Indicate that this file is open for writing in a \
* single-writer/multi-reader (SWMR) scenario. \
* Note that the process(es) opening the file for reading \
* must open the file with #H5F_ACC_RDONLY and use the \
* #H5F_ACC_SWMR_READ access flag. */
#define H5F_ACC_SWMR_READ \
(H5CHECK 0x0040u) /**< indicate that this file is \
* open for reading in a \
* single-writer/multi-reader (SWMR) \
* scenario. Note that the \
* process(es) opening the file \
* for SWMR reading must also \
* open the file with the RDONLY \
* flag. */
(H5CHECK 0x0040u) /**< Indicate that this file is open for reading in a \
* single-writer/multi-reader (SWMR) scenario. Note that \
* the process(es) opening the file for SWMR reading must \
* also open the file with the #H5F_ACC_RDONLY flag. */
/**
* Default property list identifier
@ -91,7 +87,7 @@
#define H5F_FAMILY_DEFAULT (hsize_t)0
#ifdef H5_HAVE_PARALLEL
/*
/**
* Use this constant string as the MPI_Info key to set H5Fmpio debug flags.
* To turn on H5Fmpio debug flags, set the MPI_Info value with this key to
* have the value of a string consisting of the characters that turn on the
@ -101,11 +97,12 @@
#endif /* H5_HAVE_PARALLEL */
/**
* The difference between a single file and a set of mounted files
* The scope of an operation such as H5Fflush(), e.g.,
* a single file vs. a set of mounted files
*/
typedef enum H5F_scope_t {
H5F_SCOPE_LOCAL = 0, /**< specified file handle only */
H5F_SCOPE_GLOBAL = 1 /**< entire virtual file */
H5F_SCOPE_LOCAL = 0, /**< The specified file handle only */
H5F_SCOPE_GLOBAL = 1 /**< The entire virtual file */
} H5F_scope_t;
/**
@ -117,16 +114,16 @@ typedef enum H5F_scope_t {
* How does file close behave?
*/
typedef enum H5F_close_degree_t {
H5F_CLOSE_DEFAULT = 0, /**< Use the degree pre-defined by underlining VFL */
H5F_CLOSE_DEFAULT = 0, /**< Use the degree pre-defined by underlying VFD */
H5F_CLOSE_WEAK = 1, /**< File closes only after all opened objects are closed */
H5F_CLOSE_SEMI = 2, /**< If no opened objects, file is close; otherwise, file close fails */
H5F_CLOSE_SEMI = 2, /**< If no opened objects, file is closed; otherwise, file close fails */
H5F_CLOSE_STRONG = 3 /**< If there are opened objects, close them first, then close file */
} H5F_close_degree_t;
/**
* Current "global" information about file
*/
//! [H5F_info2_t_snip]
//! <!-- [H5F_info2_t_snip] -->
typedef struct H5F_info2_t {
struct {
unsigned version; /**< Superblock version # */
@ -144,7 +141,7 @@ typedef struct H5F_info2_t {
H5_ih_info_t msgs_info; /**< Shared object header message index & heap size */
} sohm;
} H5F_info2_t;
//! [H5F_info2_t_snip]
//! <!-- [H5F_info2_t_snip] -->
/**
* Types of allocation requests. The values larger than #H5FD_MEM_DEFAULT
@ -176,12 +173,12 @@ typedef enum H5F_mem_t {
/**
* Free space section information
*/
//! [H5F_sect_info_t_snip]
//! <!-- [H5F_sect_info_t_snip] -->
typedef struct H5F_sect_info_t {
haddr_t addr; /**< Address of free space section */
hsize_t size; /**< Size of free space section */
} H5F_sect_info_t;
//! [H5F_sect_info_t_snip]
//! <!-- [H5F_sect_info_t_snip] -->
/**
* Library's format versions
@ -193,7 +190,7 @@ typedef enum H5F_libver_t {
H5F_LIBVER_V110 = 2, /**< Use the latest v110 format for storing objects */
H5F_LIBVER_V112 = 3, /**< Use the latest v112 format for storing objects */
H5F_LIBVER_V114 = 4, /**< Use the latest v114 format for storing objects */
H5F_LIBVER_NBOUNDS
H5F_LIBVER_NBOUNDS /**< Sentinel */
} H5F_libver_t;
#define H5F_LIBVER_LATEST H5F_LIBVER_V114
@ -201,7 +198,7 @@ typedef enum H5F_libver_t {
/**
* File space handling strategy
*/
//! [H5F_fspace_strategy_t_snip]
//! <!-- [H5F_fspace_strategy_t_snip] -->
typedef enum H5F_fspace_strategy_t {
H5F_FSPACE_STRATEGY_FSM_AGGR = 0, /**< Mechanisms: free-space managers, aggregators, and virtual file
drivers This is the library default when not set */
@ -211,7 +208,7 @@ typedef enum H5F_fspace_strategy_t {
H5F_FSPACE_STRATEGY_NONE = 3, /**< Mechanisms: virtual file drivers */
H5F_FSPACE_STRATEGY_NTYPES /**< Sentinel */
} H5F_fspace_strategy_t;
//! [H5F_fspace_strategy_t_snip]
//! <!-- [H5F_fspace_strategy_t_snip] -->
/**
* File space handling strategy for release 1.10.0
@ -228,7 +225,7 @@ typedef enum H5F_file_space_type_t {
H5F_FILE_SPACE_NTYPES /**< Sentinel */
} H5F_file_space_type_t;
//! [H5F_retry_info_t_snip]
//! <!-- [H5F_retry_info_t_snip] -->
#define H5F_NUM_METADATA_READ_RETRY_TYPES 21
/**
@ -239,7 +236,7 @@ typedef struct H5F_retry_info_t {
unsigned nbins;
uint32_t *retries[H5F_NUM_METADATA_READ_RETRY_TYPES];
} H5F_retry_info_t;
//! [H5F_retry_info_t_snip]
//! <!-- [H5F_retry_info_t_snip] -->
/**
* Callback for H5Pset_object_flush_cb() in a file access property list
@ -276,11 +273,6 @@ extern "C" {
*
*/
H5_DLL htri_t H5Fis_accessible(const char *container_name, hid_t fapl_id);
/**
* \example H5Fcreate.c
* After creating an HDF5 file with H5Fcreate(), we close it with
* H5Fclose().
*/
/**
* \ingroup H5F
*
@ -321,7 +313,8 @@ H5_DLL htri_t H5Fis_accessible(const char *container_name, hid_t fapl_id);
* this file identifier should be closed by calling H5Fclose() when
* it is no longer needed.
*
* \include H5Fcreate.c
* \par Example
* \snippet H5F_examples.c minimal
*
* \note #H5F_ACC_TRUNC and #H5F_ACC_EXCL are mutually exclusive; use
* exactly one.
@ -359,6 +352,11 @@ H5_DLL htri_t H5Fis_accessible(const char *container_name, hid_t fapl_id);
*
*/
H5_DLL hid_t H5Fcreate(const char *filename, unsigned flags, hid_t fcpl_id, hid_t fapl_id);
/**
* --------------------------------------------------------------------------
* \ingroup ASYNC
* \async_variant_of{H5Fcreate}
*/
H5_DLL hid_t H5Fcreate_async(const char *app_file, const char *app_func, unsigned app_line,
const char *filename, unsigned flags, hid_t fcpl_id, hid_t fapl_id, hid_t es_id);
/**
@ -408,6 +406,9 @@ H5_DLL hid_t H5Fcreate_async(const char *app_file, const char *app_func, unsigne
* identifier should be closed by calling H5Fclose() when it is no
* longer needed.
*
* \par Example
* \snippet H5F_examples.c open
*
* \note #H5F_ACC_RDWR and #H5F_ACC_RDONLY are mutually exclusive; use
* exactly one.
*
@ -451,6 +452,11 @@ H5_DLL hid_t H5Fcreate_async(const char *app_file, const char *app_func, unsigne
*
*/
H5_DLL hid_t H5Fopen(const char *filename, unsigned flags, hid_t fapl_id);
/**
* --------------------------------------------------------------------------
* \ingroup ASYNC
* \async_variant_of{H5Fopen}
*/
H5_DLL hid_t H5Fopen_async(const char *app_file, const char *app_func, unsigned app_line,
const char *filename, unsigned flags, hid_t access_plist, hid_t es_id);
/**
@ -479,6 +485,11 @@ H5_DLL hid_t H5Fopen_async(const char *app_file, const char *app_func, unsigned
*
*/
H5_DLL hid_t H5Freopen(hid_t file_id);
/**
* --------------------------------------------------------------------------
* \ingroup ASYNC
* \async_variant_of{H5Freopen}
*/
H5_DLL hid_t H5Freopen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t file_id,
hid_t es_id);
/**
@ -503,6 +514,9 @@ H5_DLL hid_t H5Freopen_async(const char *app_file, const char *app_func, unsigne
* global or local. Valid values are as follows:
* \scopes
*
* \par Example
* \snippet H5F_examples.c flush
*
* \attention HDF5 does not possess full control over buffering. H5Fflush()
* flushes the internal HDF5 buffers then asks the operating system
* (the OS) to flush the system buffers for the open files. After
@ -511,13 +525,13 @@ H5_DLL hid_t H5Freopen_async(const char *app_file, const char *app_func, unsigne
*
*/
H5_DLL herr_t H5Fflush(hid_t object_id, H5F_scope_t scope);
/**
* --------------------------------------------------------------------------
* \ingroup ASYNC
* \async_variant_of{H5Fflush}
*/
H5_DLL herr_t H5Fflush_async(const char *app_file, const char *app_func, unsigned app_line, hid_t object_id,
H5F_scope_t scope, hid_t es_id);
/**
* \example H5Fclose.c
* After creating an HDF5 file with H5Fcreate(), we close it with
* H5Fclose().
*/
/**
* \ingroup H5F
*
@ -534,8 +548,8 @@ H5_DLL herr_t H5Fflush_async(const char *app_file, const char *app_func, unsigne
* identifier, or shared datatype identifier), the file will be fully
* closed and access will end.
*
* Use H5Fclose() as shown in the following example:
* \include H5Fclose.c
* \par Example
* \snippet H5F_examples.c minimal
*
* \note \Bold{Delayed close:} Note the following deviation from the
* above-described behavior. If H5Fclose() is called for a file but one
@ -562,6 +576,11 @@ H5_DLL herr_t H5Fflush_async(const char *app_file, const char *app_func, unsigne
*
*/
H5_DLL herr_t H5Fclose(hid_t file_id);
/**
* --------------------------------------------------------------------------
* \ingroup ASYNC
* \async_variant_of{H5Fclose}
*/
H5_DLL herr_t H5Fclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t file_id,
hid_t es_id);
/**
@ -655,7 +674,7 @@ H5_DLL hid_t H5Fget_access_plist(hid_t file_id);
* \note The function will not return an error if intent is NULL; it will
* simply do nothing.
*
* \version 1.10.0 C function enhanced to work with SWMR functionality.
* \version 1.10.0 Function enhanced to work with SWMR functionality.
*
* \since 1.8.0
*
@ -707,7 +726,7 @@ H5_DLL herr_t H5Fget_fileno(hid_t file_id, unsigned long *fileno);
* \c (#H5F_OBJ_DATASET|#H5F_OBJ_GROUP) would call for datasets and
* groups.
*
* \version 1.6.8, 1.8.2 C function return type changed to \c ssize_t.
* \version 1.6.8, 1.8.2 Function return type changed to \c ssize_t.
* \version 1.6.5 #H5F_OBJ_LOCAL has been added as a qualifier on the types
* of objects to be counted. #H5F_OBJ_LOCAL restricts the
* search to objects opened through current file identifier.
@ -745,9 +764,9 @@ H5_DLL ssize_t H5Fget_obj_count(hid_t file_id, unsigned types);
* To retrieve a count of open objects, use the H5Fget_obj_count()
* function. This count can be used to set the \p max_objs parameter.
*
* \version 1.8.2 C function return type changed to \c ssize_t and \p
* \version 1.8.2 Function return type changed to \c ssize_t and \p
* max_objs parameter datatype changed to \c size_t.
* \version 1.6.8 C function return type changed to \c ssize_t and \p
* \version 1.6.8 Function return type changed to \c ssize_t and \p
* max_objs parameter datatype changed to \c size_t.
* \since 1.6.0
*
@ -798,6 +817,9 @@ H5_DLL herr_t H5Fget_vfd_handle(hid_t file_id, hid_t fapl, void **file_handle);
* attribute, then the file will be mounted at the location where the
* attribute, dataset, or named datatype is attached.
*
* \par Example
* \snippet H5F_examples.c mount
*
* \note To date, no file mount properties have been defined in HDF5. The
* proper value to pass for \p plist is #H5P_DEFAULT, indicating the
* default file mount property list.
@ -868,8 +890,6 @@ H5_DLL hssize_t H5Fget_freespace(hid_t file_id);
* if any, the HDF5 portion of the file, and any data that may have
* been appended beyond the data written through the HDF5 library.
*
* \version 1.6.3 Fortran subroutine introduced in this release.
*
* \since 1.6.3
*
*/
@ -948,9 +968,7 @@ H5_DLL herr_t H5Fincrement_filesize(hid_t file_id, hsize_t increment);
*
* \note \Bold{Recommended Reading:} This function is part of the file image
* operations feature set. It is highly recommended to study the guide
* "HDF5 File Image Operations" before using this feature set.\n See the
* "See Also" section below for links to other elements of HDF5 file
* image operations. \todo Fix the references.
* \ref_file_image_ops before using this feature set.
*
* \attention H5Pget_file_image() will fail, returning a negative value, if the
* file is too large for the supplied buffer.
@ -958,8 +976,6 @@ H5_DLL herr_t H5Fincrement_filesize(hid_t file_id, hsize_t increment);
* \see H5LTopen_file_image(), H5Pset_file_image(), H5Pget_file_image(),
* H5Pset_file_image_callbacks(), H5Pget_file_image_callbacks()
*
* \version 1.8.13 Fortran subroutine added in this release.
*
* \since 1.8.0
*
*/
@ -976,197 +992,18 @@ H5_DLL ssize_t H5Fget_file_image(hid_t file_id, void *buf_ptr, size_t buf_len);
* \ref H5AC-cache-config-t "here".
* \return \herr_t
*
* \note The \c in direction applies only to the H5AC_cache_config_t::version
* field. All other fields are out parameters.
*
* \details H5Fget_mdc_config() loads the current metadata cache configuration
* into the instance of H5AC_cache_config_t pointed to by the \p config_ptr
* parameter.
*
* Note that the \c version field of \p config_ptr must be initialized
* --this allows the library to support old versions of the H5AC_cache_config_t
* structure.
*
* \par General configuration section
* <table>
* <tr>
* <td><em>int</em> <code>version</code> </td>
* <td>IN: Integer field indicating the the version of the H5AC_cache_config_t in use. This field should
* be set to #H5AC__CURR_CACHE_CONFIG_VERSION (defined in H5ACpublic.h).</td>
* </tr>
* <tr>
* <td><em>hbool_t</em> <code>rpt_fcn_enabled</code> </td>
* <td><p>OUT: Boolean flag indicating whether the adaptive cache resize report function is enabled. This
* field should almost always be set to disabled (<code>0</code>). Since resize algorithm activity is
* reported via stdout, it MUST be set to disabled (<code>0</code>) on Windows machines.</p><p>The
* report function is not supported code, and can be expected to change between versions of the
* library. Use it at your own risk.</p></td>
* </tr>
* <tr>
* <td><em>hbool_t</em> <code>open_trace_file</code> </td>
* <td>OUT: Boolean field indicating whether the <code>trace_file_name</code> field should be used to
* open a trace file for the cache. This field will always be set to <code>0</code> in this
* context.</td>
* </tr>
* <tr>
* <td><em>hbool_t</em> <code>close_trace_file</code> </td>
* <td>OUT: Boolean field indicating whether the current trace file (if any) should be closed. This field
* will always be set to <code>0</code> in this context.</td></tr>
* <tr>
* <td><em>char*</em><code>trace_file_name</code> </td>
* <td>OUT: Full path name of the trace file to be opened if the <code>open_trace_file</code> field is
* set to <code>1</code>. This field will always be set to the empty string in this context.</td></tr>
* <tr>
* <td><em>hbool_t</em> <code>evictions_enabled</code> </td>
* <td>OUT: Boolean flag indicating whether metadata cache entry evictions are
* enabled.</td>
* </tr>
* <tr>
* <td><em>hbool_t</em> <code>set_initial_size</code> </td>
* <td>OUT: Boolean flag indicating whether the cache should be created with a user specified initial
* maximum size.<p>If the configuration is loaded from the cache, this flag will always be set
* to <code>0</code>.</p></td>
* </tr>
* <tr>
* <td><em>size_t</em> <code>initial_size</code> </td>
* <td>OUT: Initial maximum size of the cache in bytes, if applicable.<p>If the configuration is loaded
* from the cache, this field will contain the cache maximum size as of the time of the
* call.</p></td>
* </tr>
* <tr>
* <td><em>double</em> <code>min_clean_fraction</code> </td>
* <td>OUT: Float value specifying the minimum fraction of the cache that must be kept either clean or
* empty when possible.</td>
* </tr>
* <tr>
* <td><em>size_t</em> <code>max_size</code> </td>
* <td>OUT: Upper bound (in bytes) on the range of values that the adaptive cache resize code can select
* as the maximum cache size.</td>
* </tr>
* <tr>
* <td><em>size_t</em> <code>min_size</code> </td>
* <td>OUT: Lower bound (in bytes) on the range of values that the adaptive cache resize code can select
* as the maximum cache size.</td>
* </tr>
* <tr>
* <td><em>long int</em> <code>epoch_length</code> </td>
* <td>OUT: Number of cache accesses between runs of the adaptive cache resize
* code.</td>
* </tr>
* </table>
*
* \par Increment configuration section
* <table>
* <tr>
* <td><em>enum H5C_cache_incr_mode</em> <code>incr_mode</code> </td>
* <td>OUT: Enumerated value indicating the operational mode of the automatic cache size increase code.
* At present, only the following values are legal:<p>\c H5C_incr__off: Automatic cache size increase
* is disabled.</p><p>\c H5C_incr__threshold: Automatic cache size increase is enabled using the hit
* rate threshold algorithm.</p></td>
* </tr>
* <tr>
* <td><em>double</em> <code>lower_hr_threshold</code> </td>
* <td>OUT: Hit rate threshold used in the hit rate threshold cache size increase algorithm.</td>
* </tr>
* <tr>
* <td><em>double</em> <code>increment</code> </td>
* <td>OUT: The factor by which the current maximum cache size is multiplied to obtain an initial new
* maximum cache size if a size increase is triggered in the hit rate threshold cache size increase
* algorithm.</td>
* </tr>
* <tr>
* <td><em>hbool_t</em> <code>apply_max_increment</code> </td>
* <td>OUT: Boolean flag indicating whether an upper limit will be applied to the size of cache size
* increases.</td>
* </tr>
* <tr>
* <td><em>size_t</em> <code>max_increment</code> </td>
* <td>OUT: The maximum number of bytes by which the maximum cache size can be increased in a single step
* -- if applicable.</td>
* </tr>
* <tr>
* <td><em>enum H5C_cache_flash_incr_mode</em> <code>flash_incr_mode</code> </td>
* <td>OUT: Enumerated value indicating the operational mode of the flash cache size increase code. At
* present, only the following values are legal:<p>\c H5C_flash_incr__off: Flash cache size increase is
* disabled.</p><p>\c H5C_flash_incr__add_space: Flash cache size increase is enabled using the add
* space algorithm.</p></td>
* </tr>
* <tr>
* <td><em>double</em> <code>flash_threshold</code> </td>
* <td>OUT: The factor by which the current maximum cache size is multiplied to obtain the minimum size
* entry / entry size increase which may trigger a flash cache size
* increase.</td>
* </tr>
* <tr>
* <td><em>double</em> <code>flash_multiple</code> </td>
* <td>OUT: The factor by which the size of the triggering entry / entry size increase is multiplied to
* obtain the initial cache size increment. This increment may be reduced to reflect existing free
* space in the cache and the <code>max_size</code> field above.</td>
* </tr>
* </table>
*
* \par Decrement configuration section
* <table>
* <tr><td colspan="2"><strong>Decrement configuration
* section:</strong></td>
* </tr>
* <tr>
* <td><em>enum H5C_cache_decr_mode</em> <code>decr_mode</code> </td>
* <td>OUT: Enumerated value indicating the operational mode of the automatic cache size decrease code.
* At present, the following values are legal:<p>H5C_decr__off: Automatic cache size decrease is
* disabled, and the remaining decrement fields are ignored.</p><p>H5C_decr__threshold: Automatic
* cache size decrease is enabled using the hit rate threshold algorithm.</p><p>H5C_decr__age_out:
* Automatic cache size decrease is enabled using the ageout algorithm.</p>
* <p>H5C_decr__age_out_with_threshold: Automatic cache size decrease is enabled using the ageout
* with hit rate threshold algorithm</p></td>
* </tr>
* <tr><td><em>double</em> <code>upper_hr_threshold</code> </td>
* <td>OUT: Upper hit rate threshold. This value is only used if the decr_mode is either
* H5C_decr__threshold or H5C_decr__age_out_with_threshold.</td>
* </tr>
* <tr>
* <td><em>double</em> <code>decrement</code> </td>
* <td>OUT: Factor by which the current max cache size is multiplied to obtain an initial value for the
* new cache size when cache size reduction is triggered in the hit rate threshold cache size reduction
* algorithm.</td>
* </tr>
* <tr>
* <td><em>hbool_t</em> <code>apply_max_decrement</code> </td>
* <td>OUT: Boolean flag indicating whether an upper limit should be applied to the size of cache size
* decreases.</td>
* </tr>
* <tr>
* <td><em>size_t</em> <code>max_decrement</code> </td>
* <td>OUT: The maximum number of bytes by which cache size can be decreased if any single step, if
* applicable.</td>
* </tr>
* <tr>
* <td><em>int</em> <code>epochs_before_eviction</code> </td>
* <td>OUT: The minimum number of epochs that an entry must reside unaccessed in cache before being
* evicted under either of the ageout cache size reduction algorithms.</td>
* </tr>
* <tr>
* <td><em>hbool_t</em> <code>apply_empty_reserve</code> </td>
* <td>OUT: Boolean flag indicating whether an empty reserve should be maintained under either of the
* ageout cache size reduction algorithms.</td>
* </tr>
* <tr>
* <td><em>double</em> <code>empty_reserve</code> </td>
* <td>OUT: Empty reserve for use with the ageout cache size reduction algorithms, if applicable.</td>
* </tr>
* </table>
*
* \par Parallel configuration section
* <table>
* <tr><td><em>int</em> <code>dirty_bytes_threshold</code> </td>
* <td>OUT: Threshold number of bytes of dirty metadata generation for triggering synchronizations of the
* metadata caches serving the target file in the parallel case.<p>Synchronization occurs whenever the
* number of bytes of dirty metadata created since the last synchronization exceeds this
* limit.</p></td>
* </tr>
* </table>
* parameter.\n
* The fields of the H5AC_cache_config_t structure are shown below:
* \snippet H5ACpublic.h H5AC_cache_config_t_snip
* \click4more
*
* \since 1.8.0
*
* \todo Fix the reference!
*
*/
H5_DLL herr_t H5Fget_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr);
/**
@ -1183,240 +1020,11 @@ H5_DLL herr_t H5Fget_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr);
*
* \details H5Fset_mdc_config() attempts to configure the file's metadata cache
* according configuration supplied in \p config_ptr.
*
* \par General configuration fields
* <table>
* <tr>
* <td><em>int</em> <code>version</code></td>
* <td>IN: Integer field indicating the the version of the H5AC_cache_config_t in use. This
* field should be set to #H5AC__CURR_CACHE_CONFIG_VERSION (defined
* in H5ACpublic.h).</td>
* </tr>
* <tr>
* <td><em>hbool_t</em> <code>rpt_fcn_enabled</code></td>
* <td>IN: Boolean flag indicating whether the adaptive cache resize report function is enabled. This
* field should almost always be set to disabled (<code>0</code>). Since resize algorithm activity is
* reported via stdout, it MUST be set to disabled (<code>0</code>) on Windows machines.<p>The report
* function is not supported code, and can be expected to change between versions of the library. Use
* it at your own risk.</p></td>
* </tr>
* <tr>
* <td><em>hbool_t</em> <code>open_trace_File</code></td>
* <td>IN: Boolean field indicating whether the <code>trace_file_name</code> field should be used to open
* a trace file for the cache.<p>The trace file is a debuging feature that allows the capture of top
* level metadata cache requests for purposes of debugging and/or optimization. This field should
* <p>This field should only normally be set to <code>0</code>, as trace file collection imposes
* considerable overhead.</p> be set to <code>1</code> when the <code>trace_file_name</code> contains
* the full path of the desired trace file, and either there is no open trace file on the cache, or the
* <code>close_trace_file</code> field is also <code>1</code>.</p><p>The trace file feature is
* unsupported unless used at the direction of The HDF Group. It is intended to allow The HDF Group to
* collect a trace of cache activity in cases of occult failures and/or poor performance seen in the
* field, so as to aid in reproduction in the lab. If you use it absent the direction of The HDF Group,
* you are on your own.</p></td>
* </tr>
* <tr><td><em>hbool_t</em> <code>close_trace_file</code></td>
* <td>IN: Boolean field indicating whether the current trace file (if any) should be closed.<p>See the
* above comments on the <code>open_trace_file</code> field. This field should be set to
* <code>0</code> unless there is an open trace file on the cache that you wish to close.</p><p>The
* trace file feature is unsupported unless used at the direction of The HDF Group. It is intended to
* allow The HDF Group to collect a trace of cache activity in cases of occult failures and/or poor
* performance seen in the field, so as to aid in reproduction in the lab. If you use it absent the
* direction of The HDF Group, you are on your own.</p></td>
* </tr>
* <tr>
* <td><em>char</em> <code>trace_file_name[]</code></td>
* <td>IN: Full path of the trace file to be opened if the <code>open_trace_file</code> field is set
* to <code>1</code>.<p>In the parallel case, an ascii representation of the mpi rank of the process
* will be appended to the file name to yield a unique trace file name for each process.</p><p>The
* length of the path must not exceed #H5AC__MAX_TRACE_FILE_NAME_LEN characters.</p><p>The trace file
* feature is unsupported unless used at the direction of The HDF Group. It is intended to allow The
* HDF Group to collect a trace of cache activity in cases of occult failures and/or poor performance
* seen in the field, so as to aid in reproduction in the lab. If you use it absent the direction of
* The HDF Group, you are on your own.</p></td>
* </tr>
* <tr>
* <td><em>hbool_t</em> <code>evictions_enabled</code></td>
* <td>IN: A boolean flag indicating whether evictions from the metadata cache are enabled. This flag is
* initially set to enabled (<code>1</code>).<p>In rare circumstances, the raw data throughput
* requirements may be so high that the user wishes to postpone metadata writes so as to reserve I/O
* throughput for raw data. The <code>evictions_enabled</code> field exists to allow this. However,
* this is an extreme step, and you have no business doing it unless you have read the User Guide
* section on metadata caching, and have considered all other options carefully.</p><p>The
* <code>evictions_enabled</code> field may not be set to disabled (<code>0</code>) unless all adaptive
* cache resizing code is disabled via the <code>incr_mode</code>, <code>flash_incr_mode</code>, and
* <code>decr_mode</code> fields.</p><p>When this flag is set to disabled (<code>0</code>), the
* metadata cache will not attempt to evict entries to make space for new entries, and thus will grow
* without bound.</p><p>Evictions will be re-enabled when this field is set back to <code>1</code>.
* This should be done as soon as possible.</p></td>
* </tr>
* <tr>
* <td><em>hbool_t</em> <code>set_initial_size</code></td>
* <td>IN: Boolean flag indicating whether the cache should be forced to the user specified initial
* size.</td>
* </tr>
* <tr>
* <td><em>size_t</em> <code>initial_size</code></td>
* <td>IN: If <code>set_initial_size</code> is set to <code>1</code>, then <code>initial_size</code> must
* contain the desired initial size in bytes. This value must lie in the closed interval
* <code>[min_size, max_size]</code>. (see below)</td>
* </tr>
* <tr><td><em>double</em> <code>min_clean_fraction</code></td>
* <td>IN: This field specifies the minimum fraction of the cache that must be kept either clean or
* empty.<p>The value must lie in the interval [0.0, 1.0]. 0.01 is a good place to start in the serial
* case. In the parallel case, a larger value is needed -- see <a
* href="/display/HDF5/Metadata+Caching+in+HDF5">Metadata Caching in HDF5</a> in the collection
* "Advanced Topics in HDF5."</p></td>
* </tr>
* <tr><td><em>size_t</em> <code>max_size</code></td>
* <td>IN: Upper bound (in bytes) on the range of values that the adaptive cache resize code can select
* as the maximum cache size.</td>
* </tr>
* <tr>
* <td><em>size_t</em> <code>min_size</code></td>
* <td>IN: Lower bound (in bytes) on the range of values that the adaptive cache resize code can select
* as the maximum cache size.</td>
* </tr>
* <tr><td><em>long int</em> <code>epoch_length</code></td>
* <td>IN: Number of cache accesses between runs of the adaptive cache resize code. 50,000 is a good
* starting number.</td>
* </tr>
* </table>
*
* \par Increment configuration fields
* <table>
* <tr>
* <td><em>enum H5C_cache_incr_mode</em> <code>incr_mode</code></td>
* <td>IN: Enumerated value indicating the operational mode of the automatic cache size increase code. At
* present, only two values are legal:<p>\c H5C_incr__off: Automatic cache size increase is disabled,
* and the remaining increment fields are ignored.</p><p>\c H5C_incr__threshold: Automatic cache size
* increase is enabled using the hit rate threshold algorithm.</p></td>
* </tr>
* <tr>
* <td><em>double</em> <code>lower_hr_threshold</code></td>
* <td>IN: Hit rate threshold used by the hit rate threshold cache size increment algorithm.<p>When the
* hit rate over an epoch is below this threshold and the cache is full, the maximum size of the
* cache is multiplied by increment (below), and then clipped as necessary to stay within max_size, and
* possibly max_increment.</p><p>This field must lie in the interval [0.0, 1.0]. 0.8 or 0.9 is a good
* starting point.</p></td>
* </tr>
* <tr>
* <td><em>double</em> <code>increment</code></td>
* <td>IN: Factor by which the hit rate threshold cache size increment algorithm multiplies the current
* maximum cache size to obtain a tentative new cache size.<p>The actual cache size increase will be
* clipped to satisfy the max_size specified in the general configuration, and possibly max_increment
* below.</p><p>The parameter must be greater than or equal to 1.0 -- 2.0 is a reasonable
* value.</p><p>If you set it to 1.0, you will effectively disable cache size increases.</p></td>
* </tr>
* <tr>
* <td><em>hbool_t</em> <code>apply_max_increment</code></td>
* <td>IN: Boolean flag indicating whether an upper limit should be applied to the size of cache size
* increases.</td>
* </tr>
* <tr>
* <td><em>size_t</em> <code>max_increment</code></td>
* <td>IN: Maximum number of bytes by which cache size can be increased in a single step -- if
* applicable.</td>
* </tr>
* <tr>
* <td><em>enum H5C_cache_flash_incr_mode</em> <code>flash_incr_mode</code></td>
* <td>IN: Enumerated value indicating the operational mode of the flash cache size increase code. At
* present, only the following values are legal:<p>\c H5C_flash_incr__off: Flash cache size increase is
* disabled.</p><p>\c H5C_flash_incr__add_space: Flash cache size increase is enabled using the add
* space algorithm.</p></td>
* </tr>
* <tr>
* <td><em>double</em> <code>flash_threshold</code></td>
* <td>IN: The factor by which the current maximum cache size is multiplied to obtain the minimum size
* entry / entry size increase which may trigger a flash cache size increase.<p>At present, this value
* must lie in the range [0.1, 1.0].</p></td>
* </tr>
* <tr>
* <td><em>double</em> <code>flash_multiple</code></td>
* <td>IN: The factor by which the size of the triggering entry / entry size increase is multiplied to
* obtain the initial cache size increment. This increment may be reduced to reflect existing free
* space in the cache and the <code>max_size</code> field above.<p>At present, this field must lie in
* the range [0.1, 10.0].</p></td>
* </tr>
* </table>
*
* \par Decrement configuration fields
* <table>
* <tr>
* <td><em>enum H5C_cache_decr_mode</em> <code>decr_mode</code></td>
* <td>IN: Enumerated value indicating the operational mode of the automatic cache size decrease code. At
* present, the following values are legal:<p>\c H5C_decr__off: Automatic cache size decrease is
* disabled.</p><p>\c H5C_decr__threshold: Automatic cache size decrease is enabled using the hit
* rate threshold algorithm.</p><p>\c H5C_decr__age_out: Automatic cache size decrease is enabled using
* the ageout algorithm.</p><p>\c H5C_decr__age_out_with_threshold: Automatic cache size decrease is
* enabled using the ageout with hit rate threshold algorithm</p></td>
* </tr>
* <tr>
* <td><em>double</em> <code>upper_hr_threshold</code></td>
* <td>IN: Hit rate threshold for the hit rate threshold and ageout with hit rate threshold cache size
* decrement algorithms.<p>When \c decr_mode is \c H5C_decr__threshold, and the hit rate over a given
* epoch exceeds the supplied threshold, the current maximum cache size is multiplied by decrement to
* obtain a tentative new (and smaller) maximum cache size.</p><p>When \c decr_mode is \c
* H5C_decr__age_out_with_threshold, there is no attempt to find and evict aged out entries unless the
* hit rate in the previous epoch exceeded the supplied threshold.</p><p>This field must lie in the
* interval [0.0, 1.0].</p><p>For \c H5C_incr__threshold, .9995 or .99995 is a good place to
* start.</p><p>For \c H5C_decr__age_out_with_threshold, .999 might be more useful.</p></td>
* </tr>
* <tr>
* <td><em>double</em> <code>decrement</code></td>
* <td>IN: In the hit rate threshold cache size decrease algorithm, this parameter contains the factor by
* which the current max cache size is multiplied to produce a tentative new cache size.<p>The actual
* cache size decrease will be clipped to satisfy the min_size specified in the general configuration,
* and possibly max_decrement below.</p><p>The parameter must be be in the interval
* [0.0, 1.0].</p><p>If you set it to 1.0, you will effectively disable cache size decreases. 0.9 is a
* reasonable starting point.</p></td>
* </tr>
* <tr>
* <td><em>hbool_t</em> <code>apply_max_decrement</code></td>
* <td>IN: Boolean flag indicating whether an upper limit should be applied to the size of cache size
* decreases.</td>
* </tr>
* <tr>
* <td><em>size_t</em> <code>max_decrement</code></td>
* <td>IN: Maximum number of bytes by which the maximum cache size can be decreased in any single step --
* if applicable.</td>
* </tr>
* <tr>
* <td><em>int</em> <code>epochs_before_eviction</code></td>
* <td>IN: In the ageout based cache size reduction algorithms, this field contains the minimum number of
* epochs an entry must remain unaccessed in cache before the cache size reduction algorithm tries to
* evict it. 3 is a reasonable value.</td>
* </tr>
* <tr>
* <td><em>hbool_t</em> <code>apply_empty_reserve</code></td>
* <td>IN: Boolean flag indicating whether the ageout based decrement algorithms will maintain a empty
* reserve when decreasing cache size.</td>
* </tr>
* <tr>
* <td><em>double</em> <code>empty_reserve</code></td>
* <td>IN: Empty reserve as a fraction of maximum cache size if applicable.<p>When so directed, the
* ageout based algorithms will not decrease the maximum cache size unless the empty reserve can be
* met.</p><p>The parameter must lie in the interval [0.0, 1.0]. 0.1 or 0.05 is a good place to
* start.</p></td>
* </tr>
* </table>
*
* \par Parallel configuration fields
* <table>
* <tr>
* <td><em>int</em> <code>dirty_bytes_threshold</code></td>
* <td>IN: Threshold number of bytes of dirty metadata generation for triggering synchronizations of the
* metadata caches serving the target file in the parallel case.<p>Synchronization occurs whenever the
* number of bytes of dirty metadata created since the last synchronization exceeds this
* limit.</p><p>This field only applies to the parallel case. While it is ignored elsewhere, it can
* still draw a value out of bounds error.</p><p>It must be consistant across all caches on any given
* file.</p><p>By default, this field is set to 256 KB. It shouldn't be more than half the current
* maximum cache size times the minimum clean fraction.</p></td>
* </tr>
* </table>
* \snippet H5ACpublic.h H5AC_cache_config_t_snip
* \click4more
*
* \since 1.8.0
*
* \todo Fix the MDC document reference!
*/
H5_DLL herr_t H5Fset_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr);
/**
@ -1495,13 +1103,12 @@ H5_DLL herr_t H5Fget_mdc_size(hid_t file_id, size_t *max_size_ptr, size_t *min_c
* is enabled. However, the call should be useful if you choose to control metadata cache size from your
* program.
*
* See "Metadata Caching in HDF5" for details about the metadata cache and the adaptive cache resizing
* See \ref_mdc_in_hdf5 for details about the metadata cache and the adaptive cache resizing
* algorithms. If you have not read, understood, and thought about the material covered in that
* documentation,
* you should not be using this API call.
* \endparblock
*
* \todo Fix the MDC document reference!
*/
H5_DLL herr_t H5Freset_mdc_hit_rate_stats(hid_t file_id);
/**
@ -1797,6 +1404,9 @@ H5_DLL herr_t H5Fclear_elink_file_cache(hid_t file_id);
* For the parameters \p low and \p high, see the description for
* H5Pset_libver_bounds().
*
* \par Example
* \snippet H5F_examples.c libver_bounds
*
* \since 1.10.2
*
*/
@ -1835,7 +1445,7 @@ H5_DLL herr_t H5Fset_libver_bounds(hid_t file_id, H5F_libver_t low, H5F_libver_t
* list, and H5Fget_mdc_logging_status() will return the current state of
* the logging flags.
*
* The log format is described in the \Emph{Metadata Cache Logging} document.
* The log format is described in the \ref_mdc_logging document.
*
* \note Logging can only be started or stopped if metadata cache logging was enabled
* via H5Pset_mdc_log_options().\n
@ -1849,8 +1459,6 @@ H5_DLL herr_t H5Fset_libver_bounds(hid_t file_id, H5F_libver_t low, H5F_libver_t
*
* \since 1.10.0
*
* \todo Fix the document reference!
*
*/
H5_DLL herr_t H5Fstart_mdc_logging(hid_t file_id);
/**
@ -1887,7 +1495,7 @@ H5_DLL herr_t H5Fstart_mdc_logging(hid_t file_id);
* list, and H5Fget_mdc_logging_status() will return the current state of
* the logging flags.
*
* The log format is described in the \Emph{Metadata Cache Logging} document.
* The log format is described in the \ref_mdc_logging document.
*
* \note Logging can only be started or stopped if metadata cache logging was enabled
* via H5Pset_mdc_log_options().\n
@ -1933,7 +1541,7 @@ H5_DLL herr_t H5Fstop_mdc_logging(hid_t file_id);
* list, and H5Fget_mdc_logging_status() will return the current state of
* the logging flags.
*
* The log format is described in the \Emph{Metadata Cache Logging} document.
* The log format is described in the \ref_mdc_logging document.
*
* \note Unlike H5Fstart_mdc_logging() and H5Fstop_mdc_logging(), this function can
* be called on any open file identifier.
@ -1944,7 +1552,7 @@ H5_DLL herr_t H5Fget_mdc_logging_status(hid_t file_id, hbool_t *is_enabled, hboo
/**
* \ingroup SWMR
*
* \todo Finish this!
* \todo UFO?
*/
H5_DLL herr_t H5Fformat_convert(hid_t fid);
/**
@ -1998,7 +1606,7 @@ H5_DLL herr_t H5Fget_page_buffering_stats(hid_t file_id, unsigned accesses[2], u
* \brief Obtains information about a cache image if it exists
*
* \file_id
* \param[out] image_addr Offset of the cache image if it exists, or #HADDR_UNDEF if it does not
* \param[out] image_addr Offset of the cache image if it exists, or \c HADDR_UNDEF if it does not
* \param[out] image_size Length of the cache image if it exists, or 0 if it does not
* \returns \herr_t
*
@ -2139,11 +1747,10 @@ H5_DLL herr_t H5Fwait(hid_t file_id);
* the desired behavior.
* \endparblock
*
* \see Enabling a Strict Consistency Semantics Model in Parallel HDF5
* \see \ref_cons_semantics
*
* \since 1.8.9
*
* \todo Fix the reference!
*/
H5_DLL herr_t H5Fset_mpi_atomicity(hid_t file_id, hbool_t flag);
/**
@ -2163,11 +1770,10 @@ H5_DLL herr_t H5Fset_mpi_atomicity(hid_t file_id, hbool_t flag);
* Upon successful return, \p flag will be set to \c 1 if file access is set
* to atomic mode and \c 0 if file access is set to nonatomic mode.
*
* \see Enabling a Strict Consistency Semantics Model in Parallel HDF5
* \see \ref_cons_semantics
*
* \since 1.8.9
*
* \todo Fix the reference!
*/
H5_DLL herr_t H5Fget_mpi_atomicity(hid_t file_id, hbool_t *flag);
#endif /* H5_HAVE_PARALLEL */
@ -2199,14 +1805,14 @@ H5_DLL herr_t H5Fget_mpi_atomicity(hid_t file_id, hbool_t *flag);
#ifndef H5_NO_DEPRECATED_SYMBOLS
/* Macros */
#define H5F_ACC_DEBUG (H5CHECK H5OPEN 0x0000u) /*print debug info (deprecated)*/
#define H5F_ACC_DEBUG (H5CHECK H5OPEN 0x0000u) /**< Print debug info \deprecated In which version? */
/* Typedefs */
/**
* Current "global" information about file
*/
//! [H5F_info1_t_snip]
//! <!-- [H5F_info1_t_snip] -->
typedef struct H5F_info1_t {
hsize_t super_ext_size; /**< Superblock extension size */
struct {
@ -2214,7 +1820,7 @@ typedef struct H5F_info1_t {
H5_ih_info_t msgs_info; /**< Shared object header message index & heap size */
} sohm;
} H5F_info1_t;
//! [H5F_info1_t_snip]
//! <!-- [H5F_info1_t_snip] -->
/* Function prototypes */
/**
@ -2252,7 +1858,7 @@ typedef struct H5F_info1_t {
* header indexes. Each index might be either a B-tree or
* a list.
*
* \version 1.10.0 C function H5Fget_info() renamed to H5Fget_info1() and
* \version 1.10.0 Function H5Fget_info() renamed to H5Fget_info1() and
* deprecated in this release.
*
* \since 1.8.0

91
src/H5Gmodule.h
View File

@ -31,9 +31,94 @@
/**
* \defgroup H5G H5G
* \brief Group Interface
* \details The HDF5 Group Interface, H5G, provides a mechanism for managing
* HDF5 groups and their members, which are other HDF5 objects.
*
* \details \Bold{Groups in HDF5:} A group associates names with objects and
* provides a mechanism for mapping a name to an object. Since all
* objects appear in at least one group (with the possible exception of
* the root object) and since objects can have names in more than one
* group, the set of all objects in an HDF5 file is a directed
* graph. The internal nodes (nodes with out-degree greater than zero)
* must be groups while the leaf nodes (nodes with out-degree zero) are
* either empty groups or objects of some other type. Exactly one
* object in every non-empty file is the root object. The root object
* always has a positive in-degree because it is pointed to by the file
* super block.
*
* \Bold{Locating objects in the HDF5 file hierarchy:} An object name
* consists of one or more components separated from one another by
* slashes. An absolute name begins with a slash and the object is
* located by looking for the first component in the root object, then
* looking for the second component in the first object, etc., until
* the entire name is traversed. A relative name does not begin with a
* slash and the traversal begins at the location specified by the
* create or access function.
*
* \Bold{Group implementations in HDF5:} The original HDF5 group
* implementation provided a single indexed structure for link
* storage. A new group implementation, in HDF5 Release 1.8.0, enables
* more efficient compact storage for very small groups, improved link
* indexing for large groups, and other advanced features.
*
* \li The \Emph{original indexed} format remains the default. Links
* are stored in a B-tree in the group’s local heap.
* \li Groups created in the new \Emph{compact-or-indexed} format, the
* implementation introduced with Release 1.8.0, can be tuned for
* performance, switching between the compact and indexed formats
* at thresholds set in the user application.
* - The \Emph{compact} format will conserve file space and processing
* overhead when working with small groups and is particularly
* valuable when a group contains no links. Links are stored
* as a list of messages in the group’s header.
* - The \Emph{indexed} format will yield improved
* performance when working with large groups, e.g., groups
* containing thousands to millions of members. Links are stored in
* a fractal heap and indexed with an improved B-tree.
* \li The new implementation also enables the use of link names consisting of
* non-ASCII character sets (see H5Pset_char_encoding()) and is
* required for all link types other than hard or soft links, e.g.,
* external and user-defined links (see the \ref H5L APIs).
*
* The original group structure and the newer structures are not
* directly interoperable. By default, a group will be created in the
* original indexed format. An existing group can be changed to a
* compact-or-indexed format if the need arises; there is no capability
* to change back. As stated above, once in the compact-or-indexed
* format, a group can switch between compact and indexed as needed.
*
* Groups will be initially created in the compact-or-indexed format
* only when one or more of the following conditions is met:
* \li The low version bound value of the library version bounds property
* has been set to Release 1.8.0 or later in the file access property
* list (see H5Pset_libver_bounds()). Currently, that would require an
* H5Pset_libver_bounds() call with the low parameter set to
* #H5F_LIBVER_LATEST.\n When this property is set for an HDF5 file,
* all objects in the file will be created using the latest available
* format; no effort will be made to create a file that can be read by
* older libraries.
* \li The creation order tracking property, #H5P_CRT_ORDER_TRACKED, has been
* set in the group creation property list (see H5Pset_link_creation_order()).
*
* An existing group, currently in the original indexed format, will be
* converted to the compact-or-indexed format upon the occurrence of
* any of the following events:
* \li An external or user-defined link is inserted into the group.
* \li A link named with a string composed of non-ASCII characters is
* inserted into the group.
*
* The compact-or-indexed format offers performance improvements that
* will be most notable at the extremes, i.e., in groups with zero
* members and in groups with tens of thousands of members. But
* measurable differences may sometimes appear at a threshold as low as
* eight group members. Since these performance thresholds and criteria
* differ from application to application, tunable settings are
* provided to govern the switch between the compact and indexed
* formats (see H5Pset_link_phase_change()). Optimal thresholds will
* depend on the application and the operating environment.
*
* Future versions of HDF5 will retain the ability to create, read,
* write, and manipulate all groups stored in either the original
* indexed format or the compact-or-indexed format.
*
*/
#endif /* H5Gmodule_H */

826
src/H5Gpublic.h
View File

@ -41,24 +41,31 @@
/* Public Typedefs */
/*******************/
/* Types of link storage for groups */
//! <!-- [H5G_storage_t_snip] -->
/**
* Types of link storage for groups
*/
typedef enum H5G_storage_type_t {
H5G_STORAGE_TYPE_UNKNOWN = -1, /* Unknown link storage type */
H5G_STORAGE_TYPE_SYMBOL_TABLE, /* Links in group are stored with a "symbol table" */
/* (this is sometimes called "old-style" groups) */
H5G_STORAGE_TYPE_COMPACT, /* Links are stored in object header */
H5G_STORAGE_TYPE_DENSE /* Links are stored in fractal heap & indexed with v2 B-tree */
H5G_STORAGE_TYPE_UNKNOWN = -1, /**< Unknown link storage type */
H5G_STORAGE_TYPE_SYMBOL_TABLE, /**< Links in group are stored with a "symbol table" */
/**< (this is sometimes called "old-style" groups) */
H5G_STORAGE_TYPE_COMPACT, /**< Links are stored in object header */
H5G_STORAGE_TYPE_DENSE /**< Links are stored in fractal heap & indexed with v2 B-tree */
} H5G_storage_type_t;
//! <!-- [H5G_storage_t_snip] -->
/* Information struct for group (for H5Gget_info/H5Gget_info_by_name/H5Gget_info_by_idx) */
//! [H5G_info_t_snip]
//! <!-- [H5G_info_t_snip] -->
/**
* Information struct for group for
* H5Gget_info(), H5Gget_info_by_name(), and H5Gget_info_by_idx()
*/
typedef struct H5G_info_t {
H5G_storage_type_t storage_type; /* Type of storage for links in group */
hsize_t nlinks; /* Number of links in group */
int64_t max_corder; /* Current max. creation order value for group */
hbool_t mounted; /* Whether group has a file mounted on it */
H5G_storage_type_t storage_type; /**< Type of storage for links in group */
hsize_t nlinks; /**< Number of links in group */
int64_t max_corder; /**< Current max. creation order value for group */
hbool_t mounted; /**< Whether group has a file mounted on it */
} H5G_info_t;
//! [H5G_info_t_snip]
//! <!-- [H5G_info_t_snip] -->
/********************/
/* Public Variables */
@ -120,24 +127,8 @@ H5_DLL hid_t H5Gcreate2(hid_t loc_id, const char *name, hid_t lcpl_id, hid_t gcp
/**
* --------------------------------------------------------------------------
* \ingroup H5G
*
* \brief Asynchronous version of H5Gcreate2()
*
* \app_file
* \app_func
* \app_line
* \fgdta_loc_id
* \param[in] name Name of the group to create
* \lcpl_id
* \gcpl_id
* \gapl_id
* \es_id
*
* \return \hid_t{group}
*
* \see H5Gcreate2()
*
* \ingroup ASYNC
* \async_variant_of{H5Gcreate}
*/
H5_DLL hid_t H5Gcreate_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
const char *name, hid_t lcpl_id, hid_t gcpl_id, hid_t gapl_id, hid_t es_id);
@ -223,22 +214,8 @@ H5_DLL hid_t H5Gopen2(hid_t loc_id, const char *name, hid_t gapl_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5G
*
* \brief Asynchronous version of H5Gopen2()
*
* \app_file
* \app_func
* \app_line
* \fgdta_loc_id
* \param[in] name Name of the group to open
* \gapl_id
* \es_id
*
* \return \hid_t{group}
*
* \see H5Gopen2()
*
* \ingroup ASYNC
* \async_variant_of{H5Gopen}
*/
H5_DLL hid_t H5Gopen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
const char *name, hid_t gapl_id, hid_t es_id);
@ -296,21 +273,8 @@ H5_DLL herr_t H5Gget_info(hid_t loc_id, H5G_info_t *ginfo);
/**
* --------------------------------------------------------------------------
* \ingroup H5G
*
* \brief Asynchronous version of H5Gget_info()
*
* \app_file
* \app_func
* \app_line
* \fgdta_loc_id
* \param[out] ginfo Struct in which group information is returned
* \es_id
*
* \return \hid_t{group}
*
* \see H5Gget_info()
*
* \ingroup ASYNC
* \async_variant_of{H5Gget_info}
*/
H5_DLL herr_t H5Gget_info_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
H5G_info_t *ginfo /*out*/, hid_t es_id);
@ -351,23 +315,8 @@ H5_DLL herr_t H5Gget_info_by_name(hid_t loc_id, const char *name, H5G_info_t *gi
/**
* --------------------------------------------------------------------------
* \ingroup H5G
*
* \brief Asynchronous version of H5Gget_info_by_name()
*
* \app_file
* \app_func
* \app_line
* \fgdta_loc_id
* \param[in] name Name of the group to query
* \param[out] ginfo Struct in which group information is returned
* \lapl_id
* \es_id
*
* \return \herr_t
*
* \see H5Gget_info_by_name()
*
* \ingroup ASYNC
* \async_variant_of{H5Gget_info_by_name}
*/
H5_DLL herr_t H5Gget_info_by_name_async(const char *app_file, const char *app_func, unsigned app_line,
hid_t loc_id, const char *name, H5G_info_t *ginfo /*out*/,
@ -423,29 +372,8 @@ H5_DLL herr_t H5Gget_info_by_idx(hid_t loc_id, const char *group_name, H5_index_
/**
* --------------------------------------------------------------------------
* \ingroup H5G
*
* \brief Asynchronous version of H5Gcreate2()
*
* \app_file
* \app_func
* \app_line
* \fgdta_loc_id
* \param[in] group_name Name of the group to query
* \param[in] idx_type Transient index identifying object
* \param[in] order Transient index identifying object
* \param[in] n Position in the index of the group to query
* \param[out] ginfo Struct in which group information is returned
* \lapl_id
* \es_id
*
* \return Returns
* \li The size of the object name if successful, or
* \li 0 if no name is associated with the group identifier, or
* \li negative value, if failure occurred
*
* \see H5Gcreate2()
*
* \ingroup ASYNC
* \async_variant_of{H5Gget_info_by_idx}
*/
H5_DLL herr_t H5Gget_info_by_idx_async(const char *app_file, const char *app_func, unsigned app_line,
hid_t loc_id, const char *group_name, H5_index_t idx_type,
@ -523,29 +451,18 @@ H5_DLL herr_t H5Grefresh(hid_t group_id);
* Failure to release a group with this call will result in
* resource leaks.
*
* \since 1.0.0
* \par Example
* \snippet H5F_examples.c mount
*
* \version 1.4.0 Fortran function introduced in this release
* \since 1.0.0
*
*/
H5_DLL herr_t H5Gclose(hid_t group_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5G
*
* \brief Asynchronous version of H5Gcreate2()
*
* \app_file
* \app_func
* \app_line
* \group_id
* \es_id
*
* \return \herr_t
*
* \see H5Gcreate2()
*
* \ingroup ASYNC
* \async_variant_of{H5Gclose}
*/
H5_DLL herr_t H5Gclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t group_id,
hid_t es_id);
@ -595,60 +512,649 @@ H5_DLL herr_t H5Gclose_async(const char *app_file, const char *app_func, unsigne
/* Typedefs */
/*
//! <!-- [H5G_obj_t_snip] -->
/**
* An object has a certain type. The first few numbers are reserved for use
* internally by HDF5. Users may add their own types with higher values. The
* values are never stored in the file -- they only exist while an
* application is running. An object may satisfy the `isa' function for more
* than one type.
* values are never stored in the file -- they only exist while an application
* is running. An object may satisfy the `isa' function for more than one type.
*
* \deprecated
*/
typedef enum H5G_obj_t {
H5G_UNKNOWN = -1, /* Unknown object type */
H5G_GROUP, /* Object is a group */
H5G_DATASET, /* Object is a dataset */
H5G_TYPE, /* Object is a named data type */
H5G_LINK, /* Object is a symbolic link */
H5G_UDLINK, /* Object is a user-defined link */
H5G_RESERVED_5, /* Reserved for future use */
H5G_RESERVED_6, /* Reserved for future use */
H5G_RESERVED_7 /* Reserved for future use */
H5G_UNKNOWN = -1, /**< Unknown object type */
H5G_GROUP, /**< Object is a group */
H5G_DATASET, /**< Object is a dataset */
H5G_TYPE, /**< Object is a named data type */
H5G_LINK, /**< Object is a symbolic link */
H5G_UDLINK, /**< Object is a user-defined link */
H5G_RESERVED_5, /**< Reserved for future use */
H5G_RESERVED_6, /**< Reserved for future use */
H5G_RESERVED_7 /**< Reserved for future use */
} H5G_obj_t;
//! <!-- [H5G_obj_t_snip] -->
/** Define the operator function pointer for for H5Giterate() */
//! [H5G_iterate_t_snip]
//! <!-- [H5G_iterate_t_snip] -->
/**
* Callback for H5Giterate()
*
* \deprecated
*/
typedef herr_t (*H5G_iterate_t)(hid_t group, const char *name, void *op_data);
//! [H5G_iterate_t_snip]
//! <!-- [H5G_iterate_t_snip] -->
/** Information about an object */
//! [H5G_stat_t_snip]
//! <!-- [H5G_stat_t_snip] -->
/**
* Information about an object
*
* \deprecated
*/
typedef struct H5G_stat_t {
unsigned long fileno[2]; /*file number */
unsigned long objno[2]; /*object number */
unsigned nlink; /*number of hard links to object*/
H5G_obj_t type; /*basic object type */
time_t mtime; /*modification time */
size_t linklen; /*symbolic link value length */
H5O_stat_t ohdr; /* Object header information */
unsigned long fileno[2]; /**< file number */
unsigned long objno[2]; /**< object number */
unsigned nlink; /**< number of hard links to object*/
H5G_obj_t type; /**< basic object type */
time_t mtime; /**< modification time */
size_t linklen; /**< symbolic link value length */
H5O_stat_t ohdr; /**< Object header information */
} H5G_stat_t;
//! [H5G_stat_t_snip]
//! <!-- [H5G_stat_t_snip] -->
/* Function prototypes */
H5_DLL hid_t H5Gcreate1(hid_t loc_id, const char *name, size_t size_hint);
H5_DLL hid_t H5Gopen1(hid_t loc_id, const char *name);
H5_DLL herr_t H5Glink(hid_t cur_loc_id, H5G_link_t type, const char *cur_name, const char *new_name);
H5_DLL herr_t H5Glink2(hid_t cur_loc_id, const char *cur_name, H5G_link_t type, hid_t new_loc_id,
const char *new_name);
H5_DLL herr_t H5Gmove(hid_t src_loc_id, const char *src_name, const char *dst_name);
H5_DLL herr_t H5Gmove2(hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, const char *dst_name);
H5_DLL herr_t H5Gunlink(hid_t loc_id, const char *name);
H5_DLL herr_t H5Gget_linkval(hid_t loc_id, const char *name, size_t size, char *buf /*out*/);
H5_DLL herr_t H5Gset_comment(hid_t loc_id, const char *name, const char *comment);
H5_DLL int H5Gget_comment(hid_t loc_id, const char *name, size_t bufsize, char *buf);
H5_DLL herr_t H5Giterate(hid_t loc_id, const char *name, int *idx, H5G_iterate_t op, void *op_data);
H5_DLL herr_t H5Gget_num_objs(hid_t loc_id, hsize_t *num_objs);
H5_DLL herr_t H5Gget_objinfo(hid_t loc_id, const char *name, hbool_t follow_link,
H5G_stat_t *statbuf /*out*/);
H5_DLL ssize_t H5Gget_objname_by_idx(hid_t loc_id, hsize_t idx, char *name, size_t size);
/**
*-------------------------------------------------------------------------
* \ingroup H5G
*
* \brief Creates a new group and links it into the file
*
* \fgdta_loc_id
* \param[in] name Name of the group to create
* \param[in] size_hint Optional parameter indicating the number of bytes
* to reserve for the names that will appear in the group
*
* \return \hid_t{group}
*
* \deprecated This function is deprecated in favor of H5Gcreate2().
*
* \details H5Gcreate1() creates a new group with the specified name at the
* specified location, \p loc_id. \p loc_id may be a file, group,
* dataset, named datatype or attribute. If an attribute, dataset, or
* named datatype is specified for \p loc_id then the group will be
* created at the location where the attribute, dataset, or named
* datatype is attached. The name, name, must not already be taken by
* some other object and all parent groups must already exist.
*
* \p name can be a relative path based at \p loc_id or an absolute
* path from the root of the file. Use of this function requires that
* any intermediate groups specified in the path already exist.
*
* The length of a group name, or of the name of any object within a
* group, is not limited.
*
* \p size_hint is a hint for the number of bytes to reserve to store
* the names which will be eventually added to the new group. Passing a
* value of zero for \p size_hint is usually adequate since the library
* is able to dynamically resize the name heap, but a correct hint may
* result in better performance. If a non-positive value is supplied
* for \p size_hint, then a default size is chosen.
*
* The return value is a group identifier for the open group. This
* group identifier should be closed by calling H5Gclose() when it is
* no longer needed.
*
* See H5Gcreate_anon() for a discussion of the differences between
* H5Gcreate1() and H5Gcreate_anon().
*
* \par Example
* \snippet H5F_examples.c mount
*
* \version 1.8.0 Function H5Gcreate() renamed to H5Gcreate1() and deprecated
* in this release.
* \since 1.0.0
*
*/
H5_DLL hid_t H5Gcreate1(hid_t loc_id, const char *name, size_t size_hint);
/**
*-------------------------------------------------------------------------
* \ingroup H5G
*
* \brief Opens an existing group for modification and returns a group
* identifier for that group
*
* \fgdta_loc_id
* \param[in] name Name of the group to open
*
* \return \hid_t{group}
*
* \deprecated This function is deprecated in favor of H5Gopen2().
*
* \details H5Gopen1() opens an existing group, \p name, at the location
* specified by \p loc_id.
*
* H5Gopen1() returns a group identifier for the group that was
* opened. This group identifier should be released by calling
* H5Gclose() when it is no longer needed.
*
* \version 1.8.0 The function H5Gopen() was renamed to H5Gopen1()
* and deprecated in this release.
* \since 1.0.0
*
*/
H5_DLL hid_t H5Gopen1(hid_t loc_id, const char *name);
/**
*-------------------------------------------------------------------------
* \ingroup H5G
*
* \brief Creates a link of the specified type from \p new_name to \p
* cur_name
*
* \fg_loc_id{cur_loc_id}
* \param[in] type Link type
* \param[in] cur_name Name of the existing object
* \param[in] new_name New name for the object
*
* \return \herr_t
*
* \deprecated This function is deprecated.
*
* \details H5Glink() creates a new name for an object that has some current
* name, possibly one of many names it currently has.
*
* If \p link_type is #H5G_LINK_HARD, then \p cur_name must specify
* the name of an existing object and both names are interpreted
* relative to \p cur_loc_id, which is either a file identifier or a
* group identifier.
*
* If \p link_type is #H5G_LINK_SOFT, then \p cur_name can be anything
* and is interpreted at lookup time relative to the group which
* contains the final component of \p new_name. For instance, if \p
* cur_name is \Code{./foo}, \p new_name is \Code{./x/y/bar}, and a
* request is made for \Code{./x/y/bar}, then the actual object looked
* up is \Code{./x/y/./foo}.
* \version 1.8.0 Function deprecated in this release.
*
*/
H5_DLL herr_t H5Glink(hid_t cur_loc_id, H5G_link_t type, const char *cur_name, const char *new_name);
/**
*-------------------------------------------------------------------------
* \ingroup H5G
*
* \brief Creates a link of the specified type from \p cur_name to \p
* new_name
*
* \fg_loc_id{cur_loc_id}
* \param[in] cur_name Name of the existing object
* \param[in] type Link type
* \fg_loc_id{new_loc_id}
* \param[in] new_name New name for the object
*
* \return \herr_t
*
* \deprecated This function is deprecated.
*
* \details H5Glink2() creates a new name for an object that has some current
* name, possibly one of many names it currently has.
*
* If \p link_type is #H5G_LINK_HARD, then \p cur_name must specify the
* name of an existing object and both names are interpreted relative
* to \p cur_loc_id and \p new_loc_id, respectively, which are either
* file identifiers or group identifiers.
*
* If \p link_type is #H5G_LINK_SOFT, then \p cur_name can be anything
* and is interpreted at lookup time relative to the group which
* contains the final component of \p new_name. For instance, if \p
* current_name is \Code{./foo}, \p new_name is \Code{./x/y/bar}, and a
* request is made for \Code{./x/y/bar}, then the actual object looked
* up is \Code{./x/y/./foo}.
* \version 1.8.0 Function deprecated in this release.
*
*/
H5_DLL herr_t H5Glink2(hid_t cur_loc_id, const char *cur_name, H5G_link_t type, hid_t new_loc_id,
const char *new_name);
/**
*-------------------------------------------------------------------------
* \ingroup H5G
*
* \brief Renames an object within an HDF5 file
*
* \fg_loc_id{src_loc_id}
* \param[in] src_name Object's original name
* \param[in] dst_name Object's new name
*
* \return \herr_t
*
* \deprecated This function is deprecated.
*
* \details H5Gmove() renames an object within an HDF5 file. The original name,
* \p src_name, is unlinked from the group graph and the new name, \p
* dst_name, is inserted as an atomic operation. Both names are
* interpreted relative to \p loc_id, which is either a file or a group
* identifier.
*
* \attention Exercise care in moving groups as it is possible to render data in
* a file inaccessible with H5Gmove(). See The Group Interface in the
* HDF5 User's Guide.
*
* \version 1.8.0 Function deprecated in this release.
*
*/
H5_DLL herr_t H5Gmove(hid_t src_loc_id, const char *src_name, const char *dst_name);
/**
*-------------------------------------------------------------------------
* \ingroup H5G
*
* \brief Renames an object within an HDF5 file
*
* \fg_loc_id{src_loc_id}
* \param[in] src_name Object's original name
* \fg_loc_id{dst_loc_id}
* \param[in] dst_name Object's new name
*
* \return \herr_t
*
* \deprecated This function is deprecated.
*
* \details H5Gmove2() renames an object within an HDF5 file. The original name,
* \p src_name, is unlinked from the group graph and the new name, \p
* dst_name, is inserted as an atomic operation.
*
* \p src_name and \p dst_name are interpreted relative to \p
* src_loc_id and \p dst_loc_id, respectively, which are either file or
* group identifiers.
*
* \attention Exercise care in moving groups as it is possible to render data in
* a file inaccessible with H5Gmove2(). See The Group Interface in the
* HDF5 User's Guide.
*
* \version 1.8.0 Function deprecated in this release.
*
*/
H5_DLL herr_t H5Gmove2(hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, const char *dst_name);
/**
*-------------------------------------------------------------------------
* \ingroup H5G
*
* \brief Removes the link to an object from a group
*
* \fg_loc_id{loc_id}
* \param[in] name Name of the object to unlink
*
* \return \herr_t
*
* \deprecated This function is deprecated in favor of the function H5Ldelete().
*
* \details H5Gunlink() removes the object specified by \p name from the group
* graph and decrements the link count for the object to which \p name
* points. This action eliminates any association between name and the
* object to which name pointed.
*
* Object headers keep track of how many hard links refer to an object;
* when the link count reaches zero, the object can be removed from the
* file. Objects which are open are not removed until all identifiers
* to the object are closed.
*
* If the link count reaches zero, all file space associated with the
* object will be released, i.e., identified in memory as freespace. If
* any object identifier is open for the object, the space will not be
* released until after the object identifier is closed.
*
* Note that space identified as freespace is available for re-use only
* as long as the file remains open; once a file has been closed, the
* HDF5 library loses track of freespace. See “Freespace Management” in
* the HDF5 User's Guide for further details.
*
* \attention Exercise care in moving groups as it is possible to render data in
* a file inaccessible with H5Gunlink(). See The Group Interface in the
* HDF5 User's Guide.
*
* \version 1.8.0 Function deprecated in this release.
*
*/
H5_DLL herr_t H5Gunlink(hid_t loc_id, const char *name);
/**
*-------------------------------------------------------------------------
* \ingroup H5G
*
* \brief Returns the name of the object that the symbolic link points to
*
* \fg_loc_id{loc_id}
* \param[in] name Symbolic link to the object whose name is to be returned
* \param[in] size Maximum number of characters of value to be returned
* \param[out] buf A buffer to hold the name of the object being sought
*
* \return \herr_t
*
* \deprecated This function is deprecated in favor of the function H5Lget_val().
*
* \details H5Gget_linkval() returns up to size characters of the name of the
* object that the symbolic link name points to.
*
* The parameter \p loc_id is a file or group identifier.
*
* The parameter \p name must be a symbolic link pointing to the
* desired object and must be defined relative to \p loc_id.
*
* If size is smaller than the size of the returned object name, then
* the name stored in the buffer value will not be \c NULL terminated.
*
* This function fails if \p name is not a symbolic link. The presence
* of a symbolic link can be tested by passing zero for \p size and \p
* NULL for value.
*
* This function should be used only after H5Lget_info1() (or the
* deprecated function H5Gget_objinfo()) has been called to verify that
* name is a symbolic link.
*
* \version 1.8.0 Function deprecated in this release.
*
*/
H5_DLL herr_t H5Gget_linkval(hid_t loc_id, const char *name, size_t size, char *buf /*out*/);
/**
*-------------------------------------------------------------------------
* \ingroup H5G
*
* \brief Sets comment for specified object
*
* \fgdt_loc_id
* \param[in] name Name of the object whose comment is to be set or reset
* name must be \Code{'.'} (dot) if \p loc_id fully specifies
* the object for which the comment is to be set.
* \param[in] comment The new comment
*
* \return \herr_t
*
* \deprecated This function is deprecated in favor of the function
* H5Oset_comment().
*
* \details H5Gset_comment() sets the comment for the object specified by \p
* loc_id and name to comment. Any previously existing comment is
* overwritten.
*
* \p loc_id can specify any object in the file. name can be one of the
* following:
* \li The name of the object relative to \p loc_id
* \li An absolute name of the object, starting from \c /, the file’s
* root group
* \li A dot (\c .), if \p loc_id fully specifies the object
*
* If \p comment is the empty string or a null pointer, the comment
* message is removed from the object.
*
* Comments should be relatively short, null-terminated, ASCII strings.
*
* Comments can be attached to any object that has an object header,
* e.g., datasets, groups, and named datatypes, but not symbolic links.
*
* \version 1.8.0 Function deprecated in this release.
*
*/
H5_DLL herr_t H5Gset_comment(hid_t loc_id, const char *name, const char *comment);
/**
*-------------------------------------------------------------------------
* \ingroup H5G
*
* \brief Retrieves comment for specified object
*
* \fgdt_loc_id
* \param[in] name Name of the object whose comment is to be set or reset
* name must be \Code{'.'} (dot) if \p loc_id fully specifies
* the object for which the comment is to be set.
* \param[in] bufsize Maximum number of comment characters to be returned in \p buf.
* \param[in] buf The comment
*
* \return Returns the number of characters in the comment, counting the \c NULL
* terminator, if successful; the value returned may be larger than
* \p bufsize. Otherwise returns a negative value.
*
* \deprecated This function is deprecated in favor of the function
* H5Oget_comment().
*
* \details H5Gget_comment() retrieves the comment for the the object specified
* by \p loc_id and \p name. The comment is returned in the buffer \p
* buf.
*
* \p loc_id can specify any object in the file. name can be one of the
* following:
* \li The name of the object relative to \p loc_id
* \li An absolute name of the object, starting from \c /, the file’s
* root group
* \li A dot (\c .), if \p loc_id fully specifies the object
*
* At most bufsize characters, including a null-terminator, are
* returned in \p buf. The returned value is not null-terminated if the
* comment is longer than the supplied buffer. If the size of the
* comment is unknown, a preliminary \p H5Gget_comment() call will
* return the size of the comment, including space for the
* null-terminator.
*
* If an object does not have a comment, the empty string is returned
* in comment.
*
* \version 1.8.0 Function deprecated in this release.
*
*/
H5_DLL int H5Gget_comment(hid_t loc_id, const char *name, size_t bufsize, char *buf);
/**
*-------------------------------------------------------------------------
* \ingroup H5G
*
* \brief Iterates over the entries of a group invoking a callback for each
* entry encountered
*
* \fg_loc_id
* \param[in] name Group over which the iteration is performed
* \param[in,out] idx Location at which to begin the iteration
* \param[in] op Operation to be performed on an object at each step of the
* iteration
* \param[in,out] op_data Data associated with the operation
*
* \return \herr_t
*
* \deprecated This function is deprecated in favor of the function
* H5Literate1().
*
* \details H5Giterate() iterates over the members of name in the file or group
* specified with \p loc_id. For each object in the group, the \p
* op_data and some additional information, specified below, are passed
* to the operator function. The iteration begins with the \p idx
* object in the group and the next element to be processed by the
* operator is returned in \p idx. If \p idx is NULL, then the iterator
* starts at the first group member; since no stopping point is
* returned in this case, the iterator cannot be restarted if one of
* the calls to its operator returns non-zero. H5Giterate() does not
* recursively follow links into subgroups of the specified group.
*
* The prototype for \ref H5G_iterate_t is:
* \snippet this H5G_iterate_t_snip
*
* The operation receives the group identifier for the group being
* iterated over, \p group, the name of the current object within
* the group, \p name, and the pointer to the operator data
* passed in to H5Giterate(), \p op_data.
*
* The return values from an operator are:
* \li Zero causes the iterator to continue, returning zero when all
* group members have been processed.
* \li Positive causes the iterator to immediately return that positive
* value, indicating short-circuit success. The iterator can be
* restarted at the next group member.
* \li Negative causes the iterator to immediately return that value,
* indicating failure. The iterator can be restarted at the next
* group member.
*
* H5Giterate() assumes that the membership of the group identified by
* \p name remains unchanged through the iteration. If the membership
* changes during the iteration, the function's behavior is undefined.
*
* H5Giterate() is not recursive. In particular, if a member of \p name
* is found to be a group, call it \c subgroup_a, H5Giterate() does not
* examine the members of \c subgroup_a. When recursive iteration is
* required, the application must handle the recursion, explicitly
* calling H5Giterate() on discovered subgroups.
* \version 1.8.0 Function deprecated in this release.
*
*/
H5_DLL herr_t H5Giterate(hid_t loc_id, const char *name, int *idx, H5G_iterate_t op, void *op_data);
/**
*-------------------------------------------------------------------------
* \ingroup H5G
*
* \brief Returns number of objects in the group specified by its identifier
*
* \fg_loc_id
* \param[out] num_objs Number of objects in the group
*
* \return \herr_t
*
* \deprecated This function is deprecated in favor of the function H5Gget_info().
*
* \details H5Gget_num_objs() returns number of objects in a group. Group is
* specified by its identifier \p loc_id. If a file identifier is
* passed in, then the number of objects in the root group is returned.
*
* \version 1.8.0 Function deprecated in this release.
*
*/
H5_DLL herr_t H5Gget_num_objs(hid_t loc_id, hsize_t *num_objs);
/**
*-------------------------------------------------------------------------
* \ingroup H5G
*
* \brief Returns information about an object.
*
* \fgdt_loc_id
* \param[in] name Name of the object for which status is being sought
* \param[in] follow_link Link flag
* \param[out] statbuf Buffer in which to return information about the object
*
* \return \herr_t
*
* \deprecated This function is deprecated in favor of the functions H5Oget_info()
* and H5Lget_info1().
*
* \details H5Gget_objinfo() returns information about the specified object
* through the \p statbuf argument.
*
* A file or group identifier, \p loc_id, and an object name, \p name,
* relative to \p loc_id, are commonly used to specify the
* object. However, if the object identifier is already known to the
* application, an alternative approach is to use that identifier, \c
* obj_id, in place of \p loc_id, and a dot (\c .) in place of \p
* name. Thus, the alternative versions of the first portion of an
* H5Gget_objinfo() call would be as follows:
* \code
* H5Gget_objinfo (loc_id name ...)
* H5Gget_objinfo (obj_id . ...)
* \endcode
*
* If the object is a symbolic link and follow_link is zero (0), then
* the information returned describes the link itself; otherwise the
* link is followed and the information returned describes the object
* to which the link points. If \p follow_link is non-zero but the
* final symbolic link is dangling (does not point to anything), then
* an error is returned. The \p statbuf fields are undefined for an
* error. The existence of an object can be tested by calling this
* function with a \c NULL \p statbuf.
*
* H5Gget_objinfo() fills in the following data structure (defined in
* H5Gpublic.h):
* \snippet this H5G_stat_t_snip
*
* where \ref H5O_stat_t (defined in H5Opublic.h) is:
* \snippet H5Opublic.h H5O_stat_t_snip
*
* \attention Some systems will be able to record the time accurately but unable
* to retrieve the correct time; such systems (e.g., Irix64) will
* report an \c mtime value of 0 (zero).
*
* \version 1.8.0 Function deprecated in this release.
* \version 1.6.1 Two new fields were added to the \ref H5G_stat_t struct in
* this release.
*
*/
H5_DLL herr_t H5Gget_objinfo(hid_t loc_id, const char *name, hbool_t follow_link,
H5G_stat_t *statbuf /*out*/);
/**
*-------------------------------------------------------------------------
* \ingroup H5G
*
* \brief Returns a name of an object specified by an index
*
* \fg_loc_id
* \param[in] idx Transient index identifying object
* \param[in,out] name Pointer to user-provided buffer the object name
* \param[in] size Name length
*
* \return Returns the size of the object name if successful, or 0 if no name is
* associated with the group identifier. Otherwise returns a negative
* value.
*
* \deprecated This function is deprecated in favor of the function H5Lget_name_by_idx().
*
* \details H5Gget_objname_by_idx() returns a name of the object specified by
* the index \p idx in the group \p loc_id.
*
* The group is specified by a group identifier \p loc_id. If
* preferred, a file identifier may be passed in \p loc_id; that file's
* root group will be assumed.
*
* \p idx is the transient index used to iterate through the objects in
* the group. The value of \p idx is any nonnegative number less than
* the total number of objects in the group, which is returned by the
* function H5Gget_num_objs(). Note that this is a transient index; an
* object may have a different index each time a group is opened.
*
* The object name is returned in the user-specified buffer \p name.
*
* If the size of the provided buffer \p name is less or equal the
* actual object name length, the object name is truncated to
* \Code{max_size - 1} characters.
*
* Note that if the size of the object's name is unkown, a preliminary
* call to H5Gget_objname_by_idx() with \p name set to \c NULL will
* return the length of the object's name. A second call to
* H5Gget_objname_by_idx() can then be used to retrieve the actual
* name.
*
* \version 1.8.0 Function deprecated in this release.
* \since 1.6.0
*
*/
H5_DLL ssize_t H5Gget_objname_by_idx(hid_t loc_id, hsize_t idx, char *name, size_t size);
/**
*-------------------------------------------------------------------------
* \ingroup H5G
*
* \brief Returns the type of an object specified by an index
*
* \fg_loc_id
* \param[in] idx Transient index identifying object
*
* \return Returns the type of the object if successful. Otherwise returns a
* negative value.
*
* \deprecated This function is deprecated in favor of the function H5Oget_info().
*
* \details H5Gget_objtype_by_idx() returns the type of the object specified by
* the index \p idx in the group \p loc_id.
*
* The group is specified by a group identifier \p loc_id. If
* preferred, a file identifier may be passed in \p loc_id; that file's
* root group will be assumed.
*
* \p idx is the transient index used to iterate through the objects in
* the group. This parameter is described in more detail in the
* discussion of H5Gget_objname_by_idx().
*
* \version 1.8.0 Function deprecated in this release.
* \version 1.6.0 The function return type changed from \c int to the enumerated
* type \ref H5G_obj_t.
* \since 1.6.0
*
*/
H5_DLL H5G_obj_t H5Gget_objtype_by_idx(hid_t loc_id, hsize_t idx);
#endif /* H5_NO_DEPRECATED_SYMBOLS */

22
src/H5Ipublic.h
View File

@ -32,6 +32,7 @@
* test/tmisc.c to verify that the H5I{inc|dec|get}_ref() routines
* work correctly with it. \endinternal
*/
//! <!-- [H5I_type_t_snip] -->
typedef enum H5I_type_t {
H5I_UNINIT = (-2), /**< uninitialized type */
H5I_BADID = (-1), /**< invalid Type */
@ -53,6 +54,7 @@ typedef enum H5I_type_t {
H5I_EVENTSET, /**< type ID for event sets */
H5I_NTYPES /**< number of library types, MUST BE LAST! */
} H5I_type_t;
//! <!-- [H5I_type_t_snip] -->
/**
* Type of IDs to return to users
@ -86,30 +88,30 @@ typedef herr_t (*H5I_free_t)(void *, void **);
/**
* The type of a function to compare objects & keys
*/
//! [H5I_search_func_t_snip]
//! <!-- [H5I_search_func_t_snip] -->
typedef int (*H5I_search_func_t)(void *obj, hid_t id, void *key);
//! [H5I_search_func_t_snip]
//! <!-- [H5I_search_func_t_snip] -->
/**
* The type of H5Iiterate() callback functions
*/
//! [H5I_iterate_func_t_snip]
//! <!-- [H5I_iterate_func_t_snip] -->
typedef herr_t (*H5I_iterate_func_t)(hid_t id, void *udata);
//! [H5I_iterate_func_t_snip]
//! <!-- [H5I_iterate_func_t_snip] -->
/**
* The type of the realize_cb callback for H5Iregister_future
*/
//! [H5I_future_realize_func_t_snip]
//! <!-- [H5I_future_realize_func_t_snip] -->
typedef herr_t (*H5I_future_realize_func_t)(void *future_object, hid_t *actual_object_id);
//! [H5I_future_realize_func_t_snip]
//! <!-- [H5I_future_realize_func_t_snip] -->
/**
* The type of the discard_cb callback for H5Iregister_future
*/
//! [H5I_future_discard_func_t_snip]
//! <!-- [H5I_future_discard_func_t_snip] -->
typedef herr_t (*H5I_future_discard_func_t)(void *future_object);
//! [H5I_future_discard_func_t_snip]
//! <!-- [H5I_future_discard_func_t_snip] -->
#ifdef __cplusplus
extern "C" {
@ -173,7 +175,7 @@ H5_DLL hid_t H5Iregister(H5I_type_t type, const void *object);
*
* \details The \p realize_cb parameter is a function pointer that will be
* invoked by the HDF5 library to convert a future object into an
* actual object. The \realize_cb function may be invoked by
* actual object. The \p realize_cb function may be invoked by
* H5Iobject_verify() to return the actual object for a user-defined
* ID class (i.e. an ID class registered with H5Iregister_type()) or
* internally by the HDF5 library in order to use or get information
@ -281,7 +283,7 @@ H5_DLL void *H5Iremove_verify(hid_t id, H5I_type_t type);
* \p id.
*
* Valid types returned by the function are:
* \types
* \id_types
*
* If no valid type can be determined or the identifier submitted is
* invalid, the function returns #H5I_BADID.

2
src/H5Lmodule.h
View File

@ -35,6 +35,8 @@
*
* \defgroup TRAV Link Traversal
* \ingroup H5L
* \defgroup H5LA Advanced Link Functions
* \ingroup H5L
*/
#endif /* H5Lmodule_H */

76
src/H5Lpublic.h
View File

@ -92,7 +92,7 @@ typedef enum {
/**
* \brief Information struct for links
*/
//! [H5L_info2_t_snip]
//! <!-- [H5L_info2_t_snip] -->
typedef struct {
H5L_type_t type; /**< Type of link */
hbool_t corder_valid; /**< Indicate if creation order is valid */
@ -103,7 +103,7 @@ typedef struct {
size_t val_size; /**< Size of a soft link or user-defined link value */
} u;
} H5L_info2_t;
//! [H5L_info2_t_snip]
//! <!-- [H5L_info2_t_snip] -->
/* The H5L_class_t struct can be used to override the behavior of a
* "user-defined" link class. Users should populate the struct with callback
@ -150,7 +150,7 @@ typedef ssize_t (*H5L_query_func_t)(const char *link_name, const void *lnkdata,
* "user-defined" link class. Users should populate the struct with callback
* functions defined elsewhere.
*/
//! [H5L_class_t_snip]
//! <!-- [H5L_class_t_snip] -->
typedef struct {
int version; /**< Version number of this struct */
H5L_type_t id; /**< Link type ID */
@ -162,16 +162,16 @@ typedef struct {
H5L_delete_func_t del_func; /**< Callback for link deletion */
H5L_query_func_t query_func; /**< Callback for queries */
} H5L_class_t;
//! [H5L_class_t_snip]
//! <!-- [H5L_class_t_snip] -->
/**
* \brief Prototype for H5Literate2(), H5Literate_by_name2() operator
*
* The H5O_token_t version is used in the VOL layer and future public API calls.
*/
//! [H5L_iterate2_t_snip]
//! <!-- [H5L_iterate2_t_snip] -->
typedef herr_t (*H5L_iterate2_t)(hid_t group, const char *name, const H5L_info2_t *info, void *op_data);
//! [H5L_iterate2_t_snip]
//! <!-- [H5L_iterate2_t_snip] -->
/**
* \brief Callback for external link traversal
@ -201,8 +201,6 @@ typedef herr_t (*H5L_elink_traverse_t)(const char *parent_file_name, const char
*
* \return \herr_t
*
* \todo We need to get the location ID story straight!
*
* \details H5Lmove() moves a link within an HDF5 file. The original link,
* \p src_name, is removed from \p src_loc and the new link,
* \p dst_name, is inserted at dst_loc. This change is
@ -321,8 +319,6 @@ H5_DLL herr_t H5Lcopy(hid_t src_loc, const char *src_name, hid_t dst_loc, const
*
* \return \herr_t
*
* \todo We need to get the location ID story straight!
*
* \details H5Lcreate_hard() creates a new hard link to a pre-existing object
* in an HDF5 file.
*
@ -357,6 +353,11 @@ H5_DLL herr_t H5Lcopy(hid_t src_loc, const char *src_name, hid_t dst_loc, const
*/
H5_DLL herr_t H5Lcreate_hard(hid_t cur_loc, const char *cur_name, hid_t dst_loc, const char *dst_name,
hid_t lcpl_id, hid_t lapl_id);
/**
* --------------------------------------------------------------------------
* \ingroup ASYNC
* \async_variant_of{H5Lcreate_hard}
*/
H5_DLL herr_t H5Lcreate_hard_async(const char *app_file, const char *app_func, unsigned app_line,
hid_t cur_loc_id, const char *cur_name, hid_t new_loc_id,
const char *new_name, hid_t lcpl_id, hid_t lapl_id, hid_t es_id);
@ -373,8 +374,6 @@ H5_DLL herr_t H5Lcreate_hard_async(const char *app_file, const char *app_func, u
*
* \return \herr_t
*
* \todo We need to get the location ID story straight!
*
* \details H5Lcreate_soft() creates a new soft link to an object in an HDF5
* file.
*
@ -426,6 +425,11 @@ H5_DLL herr_t H5Lcreate_hard_async(const char *app_file, const char *app_func, u
*/
H5_DLL herr_t H5Lcreate_soft(const char *link_target, hid_t link_loc_id, const char *link_name, hid_t lcpl_id,
hid_t lapl_id);
/**
* --------------------------------------------------------------------------
* \ingroup ASYNC
* \async_variant_of{H5Lcreate_soft}
*/
H5_DLL herr_t H5Lcreate_soft_async(const char *app_file, const char *app_func, unsigned app_line,
const char *link_target, hid_t link_loc_id, const char *link_name,
hid_t lcpl_id, hid_t lapl_id, hid_t es_id);
@ -440,8 +444,6 @@ H5_DLL herr_t H5Lcreate_soft_async(const char *app_file, const char *app_func, u
*
* \return \herr_t
*
* \todo We need to get the location ID story straight!
*
* \details H5Ldelete() removes the link specified by \p name from the location
* \p loc_id.
*
@ -468,6 +470,11 @@ H5_DLL herr_t H5Lcreate_soft_async(const char *app_file, const char *app_func, u
*
*/
H5_DLL herr_t H5Ldelete(hid_t loc_id, const char *name, hid_t lapl_id);
/**
* --------------------------------------------------------------------------
* \ingroup ASYNC
* \async_variant_of{H5Ldelete}
*/
H5_DLL herr_t H5Ldelete_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
const char *name, hid_t lapl_id, hid_t es_id);
/**
@ -484,8 +491,6 @@ H5_DLL herr_t H5Ldelete_async(const char *app_file, const char *app_func, unsign
*
* \return \herr_t
*
* \todo We need to get the location ID story straight!
*
* \details H5Ldelete_by_idx() removes the \Emph{n}-th link in a group
* according to the specified order, \p order, in the specified index,
* \p index.
@ -500,6 +505,11 @@ H5_DLL herr_t H5Ldelete_async(const char *app_file, const char *app_func, unsign
*/
H5_DLL herr_t H5Ldelete_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type,
H5_iter_order_t order, hsize_t n, hid_t lapl_id);
/**
* --------------------------------------------------------------------------
* \ingroup ASYNC
* \async_variant_of{H5Ldelete_by_idx}
*/
H5_DLL herr_t H5Ldelete_by_idx_async(const char *app_file, const char *app_func, unsigned app_line,
hid_t loc_id, const char *group_name, H5_index_t idx_type,
H5_iter_order_t order, hsize_t n, hid_t lapl_id, hid_t es_id);
@ -516,8 +526,6 @@ H5_DLL herr_t H5Ldelete_by_idx_async(const char *app_file, const char *app_func,
*
* \return \herr_t
*
* \todo We need to get the location ID story straight!
*
* \details H5Lget_val() returns tha value of link \p name. For smbolic links,
* this is the path to which the link points, including the null
* terminator. For external and user-defined links, it is the link
@ -575,8 +583,6 @@ H5_DLL herr_t H5Lget_val(hid_t loc_id, const char *name, void *buf /*out*/, size
*
* \return \herr_t
*
* \todo We need to get the location ID story straight!
*
* \details H5Lget_val_by_idx() retrieves the value of the \Emph{n}-th link in
* a group, according to the specified order, \p order, within an
* index, \p index.
@ -630,8 +636,6 @@ H5_DLL herr_t H5Lget_val_by_idx(hid_t loc_id, const char *group_name, H5_index_t
*
* \return \herr_t
*
* \todo We need to get the location ID story straight!
*
* \details H5Lexists() allows an application to determine whether the link \p
* name exists in the location specified by \p loc_id. The link may be
* of any type; only the presence of a link with that name is checked.
@ -707,6 +711,11 @@ H5_DLL herr_t H5Lget_val_by_idx(hid_t loc_id, const char *group_name, H5_index_t
*
*/
H5_DLL htri_t H5Lexists(hid_t loc_id, const char *name, hid_t lapl_id);
/**
* --------------------------------------------------------------------------
* \ingroup ASYNC
* \async_variant_of{H5Lexists}
*/
H5_DLL herr_t H5Lexists_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
const char *name, hbool_t *exists, hid_t lapl_id, hid_t es_id);
/**
@ -721,8 +730,6 @@ H5_DLL herr_t H5Lexists_async(const char *app_file, const char *app_func, unsign
*
* \return \herr_t
*
* \todo We need to get the location ID story straight!
*
* \details H5Lget_info2() returns information about the specified link through
* the \p linfo argument.
*
@ -830,8 +837,6 @@ H5_DLL herr_t H5Lget_info2(hid_t loc_id, const char *name, H5L_info2_t *linfo, h
*
* \see H5Lget_info2()
*
* \todo Document H5Lget_info_by_idx()
*
*/
H5_DLL herr_t H5Lget_info_by_idx2(hid_t loc_id, const char *group_name, H5_index_t idx_type,
H5_iter_order_t order, hsize_t n, H5L_info2_t *linfo, hid_t lapl_id);
@ -957,6 +962,11 @@ H5_DLL ssize_t H5Lget_name_by_idx(hid_t loc_id, const char *group_name, H5_index
*/
H5_DLL herr_t H5Literate2(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx,
H5L_iterate2_t op, void *op_data);
/**
* --------------------------------------------------------------------------
* \ingroup ASYNC
* \async_variant_of{H5Literate}
*/
H5_DLL herr_t H5Literate_async(const char *app_file, const char *app_func, unsigned app_line, hid_t group_id,
H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx_p, H5L_iterate2_t op,
void *op_data, hid_t es_id);
@ -1642,8 +1652,10 @@ H5_DLL herr_t H5Lcreate_external(const char *file_name, const char *obj_name, hi
/* Typedefs */
/* Information struct for link (for H5Lget_info1/H5Lget_info_by_idx1) */
//! [H5L_info1_t_snip]
//! <!-- [H5L_info1_t_snip] -->
/**
* Information struct for link (for H5Lget_info1() and H5Lget_info_by_idx1())
*/
typedef struct {
H5L_type_t type; /**< Type of link */
hbool_t corder_valid; /**< Indicate if creation order is valid */
@ -1654,7 +1666,7 @@ typedef struct {
size_t val_size; /**< Size of a soft link or UD link value */
} u;
} H5L_info1_t;
//! [H5L_info1_t_snip]
//! <!-- [H5L_info1_t_snip] -->
/** Callback during link traversal */
typedef hid_t (*H5L_traverse_0_func_t)(const char *link_name, hid_t cur_group, const void *lnkdata,
@ -1674,9 +1686,9 @@ typedef struct {
} H5L_class_0_t;
/** Prototype for H5Literate1() / H5Literate_by_name1() operator */
//! [H5L_iterate1_t_snip]
//! <!-- [H5L_iterate1_t_snip] -->
typedef herr_t (*H5L_iterate1_t)(hid_t group, const char *name, const H5L_info1_t *info, void *op_data);
//! [H5L_iterate1_t_snip]
//! <!-- [H5L_iterate1_t_snip] -->
/* Function prototypes */
/**
@ -1694,8 +1706,6 @@ typedef herr_t (*H5L_iterate1_t)(hid_t group, const char *name, const H5L_info1_
* \deprecated As of HDF5-1.12 this function has been deprecated in favor of
* the function H5Lget_info2() or the macro H5Lget_info().
*
* \todo We need to get the location ID story straight!
*
* \details H5Lget_info1() returns information about the specified link through
* the \p linfo argument.
*

5
src/H5MMpublic.h
View File

@ -29,8 +29,13 @@
#include "H5public.h"
/* These typedefs are currently used for VL datatype allocation/freeing */
//! <!-- [H5MM_allocate_t_snip] -->
typedef void *(*H5MM_allocate_t)(size_t size, void *alloc_info);
//! <!-- [H5MM_allocate_t_snip] -->
//! <!-- [H5MM_free_t_snip] -->
typedef void (*H5MM_free_t)(void *mem, void *free_info);
//! <!-- [H5MM_free_t_snip] -->
#ifdef __cplusplus
extern "C" {

45
src/H5Mmodule.h
View File

@ -26,4 +26,49 @@
#define H5_MY_PKG_ERR H5E_MAP
#define H5_MY_PKG_INIT YES
/**
* \defgroup H5M H5M
* \brief Map Interface
*
* \details \Bold{The interface can only be used with the HDF5 VOL connectors that
* implement map objects.} The native HDF5 library does not support this
* feature.
*
* While the HDF5 data model is a flexible way to store data, some
* applications require a more general way to index information. HDF5
* effectively uses key-value stores internally for a variety of
* purposes, but it does not expose a generic key-value store to the
* API. The Map APIs provide this capability to the HDF5 applications
* in the form of HDF5 map objects. These Map objects contain
* application-defined key-value stores, to which key-value pairs can
* be added, and from which values can be retrieved by key.
*
* HDF5 VOL connectors with support for map objects:
* - DAOS
*
* \par Example:
* \code
* hid_t file_id, fapl_id, map_id, vls_type_id;
* const char *names[2] = ["Alice", "Bob"];
* uint64_t IDs[2] = [25385486, 34873275];
* uint64_t val_out;
*
* <HDF5 VOL setup code ....>
*
* vls_type_id = H5Tcopy(H5T_C_S1);
* H5Tset_size(vls_type_id, H5T_VARIABLE);
* file_id = H5Fcreate("file.h5", H5F_ACC_TRUNC, H5P_DEFAULT, fapl_id);
* map_id = H5Mcreate(file_id, "map", vls_type_id, H5T_NATIVE_UINT64, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
* H5Mput(map_id, vls_type_id, &names[0], H5T_NATIVE_UINT64, &IDs[0], H5P_DEFAULT);
* H5Mput(map_id, vls_type_id, &names[1], H5T_NATIVE_UINT64, &IDs[1], H5P_DEFAULT);
* H5Mget(map_id, vls_type_id, &names[0], H5T_NATIVE_UINT64, &val_out, H5P_DEFAULT);
* if(val_out != IDs[0])
* ERROR;
* H5Mclose(map_id);
* H5Tclose(vls_type_id);
* H5Fclose(file_id);
* \endcode
*
*/
#endif /* H5Dmodule_H */

373
src/H5Mpublic.h
View File

@ -61,8 +61,12 @@ typedef enum H5VL_map_specific_t {
H5VL_MAP_DELETE /* H5Mdelete */
} H5VL_map_specific_t;
/* Callback for H5Miterate() */
//! <!-- [H5M_iterate_t_snip] -->
/**
* Callback for H5Miterate()
*/
typedef herr_t (*H5M_iterate_t)(hid_t map_id, const void *key, void *op_data);
//! <!-- [H5M_iterate_t_snip] -->
/********************/
/* Public Variables */
@ -81,38 +85,397 @@ extern "C" {
*/
#ifdef H5_HAVE_MAP_API
/**
* \ingroup H5M
*
* \brief Creates a map object
*
* \fgdta_loc_id
* \param[in] name Map object name
* \type_id{key_type_id}
* \type_id{val_type_id}
* \lcpl_id
* \mcpl_id
* \mapl_id
* \returns \hid_t{map object}
*
* \details H5Mcreate() creates a new map object for storing key-value
* pairs. The in-file datatype for keys is defined by \p key_type_id
* and the in-file datatype for values is defined by \p val_type_id. \p
* loc_id specifies the location to create the the map object and \p
* name specifies the name of the link to the map object relative to
* \p loc_id.
*
* \since 1.13.0
*
*/
H5_DLL hid_t H5Mcreate(hid_t loc_id, const char *name, hid_t key_type_id, hid_t val_type_id, hid_t lcpl_id,
hid_t mcpl_id, hid_t mapl_id);
/**
* --------------------------------------------------------------------------
* \ingroup ASYNC
* \async_variant_of{H5Mcreate}
*/
H5_DLL hid_t H5Mcreate_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
const char *name, hid_t key_type_id, hid_t val_type_id, hid_t lcpl_id,
hid_t mcpl_id, hid_t mapl_id, hid_t es_id);
/**
* \ingroup H5M
*
* \brief
*
* \details
*
* \since 1.13.0
*
*/
H5_DLL hid_t H5Mcreate_anon(hid_t loc_id, hid_t key_type_id, hid_t val_type_id, hid_t mcpl_id, hid_t mapl_id);
/**
* \ingroup H5M
*
* \brief Opens a map object
*
* \fgdta_loc_id{loc_id}
* \param[in] name Map object name relative to \p loc_id
* \mapl_id
* \returns \hid_t{map object}
*
* \details H5Mopen() finds a map object specified by \p name under the location
* specified by \p loc_id. The map object should be close with
* H5Mclose() when the application is not longer interested in
* accessing it.
*
* \since 1.13.0
*
*/
H5_DLL hid_t H5Mopen(hid_t loc_id, const char *name, hid_t mapl_id);
/**
* --------------------------------------------------------------------------
* \ingroup ASYNC
* \async_variant_of{H5Mopen}
*/
H5_DLL hid_t H5Mopen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
const char *name, hid_t mapl_id, hid_t es_id);
/**
* \ingroup H5M
*
* \brief Terminates access to a map object
*
* \map_id
* \returns \herr_t
*
* \details H5Mclose() closes access to a map object specified by \p map_id and
* releases resources used by it.
*
* It is illegal to subsequently use that same map identifier in calls
* to other map functions.
*
* \since 1.13.0
*
*/
H5_DLL herr_t H5Mclose(hid_t map_id);
/**
* --------------------------------------------------------------------------
* \ingroup ASYNC
* \async_variant_of{H5Mclose}
*/
H5_DLL herr_t H5Mclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t map_id,
hid_t es_id);
H5_DLL hid_t H5Mget_key_type(hid_t map_id);
H5_DLL hid_t H5Mget_val_type(hid_t map_id);
H5_DLL hid_t H5Mget_create_plist(hid_t map_id);
H5_DLL hid_t H5Mget_access_plist(hid_t map_id);
/**
* \ingroup H5M
*
* \brief Gets key datatype for a map object
*
* \map_id
* \returns \hid_t{datatype}
*
* \details H5Mget_key_type() retrieves key datatype as stored in the file for a
* map object specified by \p map_id and returns identifier for the
* datatype.
*
* \since 1.13.0
*
*/
H5_DLL hid_t H5Mget_key_type(hid_t map_id);
/**
* \ingroup H5M
*
* \brief Gets value datatype for a map object
*
* \map_id
* \returns \hid_t{datatype}
*
* \details H5Mget_val_type() retrieves value datatype as stored in the file for
* a map object specified by \p map_id and returns identifier for the
* datatype .
*
* \since 1.13.0
*
*/
H5_DLL hid_t H5Mget_val_type(hid_t map_id);
/**
* \ingroup H5M
*
* \brief Gets creation property list for a map object
*
* \map_id
* \returns \hid_t{map creation property list}
*
* \details H5Mget_create_plist() returns an identifier for a copy of the
* creation property list for a map object specified by \p map_id.
*
* \since 1.13.0
*
*/
H5_DLL hid_t H5Mget_create_plist(hid_t map_id);
/**
* \ingroup H5M
*
* \brief Gets access property list for a map object
*
* \map_id
* \returns \hid_t{map access property list}
*
* \details H5Mget_access_plist() returns an identifier for a copy of the access
* property list for a map object specified by \p map_id.
*
* \since 1.13.0
*
*/
H5_DLL hid_t H5Mget_access_plist(hid_t map_id);
/**
* \ingroup H5M
*
* \brief Retrieves the number of key-value pairs in a map object
*
* \map_id
* \param[out] count The number of key-value pairs stored in the map object
* \dxpl_id
* \returns \herr_t
*
* \details H5Mget_count() retrieves the number of key-value pairs stored in a
* map specified by map_id.
*
* \since 1.13.0
*
*/
H5_DLL herr_t H5Mget_count(hid_t map_id, hsize_t *count, hid_t dxpl_id);
/**
* \ingroup H5M
*
* \brief Adds a key-value pair to a map object
*
* \map_id
* \type_id{key_mem_type_id}
* \param[in] key Pointer to key buffer
* \type_id{val_mem_type_id}
* \param[in] value Pointer to value buffer
* \dxpl_id
* \returns \herr_t
*
* \details H5Mput() adds a key-value pair to a map object specified by \p
* map_id, or updates the value for the specified key if one was set
* previously.
*
* \p key_mem_type_id and \p val_mem_type_id specify the datatypes for
* the provided key and value buffers, and if different from those used
* to create the map object, the key and value will be internally
* converted to the datatypes for the map object.
*
* Any further options can be specified through the property list
* \p dxpl_id.
*
* \since 1.13.0
*
*/
H5_DLL herr_t H5Mput(hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t val_mem_type_id,
const void *value, hid_t dxpl_id);
/**
* --------------------------------------------------------------------------
* \ingroup ASYNC
* \async_variant_of{H5Mput}
*/
H5_DLL herr_t H5Mput_async(const char *app_file, const char *app_func, unsigned app_line, hid_t map_id,
hid_t key_mem_type_id, const void *key, hid_t val_mem_type_id, const void *value,
hid_t dxpl_id, hid_t es_id);
/**
* \ingroup H5M
*
* \brief Retrieves a key-value pair from a map object
*
* \map_id
* \type_id{key_mem_type_id}
* \param[in] key Pointer to key buffer
* \type_id{val_mem_type_id}
* \param[out] value Pointer to value buffer
* \dxpl_id
* \returns \herr_t
*
* \details H5Mget() retrieves from a map object specified by \p map_id, the
* value associated with the provided key \p key. \p key_mem_type_id
* and \p val_mem_type_id specify the datatypes for the provided key
* and value buffers. If if the datatype specified by \p
* key_mem_type_id is different from that used to create the map object
* the key will be internally converted to the datatype for the map
* object for the query, and if the datatype specified by \p
* val_mem_type_id is different from that used to create the map object
* the returned value will be converted to have a datatype as specified
* by \p val_mem_type_id before the function returns.
*
* Any further options can be specified through the property list
* \p dxpl_id.
*
* \since 1.13.0
*
*/
H5_DLL herr_t H5Mget(hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t val_mem_type_id, void *value,
hid_t dxpl_id);
/**
* --------------------------------------------------------------------------
* \ingroup ASYNC
* \async_variant_of{H5Mget}
*/
H5_DLL herr_t H5Mget_async(const char *app_file, const char *app_func, unsigned app_line, hid_t map_id,
hid_t key_mem_type_id, const void *key, hid_t val_mem_type_id, void *value,
hid_t dxpl_id, hid_t es_id);
/**
* \ingroup H5M
*
* \brief Checks if provided key exists in a map object
*
* \map_id
* \type_id{key_mem_type_id}
* \param[in] key Pointer to key buffer
* \param[out] exists Pointer to a buffer to return the existence status
* \dxpl_id
* \returns \herr_t
*
* \details H5Mexists() checks if the provided key is stored in the map object
* specified by \p map_id. If \p key_mem_type_id is different from that
* used to create the map object the key will be internally converted
* to the datatype for the map object for the query.
*
* Any further options can be specified through the property list
* \p dxpl_id.
*
* \since 1.13.0
*
*/
H5_DLL herr_t H5Mexists(hid_t map_id, hid_t key_mem_type_id, const void *key, hbool_t *exists, hid_t dxpl_id);
/**
* \ingroup H5M
*
* \brief Iterates over all key-value pairs in a map object
*
* \map_id
* \param[in,out] idx iteration index
* \type_id{key_mem_type_id}
* \param[in] op User-defined iterator function
* \op_data
* \dxpl_id
* \returns \herr_t
*
* \details H5Miterate() iterates over all key-value pairs stored in the map
* object specified by \p map_id, making the callback specified by \p
* op for each. The \p idx parameter is an in/out parameter that may be
* used to restart a previously interrupted iteration. At the start of
* iteration \p idx should be set to 0, and to restart iteration at the
* same location on a subsequent call to H5Miterate(), \p idx should be
* the same value as returned by the previous call. Iterate callback is
* defined as:
* \snippet this H5M_iterate_t_snip
* The \p key parameter is the buffer for the key for this iteration,
* converted to the datatype specified by \p key_mem_type_id. The \p
* op_data parameter is a simple pass through of the value passed to
* H5Miterate(), which can be used to store application-defined data for
* iteration. A negative return value from this function will cause
* H5Miterate() to issue an error, while a positive return value will
* cause H5Miterate() to stop iterating and return this value without
* issuing an error. A return value of zero allows iteration to continue.
*
* Any further options can be specified through the property list \p dxpl_id.
*
* \since 1.13.0
*
*/
H5_DLL herr_t H5Miterate(hid_t map_id, hsize_t *idx, hid_t key_mem_type_id, H5M_iterate_t op, void *op_data,
hid_t dxpl_id);
/**
* \ingroup H5M
*
* \brief Iterates over all key-value pairs in a map object
*
* \loc_id
* \param[in] map_name Map object name relative to the location specified by \p loc_id
* \param[in,out] idx Iteration index
* \type_id{key_mem_type_id}
* \param[in] op User-defined iterator function
* \op_data
* \dxpl_id
* \lapl_id
* \returns \herr_t
*
* \details H5Miterate_by_name() iterates over all key-value pairs stored in the
* map object specified by \p map_id, making the callback specified by
* \p op for each. The \p idx parameter is an in/out parameter that may
* be used to restart a previously interrupted iteration. At the start
* of iteration \p idx should be set to 0, and to restart iteration at
* the same location on a subsequent call to H5Miterate(), \p idx
* should be the same value as returned by the previous call. Iterate
* callback is defined as:
* \snippet this H5M_iterate_t_snip
* The\p key parameter is the buffer for the key for this iteration,
* converted to the datatype specified by \p key_mem_type_id. The \p
* op_data parameter is a simple pass through of the value passed to
* H5Miterate(), which can be used to store application-defined data
* for iteration. A negative return value from this function will cause
* H5Miterate() to issue an error, while a positive return value will cause
* H5Miterate() to stop iterating and return this value without issuing an
* error. A return value of zero allows iteration to continue.
*
* Any further options can be specified through the property list \p dxpl_id.
*
* \since 1.13.0
*
*/
H5_DLL herr_t H5Miterate_by_name(hid_t loc_id, const char *map_name, hsize_t *idx, hid_t key_mem_type_id,
H5M_iterate_t op, void *op_data, hid_t dxpl_id, hid_t lapl_id);
/**
* \ingroup H5M
*
* \brief Deletes a key-value pair from a map object
*
* \map_id
* \type_id{key_mem_type_id}
* \param[in] key Pointer to key buffer
* \dxpl_id
* \returns \herr_t
*
* \details H5Mdelete() deletes a key-value pair from the map object specified
* by \p map_id. \p key_mem_type_id specifies the datatype for the
* provided key buffer key, and if different from that used to create
* the map object, the key will be internally converted to the datatype
* for the map object.
*
* Any further options can be specified through the property list \p dxpl_id.
*
* \since 1.13.0
*
*/
H5_DLL herr_t H5Mdelete(hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t dxpl_id);
/* API Wrappers for async routines */

227
src/H5Opublic.h
View File

@ -86,17 +86,15 @@
#define H5O_INFO_NUM_ATTRS 0x0004u /* Fill in the num_attrs field */
#define H5O_INFO_ALL (H5O_INFO_BASIC | H5O_INFO_TIME | H5O_INFO_NUM_ATTRS)
/* Flags for H5Oget_native_info.
* Theses flags determine which fields will be filled in in the H5O_native_info_t
* struct.
//! <!-- [H5O_native_info_fields_snip] -->
/**
* Flags for H5Oget_native_info(). Theses flags determine which fields will be
* filled in in the \ref H5O_native_info_t struct.
*/
//! [H5O_native_info_fields_snip]
#define H5O_NATIVE_INFO_HDR 0x0008u /* Fill in the hdr field */
#define H5O_NATIVE_INFO_META_SIZE 0x0010u /* Fill in the meta_size field */
#define H5O_NATIVE_INFO_ALL (H5O_NATIVE_INFO_HDR | H5O_NATIVE_INFO_META_SIZE)
//! [H5O_native_info_fields_snip]
//! <!-- [H5O_native_info_fields_snip] -->
/* Convenience macro to check if the token is the 'undefined' token value */
#define H5O_IS_TOKEN_UNDEF(token) (!HDmemcmp(&(token), &(H5O_TOKEN_UNDEF), sizeof(H5O_token_t)))
@ -105,46 +103,48 @@
/* Public Typedefs */
/*******************/
//! [H5O_type_t_snip]
/* Types of objects in file */
//! <!-- [H5O_type_t_snip] -->
/**
* Types of objects in file
*/
typedef enum H5O_type_t {
H5O_TYPE_UNKNOWN = -1, /* Unknown object type */
H5O_TYPE_GROUP, /* Object is a group */
H5O_TYPE_DATASET, /* Object is a dataset */
H5O_TYPE_NAMED_DATATYPE, /* Object is a named data type */
H5O_TYPE_MAP, /* Object is a map */
H5O_TYPE_NTYPES /* Number of different object types (must be last!) */
H5O_TYPE_UNKNOWN = -1, /**< Unknown object type */
H5O_TYPE_GROUP, /**< Object is a group */
H5O_TYPE_DATASET, /**< Object is a dataset */
H5O_TYPE_NAMED_DATATYPE, /**< Object is a named data type */
H5O_TYPE_MAP, /**< Object is a map */
H5O_TYPE_NTYPES /**< Number of different object types (must be last!) */
} H5O_type_t;
//! <!-- [H5O_type_t_snip] -->
//! [H5O_type_t_snip]
/* Information struct for object header metadata (for H5Oget_info/H5Oget_info_by_name/H5Oget_info_by_idx) */
//! [H5O_hdr_info_t_snip]
//! <!-- [H5O_hdr_info_t_snip] -->
/**
* Information struct for object header metadata (for
* H5Oget_info(), H5Oget_info_by_name(), H5Oget_info_by_idx())
*/
typedef struct H5O_hdr_info_t {
unsigned version; /* Version number of header format in file */
unsigned nmesgs; /* Number of object header messages */
unsigned nchunks; /* Number of object header chunks */
unsigned flags; /* Object header status flags */
unsigned version; /**< Version number of header format in file */
unsigned nmesgs; /**< Number of object header messages */
unsigned nchunks; /**< Number of object header chunks */
unsigned flags; /**< Object header status flags */
struct {
hsize_t total; /* Total space for storing object header in file */
hsize_t meta; /* Space within header for object header metadata information */
hsize_t mesg; /* Space within header for actual message information */
hsize_t free; /* Free space within object header */
hsize_t total; /**< Total space for storing object header in file */
hsize_t meta; /**< Space within header for object header metadata information */
hsize_t mesg; /**< Space within header for actual message information */
hsize_t free; /**< Free space within object header */
} space;
struct {
uint64_t present; /* Flags to indicate presence of message type in header */
uint64_t shared; /* Flags to indicate message type is shared in header */
uint64_t present; /**< Flags to indicate presence of message type in header */
uint64_t shared; /**< Flags to indicate message type is shared in header */
} mesg;
} H5O_hdr_info_t;
//! <!-- [H5O_hdr_info_t_snip] -->
//! [H5O_hdr_info_t_snip]
//! [H5O_info2_t_snip]
/* Data model information struct for objects */
/* (For H5Oget_info / H5Oget_info_by_name / H5Oget_info_by_idx version 3) */
//! <!-- [H5O_info2_t_snip] -->
/**
* Data model information struct for objects
* (For H5Oget_info(), H5Oget_info_by_name(), H5Oget_info_by_idx() version 3)
*/
typedef struct H5O_info2_t {
unsigned long fileno; /* File number that object is located in */
H5O_token_t token; /* Token representing the object */
@ -156,44 +156,52 @@ typedef struct H5O_info2_t {
time_t btime; /* Birth time */
hsize_t num_attrs; /* # of attributes attached to object */
} H5O_info2_t;
//! <!-- [H5O_info2_t_snip] -->
//! [H5O_info2_t_snip]
//! [H5O_native_info_t_snip]
/* Native file format information struct for objects */
/* (For H5Oget_native_info / H5Oget_native_info_by_name / H5Oget_native_info_by_idx) */
//! <!-- [H5O_native_info_t_snip] -->
/**
* Native file format information struct for objects.
* (For H5Oget_native_info(), H5Oget_native_info_by_name(), H5Oget_native_info_by_idx())
*/
typedef struct H5O_native_info_t {
H5O_hdr_info_t hdr; /* Object header information */
H5O_hdr_info_t hdr; /**< Object header information */
/* Extra metadata storage for obj & attributes */
struct {
H5_ih_info_t obj; /* v1/v2 B-tree & local/fractal heap for groups, B-tree for chunked datasets */
H5_ih_info_t attr; /* v2 B-tree & heap for attributes */
H5_ih_info_t obj; /**< v1/v2 B-tree & local/fractal heap for groups, B-tree for chunked datasets */
H5_ih_info_t attr; /**< v2 B-tree & heap for attributes */
} meta_size;
} H5O_native_info_t;
//! <!-- [H5O_native_info_t_snip] -->
//! [H5O_native_info_t_snip]
/* Typedef for message creation indexes */
/**
* Typedef for message creation indexes
*/
typedef uint32_t H5O_msg_crt_idx_t;
/* Prototype for H5Ovisit/H5Ovisit_by_name() operator (version 3) */
//! [H5O_iterate2_t_snip]
//! <!-- [H5O_iterate2_t_snip] -->
/**
* Prototype for H5Ovisit(), H5Ovisit_by_name() operator (version 3)
*/
typedef herr_t (*H5O_iterate2_t)(hid_t obj, const char *name, const H5O_info2_t *info, void *op_data);
//! <!-- [H5O_iterate2_t_snip] -->
//! [H5O_iterate2_t_snip]
//! <!-- [H5O_mcdt_search_ret_t_snip] -->
typedef enum H5O_mcdt_search_ret_t {
H5O_MCDT_SEARCH_ERROR = -1, /* Abort H5Ocopy */
H5O_MCDT_SEARCH_CONT, /* Continue the global search of all committed datatypes in the destination file */
H5O_MCDT_SEARCH_STOP /* Stop the search, but continue copying. The committed datatype will be copied but
not merged. */
H5O_MCDT_SEARCH_ERROR = -1, /**< Abort H5Ocopy */
H5O_MCDT_SEARCH_CONT, /**< Continue the global search of all committed datatypes in the destination file
*/
H5O_MCDT_SEARCH_STOP /**< Stop the search, but continue copying. The committed datatype will be copied
but not merged. */
} H5O_mcdt_search_ret_t;
//! <!-- [H5O_mcdt_search_ret_t_snip] -->
/* Callback to invoke when completing the search for a matching committed datatype from the committed dtype
* list */
//! <!-- [H5O_mcdt_search_cb_t_snip] -->
/**
* Callback to invoke when completing the search for a matching committed
* datatype from the committed dtype list
*/
typedef H5O_mcdt_search_ret_t (*H5O_mcdt_search_cb_t)(void *op_data);
//! <!-- [H5O_mcdt_search_cb_t_snip] -->
/********************/
/* Public Variables */
@ -249,6 +257,11 @@ extern "C" {
*
*/
H5_DLL hid_t H5Oopen(hid_t loc_id, const char *name, hid_t lapl_id);
/**
* --------------------------------------------------------------------------
* \ingroup ASYNC
* \async_variant_of{H5Oopen}
*/
H5_DLL hid_t H5Oopen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
const char *name, hid_t lapl_id, hid_t es_id);
@ -332,6 +345,11 @@ H5_DLL hid_t H5Oopen_by_token(hid_t loc_id, H5O_token_t token);
*/
H5_DLL hid_t H5Oopen_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order,
hsize_t n, hid_t lapl_id);
/**
* --------------------------------------------------------------------------
* \ingroup ASYNC
* \async_variant_of{H5Oopen_by_idx}
*/
H5_DLL hid_t H5Oopen_by_idx_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
const char *group_name, H5_index_t idx_type, H5_iter_order_t order,
hsize_t n, hid_t lapl_id, hid_t es_id);
@ -553,6 +571,11 @@ H5_DLL herr_t H5Oget_info3(hid_t loc_id, H5O_info2_t *oinfo, unsigned fields);
*/
H5_DLL herr_t H5Oget_info_by_name3(hid_t loc_id, const char *name, H5O_info2_t *oinfo, unsigned fields,
hid_t lapl_id);
/**
* --------------------------------------------------------------------------
* \ingroup ASYNC
* \async_variant_of{H5Oget_info_by_name}
*/
H5_DLL herr_t H5Oget_info_by_name_async(const char *app_file, const char *app_func, unsigned app_line,
hid_t loc_id, const char *name, H5O_info2_t *oinfo /*out*/,
unsigned fields, hid_t lapl_id, hid_t es_id);
@ -968,7 +991,6 @@ H5_DLL herr_t H5Odecr_refcount(hid_t object_id);
* - H5Pset_copy_object()
* - H5Pset_create_intermediate_group()
* - H5Pset_mcdt_search_cb()
* .
* - Copying Committed Datatypes with #H5Ocopy - A comprehensive
* discussion of copying committed datatypes (PDF) in
* Advanced Topics in HDF5
@ -980,6 +1002,11 @@ H5_DLL herr_t H5Odecr_refcount(hid_t object_id);
*/
H5_DLL herr_t H5Ocopy(hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, const char *dst_name,
hid_t ocpypl_id, hid_t lcpl_id);
/**
* --------------------------------------------------------------------------
* \ingroup ASYNC
* \async_variant_of{H5Ocopy}
*/
H5_DLL herr_t H5Ocopy_async(const char *app_file, const char *app_func, unsigned app_line, hid_t src_loc_id,
const char *src_name, hid_t dst_loc_id, const char *dst_name, hid_t ocpypl_id,
hid_t lcpl_id, hid_t es_id);
@ -1522,6 +1549,11 @@ H5_DLL herr_t H5Ovisit_by_name3(hid_t loc_id, const char *obj_name, H5_index_t i
*
*/
H5_DLL herr_t H5Oclose(hid_t object_id);
/**
* --------------------------------------------------------------------------
* \ingroup ASYNC
* \async_variant_of{H5Oclose}
*/
H5_DLL herr_t H5Oclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t object_id,
hid_t es_id);
@ -1572,6 +1604,11 @@ H5_DLL herr_t H5Oclose_async(const char *app_file, const char *app_func, unsigne
*
*/
H5_DLL herr_t H5Oflush(hid_t obj_id);
/**
* --------------------------------------------------------------------------
* \ingroup ASYNC
* \async_variant_of{H5Oflush}
*/
H5_DLL herr_t H5Oflush_async(const char *app_file, const char *app_func, unsigned app_line, hid_t obj_id,
hid_t es_id);
/**
@ -1599,6 +1636,11 @@ H5_DLL herr_t H5Oflush_async(const char *app_file, const char *app_func, unsigne
*
*/
H5_DLL herr_t H5Orefresh(hid_t oid);
/**
* --------------------------------------------------------------------------
* \ingroup ASYNC
* \async_variant_of{H5Orefresh}
*/
H5_DLL herr_t H5Orefresh_async(const char *app_file, const char *app_func, unsigned app_line, hid_t oid,
hid_t es_id);
@ -1873,46 +1915,49 @@ H5_DLLVAR const H5O_token_t H5O_TOKEN_UNDEF_g;
/* Typedefs */
/* A struct that's part of the H5G_stat_t structure (deprecated) */
//! [H5O_stat_t_snip]
//! <!-- [H5O_stat_t_snip] -->
/**
* A struct that's part of the \ref H5G_stat_t structure
* \deprecated
*/
typedef struct H5O_stat_t {
hsize_t size; /* Total size of object header in file */
hsize_t free; /* Free space within object header */
unsigned nmesgs; /* Number of object header messages */
unsigned nchunks; /* Number of object header chunks */
hsize_t size; /**< Total size of object header in file */
hsize_t free; /**< Free space within object header */
unsigned nmesgs; /**< Number of object header messages */
unsigned nchunks; /**< Number of object header chunks */
} H5O_stat_t;
//! [H5O_stat_t_snip]
//! <!-- [H5O_stat_t_snip] -->
//! [H5O_info1_t_snip]
/* Information struct for object */
/* (For H5Oget_info/H5Oget_info_by_name/H5Oget_info_by_idx versions 1 & 2) */
//! <!-- [H5O_info1_t_snip] -->
/**
* Information struct for object (For H5Oget_info(), H5Oget_info_by_name(),
* H5Oget_info_by_idx() versions 1 & 2.)
*/
typedef struct H5O_info1_t {
unsigned long fileno; /* File number that object is located in */
haddr_t addr; /* Object address in file */
H5O_type_t type; /* Basic object type (group, dataset, etc.) */
unsigned rc; /* Reference count of object */
time_t atime; /* Access time */
time_t mtime; /* Modification time */
time_t ctime; /* Change time */
time_t btime; /* Birth time */
hsize_t num_attrs; /* # of attributes attached to object */
H5O_hdr_info_t hdr; /* Object header information */
unsigned long fileno; /**< File number that object is located in */
haddr_t addr; /**< Object address in file */
H5O_type_t type; /**< Basic object type (group, dataset, etc.) */
unsigned rc; /**< Reference count of object */
time_t atime; /**< Access time */
time_t mtime; /**< Modification time */
time_t ctime; /**< Change time */
time_t btime; /**< Birth time */
hsize_t num_attrs; /**< # of attributes attached to object */
H5O_hdr_info_t hdr; /**< Object header information */
/* Extra metadata storage for obj & attributes */
struct {
H5_ih_info_t obj; /* v1/v2 B-tree & local/fractal heap for groups, B-tree for chunked datasets */
H5_ih_info_t attr; /* v2 B-tree & heap for attributes */
H5_ih_info_t obj; /**< v1/v2 B-tree & local/fractal heap for groups, B-tree for chunked datasets */
H5_ih_info_t attr; /**< v2 B-tree & heap for attributes */
} meta_size;
} H5O_info1_t;
//! <!-- [H5O_info1_t_snip] -->
//! [H5O_info1_t_snip]
/* Prototype for H5Ovisit/H5Ovisit_by_name() operator (versions 1 & 2) */
//! [H5O_iterate1_t_snip]
//! <!-- [H5O_iterate1_t_snip] -->
/**
* Prototype for H5Ovisit(), H5Ovisit_by_name() operator (versions 1 & 2)
*/
typedef herr_t (*H5O_iterate1_t)(hid_t obj, const char *name, const H5O_info1_t *info, void *op_data);
//! [H5O_iterate1_t_snip]
//! <!-- [H5O_iterate1_t_snip] -->
/* Function prototypes */

6
src/H5PLpublic.h
View File

@ -28,8 +28,7 @@
*/
#define H5PL_NO_PLUGIN "::"
//! [H5PL_type_t_snip]
//! <!-- [H5PL_type_t_snip] -->
/**
* Plugin type (bit-position) used by the plugin library
*/
@ -39,8 +38,7 @@ typedef enum H5PL_type_t {
H5PL_TYPE_VOL = 1, /**< VOL driver */
H5PL_TYPE_NONE = 2 /**< Sentinel: This must be last! */
} H5PL_type_t;
//! [H5PL_type_t_snip]
//! <!-- [H5PL_type_t_snip] -->
/* Common dynamic plugin type flags used by the set/get_loading_state functions */
#define H5PL_FILTER_PLUGIN 0x0001

5
src/H5Pmodule.h
View File

@ -44,7 +44,6 @@
* and compressed.
*
* \todo Describe concisely what the functions in this module are about.
* \todo Clicking on "more" after "Property List Interface" at the top does not work
*
* \defgroup GPLO General Property List Operations
* \ingroup H5P
@ -70,6 +69,10 @@
* \ingroup H5P
* \defgroup OCPPL Object Copy Properties
* \ingroup H5P
* \defgroup GACPL General Access Properties
* \ingroup H5P
* \defgroup MAPL Map Access Properties
* \ingroup H5P
*/
#endif /* H5Pmodule_H */

3130
src/H5Ppublic.h
View File

File diff suppressed because it is too large Load Diff

Some files were not shown because too many files have changed in this diff Show More