summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorLarry Knox <lrknox@hdfgroup.org>2020-11-26 12:32:33 (GMT)
committerGitHub <noreply@github.com>2020-11-26 12:32:33 (GMT)
commit71a42ab05e4c16f8d2915ddc131ef5892ddf9a24 (patch)
treebbc3807295b9cff2aab1bf57b1d86f7fcccebabc
parentb7bfe68968330c3ac39f4d4179498caec1e0ae24 (diff)
downloadhdf5-71a42ab05e4c16f8d2915ddc131ef5892ddf9a24.zip
hdf5-71a42ab05e4c16f8d2915ddc131ef5892ddf9a24.tar.gz
hdf5-71a42ab05e4c16f8d2915ddc131ef5892ddf9a24.tar.bz2
Merge available RM doxygen from develop to hdf5 1 12 (#131)
* Snapshot version 1.12 release 1-3. Update version to 1.12.1-4. * First cut of the H5 public API documentation. (#80) * First cut of the H5 public API documentation. * Added H5Z "bonus track." * Applied Quincey's patch. * Added the missing patches from Quincey's original patch. * H5PL (complete) and basic H5VL API documentation. * Added H5I API docs. * Added H5L API docs. * First installment from Elena's H5T batch. * Second installment of Elena's H5T batch. * Final installment of Elena's H5T batch. * Full set of current H5F documentation. (#105) * First cut of the H5 public API documentation. * Added H5Z "bonus track." * Applied Quincey's patch. * Added the missing patches from Quincey's original patch. * H5PL (complete) and basic H5VL API documentation. * Added H5I API docs. * Added H5L API docs. * First installment from Elena's H5T batch. * Second installment of Elena's H5T batch. * Final installment of Elena's H5T batch. * Migrated documentation for SWMR functions. * Catching up on MDC functions. * Integrated the H5F MDC function documentation. * Added MDC and parallel H5F functions. * Slightly updated main page. * Added doxygen/dox/H5AC_cache_config_t.dox to MANIFEST. * Doxygen - added (mostly) beginner functions (#112) * Doxygen - added (mostly) beginner functions * Removed duplicate H5Pset_szip function * Add src/H5module.h to MANIFEST. Co-authored-by: Gerd Heber <gheber@hdfgroup.org> Co-authored-by: bljhdf <58825073+bljhdf@users.noreply.github.com>
-rw-r--r--MANIFEST2
-rw-r--r--doxygen/Doxyfile.in1
-rw-r--r--doxygen/aliases16
-rw-r--r--doxygen/dox/H5AC_cache_config_t.dox415
-rw-r--r--doxygen/dox/mainpage.dox70
-rw-r--r--src/H5.c36
-rw-r--r--src/H5Amodule.h17
-rw-r--r--src/H5Apublic.h341
-rw-r--r--src/H5Fpublic.h868
-rw-r--r--src/H5Imodule.h5
-rw-r--r--src/H5Ipublic.h615
-rw-r--r--src/H5Lmodule.h8
-rw-r--r--src/H5Lpublic.h2035
-rw-r--r--src/H5PLmodule.h5
-rw-r--r--src/H5PLpublic.h176
-rw-r--r--src/H5Pmodule.h43
-rw-r--r--src/H5Ppublic.h868
-rw-r--r--src/H5Smodule.h27
-rw-r--r--src/H5Spublic.h282
-rw-r--r--src/H5Tmodule.h76
-rw-r--r--src/H5Tpublic.h2884
-rw-r--r--src/H5VLconnector.h91
-rw-r--r--src/H5VLmodule.h15
-rw-r--r--src/H5VLnative.h6
-rw-r--r--src/H5VLpublic.h287
-rw-r--r--src/H5Zmodule.h67
-rw-r--r--src/H5Zpublic.h661
-rw-r--r--src/H5checksum.c3
-rw-r--r--src/H5dbg.c1
-rw-r--r--src/H5err.txt1
-rw-r--r--src/H5module.h34
-rw-r--r--src/H5private.h2
-rw-r--r--src/H5public.h459
-rw-r--r--src/H5system.c3
-rw-r--r--src/H5timer.c1
-rw-r--r--src/H5trace.c1
36 files changed, 9790 insertions, 632 deletions
diff --git a/MANIFEST b/MANIFEST
index c925f6f..c78280d 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -197,6 +197,7 @@
./doxygen/aliases
./doxygen/Doxyfile.in
./doxygen/dox/api-compat-macros.dox
+./doxygen/dox/H5AC_cache_config_t.dox
./doxygen/dox/H5Acreate.dox
./doxygen/dox/H5Aiterate.dox
./doxygen/dox/H5Fget_info.dox
@@ -563,6 +564,7 @@
./src/H5err.txt
./src/H5detect.c
./src/H5make_libsettings.c
+./src/H5module.h
./src/H5mpi.c
./src/H5overflow.txt
./src/H5private.h
diff --git a/doxygen/Doxyfile.in b/doxygen/Doxyfile.in
index 711fa7a..24fc4ba 100644
--- a/doxygen/Doxyfile.in
+++ b/doxygen/Doxyfile.in
@@ -854,6 +854,7 @@ INPUT_ENCODING = UTF-8
FILE_PATTERNS = H5*public.h \
H5*module.h \
+ H5FDmpio.h \
H5VLconnector.h \
H5VLconnector_passthru.h \
H5VLnative.h \
diff --git a/doxygen/aliases b/doxygen/aliases
index aa22bd4..c10c3e8 100644
--- a/doxygen/aliases
+++ b/doxygen/aliases
@@ -60,8 +60,8 @@ ALIASES += space_id{1}="\param[in] \1 Dataspace identifier"
# Dataypes
################################################################################
-ALIASES += dtype_id="\param[in] dtype_id Datatype identifier"
-ALIASES += dtype_id{1}="\param[in] \1 Datatype identifier"
+ALIASES += type_id="\param[in] type_id Datatype identifier"
+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"
@@ -133,15 +133,21 @@ 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 += vipl_id="\param[in] vipl_id VOL initialization property list identifier"
-ALIASES += vipl_id{1}="\param[in] \1 vipl_id VOL initialization property list identifier"
-
ALIASES += plist_id="\param[in] plist_id Property list identifier"
ALIASES += plist_id{1}="\param[in] \1 Property list identifier"
ALIASES += plistcls_id="\param[in] plistcls_id Property list class identifier"
ALIASES += plistcls_id{1}="\param[in] \1 Property list class identifier"
+ALIASES += tapl_id="\param[in] tapl_id Datatype access property list identifier"
+ALIASES += tapl_id{1}="\param[in] \1 Datatype access property list identifier"
+
+ALIASES += tcpl_id="\param[in] tcpl_id Datatype creation property list identifier"
+ALIASES += tcpl_id{1}="\param[in] \1 Datatype creation property list identifier"
+
+ALIASES += vipl_id="\param[in] vipl_id VOL initialization property list identifier"
+ALIASES += vipl_id{1}="\param[in] \1 vipl_id VOL initialization property list identifier"
+
################################################################################
# Objects
################################################################################
diff --git a/doxygen/dox/H5AC_cache_config_t.dox b/doxygen/dox/H5AC_cache_config_t.dox
new file mode 100644
index 0000000..9b9862b
--- /dev/null
+++ b/doxygen/dox/H5AC_cache_config_t.dox
@@ -0,0 +1,415 @@
+/**
+ * \page H5AC-cache-config-t Metadata Cache Configuration
+ * \tableofcontents
+ *
+ * \section gcf General configuration fields
+ *
+ * \par version
+ * Integer field containing the version number of this version
+ * of the H5AC_cache_config_t structure. Any instance of
+ * H5AC_cache_config_t passed to the cache must have a known
+ * version number, or an error will be flagged.
+ *
+ * \par rpt_fcn_enabled
+ * \parblock
+ * Boolean field used to enable and disable the default
+ * reporting function. This function is invoked every time the
+ * automatic cache resize code is run, and reports on its activities.
+ *
+ * This is a debugging function, and should normally be turned off.
+ * \endparblock
+ *
+ * \par open_trace_file
+ * \parblock
+ * Boolean field indicating whether the trace_file_name
+ * field should be used to open a trace file for the cache.
+ *
+ * \Emph{*** DEPRECATED ***} Use \Code{H5Fstart/stop} logging functions instead
+ *
+ * The trace file is a debuging feature that allow the capture of
+ * top level metadata cache requests for purposes of debugging and/or
+ * optimization. This field should normally be set to \c FALSE, as
+ * trace file collection imposes considerable overhead.
+ *
+ * This field should only be set to \c TRUE when the 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 \c close_trace_file
+ * field is also \c TRUE.
+ * \endparblock
+ *
+ * \par close_trace_file
+ * \parblock
+ * Boolean field indicating whether the current trace
+ * file (if any) should be closed.
+ *
+ * \Emph{*** DEPRECATED ***} Use \Code{H5Fstart/stop} logging functions instead
+ *
+ * See the above comments on the open_trace_file field. This field
+ * should be set to \c FALSE unless there is an open trace file on the
+ * cache that you wish to close.
+ * \endparblock
+ *
+ * \par trace_file_name
+ * \parblock
+ * Full path of the trace file to be opened if the
+ * open_trace_file field is \c TRUE.
+ *
+ * \Emph{*** DEPRECATED ***} Use \Code{H5Fstart/stop} logging functions instead
+ *
+ * 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.
+ *
+ * The length of the path must not exceed #H5AC__MAX_TRACE_FILE_NAME_LEN
+ * characters.
+ * \endparblock
+ *
+ * \par evictions_enabled
+ * \parblock
+ * Boolean field used to either report the current
+ * evictions enabled status of the cache, or to set the cache's
+ * evictions enabled status.
+ *
+ * In general, the metadata cache should always be allowed to
+ * evict entries. However, in some cases it is advantageous to
+ * disable evictions briefly, and thereby postpone metadata
+ * writes. However, this must be done with care, as the cache
+ * can grow quickly. If you do this, re-enable evictions as
+ * soon as possible and monitor cache size.
+ *
+ * At present, evictions can only be disabled if automatic
+ * cache resizing is also disabled (that is, \Code{(incr_mode ==
+ * H5C_incr__off ) && ( decr_mode == H5C_decr__off )}). There
+ * is no logical reason why this should be so, but it simplifies
+ * implementation and testing, and I can't think of any reason
+ * why it would be desireable. If you can think of one, I'll
+ * revisit the issue. (JM)
+ * \endparblock
+ *
+ * \par set_initial_size
+ * Boolean flag indicating whether the size of the
+ * initial size of the cache is to be set to the value given in
+ * the initial_size field. If set_initial_size is \c FALSE, the
+ * initial_size field is ignored.
+ *
+ * \par initial_size
+ * If enabled, this field contain the size the cache is
+ * to be set to upon receipt of this structure. Needless to say,
+ * initial_size must lie in the closed interval \Code{[min_size, max_size]}.
+ *
+ * \par min_clean_fraction
+ * \c double in the range 0 to 1 indicating the fraction
+ * of the cache that is to be kept clean. This field is only used
+ * in parallel mode. Typical values are 0.1 to 0.5.
+ *
+ * \par max_size
+ * Maximum size to which the cache can be adjusted. The
+ * supplied value must fall in the closed interval
+ * \Code{[MIN_MAX_CACHE_SIZE, MAX_MAX_CACHE_SIZE]}. Also, \c max_size must
+ * be greater than or equal to \c min_size.
+ *
+ * \par min_size
+ * Minimum size to which the cache can be adjusted. The
+ * supplied value must fall in the closed interval
+ * \Code{[H5C__MIN_MAX_CACHE_SIZE, H5C__MAX_MAX_CACHE_SIZE]}. Also, \c min_size
+ * must be less than or equal to \c max_size.
+ *
+ * \par epoch_length
+ * \parblock
+ * Number of accesses on the cache over which to collect
+ * hit rate stats before running the automatic cache resize code,
+ * if it is enabled.
+ *
+ * At the end of an epoch, we discard prior hit rate data and start
+ * collecting afresh. The epoch_length must lie in the closed
+ * interval \Code{[H5C__MIN_AR_EPOCH_LENGTH, H5C__MAX_AR_EPOCH_LENGTH]}.
+ * \endparblock
+ *
+ *
+ * \section csicf Cache size increase control fields
+ *
+ * \par incr_mode
+ * Instance of the \c H5C_cache_incr_mode enumerated type whose
+ * value indicates how we determine whether the cache size should be
+ * increased. At present there are two possible values:
+ * \li \c H5C_incr__off: Don't attempt to increase the size of the cache
+ * automatically.\n
+ * When this increment mode is selected, the remaining fields
+ * in the cache size increase section ar ignored.
+ * \li \c H5C_incr__threshold: Attempt to increase the size of the cache
+ * whenever the average hit rate over the last epoch drops
+ * below the value supplied in the \c lower_hr_threshold
+ * field.\n
+ * Note that this attempt will fail if the cache is already
+ * at its maximum size, or if the cache is not already using
+ * all available space.
+ *
+ * Note that you must set \c decr_mode to \c H5C_incr__off if you
+ * disable metadata cache entry evictions.
+ *
+ * \par lower_hr_threshold
+ * \parblock
+ * Lower hit rate threshold. If the increment mode
+ * (\c incr_mode) is \c H5C_incr__threshold and the hit rate drops below the
+ * value supplied in this field in an epoch, increment the cache size by
+ * \c size_increment. Note that cache size may not be incremented above
+ * \c max_size, and that the increment may be further restricted by the
+ * \c max_increment field if it is enabled.
+ *
+ * When enabled, this field must contain a value in the range [0.0, 1.0].
+ * Depending on the \c incr_mode selected, it may also have to be less than
+ * \c upper_hr_threshold.
+ * \endparblock
+ *
+ * \par increment
+ * \parblock
+ * Double containing the multiplier used to derive the new
+ * cache size from the old if a cache size increment is triggered.
+ * The increment must be greater than 1.0, and should not exceed 2.0.
+ *
+ * The new cache size is obtained my multiplying the current max cache
+ * size by the increment, and then clamping to \c max_size and to stay
+ * within the \c max_increment as necessary.
+ * \endparblock
+ *
+ * \par apply_max_increment
+ * Boolean flag indicating whether the \c max_increment
+ * field should be used to limit the maximum cache size increment.
+ *
+ * \par max_increment
+ * If enabled by the \c apply_max_increment field described
+ * above, this field contains the maximum number of bytes by which the
+ * cache size can be increased in a single re-size.
+ *
+ * \par flash_incr_mode
+ * \parblock
+ * Instance of the \c H5C_cache_flash_incr_mode enumerated
+ * type whose value indicates whether and by which algorithm we should
+ * make flash increases in the size of the cache to accommodate insertion
+ * of large entries and large increases in the size of a single entry.
+ *
+ * The addition of the flash increment mode was occasioned by performance
+ * problems that appear when a local heap is increased to a size in excess
+ * of the current cache size. While the existing re-size code dealt with
+ * this eventually, performance was very bad for the remainder of the
+ * epoch.
+ *
+ * At present, there are two possible values for the \c flash_incr_mode:
+ *
+ * \li \c H5C_flash_incr__off: Don't perform flash increases in the size of the cache.
+ *
+ * \li \c H5C_flash_incr__add_space: Let \c x be either the size of a newly
+ * newly inserted entry, or the number of bytes by which the
+ * size of an existing entry has been increased.\n
+ * If \Code{x > flash_threshold * current max cache size},
+ * increase the current maximum cache size by \Code{x * flash_multiple}
+ * less any free space in the cache, and star a new epoch. For
+ * now at least, pay no attention to the maximum increment.
+ *
+ * In both of the above cases, the flash increment pays no attention to
+ * the maximum increment (at least in this first incarnation), but DOES
+ * stay within max_size.
+ *
+ * With a little thought, it should be obvious that the above flash
+ * cache size increase algorithm is not sufficient for all circumstances
+ * -- for example, suppose the user round robins through
+ * \Code{(1/flash_threshold) +1} groups, adding one data set to each on each
+ * pass. Then all will increase in size at about the same time, requiring
+ * the max cache size to at least double to maintain acceptable
+ * performance, however the above flash increment algorithm will not be
+ * triggered.
+ *
+ * Hopefully, the add space algorithms detailed above will be sufficient
+ * for the performance problems encountered to date. However, we should
+ * expect to revisit the issue.
+ * \endparblock
+ *
+ * \par flash_multiple
+ * Double containing the multiple described above in the
+ * \c H5C_flash_incr__add_space section of the discussion of the
+ * \c flash_incr_mode section. This field is ignored unless \c flash_incr_mode
+ * is \c H5C_flash_incr__add_space.
+ *
+ * \par flash_threshold
+ * Double containing the factor by which current max cache
+ * size is multiplied to obtain the size threshold for the add_space flash
+ * increment algorithm. The field is ignored unless \c flash_incr_mode is
+ * \c H5C_flash_incr__add_space.
+ *
+ *
+ * \section csdcf Cache size decrease control fields
+ *
+ * \par decr_mode
+ * \parblock
+ * Instance of the \c H5C_cache_decr_mode enumerated type whose
+ * value indicates how we determine whether the cache size should be
+ * decreased. At present there are four possibilities.
+ *
+ * \li \c H5C_decr__off: Don't attempt to decrease the size of the cache
+ * automatically.\n
+ * When this increment mode is selected, the remaining fields
+ * in the cache size decrease section are ignored.
+ * \li \c H5C_decr__threshold: Attempt to decrease the size of the cache
+ * whenever the average hit rate over the last epoch rises
+ * above the value supplied in the \c upper_hr_threshold
+ * field.
+ * \li \c H5C_decr__age_out: At the end of each epoch, search the cache for
+ * entries that have not been accessed for at least the number
+ * of epochs specified in the epochs_before_eviction field, and
+ * evict these entries. Conceptually, the maximum cache size
+ * is then decreased to match the new actual cache size. However,
+ * this reduction may be modified by the \c min_size, the
+ * \c max_decrement, and/or the \c empty_reserve.
+ * \li \c H5C_decr__age_out_with_threshold: Same as age_out, but we only
+ * attempt to reduce the cache size when the hit rate observed
+ * over the last epoch exceeds the value provided in the
+ * \c upper_hr_threshold field.
+ *
+ * Note that you must set \c decr_mode to \c H5C_decr__off if you
+ * disable metadata cache entry evictions.
+ * \endparblock
+ *
+ * \par upper_hr_threshold
+ * \parblock
+ * Upper hit rate threshold. The use of this field
+ * varies according to the current \c decr_mode :
+ *
+ * \c H5C_decr__off or \c H5C_decr__age_out: The value of this field is
+ * ignored.
+ *
+ * \li \c H5C_decr__threshold: If the hit rate exceeds this threshold in any
+ * epoch, attempt to decrement the cache size by size_decrement.\n
+ * Note that cache size may not be decremented below \c min_size.\n
+ * Note also that if the \c upper_threshold is 1.0, the cache size\n
+ * will never be reduced.
+ *
+ * \li \c H5C_decr__age_out_with_threshold: If the hit rate exceeds this
+ * threshold in any epoch, attempt to reduce the cache size
+ * by evicting entries that have not been accessed for more
+ * than the specified number of epochs.
+ * \endparblock
+ *
+ * \par decrement
+ * \parblock
+ * This field is only used when the decr_mode is
+ * \c H5C_decr__threshold.
+ *
+ * The field is a double containing the multiplier used to derive the
+ * new cache size from the old if a cache size decrement is triggered.
+ * The decrement must be in the range 0.0 (in which case the cache will
+ * try to contract to its minimum size) to 1.0 (in which case the
+ * cache will never shrink).
+ * \endparblock
+ *
+ * \par apply_max_decrement
+ * Boolean flag used to determine whether decrements
+ * in cache size are to be limited by the \c max_decrement field.
+ *
+ * \par max_decrement
+ * Maximum number of bytes by which the cache size can be
+ * decreased in a single re-size. Note that decrements may also be
+ * restricted by the \c min_size of the cache, and (in age out modes) by
+ * the \c empty_reserve field.
+ *
+ * \par epochs_before_eviction
+ * \parblock
+ * Integer field used in \c H5C_decr__age_out and
+ * \c H5C_decr__age_out_with_threshold decrement modes.
+ *
+ * This field contains the number of epochs an entry must remain
+ * unaccessed before it is evicted in an attempt to reduce the
+ * cache size. If applicable, this field must lie in the range
+ * \Code{[1, H5C__MAX_EPOCH_MARKERS]}.
+ * \endparblock
+ *
+ * \par apply_empty_reserve
+ * Boolean field controlling whether the empty_reserve
+ * field is to be used in computing the new cache size when the
+ * decr_mode is H5C_decr__age_out or H5C_decr__age_out_with_threshold.
+ *
+ * \par empty_reserve
+ * \parblock
+ * To avoid a constant racheting down of cache size by small
+ * amounts in the \c H5C_decr__age_out and \c H5C_decr__age_out_with_threshold
+ * modes, this field allows one to require that any cache size
+ * reductions leave the specified fraction of unused space in the cache.
+ *
+ * The value of this field must be in the range [0.0, 1.0]. I would
+ * expect typical values to be in the range of 0.01 to 0.1.
+ * \endparblock
+ *
+ *
+ * \section pcf Parallel Configuration Fields
+ *
+ * In PHDF5, all operations that modify metadata must be executed collectively.
+ *
+ * We used to think that this was enough to ensure consistency across the
+ * metadata caches, but since we allow processes to read metadata individually,
+ * the order of dirty entries in the LRU list can vary across processes,
+ * which can result in inconsistencies between the caches.
+ *
+ * PHDF5 uses several strategies to prevent such inconsistencies in metadata,
+ * all of which use the fact that the same stream of dirty metadata is seen
+ * by all processes for purposes of synchronization. This is done by
+ * having each process count the number of bytes of dirty metadata generated,
+ * and then running a "sync point" whenever this count exceeds a user
+ * specified threshold (see \c dirty_bytes_threshold below).
+ *
+ * The current metadata write strategy is indicated by the
+ * \c metadata_write_strategy field. The possible values of this field, along
+ * with the associated metadata write strategies are discussed below.
+ *
+ * \par dirty_bytes_threshold
+ * \parblock
+ * Threshold of dirty byte creation used to
+ * synchronize updates between caches. (See above for outline and
+ * motivation.)
+ *
+ * This value MUST be consistent across all processes accessing the
+ * file. This field is ignored unless HDF5 has been compiled for
+ * parallel.
+ * \endparblock
+ *
+ * \par metadata_write_strategy
+ * Integer field containing a code indicating the
+ * desired metadata write strategy. The valid values of this field
+ * are enumerated and discussed below:
+ *
+ * \li #H5AC_METADATA_WRITE_STRATEGY__PROCESS_0_ONLY\n
+ * When metadata_write_strategy is set to this value, only process
+ * zero is allowed to write dirty metadata to disk. All other
+ * processes must retain dirty metadata until they are informed at
+ * a sync point that the dirty metadata in question has been written
+ * to disk.\n
+ * When the sync point is reached (or when there is a user generated
+ * flush), process zero flushes sufficient entries to bring it into
+ * complience with its min clean size (or flushes all dirty entries in
+ * the case of a user generated flush), broad casts the list of
+ * entries just cleaned to all the other processes, and then exits
+ * the sync point.\n
+ * Upon receipt of the broadcast, the other processes mark the indicated
+ * entries as clean, and leave the sync point as well.
+ *
+ * \li #H5AC_METADATA_WRITE_STRATEGY__DISTRIBUTED\n
+ * In the distributed metadata write strategy, 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
+ * In this strategy, when a sync point is triggered (either by dirty
+ * metadata creation or manual flush), all processes enter a barrier.\n
+ * On the other side of the barrier, process 0 constructs an ordered
+ * list of the entries to be flushed, and then broadcasts this list
+ * to the caches in all the processes.\n
+ * All processes then scan the list of entries to be flushed, flushing
+ * some, and marking the rest as clean. The algorithm for this purpose
+ * ensures that each entry in the list is flushed exactly once, and
+ * all are marked clean in each cache.\n
+ * Note that in the case of a flush of the cache, no message passing
+ * is necessary, as all processes have the same list of dirty entries,
+ * and all of these entries must be flushed. Thus in this case it is
+ * sufficient for each process to sort its list of dirty entries after
+ * leaving the initial barrier, and use this list as if it had been
+ * received from process zero.\n
+ * To avoid possible messages from the past/future, all caches must
+ * wait until all caches are done before leaving the sync point.
+ */ \ No newline at end of file
diff --git a/doxygen/dox/mainpage.dox b/doxygen/dox/mainpage.dox
index 83fc323..eda967b 100644
--- a/doxygen/dox/mainpage.dox
+++ b/doxygen/dox/mainpage.dox
@@ -1,36 +1,44 @@
-/*! \mainpage API Documentation for HDF5 Version 1.13 (Draft)
+/*! \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
*
- * \section intro_sec Introduction
- *
- * \todo Write an introduction.
- *
- * \section quick_links Quick Links
- *
- * <ul>
- * <li>\ref PDT "Predefined Datatypes"</li>
- * <li>\ref api-compat-macros "API Compatibility Macros"</li>
- * <li><a href="https://hdf5.wiki/">HDF5 Wiki</a></li>
- * </ul>
- *
- * \section using_locations The Use of Locations (Identifier + Name) in the HDF5 API
- *
- * \todo Make this crystal clear!
- *
- * \section cpp_note Programming Note for C++ Developers Using C Functions
- *
- * 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().
- *
- * 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.
*/ \ No newline at end of file
diff --git a/src/H5.c b/src/H5.c
index e7514b4..7efd4f0 100644
--- a/src/H5.c
+++ b/src/H5.c
@@ -14,6 +14,7 @@
/****************/
/* Module Setup */
/****************/
+#include "H5module.h" /* This source code file is part of the H5 module */
/***********/
/* Headers */
@@ -55,6 +56,9 @@ static int H5__mpi_delete_cb(MPI_Comm comm, int keyval, void *attr_val, int *fla
/* Package Variables */
/*********************/
+/* Package initialization variable */
+hbool_t H5_PKG_INIT_VAR = FALSE;
+
/*****************************/
/* Library Private Variables */
/*****************************/
@@ -85,6 +89,33 @@ H5_debug_t H5_debug_g; /* debugging info */
/*******************/
/*--------------------------------------------------------------------------
+NAME
+ H5__init_package -- Initialize interface-specific information
+USAGE
+ herr_t H5__init_package()
+RETURNS
+ Non-negative on success/Negative on failure
+DESCRIPTION
+ Initializes any interface-specific data or routines.
+--------------------------------------------------------------------------*/
+herr_t
+H5__init_package(void)
+{
+ herr_t ret_value = SUCCEED; /* Return value */
+
+ FUNC_ENTER_NOAPI_NOINIT
+
+ /* Run the library initialization routine, if it hasn't already ran */
+ if (!H5_INIT_GLOBAL && !H5_TERM_GLOBAL) { \
+ if (H5_init_library() < 0)
+ HGOTO_ERROR(H5E_LIB, H5E_CANTINIT, FAIL, "unable to initialize library")
+ } /* end if */
+
+done:
+ FUNC_LEAVE_NOAPI(ret_value)
+} /* end H5__init_package() */
+
+/*--------------------------------------------------------------------------
* NAME
* H5_init_library -- Initialize library-global information
* USAGE
@@ -103,6 +134,11 @@ H5_init_library(void)
{
herr_t ret_value = SUCCEED;
+ /* Set the 'library initialized' flag as early as possible, to avoid
+ * possible re-entrancy.
+ */
+ H5_INIT_GLOBAL = TRUE; \
+
FUNC_ENTER_NOAPI(FAIL)
#ifdef H5_HAVE_PARALLEL
diff --git a/src/H5Amodule.h b/src/H5Amodule.h
index 707fc54..09e6c4a 100644
--- a/src/H5Amodule.h
+++ b/src/H5Amodule.h
@@ -29,4 +29,21 @@
#define H5_MY_PKG_ERR H5E_ATTR
#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.
+ *
+ * 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.
+ *
+ */
+
#endif /* _H5Amodule_H */
diff --git a/src/H5Apublic.h b/src/H5Apublic.h
index 89a3b04..3b836e7 100644
--- a/src/H5Apublic.h
+++ b/src/H5Apublic.h
@@ -45,18 +45,306 @@ typedef herr_t (*H5A_operator2_t)(hid_t location_id /*in*/, const char *attr_nam
extern "C" {
#endif
+/*-------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Closes the specified attribute
+ *
+ * \attr_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Aclose() terminates access to the attribute specified by
+ * \p attr_id by releasing the identifier.
+ *
+ * \attention Further use of a released attribute identifier is illegal; a
+ * function using such an identifier will generate an error.
+ *
+ * \since 1.0.0
+ *
+ * \see H5Acreate(), H5Aopen()
+ */
+H5_DLL herr_t H5Aclose(hid_t attr_id);
+/* --------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Creates an attribute attached to a specified object
+ *
+ * \fgdt_loc_id
+ * \param[in] attr_name Name of attribute
+ * \param[in] type_id Attribute datatype identifier
+ * \space_id
+ * \acpl_id
+ * \aapl_id
+ *
+ * \return \hid_tv{attribute}
+ *
+ * \details H5Acreate2() creates an attribute, \p attr_name, which is attached
+ * to the object specified by the identifier \p loc_id.
+ *
+ * The attribute name, \p attr_name, must be unique for the object.
+ *
+ * The attribute is created with the specified datatype and dataspace,
+ * \p type_id and \p space_id, which are created with the H5T and
+ * H5S interfaces, respectively.
+ *
+ * If \p type_id is either a fixed-length or variable-length string,
+ * it is important to set the string length when defining the
+ * datatype. String datatypes are derived from #H5T_C_S1 (or
+ * #H5T_FORTRAN_S1 for Fortran), which defaults to 1 character in
+ * size. See H5Tset_size() and Creating variable-length string
+ * datatypes.
+ *
+ * The access property list is currently unused, but will be used in
+ * the future. This property list should currently be #H5P_DEFAULT.
+ *
+ * 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 If \p loc_id is a file identifier, the attribute will be attached
+ * that file’s root group.
+ *
+ * \since 1.8.0
+ *
+ * \see H5Aclose()
+ *
+ */
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 H5A
+ *
+ * \brief Creates an attribute attached to a specified object
+ *
+ * \fgdt_loc_id
+ * \param[in] obj_name Name, relative to \p loc_id, of object that
+ * attribute is to be attached to
+ * \param[in] attr_name Attribute name
+ * \param[in] type_id Attribute datatype identifier
+ * \space_id
+ * \acpl_id
+ * \aapl_id
+ * \lapl_id
+ *
+ * \return \hid_tv{attribute}
+ *
+ * \details H5Acreate_by_name() creates an attribute, \p attr_name, which is
+ * attached to the object specified by \p loc_id and \p obj_name.
+ *
+ * \p loc_id is a location identifier; \p obj_name is the object
+ * name relative to \p loc_id. If \p loc_id fully specifies the
+ * object to which the attribute is to be attached, \p obj_name
+ * should be '.' (a dot).
+ *
+ * The attribute name, \p attr_name, must be unique for the object.
+ *
+ * The attribute is created with the specified datatype and
+ * dataspace, \p type_id and \p space_id, which are created with
+ * the H5T and H5S interfaces respectively.
+ *
+ * The attribute creation and access property lists are currently
+ * unused, but will be used in the future for optional attribute
+ * creation and access properties. These property lists should
+ * currently be #H5P_DEFAULT.
+ *
+ * The link access property list, \p lapl_id, may provide
+ * information regarding the properties of links required to access
+ * the object, \p obj_name.
+ *
+ * The attribute identifier returned by this function must be
+ * released with H5close() or resource leaks will develop.
+ *
+ * \since 1.8.0
+ *
+ */
H5_DLL hid_t H5Acreate_by_name(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);
+/*--------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Opens an attribute for an object specified by object identifier and
+ * attribute name
+ *
+ * \fgdt_loc_id{obj_id}
+ * \param[in] attr_name Name of attribute to open
+ * \aapl_id
+ *
+ * \return \hid_tv{attribute}
+ *
+ * \details H5Aopen() opens an existing attribute, \p attr_name, that is
+ * attached to object specified by an object identifier, \p obj_id.
+ *
+ * The attribute access property list, \p aapl_id, is currently unused
+ * and should be #H5P_DEFAULT.
+ *
+ * This function, H5Aopen_by_idx() or H5Aopen_by_name() must be called
+ * before the attribute can be accessed for any further purpose,
+ * including reading, writing, or any modification.
+ *
+ * The attribute identifier returned by this function must be released
+ * with H5Aclose() or resource leaks will develop.
+ *
+ * \since 1.8.0
+ *
+ * \see H5Aclose(), H5Acreate()
+ */
H5_DLL hid_t H5Aopen(hid_t obj_id, const char *attr_name, hid_t aapl_id);
-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 H5A
+ *
+ * \brief Opens the nth attribute attached to an object
+ *
+ * \loc_id
+ * \param[in] obj_name Name of object to which attribute is attached,
+ * relative to location
+ * \param[in] idx_type Type of index
+ * \param[in] order Index traversal order
+ * \param[in] n Attribute’s position in index
+ * \aapl_id
+ * \lapl_id
+ *
+ * \return \hid_tv{attribute}
+ *
+ * \details H5Aopen_by_idx() opens an existing attribute that is attached
+ * to an object specified by location and name, \p loc_id and
+ * \p obj_name, respectively. If \p loc_id fully specifies the
+ * object to which the attribute is attached, \p obj_name, should
+ * be '.' (a dot).
+ *
+ * The attribute is identified by an index type, an index traversal
+ * order, and a position in the index, \p idx_type, \p order and
+ * \p n, respectively. These parameters and their valid values are
+ * discussed in the description of H5Aiterate2().
+ *
+ * The attribute access property list, \p aapl_id, is currently
+ * unused and should currently be #H5P_DEFAULT.
+ *
+ * The link access property list, \p lapl_id, may provide
+ * information regarding the properties of links required to access
+ * the object, \p obj_name.
+ *
+ * This function, H5Aopen(), or H5Aopen_by_name() must be called
+ * before an attribute can be accessed for any further purpose,
+ * including reading, writing, or any modification.
+ *
+ * The attribute identifier returned by this function must be
+ * released with H5Aclose() or resource leaks will develop.
+ *
+ * \since 1.8.0
+ *
+ */
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);
-H5_DLL herr_t H5Awrite(hid_t attr_id, hid_t type_id, const void *buf);
+/*--------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Opens an attribute for an object by object name and attribute name
+ *
+ * \fgdt_loc_id
+ * \param[in] obj_name Name of object to which attribute is attached,
+ * relative to \p loc_id
+ * \param[in] attr_name Name of attribute to open
+ * \aapl_id
+ * \lapl_id
+ *
+ * \return \hid_tv{attribute}
+ *
+ * \details H5Aopen_by_name() opens an existing attribute, \p attr_name,
+ * that is attached to an object specified by location and name,
+ * \p loc_id and \p obj_name, respectively.
+ *
+ * \p loc_id specifies a location from which the target object can
+ * be located and \p obj_name is an object name relative to
+ * \p loc_id. If \p loc_id fully specifies the object to which the
+ * attribute is attached, \p obj_name should be '.' (a dot).
+ *
+ * The attribute access property list, \p aapl_id, is currently
+ * unused and should currently be #H5P_DEFAULT.
+ *
+ * The link access property list, \p lapl_id, may provide
+ * information regarding the properties of links required to access
+ * the object, \p obj_name.
+ *
+ * This function, H5Aopen(), or H5Aopen_by_idx() must be called
+ * before an attribute can be accessed for any further purpose,
+ * including reading, writing, or any modification.
+ *
+ * The attribute identifier returned by this function must be
+ * released with H5Aclose() or resource leaks will develop.
+ *
+ * \since 1.8.0
+ *
+ */
+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 H5A
+ *
+ * \brief Reads the value of an attribute
+ *
+ * \attr_id
+ * \mem_type_id{type_id}
+ * \param[out] buf Buffer for data to be read
+ *
+ * \return \herr_t
+ *
+ * \details H5Aread() reads an attribute, specified with \p attr_id. The
+ * attribute's in-memory datatype is specified with \p type_id. The
+ * entire attribute is read into \p buf from the file.
+ *
+ * Datatype conversion takes place at the time of a read or write and
+ * is automatic.
+ *
+ * \version 1.8.8 Fortran updated to Fortran2003.
+ * \version 1.4.2 The \p dims parameter was added to the Fortran API in this
+ * release.
+ * \since 1.0.0
+ *
+ * \see H5Awrite()
+ *
+*/
H5_DLL herr_t H5Aread(hid_t attr_id, hid_t type_id, void *buf);
-H5_DLL herr_t H5Aclose(hid_t attr_id);
+/*--------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Writes data to an attribute
+ *
+ * \attr_id
+ * \mem_type_id{type_id}
+ * \param[out] buf Data to be written
+ *
+ * \return \herr_t
+ *
+ * \details H5Awrite() writes an attribute, specified with \p attr_id. The
+ * attribute's in-memory datatype is specified with \p type_id.
+ * The entire attribute is written from \p buf to the file.
+ *
+ * If \p type_id is either a fixed-length or variable-length string,
+ * it is important to set the string length when defining the datatype.
+ * String datatypes are derived from #H5T_C_S1 (or #H5T_FORTRAN_S1 for
+ * Fortran codes), which defaults to 1 character in size.
+ * See H5Tset_size() and Creating variable-length string datatypes.
+ *
+ * Datatype conversion takes place at the time of a read or write and
+ * is automatic.
+ *
+ * \version 1.8.8 Fortran updated to Fortran2003.
+ * \version 1.4.2 Fortran \p dims parameter added in this release
+ * \since 1.0.0
+ * \see H5Aread()
+ *
+ */
+H5_DLL herr_t H5Awrite(hid_t attr_id, hid_t type_id, const void *buf);
H5_DLL hid_t H5Aget_space(hid_t attr_id);
H5_DLL hid_t H5Aget_type(hid_t attr_id);
H5_DLL hid_t H5Aget_create_plist(hid_t attr_id);
@@ -100,6 +388,51 @@ typedef herr_t (*H5A_operator1_t)(hid_t location_id /*in*/, const char *attr_nam
void *operator_data /*in,out*/);
/* Function prototypes */
+/* --------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Creates an attribute attached to a specified object
+ *
+ * \fgdt_loc_id
+ * \param[in] name Name of attribute to locate and open
+ * \param[in] type_id Identifier of attribute datatype
+ * \space_id
+ * \acpl_id
+ *
+ * \return \hid_tv{attribute}
+ *
+ * \note The \p acpl parameters is currently not used; specify #H5P_DEFAULT.
+ *
+ * \deprecated Deprecated in favor of H5Acreate2()
+ *
+ * \details H5Acreate1() creates an attribute, \p name, which is attached
+ * to the object specified by the identifier \p loc_id.
+ *
+ * The attribute name, \p name, must be unique for the object.
+ *
+ * The attribute is created with the specified datatype and dataspace,
+ * \p type_id and \p space_id, which are created with the H5T and
+ * H5S interfaces, respectively.
+ *
+ * If \p type_id is either a fixed-length or variable-length string,
+ * it is important to set the string length when defining the
+ * datatype. String datatypes are derived from #H5T_C_S1 (or
+ * #H5T_FORTRAN_S1 for Fortran), which defaults to 1 character in
+ * size. See H5Tset_size() and Creating variable-length string
+ * datatypes.
+ *
+ * The attribute identifier returned by this function must be released
+ * with H5Aclose() resource leaks will develop.
+ *
+ * \since 1.8.0
+ *
+ * \version 1.8.0 The function H5Acreate() was renamed to H5Acreate1() and
+ * deprecated in this release.
+ *
+ * \see H5Aclose()
+ *
+ */
H5_DLL hid_t H5Acreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t acpl_id);
H5_DLL hid_t H5Aopen_name(hid_t loc_id, const char *name);
H5_DLL hid_t H5Aopen_idx(hid_t loc_id, unsigned idx);
diff --git a/src/H5Fpublic.h b/src/H5Fpublic.h
index fbee9c5..10cfbbe 100644
--- a/src/H5Fpublic.h
+++ b/src/H5Fpublic.h
@@ -225,6 +225,7 @@ typedef enum H5F_file_space_type_t {
H5F_FILE_SPACE_NTYPES /**< Sentinel */
} H5F_file_space_type_t;
+//! [H5F_retry_info_t_snip]
#define H5F_NUM_METADATA_READ_RETRY_TYPES 21
/**
@@ -235,6 +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]
/**
* Callback for H5Pset_object_flush_cb() in a file access property list
@@ -952,32 +954,542 @@ H5_DLL ssize_t H5Fget_file_image(hid_t file_id, void *buf_ptr, size_t buf_len);
/**
* \ingroup MDC
*
- * \todo Finish this!
+ * \brief Obtains current metadata cache configuration for target file
+ *
+ * \file_id
+ * \param[in,out] config_ptr Pointer to the H5AC_cache_config_t instance in which
+ * the current metadata cache configuration is to be
+ * reported. The fields of this structure are discussed
+ * \ref H5AC-cache-config-t "here".
+ * \return \herr_t
+ *
+ * \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>
+ *
+ * \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);
/**
* \ingroup MDC
*
- * \todo Finish this!
+ * \brief Attempts to configure metadata cache of target file
+ *
+ * \file_id
+ * \param[in,out] config_ptr Pointer to the H5AC_cache_config_t instance
+ * containing the desired configuration.
+ * The fields of this structure are discussed
+ * \ref H5AC-cache-config-t "here".
+ * \return \herr_t
+ *
+ * \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 normally be set
+ * to <code>0</code>, as trace file collection imposes considerable overhead.</p><p>This field should only 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>
+ *
+ * \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);
/**
* \ingroup MDC
*
- * \todo Finish this!
+ * \brief Obtains target file's metadata cache hit rate
+ *
+ * \file_id
+ * \param[out] hit_rate_ptr Pointer to the double in which the hit rate is returned. Note that
+ * \p hit_rate_ptr is undefined if the API call fails
+ * \return \herr_t
+ *
+ * \details H5Fget_mdc_hit_rate() queries the metadata cache of the target file to obtain its hit rate
+ * \Code{(cache hits / (cache hits + cache misses))} since the last time hit rate statistics
+ * were reset. If the cache has not been accessed since the last time the hit rate stats were
+ * reset, the hit rate is defined to be 0.0.
+ *
+ * The hit rate stats can be reset either manually (via H5Freset_mdc_hit_rate_stats()), or
+ * automatically. If the cache's adaptive resize code is enabled, the hit rate stats will be
+ * reset once per epoch. If they are reset manually as well, the cache may behave oddly.
+ *
+ * See the overview of the metadata cache in the special topics section of the user manual for
+ * details on the metadata cache and its adaptive resize algorithms.
+ *
*/
H5_DLL herr_t H5Fget_mdc_hit_rate(hid_t file_id, double *hit_rate_ptr);
/**
* \ingroup MDC
*
- * \todo Finish this!
+ * \brief Obtains current metadata cache size data for specified file
+ *
+ * \file_id
+ * \param[out] max_size_ptr Pointer to the location in which the current cache maximum size is to be
+ * returned, or NULL if this datum is not desired
+ * \param[out] min_clean_size_ptr Pointer to the location in which the current cache minimum clean
+ * size is to be returned, or NULL if that datum is not desired
+ * \param[out] cur_size_ptr Pointer to the location in which the current cache size is to be returned,
+ * or NULL if that datum is not desired
+ * \param[out] cur_num_entries_ptr Pointer to the location in which the current number of entries in
+ * the cache is to be returned, or NULL if that datum is not desired
+ * \returns \herr_t
+ *
+ * \details H5Fget_mdc_size() queries the metadata cache of the target file for the desired size
+ * information, and returns this information in the locations indicated by the pointer
+ * parameters. If any pointer parameter is NULL, the associated data is not returned.
+ *
+ * If the API call fails, the values returned via the pointer parameters are undefined.
+ *
+ * If adaptive cache resizing is enabled, the cache maximum size and minimum clean size
+ * may change at the end of each epoch. Current size and current number of entries can
+ * change on each cache access.
+ *
+ * Current size can exceed maximum size under certain conditions. See the overview of the
+ * metadata cache in the special topics section of the user manual for a discussion of this.
+ *
*/
H5_DLL herr_t H5Fget_mdc_size(hid_t file_id, size_t *max_size_ptr, size_t *min_clean_size_ptr,
size_t *cur_size_ptr, int *cur_num_entries_ptr);
/**
* \ingroup MDC
*
- * \todo Finish this!
+ * \brief Resets hit rate statistics counters for the target file
+ *
+ * \file_id
+ * \returns \herr_t
+ *
+ * \details
+ * \parblock
+ * H5Freset_mdc_hit_rate_stats() resets the hit rate statistics counters in the metadata cache
+ * associated with the specified file.
+ *
+ * If the adaptive cache resizing code is enabled, the hit rate statistics are reset at the beginning
+ * of each epoch. This API call allows you to do the same thing from your program.
+ *
+ * The adaptive cache resizing code may behave oddly if you use this call when adaptive cache resizing
+ * 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
+ * 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);
/**
@@ -1067,13 +1579,118 @@ H5_DLL herr_t H5Fget_info2(hid_t obj_id, H5F_info2_t *file_info);
/**
* \ingroup SWMR
*
- * \todo Finish this!
+ * \brief Retrieves the collection of read retries for metadata entries with checksum
+ *
+ * \file_id
+ * \param[out] info Struct containing the collection of read retries for metadata
+ * entries with checksum
+ * \return \herr_t\n
+ *
+ * \details \Bold{Failure Modes:}
+ * \li When the input identifier is not a file identifier.
+ * \li When the pointer to the output structure is NULL.
+ * \li When the memory allocation for \p retries failed.
+ *
+ * \details H5Fget_metadata_read_retry_info() retrieves information regarding the number
+ * of read retries for metadata entries with checksum for the file \p file_id.
+ * This information is reported in the H5F_retry_info_t struct defined in
+ * H5Fpublic.h as follows:
+ * \snippet this H5F_retry_info_t_snip
+ * \c nbins is the number of bins for each \c retries[i] of metadata entry \c i.
+ * It is calculated based on the current number of read attempts used in the
+ * library and logarithmic base 10.
+ *
+ * If read retries are incurred for a metadata entry \c i, the library will
+ * allocate memory for \Code{retries[i] (nbins * sizeof(uint32_t)} and store
+ * the collection of retries there. If there are no retries for a metadata entry
+ * \c i, \Code{retries[i]} will be NULL. After a call to this routine, users should
+ * free each \Code{retries[i]} that is non-NULL, otherwise resource leak will occur.
+ *
+ * For the library default read attempts of 100 for SWMR access, nbins will be 2
+ * as depicted below:
+ * \li \Code{retries[i][0]} is the number of 1 to 9 read retries.
+ * \li \Code{retries[i][1]} is the number of 10 to 99 read retries.
+ * For the library default read attempts of 1 for non-SWMR access, \c nbins will
+ * be 0 and each \Code{retries[i]} will be NULL.
+ *
+ * The following table lists the 21 metadata entries of \Code{retries[]}:
+ * <table>
+ * <tr>
+ * <th>Index for \Code{retries[]}</th>
+ * <th>Metadata entries<sup>*</sup></th>
+ * </tr>
+ * <tr><td>0</td><td>Object header (version 2)</td></tr>
+ * <tr><td>1</td><td>Object header chunk (version 2)</td></tr>
+ * <tr><td>2</td><td>B-tree header (version 2)</td></tr>
+ * <tr><td>3</td><td>B-tree internal node (version 2)</td></tr>
+ * <tr><td>4</td><td>B-tree leaf node (version 2)</td></tr>
+ * <tr><td>5</td><td>Fractal heap header</td></tr>
+ * <tr><td>6</td><td>Fractal heap direct block (optional checksum)</td></tr>
+ * <tr><td>7</td><td>Fractal heap indirect block</td></tr>
+ * <tr><td>8</td><td>Free-space header</td></tr>
+ * <tr><td>9</td><td>Free-space sections</td></tr>
+ * <tr><td>10</td><td>Shared object header message table</td></tr>
+ * <tr><td>11</td><td>Shared message record list</td></tr>
+ * <tr><td>12</td><td>Extensive array header</td></tr>
+ * <tr><td>13</td><td>Extensive array index block</td></tr>
+ * <tr><td>14</td><td>Extensive array super block</td></tr>
+ * <tr><td>15</td><td>Extensive array data block</td></tr>
+ * <tr><td>16</td><td>Extensive array data block page</td></tr>
+ * <tr><td>17</td><td>Fixed array super block</td></tr>
+ * <tr><td>18</td><td>Fixed array data block</td></tr>
+ * <tr><td>19</td><td>Fixed array data block page</td></tr>
+ * <tr><td>20</td><td>File's superblock (version 2)</td></tr>
+ * <tr><td colspan=2><sup>*</sup> All entries are of version 0 (zero) unless indicated otherwise.</td></tr>
+ * </table>
+ *
+ * \note On a system that is not atomic, the library might possibly read inconsistent
+ * metadata with checksum when performing single-writer/multiple-reader (SWMR)
+ * operations for an HDF5 file. Upon encountering such situations, the library
+ * will try reading the metadata again for a set number of times to attempt to
+ * obtain consistent data. The maximum number of read attempts used by the library
+ * will be either the value set via H5Pset_metadata_read_attempts() or the library
+ * default value when a value is not set.\n
+ * When the current number of metadata read attempts used in the library is unable
+ * to remedy the reading of inconsistent metadata on a system, the user can assess
+ * the information obtained via this routine to derive a different maximum value.
+ * The information can also be helpful for debugging purposes to identify potential
+ * issues with metadata flush dependencies and SWMR implementation in general.
+ *
+ * \since 1.10.0
+ *
*/
H5_DLL herr_t H5Fget_metadata_read_retry_info(hid_t file_id, H5F_retry_info_t *info);
/**
* \ingroup SWMR
*
- * \todo Finish this!
+ * \brief Retrieves free-space section information for a file
+ *
+ * \file_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Fstart_swmr_write() will activate SWMR writing mode for a file
+ * associated with \p file_id. This routine will prepare and ensure
+ * the file is safe for SWMR writing as follows:
+ * \li Check that the file is opened with write access (#H5F_ACC_RDWR).
+ * \li Check that the file is opened with the latest library format to
+ * ensure data structures with check-summed metadata are used.
+ * \li Check that the file is not already marked in SWMR writing mode.
+ * \li Enable reading retries for check-summed metadata to remedy
+ * possible checksum failures from reading inconsistent metadata
+ * on a system that is not atomic.
+ * \li Turn off usage of the library's accumulator to avoid possible
+ * ordering problem on a system that is not atomic.
+ * \li Perform a flush of the file’s data buffers and metadata to set
+ * a consistent state for starting SWMR write operations.
+ *
+ * Library objects are groups, datasets, and committed datatypes. For
+ * the current implementation, groups and datasets can remain open when
+ * activating SWMR writing mode, but not committed datatypes. Attributes
+ * attached to objects cannot remain open either.
+ *
+ * \since 1.10.0
+ *
*/
H5_DLL herr_t H5Fstart_swmr_write(hid_t file_id);
/**
@@ -1174,19 +1791,141 @@ H5_DLL herr_t H5Fset_libver_bounds(hid_t file_id, H5F_libver_t low, H5F_libver
/**
* \ingroup MDC
*
- * \todo Finish this!
+ * \brief Starts logging metadata cache events if logging was previously enabled
+ *
+ * \file_id
+ *
+ * \return \herr_t
+ *
+ * \details The metadata cache is a central part of the HDF5 library through
+ * which all \Emph{file metadata} reads and writes take place. File
+ * metadata is normally invisible to the user and is used by the
+ * library for purposes such as locating and indexing data. File
+ * metadata should not be confused with user metadata, which consists
+ * of attributes created by users and attached to HDF5 objects such
+ * as datasets via H5A API calls.
+ *
+ * Due to the complexity of the cache, a trace/logging feature has been
+ * created that can be used by HDF5 developers for debugging and performance
+ * analysis. The functions that control this functionality will normally be
+ * of use to a very limited number of developers outside of The HDF Group.
+ * The functions have been documented to help users create logs that can
+ * be sent with bug reports.
+ *
+ * Control of the log functionality is straightforward. Logging is enabled
+ * via the H5Pset_mdc_log_options() function, which will modify the file
+ * access property list used to open or create a file. This function has
+ * a flag that determines whether logging begins at file open or starts
+ * in a paused state. Log messages can then be controlled via the
+ * H5Fstart_mdc_logging() and H5Fstop_mdc_logging() functions.
+ * H5Pget_mdc_log_options() can be used to examine a file access property
+ * 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.
+ *
+ * \note Logging can only be started or stopped if metadata cache logging was enabled
+ * via H5Pset_mdc_log_options().\n
+ * When enabled and currently logging, the overhead of the logging feature will
+ * almost certainly be significant.\n
+ * The log file is opened when the HDF5 file is opened or created and not when
+ * this function is called for the first time.\n
+ * This function opens the log file and starts logging metadata cache operations
+ * for a particular file. Calling this function when logging has already been
+ * enabled will be considered an error.
+ *
+ * \since 1.10.0
+ *
+ * \todo Fix the document reference!
+ *
*/
H5_DLL herr_t H5Fstart_mdc_logging(hid_t file_id);
/**
* \ingroup MDC
*
- * \todo Finish this!
+ * \brief Stops logging metadata cache events if logging was previously enabled and is currently ongoing
+ *
+ * \file_id
+ *
+ * \return \herr_t
+ *
+ * \details The metadata cache is a central part of the HDF5 library through
+ * which all \Emph{file metadata} reads and writes take place. File
+ * metadata is normally invisible to the user and is used by the
+ * library for purposes such as locating and indexing data. File
+ * metadata should not be confused with user metadata, which consists
+ * of attributes created by users and attached to HDF5 objects such
+ * as datasets via H5A API calls.
+ *
+ * Due to the complexity of the cache, a trace/logging feature has been
+ * created that can be used by HDF5 developers for debugging and performance
+ * analysis. The functions that control this functionality will normally be
+ * of use to a very limited number of developers outside of The HDF Group.
+ * The functions have been documented to help users create logs that can
+ * be sent with bug reports.
+ *
+ * Control of the log functionality is straightforward. Logging is enabled
+ * via the H5Pset_mdc_log_options() function, which will modify the file
+ * access property list used to open or create a file. This function has
+ * a flag that determines whether logging begins at file open or starts
+ * in a paused state. Log messages can then be controlled via the
+ * H5Fstart_mdc_logging() and H5Fstop_mdc_logging() functions.
+ * H5Pget_mdc_log_options() can be used to examine a file access property
+ * 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.
+ *
+ * \note Logging can only be started or stopped if metadata cache logging was enabled
+ * via H5Pset_mdc_log_options().\n
+ * This function only suspends the logging operations. The log file will remain
+ * open and will not be closed until the HDF5 file is closed.
+ *
+ * \since 1.10.0
+ *
*/
H5_DLL herr_t H5Fstop_mdc_logging(hid_t file_id);
/**
* \ingroup MDC
*
- * \todo Finish this!
+ * \brief Gets the current metadata cache logging status
+ *
+ * \file_id
+ * \param[out] is_enabled Whether logging is enabled
+ * \param[out] is_currently_logging Whether events are currently being logged
+ * \return \herr_t
+ *
+ * \details The metadata cache is a central part of the HDF5 library through
+ * which all \Emph{file metadata} reads and writes take place. File
+ * metadata is normally invisible to the user and is used by the
+ * library for purposes such as locating and indexing data. File
+ * metadata should not be confused with user metadata, which consists
+ * of attributes created by users and attached to HDF5 objects such
+ * as datasets via H5A API calls.
+ *
+ * Due to the complexity of the cache, a trace/logging feature has been
+ * created that can be used by HDF5 developers for debugging and performance
+ * analysis. The functions that control this functionality will normally be
+ * of use to a very limited number of developers outside of The HDF Group.
+ * The functions have been documented to help users create logs that can
+ * be sent with bug reports.
+ *
+ * Control of the log functionality is straightforward. Logging is enabled
+ * via the H5Pset_mdc_log_options() function, which will modify the file
+ * access property list used to open or create a file. This function has
+ * a flag that determines whether logging begins at file open or starts
+ * in a paused state. Log messages can then be controlled via the
+ * H5Fstart_mdc_logging() and H5Fstop_mdc_logging() functions.
+ * H5Pget_mdc_log_options() can be used to examine a file access property
+ * 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.
+ *
+ * \note Unlike H5Fstart_mdc_logging() and H5Fstop_mdc_logging(), this function can
+ * be called on any open file identifier.
+ *
+ * \since 1.10.0
*/
H5_DLL herr_t H5Fget_mdc_logging_status(hid_t file_id,
/*OUT*/ hbool_t *is_enabled,
@@ -1245,7 +1984,32 @@ H5_DLL herr_t H5Fget_page_buffering_stats(hid_t file_id, unsigned accesses[2],
/**
* \ingroup MDC
*
- * \todo Finish this!
+ * \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_size Length of the cache image if it exists, or 0 if it does not
+ * \returns \herr_t
+ *
+ * \details
+ * \parblock
+ * H5Fget_mdc_image_info() returns information about a cache image if it exists.
+ *
+ * When an HDF5 file is opened in Read/Write mode, any metadata cache image will
+ * be read and deleted from the file on the first metadata cache access (or, if
+ * persistent free space managers are enabled, on the first file space
+ * allocation / deallocation, or read of free space manager status, whichever
+ * comes first).
+ *
+ * Thus, if the file is opened Read/Write, H5Fget_mdc_image_info() should be called
+ * immediately after file open and before any other operation. If H5Fget_mdc_image_info()
+ * is called after the cache image is loaded, it will correctly report that no cache image
+ * exists, as the image will have already been read and deleted from the file. In the Read Only
+ * case, the function may be called at any time, as any cache image will not be deleted
+ * from the file.
+ * \endparblock
+ *
+ * \since 1.10.1
*/
H5_DLL herr_t H5Fget_mdc_image_info(hid_t file_id, haddr_t *image_addr, hsize_t *image_size);
/**
@@ -1307,13 +2071,91 @@ H5_DLL herr_t H5Fset_dset_no_attrs_hint(hid_t file_id, hbool_t minimize);
/**
* \ingroup PH5F
*
- * \todo Finish this!
+ * \brief Sets the MPI atomicity mode
+ *
+ * \file_id
+ * \param[in] flag Logical flag for atomicity setting. Valid values are:
+ * \li \c 1 -- Sets MPI file access to atomic mode.
+ * \li \c 0 -- Sets MPI file access to nonatomic mode.
+ * \returns \herr_t
+ *
+ * \par Motivation
+ * H5Fset_mpi_atomicity() is applicable only in parallel environments using MPI I/O.
+ * The function is one of the tools used to ensure sequential consistency. This means
+ * that a set of operations will behave as though they were performed in a serial
+ * order consistent with the program order.
+ *
+ * \details
+ * \parblock
+ * H5Fset_mpi_atomicity() sets MPI consistency semantics for data access to the file,
+ * \p file_id.
+ *
+ * If \p flag is set to \c 1, all file access operations will appear atomic, guaranteeing
+ * sequential consistency. If \p flag is set to \c 0, enforcement of atomic file access
+ * will be turned off.
+ *
+ * H5Fset_mpi_atomicity() is a collective function and all participating processes must
+ * pass the same values for \p file_id and \p flag.
+ *
+ * This function is available only when the HDF5 library is configured with parallel support
+ * (\Code{--enable-parallel}). It is useful only when used with the #H5FD_MPIO driver
+ * (see H5Pset_fapl_mpio()).
+ * \endparblock
+ *
+ * \attention
+ * \parblock
+ * H5Fset_mpi_atomicity() calls \Code{MPI_File_set_atomicity} underneath and is not supported
+ * if the execution platform does not support \Code{MPI_File_set_atomicity}. When it is
+ * supported and used, the performance of data access operations may drop significantly.
+ *
+ * In certain scenarios, even when \Code{MPI_File_set_atomicity} is supported, setting
+ * atomicity with H5Fset_mpi_atomicity() and \p flag set to 1 does not always yield
+ * strictly atomic updates. For example, some H5Dwrite() calls translate to multiple
+ * \Code{MPI_File_write_at} calls. This happens in all cases where the high-level file
+ * access routine translates to multiple lower level file access routines.
+ * The following scenarios will raise this issue:
+ * \li Non-contiguous file access using independent I/O
+ * \li Partial collective I/O using chunked access
+ * \li Collective I/O using filters or when data conversion is required
+ *
+ * This issue arises because MPI atomicity is a matter of MPI file access operations rather
+ * than HDF5 access operations. But the user is normally seeking atomicity at the HDF5 level.
+ * To accomplish this, the application must set a barrier after a write, H5Dwrite(), but before
+ * the next read, H5Dread(), in addition to calling H5Fset_mpi_atomicity().The barrier will
+ * guarantee that all underlying write operations execute atomically before the read
+ * operations starts. This ensures additional ordering semantics and will normally produce
+ * the desired behavior.
+ * \endparblock
+ *
+ * \see Enabling a Strict Consistency Semantics Model in Parallel HDF5
+ *
+ * \since 1.8.9
+ *
+ * \todo Fix the reference!
*/
H5_DLL herr_t H5Fset_mpi_atomicity(hid_t file_id, hbool_t flag);
/**
* \ingroup PH5F
*
- * \todo Finish this!
+ * \brief Retrieves the atomicity mode in use
+ *
+ * \file_id
+ * \param[out] flag Logical flag for atomicity setting. Valid values are:
+ * \li 1 -- MPI file access is set to atomic mode.
+ * \li 0 -- MPI file access is set to nonatomic mode.
+ * \returns \herr_t
+ *
+ * \details H5Fget_mpi_atomicity() retrieves the current consistency semantics mode for
+ * data access for the file \p file_id.
+ *
+ * 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
+ *
+ * \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 */
diff --git a/src/H5Imodule.h b/src/H5Imodule.h
index 768fa81..7fc6af0 100644
--- a/src/H5Imodule.h
+++ b/src/H5Imodule.h
@@ -29,4 +29,9 @@
#define H5_MY_PKG_ERR H5E_ATOM
#define H5_MY_PKG_INIT NO
+/**\defgroup H5I H5I
+ * \brief Identifier Interface
+ * \todo Describe concisely what the functions in this module are about.
+ */
+
#endif /* _H5Imodule_H */
diff --git a/src/H5Ipublic.h b/src/H5Ipublic.h
index 2b8a978..f981d2e2 100644
--- a/src/H5Ipublic.h
+++ b/src/H5Ipublic.h
@@ -21,34 +21,36 @@
/* Public headers needed by this file */
#include "H5public.h"
-/*
- * Library type values. Start with `1' instead of `0' because it makes the
- * tracing output look better when hid_t values are large numbers. Change the
- * TYPE_BITS in H5I.c if the MAXID gets larger than 32 (an assertion will
- * fail otherwise).
+/**
+ * Library type values.
+ * \internal Library type values. Start with `1' instead of `0' because it
+ * makes the tracing output look better when hid_t values are large
+ * numbers. Change the TYPE_BITS in H5I.c if the MAXID gets larger
+ * than 32 (an assertion will fail otherwise).
*
- * When adding types here, add a section to the 'misc19' test in test/tmisc.c
- * to verify that the H5I{inc|dec|get}_ref() routines work correctly with it.
+ * When adding types here, add a section to the 'misc19' test in
+ * test/tmisc.c to verify that the H5I{inc|dec|get}_ref() routines
+ * work correctly with it. \endinternal
*/
typedef enum H5I_type_t {
- H5I_UNINIT = (-2), /* uninitialized type */
- H5I_BADID = (-1), /* invalid Type */
- H5I_FILE = 1, /* type ID for File objects */
- H5I_GROUP, /* type ID for Group objects */
- H5I_DATATYPE, /* type ID for Datatype objects */
- H5I_DATASPACE, /* type ID for Dataspace objects */
- H5I_DATASET, /* type ID for Dataset objects */
- H5I_MAP, /* type ID for Map objects */
- H5I_ATTR, /* type ID for Attribute objects */
- H5I_VFL, /* type ID for virtual file layer */
- H5I_VOL, /* type ID for virtual object layer */
- H5I_GENPROP_CLS, /* type ID for generic property list classes */
- H5I_GENPROP_LST, /* type ID for generic property lists */
- H5I_ERROR_CLASS, /* type ID for error classes */
- H5I_ERROR_MSG, /* type ID for error messages */
- H5I_ERROR_STACK, /* type ID for error stacks */
- H5I_SPACE_SEL_ITER, /* type ID for dataspace selection iterator */
- H5I_NTYPES /* number of library types, MUST BE LAST! */
+ H5I_UNINIT = (-2), /**< uninitialized type */
+ H5I_BADID = (-1), /**< invalid Type */
+ H5I_FILE = 1, /**< type ID for File objects */
+ H5I_GROUP, /**< type ID for Group objects */
+ H5I_DATATYPE, /**< type ID for Datatype objects */
+ H5I_DATASPACE, /**< type ID for Dataspace objects */
+ H5I_DATASET, /**< type ID for Dataset objects */
+ H5I_MAP, /**< type ID for Map objects */
+ H5I_ATTR, /**< type ID for Attribute objects */
+ H5I_VFL, /**< type ID for virtual file layer */
+ H5I_VOL, /**< type ID for virtual object layer */
+ H5I_GENPROP_CLS, /**< type ID for generic property list classes */
+ H5I_GENPROP_LST, /**< type ID for generic property lists */
+ H5I_ERROR_CLASS, /**< type ID for error classes */
+ H5I_ERROR_MSG, /**< type ID for error messages */
+ H5I_ERROR_STACK, /**< type ID for error stacks */
+ H5I_SPACE_SEL_ITER, /**< type ID for dataspace selection iterator */
+ H5I_NTYPES /**< number of library types, MUST BE LAST! */
} H5I_type_t;
/* Type of IDs to return to users */
@@ -59,13 +61,18 @@ typedef int64_t hid_t;
#define PRIXHID PRIX64
#define PRIoHID PRIo64
-#define H5_SIZEOF_HID_T H5_SIZEOF_INT64_T
+/**
+ * The size of identifiers
+ */
+#define H5_SIZEOF_HID_T H5_SIZEOF_INT64_T
-/* An invalid object ID. This is also negative for error return. */
-#define H5I_INVALID_HID (-1)
+/**
+ * An invalid object ID. This is also negative for error return.
+ */
+#define H5I_INVALID_HID (-1)
-/*
- * Function for freeing objects. This function will be called with an object
+/**
+ * A function for freeing objects. This function will be called with an object
* ID type number and a pointer to the object. The function should free the
* object and return non-negative to indicate that the object
* can be removed from the ID type. If the function returns negative
@@ -73,11 +80,19 @@ typedef int64_t hid_t;
*/
typedef herr_t (*H5I_free_t)(void *);
-/* Type of the function to compare objects & keys */
+/**
+ * The type of a function to compare objects & keys
+ */
+//! [H5I_search_func_t_snip]
typedef int (*H5I_search_func_t)(void *obj, hid_t id, void *key);
+//! [H5I_search_func_t_snip]
-/* Type of the H5Iiterate callback function */
+/**
+ * The type of H5Iiterate() callback functions
+ */
+//! [H5I_iterate_func_t_snip]
typedef herr_t (*H5I_iterate_func_t)(hid_t id, void *udata);
+//! [H5I_iterate_func_t_snip]
#ifdef __cplusplus
extern "C" {
@@ -85,25 +100,561 @@ extern "C" {
/* Public API functions */
+/**
+ * \ingroup H5I
+ *
+ * \brief Registers an object under a type and returns an ID for it
+ *
+ * \param[in] type The identifier of the type of the new ID
+ * \param[in] object Pointer to object for which a new ID is created
+ *
+ * \return \hid_t{object}
+ *
+ * \details H5Iregister() allocates and returns a new ID for an object.
+ *
+ * \details The \p type parameter is the identifier for the ID type to which
+ * this new ID will belong. This identifier must have been created by
+ * a call to H5Iregister_type().
+ *
+ * \details The \p object parameter is a pointer to the memory which the new ID
+ * will be a reference to. This pointer will be stored by the library
+ * and returned via a call to H5Iobject_verify().
+ *
+ */
H5_DLL hid_t H5Iregister(H5I_type_t type, const void *object);
+/**
+ * \ingroup H5I
+ *
+ * \brief Returns the object referenced by an ID
+ *
+ * \param[in] id ID to be dereferenced
+ * \param[in] id_type The identifier type
+
+ *
+ * \return Pointer to the object referenced by \p id on success, NULL on failure.
+ *
+ * \details H5Iobject_verify() returns a pointer to the memory referenced by id
+ * after verifying that \p id is of type \p id_type. This function is
+ * analogous to dereferencing a pointer in C with type checking.
+ *
+ * \note H5Iobject_verify() does not change the ID it is called on in any way
+ * (as opposed to H5Iremove_verify(), which removes the ID from its
+ * type’s hash table).
+ *
+ * \see H5Iregister()
+ *
+ */
H5_DLL void * H5Iobject_verify(hid_t id, H5I_type_t id_type);
+/**
+ * \ingroup H5I
+ *
+ * \brief Removes an ID from its type
+ *
+ * \param[in] id The ID to be removed from its type
+ * \param[in] id_type The identifier type
+
+ *
+ * \return Returns a pointer to the memory referred to by \p id on success,
+ * NULL on failure.
+ *
+ * \details H5Iremove_verify() first ensures that \p id belongs to \p id_type.
+ * If so, it removes \p id from its type and returns the pointer
+ * to the memory it referred to. This pointer is the same pointer that
+ * was placed in storage by H5Iregister(). If id does not belong to
+ * \p id_type, then NULL is returned.
+ *
+ * The \p id parameter is the ID which is to be removed from its type.
+ *
+ * The \p type parameter is the identifier for the ID type which \p id
+ * is supposed to belong to. This identifier must have been created by
+ * a call to H5Iregister_type().
+ *
+ * \note This function does NOT deallocate the memory that \p id refers to.
+ * The pointer returned by H5Iregister() must be deallocated by the user
+ * to avoid memory leaks.
+ *
+ */
H5_DLL void * H5Iremove_verify(hid_t id, H5I_type_t id_type);
+/**
+ * \ingroup H5I
+ *
+ * \brief Retrieves the type of an object
+ *
+ * \obj_id{id}
+ *
+ * \return Returns the object type if successful; otherwise #H5I_BADID.
+ *
+ * \details H5Iget_type() retrieves the type of the object identified by
+ * \p id.
+ *
+ * Valid types returned by the function are:
+ * \id_types
+ *
+ * If no valid type can be determined or the identifier submitted is
+ * invalid, the function returns #H5I_BADID.
+ *
+ * This function is of particular use in determining the type of
+ * object closing function (H5Dclose(), H5Gclose(), etc.) to call
+ * after a call to H5Rdereference().
+ *
+ * \note Note that this function returns only the type of object that \p id
+ * would identify if it were valid; it does not determine whether \p id
+ * is valid identifier. Validity can be determined with a call to
+ * H5Iis_valid().
+ *
+ */
H5_DLL H5I_type_t H5Iget_type(hid_t id);
+/**
+ * \ingroup H5I
+ *
+ * \brief Retrieves an identifier for the file containing the specified object
+ *
+ * \obj_id{id}
+ *
+ * \return \hid_t{file}
+ *
+ * \details H5Iget_file_id() returns the identifier of the file associated with
+ * the object referenced by \p id.
+ *
+ * \note Note that the HDF5 library permits an application to close a file
+ * while objects within the file remain open. If the file containing the
+ * object \p id is still open, H5Iget_file_id() will retrieve the
+ * existing file identifier. If there is no existing file identifier for
+ * the file, i.e., the file has been closed, H5Iget_file_id() will reopen
+ * the file and return a new file identifier. In either case, the file
+ * identifier must eventually be released using H5Fclose().
+ *
+ * \since 1.6.3
+ *
+ */
H5_DLL hid_t H5Iget_file_id(hid_t id);
+/**
+ * \ingroup H5I
+ *
+ * \brief Retrieves a name of an object based on the object identifier
+ *
+ * \obj_id{id}
+ * \param[out] name A buffer for thename associated with the identifier
+ * \param[in] size The size of the \p name buffer; usually the size of
+ * the name in bytes plus 1 for a NULL terminator
+ *
+ * \return ssize_t
+ *
+ * \details H5Iget_name() retrieves a name for the object identified by \p id.
+ *
+ * \details Up to size characters of the name are returned in \p name;
+ * additional characters, if any, are not returned to the user
+ * application.
+ *
+ * If the length of the name, which determines the required value of
+ * \p size, is unknown, a preliminary H5Iget_name() call can be made.
+ * The return value of this call will be the size in bytes of the
+ * object name. That value, plus 1 for a NULL terminator, is then
+ * assigned to size for a second H5Iget_name() call, which will
+ * retrieve the actual name.
+ *
+ * If the object identified by \p id is an attribute, as determined
+ * via H5Iget_type(), H5Iget_name() retrieves the name of the object
+ * to which that attribute is attached. To retrieve the name of the
+ * attribute itself, use H5Aget_name().
+ *
+ * If there is no name associated with the object identifier or if the
+ * name is NULL, H5Iget_name() returns 0 (zero).
+ *
+ * \note Note that an object in an HDF5 file may have multiple paths if there
+ * are multiple links pointing to it. This function may return any one of
+ * these paths. When possible, H5Iget_name() returns the path with which
+ * the object was opened.
+ *
+ * \since 1.6.0
+ *
+ */
H5_DLL ssize_t H5Iget_name(hid_t id, char *name /*out*/, size_t size);
+/**
+ * \ingroup H5I
+ *
+ * \brief Increments the reference count for an object
+ *
+ * \obj_id{id}
+ *
+ * \return Returns a non-negative reference count of the object ID after
+ * incrementing it if successful; otherwise a negative value is
+ * returned.
+ *
+ * \details H5Iinc_ref() increments the reference count of the object
+ * identified by \p id.
+ *
+ * The reference count for an object ID is attached to the information
+ * about an object in memory and has no relation to the number of
+ * links to an object on disk.
+ *
+ * The reference count for a newly created object will be 1. Reference
+ * counts for objects may be explicitly modified with this function or
+ * with H5Idec_ref(). When an object ID's reference count reaches
+ * zero, the object will be closed. Calling an object ID's \c close
+ * function decrements the reference count for the ID which normally
+ * closes the object, but if the reference count for the ID has been
+ * incremented with this function, the object will only be closed when
+ * the reference count reaches zero with further calls to H5Idec_ref()
+ * or the object ID's \c close function.
+ *
+ * If the object ID was created by a collective parallel call (such as
+ * H5Dcreate(), H5Gopen(), etc.), the reference count should be
+ * modified by all the processes which have copies of the ID.
+ * Generally this means that group, dataset, attribute, file and named
+ * datatype IDs should be modified by all the processes and that all
+ * other types of IDs are safe to modify by individual processes.
+ *
+ * This function is of particular value when an application is
+ * maintaining multiple copies of an object ID. The object ID can be
+ * incremented when a copy is made. Each copy of the ID can then be
+ * safely closed or decremented and the HDF5 object will be closed
+ * when the reference count for that that object drops to zero.
+ *
+ * \since 1.6.2
+ *
+ */
H5_DLL int H5Iinc_ref(hid_t id);
+/**
+ * \ingroup H5I
+ *
+ * \brief Decrements the reference count for an object
+ *
+ * \obj_id{id}
+ *
+ * \return Returns a non-negative reference count of the object ID after
+ * decrementing it, if successful; otherwise a negative value is
+ * returned.
+ *
+ * \details H5Idec_ref() decrements the reference count of the object
+ * identified by \p id.
+ *
+ * The reference count for an object ID is attached to the information
+ * about an object in memory and has no relation to the number of
+ * links to an object on disk.
+ *
+ * The reference count for a newly created object will be 1. Reference
+ * counts for objects may be explicitly modified with this function or
+ * with H5Iinc_ref(). When an object identifier’s reference count
+ * reaches zero, the object will be closed. Calling an object
+ * identifier’s \c close function decrements the reference count for
+ * the identifier which normally closes the object, but if the
+ * reference count for the identifier has been incremented with
+ * H5Iinc_ref(), the object will only be closed when the reference
+ * count reaches zero with further calls to this function or the
+ * object identifier’s \c close function.
+ *
+ * If the object ID was created by a collective parallel call (such as
+ * H5Dcreate(), H5Gopen(), etc.), the reference count should be
+ * modified by all the processes which have copies of the ID.
+ * Generally this means that group, dataset, attribute, file and named
+ * datatype IDs should be modified by all the processes and that all
+ * other types of IDs are safe to modify by individual processes.
+ *
+ * This function is of particular value when an application is
+ * maintaining multiple copies of an object ID. The object ID can be
+ * incremented when a copy is made. Each copy of the ID can then be
+ * safely closed or decremented and the HDF5 object will be closed
+ * when the reference count for that that object drops to zero.
+ *
+ * \since 1.6.2
+ *
+ */
H5_DLL int H5Idec_ref(hid_t id);
+/**
+ * \ingroup H5I
+ *
+ * \brief Retrieves the reference count for an object
+ *
+ * \obj_id{id}
+ *
+ * \return Returns a non-negative current reference count of the object
+ * identifier if successful; otherwise a negative value is returned.
+ *
+ * \details H5Iget_ref() retrieves the reference count of the object identified
+ * by \p id.
+ *
+ * The reference count for an object identifier is attached to the
+ * information about an object in memory and has no relation to the
+ * number of links to an object on disk.
+ *
+ * The function H5Iis_valid() is used to determine whether a specific
+ * object identifier is valid.
+ *
+ * \since 1.6.2
+ *
+ */
H5_DLL int H5Iget_ref(hid_t id);
+/**
+ * \ingroup H5I
+ *
+ * \brief Creates and returns a new ID type
+ *
+ * \param[in] hash_size Minimum hash table size (in entries) used to store IDs
+ * for the new type
+ * \param[in] reserved Number of reserved IDs for the new type
+ * \param[in] free_func Function used to deallocate space for a single ID
+ *
+ * \return Returns the type identifier on success, negative on failure.
+ *
+ * \details H5Iregister_type() allocates space for a new ID type and returns an
+ * identifier for it.
+ *
+ * The \p hash_size parameter indicates the minimum size of the hash
+ * table used to store IDs in the new type.
+ *
+ * The \p reserved parameter indicates the number of IDs in this new
+ * type to be reserved. Reserved IDs are valid IDs which are not
+ * associated with any storage within the library.
+ *
+ * The \p free_func parameter is a function pointer to a function
+ * which returns an herr_t and accepts a \c void*. The purpose of this
+ * function is to deallocate memory for a single ID. It will be called
+ * by H5Iclear_type() and H5Idestroy_type() on each ID. This function
+ * is NOT called by H5Iremove_verify(). The \c void* will be the same
+ * pointer which was passed in to the H5Iregister() function. The \p
+ * free_func function should return 0 on success and -1 on failure.
+ *
+ */
H5_DLL H5I_type_t H5Iregister_type(size_t hash_size, unsigned reserved, H5I_free_t free_func);
+/**
+ * \ingroup H5I
+ *
+ * \brief Deletes all identifiers of the given type
+ *
+ * \param[in] type Identifier of identifier type which is to be cleared of identifiers
+ * \param[in] force Whether or not to force deletion of all identifiers
+ *
+ * \return \herr_t
+ *
+ * \details H5Iclear_type() deletes all identifiers of the type identified by
+ * the argument \p type.
+ *
+ * The identifier type's free function is first called on all of these
+ * identifiers to free their memory, then they are removed from the
+ * type.
+ *
+ * If the \p force flag is set to false, only those identifiers whose
+ * reference counts are equal to 1 will be deleted, and all other
+ * identifiers will be entirely unchanged. If the force flag is true,
+ * all identifiers of this type will be deleted.
+ *
+ */
H5_DLL herr_t H5Iclear_type(H5I_type_t type, hbool_t force);
+/**
+ * \ingroup H5I
+ *
+ * \brief Removes an identifier type and all identifiers within that type
+ *
+ * \param[in] type Identifier of identifier type which is to be destroyed
+ *
+ * \return \herr_t
+ *
+ * \details H5Idestroy_type deletes an entire identifier type \p type. All
+ * identifiers of this type are destroyed and no new identifiers of
+ * this type can be registered.
+ *
+ * The type’s free function is called on all of the identifiers which
+ * are deleted by this function, freeing their memory. In addition,
+ * all memory used by this type’s hash table is freed.
+ *
+ * Since the H5I_type_t values of destroyed identifier types are
+ * reused when new types are registered, it is a good idea to set the
+ * variable holding the value of the destroyed type to #H5I_UNINIT.
+ *
+ */
H5_DLL herr_t H5Idestroy_type(H5I_type_t type);
+/**
+ * \ingroup H5I
+ *
+ * \brief Increments the reference count on an ID type
+ *
+ * \param[in] type The identifier of the type whose reference count is to be incremented
+ *
+ * \return Returns the current reference count on success, negative on failure.
+ *
+ * \details H5Iinc_type_ref() increments the reference count on an ID type. The
+ * reference count is used by the library to indicate when an ID type
+ * can be destroyed.
+ *
+ * The type parameter is the identifier for the ID type whose
+ * reference count is to be incremented. This identifier must have
+ * been created by a call to H5Iregister_type().
+ *
+ */
H5_DLL int H5Iinc_type_ref(H5I_type_t type);
+/**
+ * \ingroup H5I
+ *
+ * \brief Decrements the reference count on an identifier type
+ *
+ * \param[in] type The identifier of the type whose reference count is to be decremented
+ *
+ * \return Returns the current reference count on success, negative on failure.
+ *
+ * \details H5Idec_type_ref() decrements the reference count on an identifier
+ * type. The reference count is used by the library to indicate when
+ * an identifier type can be destroyed. If the reference count reaches
+ * zero, this function will destroy it.
+ *
+ * The type parameter is the identifier for the identifier type whose
+ * reference count is to be decremented. This identifier must have
+ * been created by a call to H5Iregister_type().
+ *
+ */
H5_DLL int H5Idec_type_ref(H5I_type_t type);
+/**
+ * \ingroup H5I
+ *
+ * \brief Retrieves the reference count on an ID type
+ *
+ * \param[in] type The identifier of the type whose reference count is to be retieved
+ *
+ * \return Returns the current reference count on success, negative on failure.
+ *
+ * \details H5Iget_type_ref() retrieves the reference count on an ID type. The
+ * reference count is used by the library to indicate when an ID type
+ * can be destroyed.
+ *
+ * The type parameter is the identifier for the ID type whose
+ * reference count is to be retrieved. This identifier must have been
+ * created by a call to H5Iregister_type().
+ *
+ */
H5_DLL int H5Iget_type_ref(H5I_type_t type);
+/**
+ * \ingroup H5I
+ *
+ * \brief Finds the memory referred to by an ID within the given ID type such
+ * that some criterion is satisfied
+ *
+ * \param[in] type The identifier of the type to be searched
+ * \param[in] func The function defining the search criteria
+ * \param[in] key A key for the search function
+ *
+ * \return Returns a pointer to the object which satisfies the search function
+ * on success, NULL on failure.
+ *
+ * \details H5Isearch() searches through a given ID type to find an object that
+ * satisfies the criteria defined by \p func. If such an object is
+ * found, the pointer to the memory containing this object is
+ * returned. Otherwise, NULL is returned. To do this, \p func is
+ * called on every member of type \p type. The first member to satisfy
+ * \p func is returned.
+ *
+ * The \p type parameter is the identifier for the ID type which is to
+ * be searched. This identifier must have been created by a call to
+ * H5Iregister_type().
+ *
+ * The parameter \p func is a function pointer to a function which
+ * takes three parameters. The first parameter is a \c void* and will
+ * be a pointer to the object to be tested. This is the same object
+ * that was placed in storage using H5Iregister(). The second
+ * parameter is a hid_t and is the ID of the object to be tested. The
+ * last parameter is a \c void*. This is the \p key parameter and can
+ * be used however the user finds helpful, or it can be ignored if it
+ * is not needed. \p func returns 0 if the object it is testing does
+ * not pass its criteria. A non-zero value should be returned if the
+ * object does pass its criteria. H5I_search_func_t is defined in
+ * H5Ipublic.h and is shown below.
+ * \snippet this H5I_search_func_t_snip
+ * The \p key parameter will be passed to the search function as a
+ * parameter. It can be used to further define the search at run-time.
+ *
+ */
H5_DLL void * H5Isearch(H5I_type_t type, H5I_search_func_t func, void *key);
+/**
+ * \ingroup H5I
+ *
+ * \brief Calls a callback for each member of the identifier type specified
+ *
+ * \param[in] type The identifier type
+ * \param[in] op The callback function
+ * \param[in,out] op_data The data for the callback function
+ *
+ * \return The last value returned by \p op
+ *
+ * \details H5Iiterate() calls the callback function \p op for each member of
+ * the identifier type \p type. The callback function type for \p op,
+ * H5I_iterate_func_t, is defined in H5Ipublic.h as:
+ * \snippet this H5I_iterate_func_t_snip
+ * \p op takes as parameters the identifier and a pass through of
+ * \p op_data, and returns an herr_t.
+ *
+ * A positive return from op will cause the iteration to stop and
+ * H5Iiterate() will return the value returned by \p op. A negative
+ * return from \p op will cause the iteration to stop and H5Iiterate()
+ * will return failure. A zero return from \p op will allow iteration
+ * to continue, as long as there are other identifiers remaining in
+ * type.
+ *
+ * \since 1.12.0
+ *
+ */
H5_DLL herr_t H5Iiterate(H5I_type_t type, H5I_iterate_func_t op, void *op_data);
+/**
+ * \ingroup H5I
+ *
+ * \brief Returns the number of identifiers in a given identifier type
+ *
+ * \param[in] type The identifier type
+ * \param[out] num_members Number of identifiers of the specified identifier type
+ *
+ * \return \herr_t
+ *
+ * \details H5Inmembers() returns the number of identifiers of the identifier
+ * type specified in \p type.
+ *
+ * The number of identifiers is returned in \p num_members. If no
+ * identifiers of this type have been registered, the type does not
+ * exist, or it has been destroyed, \p num_members is returned with
+ * the value 0.
+ *
+ */
H5_DLL herr_t H5Inmembers(H5I_type_t type, hsize_t *num_members);
+/**
+ * \ingroup H5I
+ *
+ * \brief Determines whether an identifier type is registered
+ *
+ * \param[in] type Identifier type
+ *
+ * \return \htri_t
+ *
+ * \details H5Itype_exists() determines whether the given identifier type,
+ * \p type, is registered with the library.
+ *
+ * \since 1.8.0
+ *
+ */
H5_DLL htri_t H5Itype_exists(H5I_type_t type);
+/**
+ * \ingroup H5I
+ *
+ * \brief Determines whether an identifier is valid
+ *
+ * \obj_id{id}
+ *
+ * \return \htri_t
+ *
+ * \details H5Iis_valid() determines whether the identifier \p id is valid.
+ *
+ * \details Valid identifiers are those that have been obtained by an
+ * application and can still be used to access the original target.
+ * Examples of invalid identifiers include:
+ * \li Out of range values: negative, for example
+ * \li Previously-valid identifiers that have been released:
+ * for example, a dataset identifier for which the dataset has
+ * been closed
+ *
+ * H5Iis_valid() can be used with any type of identifier: object
+ * identifier, property list identifier, attribute identifier, error
+ * message identifier, etc. When necessary, a call to H5Iget_type()
+ * can determine the type of the object that \p id identifies.
+ *
+ * \since 1.8.3
+ *
+ */
H5_DLL htri_t H5Iis_valid(hid_t id);
#ifdef __cplusplus
diff --git a/src/H5Lmodule.h b/src/H5Lmodule.h
index 043a865..ad737d6 100644
--- a/src/H5Lmodule.h
+++ b/src/H5Lmodule.h
@@ -29,4 +29,12 @@
#define H5_MY_PKG_ERR H5E_LINK
#define H5_MY_PKG_INIT YES
+/**\defgroup H5L H5L
+ * \brief Link Interface
+ * \todo Describe concisely what the functions in this module are about.
+ *
+ * \defgroup TRAV Link Traversal
+ * \ingroup H5L
+ */
+
#endif /* _H5Lmodule_H */
diff --git a/src/H5Lpublic.h b/src/H5Lpublic.h
index be920c2..14975bc 100644
--- a/src/H5Lpublic.h
+++ b/src/H5Lpublic.h
@@ -34,14 +34,21 @@
/* Public Macros */
/*****************/
-/* Maximum length of a link's name */
-/* (encoded in a 32-bit unsigned integer) */
+/**
+ * \brief Maximum length of a link's name
+ *
+ * The maximum length of a link's name is encoded in a 32-bit unsigned integer.
+ */
#define H5L_MAX_LINK_NAME_LEN ((uint32_t)(-1)) /* (4GB - 1) */
-/* Macro to indicate operation occurs on same location */
+/**
+ * \brief Macro to indicate operation occurs on same location
+ */
#define H5L_SAME_LOC (hid_t)0
-/* Current version of the H5L_class_t struct */
+/**
+ * \brief Current version of the H5L_class_t struct
+ */
#define H5L_LINK_CLASS_T_VERS 1
#ifdef __cplusplus
@@ -52,91 +59,128 @@ extern "C" {
/* Public Typedefs */
/*******************/
-/* Link class types.
- * Values less than 64 are reserved for the HDF5 library's internal use.
- * Values 64 to 255 are for "user-defined" link class types; these types are
- * defined by HDF5 but their behavior can be overridden by users.
- * Users who want to create new classes of links should contact the HDF5
- * development team at help@hdfgroup.org.
- * These values can never change because they appear in HDF5 files.
+/**
+ * \brief Link class types.
+ *
+ * Values less than 64 are reserved for the HDF5 library's internal use. Values
+ * 64 to 255 are for "user-defined" link class types; these types are defined
+ * by HDF5 but their behavior can be overridden by users. Users who want to
+ * create new classes of links should contact the HDF5 development team at
+ * mailto:help@hdfgroup.org. These values can never change because they appear
+ * in HDF5 files.
*/
typedef enum {
- H5L_TYPE_ERROR = (-1), /* Invalid link type id */
- H5L_TYPE_HARD = 0, /* Hard link id */
- H5L_TYPE_SOFT = 1, /* Soft link id */
- H5L_TYPE_EXTERNAL = 64, /* External link id */
- H5L_TYPE_MAX = 255 /* Maximum link type id */
+ H5L_TYPE_ERROR = (-1), /**< Invalid link type id */
+ H5L_TYPE_HARD = 0, /**< Hard link id */
+ H5L_TYPE_SOFT = 1, /**< Soft link id */
+ H5L_TYPE_EXTERNAL = 64, /**< External link id */
+ H5L_TYPE_MAX = 255 /**< Maximum link type id */
} H5L_type_t;
-/* Maximum value link value for "built-in" link types */
+/**
+ * \brief Maximum value link value for "built-in" link types
+ */
#define H5L_TYPE_BUILTIN_MAX H5L_TYPE_SOFT
-/* Link ids at or above this value are "user-defined" link types. */
-#define H5L_TYPE_UD_MIN H5L_TYPE_EXTERNAL
+/**
+ * \brief Link ids at or above this value are "user-defined" link types.
+ */
+#define H5L_TYPE_UD_MIN H5L_TYPE_EXTERNAL
+/**
+ * \brief Maximum link id value for "user-defined" link types.
+ */
+#define H5L_TYPE_UD_MAX H5L_TYPE_MAX
-/* Information struct for link (for H5Lget_info2/H5Lget_info_by_idx2)
- * H5O_token_t version used in VOL layer and future public API calls
+/**
+ * \brief Information struct for links
*/
+//! [H5L_info2_t_snip]
typedef struct {
- H5L_type_t type; /* Type of link */
- hbool_t corder_valid; /* Indicate if creation order is valid */
- int64_t corder; /* Creation order */
- H5T_cset_t cset; /* Character set of link name */
+ H5L_type_t type; /**< Type of link */
+ hbool_t corder_valid; /**< Indicate if creation order is valid */
+ int64_t corder; /**< Creation order */
+ H5T_cset_t cset; /**< Character set of link name */
union {
- H5O_token_t token; /* Token of location that hard link points to */
- size_t val_size; /* Size of a soft link or UD link value */
+ H5O_token_t token; /**< Token of location that hard link points to */
+ size_t val_size; /**< Size of a soft link or user-defined link value */
} u;
} H5L_info2_t;
+//! [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
* functions defined below.
*/
/* Callback prototypes for user-defined links */
-/* Link creation callback */
-typedef herr_t (*H5L_create_func_t)(const char *link_name, hid_t loc_group, const void *lnkdata,
- size_t lnkdata_size, hid_t lcpl_id);
-
-/* Callback for when the link is moved */
-typedef herr_t (*H5L_move_func_t)(const char *new_name, hid_t new_loc, const void *lnkdata,
- size_t lnkdata_size);
-
-/* Callback for when the link is copied */
-typedef herr_t (*H5L_copy_func_t)(const char *new_name, hid_t new_loc, const void *lnkdata,
- size_t lnkdata_size);
-
-/* Callback during link traversal */
-typedef hid_t (*H5L_traverse_func_t)(const char *link_name, hid_t cur_group, const void *lnkdata,
- size_t lnkdata_size, hid_t lapl_id, hid_t dxpl_id);
-
-/* Callback for when the link is deleted */
-typedef herr_t (*H5L_delete_func_t)(const char *link_name, hid_t file, const void *lnkdata,
- size_t lnkdata_size);
-
-/* Callback for querying the link */
-/* Returns the size of the buffer needed */
-typedef ssize_t (*H5L_query_func_t)(const char *link_name, const void *lnkdata, size_t lnkdata_size,
- void *buf /*out*/, size_t buf_size);
+/**
+ * \brief Link creation callback
+ */
+typedef herr_t (*H5L_create_func_t)(const char *link_name, hid_t loc_group,
+ const void *lnkdata, size_t lnkdata_size, hid_t lcpl_id);
+/**
+ * \brief Callback for link move
+ */
+typedef herr_t (*H5L_move_func_t)(const char *new_name, hid_t new_loc,
+ const void *lnkdata, size_t lnkdata_size);
+/**
+ * \brief Callback for link copy
+ */
+typedef herr_t (*H5L_copy_func_t)(const char *new_name, hid_t new_loc,
+ const void *lnkdata, size_t lnkdata_size);
+/**
+ * \brief Callback during link traversal
+ */
+typedef hid_t (*H5L_traverse_func_t)(const char *link_name, hid_t cur_group,
+ const void *lnkdata, size_t lnkdata_size, hid_t lapl_id, hid_t dxpl_id);
+/**
+ * \brief Callback for link deletion
+ */
+typedef herr_t (*H5L_delete_func_t)(const char *link_name, hid_t file,
+ const void *lnkdata, size_t lnkdata_size);
+/**
+ * \brief Callback for querying the link.
+ *
+ * Returns the size of the buffer needed.
+ */
+typedef ssize_t (*H5L_query_func_t)(const char *link_name, const void *lnkdata,
+ size_t lnkdata_size, void *buf /*out*/, size_t buf_size);
+/**
+ * \brief Link prototype
+ *
+ * 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
+ * functions defined elsewhere.
+ */
+//! [H5L_class_t_snip]
typedef struct {
- int version; /* Version number of this struct */
- H5L_type_t id; /* Link type ID */
- const char * comment; /* Comment for debugging */
- H5L_create_func_t create_func; /* Callback during link creation */
- H5L_move_func_t move_func; /* Callback after moving link */
- H5L_copy_func_t copy_func; /* Callback after copying link */
- H5L_traverse_func_t trav_func; /* Callback during link traversal */
- H5L_delete_func_t del_func; /* Callback for link deletion */
- H5L_query_func_t query_func; /* Callback for queries */
+ int version; /**< Version number of this struct */
+ H5L_type_t id; /**< Link type ID */
+ const char *comment; /**< Comment for debugging */
+ H5L_create_func_t create_func; /**< Callback during link creation */
+ H5L_move_func_t move_func; /**< Callback after moving link */
+ H5L_copy_func_t copy_func; /**< Callback after copying link */
+ H5L_traverse_func_t trav_func; /**< Callback during link traversal */
+ 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]
-/* Prototype for H5Literate2/H5Literate_by_name2() operator
- * H5O_token_t version used in VOL layer and future public API calls
+/**
+ * \brief Prototype for H5Literate2(), H5Literate_by_name2() operator
+ *
+ * The H5O_token_t version is used in the VOL layer and future public API calls.
*/
-typedef herr_t (*H5L_iterate2_t)(hid_t group, const char *name, const H5L_info2_t *info, void *op_data);
+//! [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]
-/* Callback for external link traversal */
-typedef herr_t (*H5L_elink_traverse_t)(const char *parent_file_name, const char *parent_group_name,
- const char *child_file_name, const char *child_object_name,
- unsigned *acc_flags, hid_t fapl_id, void *op_data);
+/**
+ * \brief Callback for external link traversal
+ */
+typedef herr_t (*H5L_elink_traverse_t)(const char *parent_file_name,
+ const char *parent_group_name, const char *child_file_name,
+ const char *child_object_name, unsigned *acc_flags, hid_t fapl_id,
+ void *op_data);
/********************/
/* Public Variables */
@@ -145,49 +189,1409 @@ typedef herr_t (*H5L_elink_traverse_t)(const char *parent_file_name, const char
/*********************/
/* Public Prototypes */
/*********************/
+/**
+ * \ingroup H5L
+ *
+ * \brief Moves a link within an HDF5 file
+ *
+ * \fgdta_loc_id{src_loc}
+ * \param[in] src_name Original link name
+ * \fgdta_loc_id{dst_loc}
+ * \param[in] dst_name New link name
+ * \lcpl_id
+ * \lapl_id
+ *
+ * \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
+ * accomplished as an atomic operation.
+ *
+ * \p src_loc and \p src_name identify the original link.
+ * \p src_loc is the original location identifier; \p src_name is
+ * the path to the link and is interpreted relative to \p src_loc.
+ *
+ * \p dst_loc and \p dst_name identify the new link. \p dst_loc is
+ * either a file or group identifier; \p dst_name is the path to
+ * the link and is interpreted relative to \p dst_loc.
+ *
+ * \p lcpl_id and \p lapl_id are the link creation and link access
+ * property lists, respectively, associated with the new link,
+ * \p dst_name.
+ *
+ * Through these property lists, several properties are available to
+ * govern the behavior of H5Lmove(). The property controlling creation
+ * of missing intermediate groups is set in the link creation property
+ * list with H5Pset_create_intermediate_group(); H5Lmove() ignores any
+ * other properties in the link creation property list. Properties
+ * controlling character encoding, link traversals, and external link
+ * prefixes are set in the link access property list with
+ * H5Pset_char_encoding(), H5Pset_nlinks(), and H5Pset_elink_prefix(),
+ * respectively.
+ *
+ * \note Note that H5Lmove() does not modify the value of the link; the new
+ * link points to the same object as the original link pointed to.
+ * Furthermore, if the object pointed to by the original link was already
+ * open with a valid object identifier, that identifier will remain valid
+ * after the call to H5Lmove().
+ *
+ * \attention Exercise care in moving links as it is possible to render data in
+ * a file inaccessible with H5Lmove(). If the link being moved is on
+ * the only path leading to an HDF5 object, that object may become
+ * permanently inaccessible in the file.
+ *
+ * \since 1.8.0
+ *
+ *-------------------------------------------------------------------------
+ */
H5_DLL herr_t H5Lmove(hid_t src_loc, const char *src_name, hid_t dst_loc, const char *dst_name, hid_t lcpl_id,
hid_t lapl_id);
+/**
+ * \ingroup H5L
+ *
+ * \brief Creates an identical copy of a link with the same creation time and
+ * target. The new link can have a different name and be in a different
+ * location than the original.
+ *
+ * \fgdt_loc_id{src_loc}
+ * \param[in] src_name Name of the link to be copied
+ * \fgdt_loc_id{dst_loc}
+ * \param[in] dst_name Name to be assigned to the new copy
+ * \lcpl_id
+ * \lapl_id
+ * \return \herr_t
+ *
+ * \details H5Lcopy() copies the link specified by \p src_name from the location
+ * specified by \p src_loc_id to the location specified by
+ * \p dst_loc_id. The new copy of the link is created with the name
+ * \p dst_name.
+ *
+ * If \p dst_loc_id is a file identifier, \p dst_name will be
+ * interpreted relative to that file’s root group.
+ *
+ * The new link is created with the creation and access property lists
+ * specified by \p lcpl_id and \p lapl_id. The interpretation of
+ * \p lcpl_id is limited in the manner described in the next paragraph.
+ *
+ * H5Lcopy() retains the creation time and the target of the original
+ * link. However, since the link may be renamed, the character
+ * encoding is that specified in \p lcpl_id rather than that of the
+ * original link. Other link creation properties are ignored.
+ *
+ * If the link is a soft link, also known as a symbolic link, its
+ * target is interpreted relative to the location of the copy.
+ *
+ * Several properties are available to govern the behavior of
+ * H5Lcopy(). These properties are set in the link creation and access
+ * property lists, \p lcpl_id and \p lapl_id, respectively. The
+ * property controlling creation of missing intermediate groups is set
+ * in the link creation property list with
+ * H5Pset_create_intermediate_group(); this function ignores any
+ * other properties in the link creation property list. Properties
+ * controlling character encoding, link traversals, and external link
+ * prefixes are set in the link access property list with
+ * H5Pset_char_encoding(), H5Pset_nlinks(), and
+ * H5Pset_elink_prefix().
+ *
+ * \note H5Lcopy() does not affect the object that the link points to.
+ *
+ * \attention H5Lcopy() cannot copy hard links across files as a hard link is
+ * not valid without a target object; to copy objects from one file
+ * to another, see H5Ocopy().
+ *
+ * \see H5Ocopy()
+ *
+ * \since 1.8.0
+ *
+ */
H5_DLL herr_t H5Lcopy(hid_t src_loc, const char *src_name, hid_t dst_loc, const char *dst_name, hid_t lcpl_id,
hid_t lapl_id);
+/**
+ * \ingroup H5L
+ *
+ * \brief Creates a hard link to an object
+ *
+ * \fgdta_loc_id{cur_loc}
+ * \param[in] cur_name Name of the target object, which must already exist
+ * \fgdta_loc_id{dst_loc}
+ * \param[in] dst_name The name of the new link
+ * \lcpl_id
+ * \lapl_id
+ *
+ * \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.
+ *
+ * \p cur_loc and \p cur_name specify the location
+ * and name, respectively, of the target object, i.e., the object that
+ * the new hard link points to. \p dst_loc and \p dst_name specify the
+ * location and name, respectively, of the new hard link.
+ *
+ * \p cur_name and \p dst_name are interpreted relative to \p cur_loc
+ * and \p dst_loc, respectively. If \p cur_loc and \p dst_loc are the
+ * same location, the HDF5 macro #H5L_SAME_LOC can be used for either
+ * parameter (but not both).
+ *
+ * \p lcpl_id and \p lapl_id are the link creation and access property
+ * lists associated with the new link.
+ *
+ * \note Hard and soft links are for use only if the target object is in the
+ * current file. If the desired target object is in a different file from
+ * the new link, an external link may be created with
+ * H5Lcreate_external().
+ *
+ * \note The HDF5 library keeps a count of all hard links pointing to an
+ * object; if the hard link count reaches zero (0), the object will be
+ * deleted from the file. Creating new hard links to an object will
+ * prevent it from being deleted if other links are removed. The
+ * library maintains no similar count for soft links and they can dangle.
+ *
+ * \note The new link may be one of many that point to that object.
+ *
+ * \since 1.8.0
+ *
+ */
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 H5L
+ *
+ * \brief Creates a soft link
+ *
+ * \param[in] link_target An HDF5 path name
+ * \fgdta_loc_id{link_loc_id}
+ * \param[in] link_name The name of the new link
+ * \lcpl_id
+ * \lapl_id
+ *
+ * \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.
+ *
+ * \p link_target specifies the HDF5 path name the soft link contains.
+ * \p link_target can be an arbitrary HDF5 path name and is
+ * interpreted only at lookup time. This path may be absolute in the
+ * file or relative to \p link_loc_id.
+ *
+ * \p link_loc_id and \p link_name specify the location and name,
+ * respectively, of the new soft link. \p link_name is interpreted
+ * relative to \p link_loc_id and must contain only the name of the soft
+ * link; \p link_name may not contain any additional path elements.
+ *
+ * If \p link_loc_id is a group identifier, the object pointed to by
+ * \p link_name will be accessed as a member of that group. If
+ * \p link_loc_id is a file identifier, the object will be accessed as a
+ * member of the file's root group.
+ *
+ * \p lcpl_id and \p lapl_id are the link creation and access property
+ * lists associated with the new link.
+ *
+ * For instance, if target_path is \c ./foo, \p link_loc_id specifies
+ * \c ./x/y/bar, and the name of the new link is \c new_link, then a
+ * subsequent request for \c ./x/y/bar/new_link will return same the
+ * object as would be found at \c ./foo.
+ *
+ * \note H5Lcreate_soft() is for use only if the target object is in the
+ * current file. If the desired target object is in a different file from
+ * the new link, use H5Lcreate_external() to create an external link.
+ *
+ * \note Soft links and external links are also known as symbolic links as they
+ * use a name to point to an object; hard links employ an object’s
+ * address in the file.
+ *
+ * \note Unlike hard links, a soft link in an HDF5 file is allowed to dangle,
+ * meaning that the target object need not exist at the time that the
+ * link is created.
+ *
+ * \note The HDF5 library does not keep a count of soft links as it does of
+ * hard links.
+ *
+ * \note The new link may be one of many that point to that object.
+ *
+ * \see H5Lcreate_hard(), H5Lcreate_external()
+ *
+ * \since 1.8.0
+ *
+
+ */
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 H5L
+ *
+ * \brief Removes a link from a group
+ *
+ * \fgdta_loc_id
+ * \param[in] name Name of the link to delete
+ * \lapl_id
+ *
+ * \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.
+ *
+ * If the link being removed is a hard link, H5Ldelete() also
+ * decrements the link count for the object to which name points.
+ * Unless there is a duplicate hard link in that group, this action
+ * removes the object to which name points from the group that
+ * previously contained it.
+ *
+ * Object headers keep track of how many hard links refer to an
+ * object; when the hard link count, also referred to as the reference
+ * count, reaches zero, the object can be removed from the file. The
+ * file space associated will then be released, i.e., identified in
+ * memory as freespace. Objects which are open are not removed until
+ * all identifiers to the object are closed.
+ *
+ * \attention Exercise caution in the use of H5Ldelete(); if the link being
+ * removed is on the only path leading to an HDF5 object, that
+ * object may become permanently inaccessible in the file.
+ *
+ * \see H5Lcreate_hard(), H5Lcreate_soft(), H5Lcreate_external()
+ *
+ * \since 1.8.0
+ *
+ */
H5_DLL herr_t H5Ldelete(hid_t loc_id, const char *name, hid_t lapl_id);
+/**
+ * \ingroup H5L
+ *
+ * \brief Removes the \Emph{n}-th link in a group
+ *
+ * \fgdta_loc_id
+ * \param[in] group_name Name of subject group
+ * \param[in] idx_type Index or field which determines the order
+ * \param[in] order Order within field or index
+ * \param[in] n Link for which to retrieve information
+ * \lapl_id
+ *
+ * \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.
+ *
+ * If \p loc_id specifies the group in which the link resides,
+ * \p group_name can be a dot (\c .).
+ *
+ * \see H5Ldelete()
+ *
+ * \since 1.8.0
+ *
+ */
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 H5L
+ *
+ * \brief Returns the value of a link
+ *
+ * \fgdta_loc_id
+ * \param[in] name Link name
+ * \param[out] buf The buffer to hold the link value
+ * \param[in] size Maximum number of bytes of link value to be returned
+ * \lapl_id
+ *
+ * \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
+ * buffer.
+ *
+ * \p size is the size of \p buf and should be the size of the link
+ * value being returned. This size value can be determined through a
+ * call to H5Lget_info(); it is returned in the \c val_size field of
+ * the \ref H5L_info_t \c struct.
+ *
+ * If \p size is smaller than the size of the returned value, then the
+ * string stored in \p buf will be truncated to \p size bytes. For
+ * soft links, this means that the value will not be null terminated.
+ *
+ * In the case of external links, the target file and object names are
+ * extracted from \p buf by calling H5Lunpack_elink_val().
+ *
+ * The link class of link \p name can be determined with a call to
+ * H5Lget_info().
+ *
+ * \p lapl_id specifies the link access property list associated with
+ * the link \p name. In the general case, when default link access
+ * properties are acceptable, this can be passed in as #H5P_DEFAULT. An
+ * example of a situation that requires a non-default link access
+ * property list is when the link is an external link; an external
+ * link may require that a link prefix be set in a link access
+ * property list (see H5Pset_elink_prefix()).
+ *
+ * This function should be used only after H5Lget_info() has been
+ * called to verify that \p name is a symbolic link. This can be
+ * deteremined from the \c link_type field of the \ref H5L_info_t
+ * \c struct.
+ *
+ * \note This function will fail if called on a hard link.
+ *
+ * \see H5Lget_val_by_idx()
+ *
+ * \since 1.8.0
+ *
+ */
H5_DLL herr_t H5Lget_val(hid_t loc_id, const char *name, void *buf /*out*/, size_t size, hid_t lapl_id);
+/**
+ * \ingroup H5L
+ *
+ * \brief Retrieves value of the \Emph{n}-th link in a group, according to the order within an index
+ *
+ * \fgdta_loc_id
+ * \param[in] group_name Group name
+ * \param[in] idx_type Type of index
+ * \param[in] order Order within field or index
+ * \param[in] n Link position for which to retrieve information
+ * \param[out] buf The buffer to hold the link value
+ * \param[in] size Maximum number of bytes of link value to be returned
+ * \lapl_id
+ *
+ * \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.
+ *
+ * For soft links, the value is an HDF5 path name.
+ *
+ * For external links, this is a compound value containing file and
+ * path name information; to use this external link information, it
+ * must first be decoded with H5Lunpack_elink_val()
+ *
+ * For user-defined links, this value will be described in the
+ * definition of the user-defined link type.
+ *
+ * \p loc_id specifies the location identifier of the group specified
+ * by \p group_name.
+ *
+ * \p group_name specifies the group in which the link exists. If
+ * \p loc_id already specifies the group in which the link exists,
+ * \p group_name must be a dot (\c .).
+ *
+ * The size in bytes of link_val is specified in \p size. The size
+ * value can be determined through a call to H5Lget_info_by_idx(); it
+ * is returned in the \c val_size field of the \ref H5L_info_t
+ * \c struct. If
+ * size is smaller than the size of the returned value, then the
+ * string stored in link_val will be truncated to size bytes. For soft
+ * links, this means that the value will not be null terminated.
+ *
+ * If the type of the link is unknown or uncertain, H5Lget_val_by_idx()
+ * should be called only after the type has been determined via a call
+ * to H5Lget_info_by_idx().
+ *
+ * \note This function will fail if called on a hard link.
+ *
+ * \see H5Lget_val()
+ *
+ * \since 1.8.0
+ *
+ */
H5_DLL herr_t H5Lget_val_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type,
H5_iter_order_t order, hsize_t n, void *buf /*out*/, size_t size,
hid_t lapl_id);
+/**
+ * \ingroup H5L
+ *
+ * \brief Determines whether a link with the specified name exists in a group
+ *
+ * \fgdta_loc_id
+ * \param[in] name Link name
+ * \lapl_id
+ *
+ * \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.
+ *
+ * Note that H5Lexists() verifies only that the target link exists. If
+ * name includes either a relative path or an absolute path to the
+ * target link, intermediate steps along the path must be verified
+ * before the existence of the target link can be safely checked. If
+ * the path is not verified and an intermediate element of the path
+ * does not exist, H5Lexists() will fail. The example in the next
+ * paragraph illustrates one step-by-step method for verifying the
+ * existence of a link with a relative or absolute path.
+ *
+ * \Bold{Example:} Use the following steps to verify the existence of
+ * the link \c datasetD in the \c group group1/group2/softlink_to_group3/,
+ * where \c group1 is a member of the group specified by \c loc_id:
+ *
+ * 1. First use H5Lexists() to verify that \c group1 exists.
+ * 2. If \c group1 exists, use H5Lexists() again, this time with name
+ * set to \c group1/group2, to verify that \c group2 exists.
+ * 3. If \c group2 exists, use H5Lexists() with name set to
+ * \c group1/group2/softlink_to_group3 to verify that
+ * \c softlink_to_group3 exists.
+ * 4. If \c softlink_to_group3 exists, you can now safely use
+ * H5Lexists() with \c name set to
+ * \c group1/group2/softlink_to_group3/datasetD to verify that the
+ * target link, \c datasetD, exists.
+ *
+ * If the link to be verified is specified with an absolute path, the
+ * same approach should be used, but starting with the first link in
+ * the file’s root group. For instance, if \c datasetD were in
+ * \c /group1/group2/softlink_to_group3, the first call to H5Lexists()
+ * would have name set to \c /group1.
+ *
+ * Note that this is an outline and does not include all necessary
+ * details. Depending on circumstances, for example, you may need to
+ * verify that an intermediate link points to a group and that a soft
+ * link points to an existing target.
+ *
+ * \note The behavior of H5Lexists() was changed in the 1.10 release in the
+ * case where the root group, \c "/", is the name of the link. This
+ * change is described below:
+ * <ol>
+ * <li>Let \c file denote a valid HDF5 file identifier, and let \c lapl
+ * denote a valid link access property list identifier. A call to
+ * H5Lexists() with arguments \c file, \c "/", and \c lapl
+ * returns a positive value; in other words,
+ * \Code{H5Lexists(file, "/", lapl)} returns a positive value.
+ * In HDF5 version 1.8.16, this function returns 0.</li>
+ * <li>Let \c root denote a valid HDF5 group identifier that refers to the
+ * root group of an HDF5 file, and let \c lapl denote a valid link
+ * access property list identifier. A call to H5Lexists() with
+ * arguments c root, \c "/", and \c lapl returns a positive value;
+ * in other words, \Code{H5Lexists(root, "/", lapl)} returns a postive
+ * value. In HDF5 version 1.8.16, this function returns 0.</li>
+ * </ol>
+ * Note that the function accepts link names and path names. This is
+ * potentially misleading to callers, and we plan to separate the
+ * functionality for link names and path names in a future release.
+ *
+ * \attention H5Lexists() checks the existence of only the final element in a
+ * relative or absolute path; it does not check any other path
+ * elements. The function will therefore fail when both of the
+ * following conditions exist:
+ * - \c name is not local to the group specified by \c loc_id or,
+ * if \c loc_id is something other than a group identifier, \c name
+ * is not local to the root group.
+ * - Any element of the relative path or absolute path in name,
+ * except the target link, does not exist.
+ *
+ * \version 1.10.0 Function behavior changed in this release. (See the note.)
+ * \since 1.8.0
+ *
+ */
H5_DLL htri_t H5Lexists(hid_t loc_id, const char *name, hid_t lapl_id);
+/**
+ * \ingroup H5L
+ *
+ * \brief Returns information about a link
+ *
+ * \fgdta_loc_id
+ * \param[in] name Link name
+ * \param[out] linfo Buffer in which link information is returned
+ * \lapl_id
+ *
+ * \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.
+ *
+ * The location identifier, \p loc_id, specifies the location of the
+ * link. A link name, \p name, interpreted relative to \p loc_id,
+ * specifies the link being queried.
+ *
+ * \p lapl_id is the link access property list associated with the
+ * link name. In the general case, when default link access properties
+ * are acceptable, this can be passed in as #H5P_DEFAULT. An example
+ * of a situation that requires a non-default link access property
+ * list is when the link is an external link; an external link may
+ * require that a link prefix be set in a link access property list
+ * (see H5Pset_elink_prefix()).
+ *
+ * H5Lget_info2() returns information about name in the data structure
+ * H5L_info2_t, which is described below and defined in H5Lpublic.h.
+ * This structure is returned in the buffer \p linfo.
+ * \snippet this H5L_info2_t_snip
+ * In the above struct, \c type specifies the link class. Valid values
+ * include the following:
+ * \link_types
+ * There will be additional valid values if user-defined links have
+ * been registered.
+ *
+ * \p corder specifies the link’s creation order position while
+ * \p corder_valid indicates whether the value in corder is valid.
+ *
+ * If \p corder_valid is \c TRUE, the value in \p corder is known to
+ * be valid; if \p corder_valid is \c FALSE, the value in \p corder is
+ * presumed to be invalid; \p corder starts at zero (0) and is
+ * incremented by one (1) as new links are created. But
+ * higher-numbered entries are not adjusted when a lower-numbered link
+ * is deleted; the deleted link's creation order position is simply
+ * left vacant. In such situations, the value of \p corder for the
+ * last link created will be larger than the number of links remaining
+ * in the group.
+ *
+ * \p cset specifies the character set in which the link name is
+ * encoded. Valid values include the following:
+ * \csets
+ * This value is set with H5Pset_char_encoding().
+ *
+ * \c token is the location that a hard link points to, and
+ * \c val_size is the size of a soft link or user defined link value.
+ * H5O_token_t is used in the VOL layer. It is defined in H5public.h
+ * as:
+ * \snippet H5public.h H5O_token_t_snip
+ *
+ * If the link is a symbolic link, \c val_size will be the length of
+ * the link value, e.g., the length of the HDF5 path name with a null
+ * terminator.
+ *
+ * \since 1.12.0
+ *
+ */
H5_DLL herr_t H5Lget_info2(hid_t loc_id, const char *name, H5L_info2_t *linfo /*out*/, hid_t lapl_id);
+/**
+ * \ingroup H5L
+ *
+ * \brief Retrieves metadata for a link in a group, according to the order
+ * within a field or index
+ *
+ * \loc_id
+ * \param[in] group_name Group name
+ * \idx_type
+ * \order
+ * \param[in] n Link position for which to retrieve information
+ * \param[out] linfo Buffer in which link information is returned
+ * \lapl_id
+ *
+ * \return \herr_t
+ *
+ * \details H5get_info_by_idx2() returns the metadata for a link in a group
+ * according to a specified field or index and a specified order. The
+ * link for which information is to be returned is specified by \p
+ * idx_type, \p order, and \p n as follows:
+ *
+ * - \p idx_type specifies the field by which the links in \p
+ * group_name are ordered. The links may be indexed on this field,
+ * in which case operations seeking specific links are likely to
+ * complete more quickly.
+ * - \p order specifies the order in which
+ * the links are to be referenced for the purposes of this function.
+ * - \p n specifies the position of the subject link. Note that this
+ * count is zero-based; 0 (zero) indicates that the function will
+ * return the value of the first link; if \p n is 5, the function
+ * will return the value of the sixth link; etc.
+ *
+ * For example, assume that \p idx_type, \p order, and \p n are
+ * #H5_INDEX_NAME, #H5_ITER_DEC, and 5, respectively. #H5_INDEX_NAME
+ * indicates that the links are accessed in lexicographic order by
+ * their names. #H5_ITER_DEC specifies that the list be traversed in
+ * reverse order, or in decremented order. And 5 specifies that this
+ * call to the function will return the metadata for the 6th link
+ * (\c n + 1) from the end.
+ *
+ * See H5Literate2() for a list of valid values and further discussion
+ * regarding \p idx_type and \p order.
+ *
+ * If \p loc_id specifies the group in which the link resides,
+ * \p group_name can be a dot (\c .).
+ *
+ * \since 1.12.0
+ *
+ * \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 /*out*/,
hid_t lapl_id);
+/**
+ * \ingroup H5L
+ *
+ * \brief Retrieves name of the \Emph{n}-th link in a group, according to the
+ * order within a specified field or index
+ *
+ * \loc_id
+ * \param[in] group_name Group name
+ * \idx_type
+ * \order
+ * \param[in] n Link position for which to retrieve information
+ * \param[out] name Buffer in which link name is returned
+ * \param[in] size Size in bytes of \p name
+ * \lapl_id
+ *
+ * \return Returns the size of the link name if successful; otherwise returns a
+ * negative value.
+ *
+ * \details H5get_name_by_idx() retrieves the name of the \Emph{n}-th link in a
+ * group, according to the specified order, \p order, within a specified
+ * field or index, \p idx_type.
+ *
+ * \p idx_type specifies the index that is used. Valid values include
+ * the following:
+ * \indexes
+ *
+ * \p order specifies the order in which objects are inspected along
+ * the index specified in \p idx_type. Valid values include the
+ * following:
+ * \orders
+ *
+ * If \p loc_id specifies the group in which the link resides,
+ * \p group_name can be a dot (\c .).
+ *
+ * The size in bytes of name is specified in \p size. If \p size is
+ * unknown, it can be determined via an initial H5Lget_name_by_idx()
+ * call with name set to NULL; the function's return value will be the
+ * size of the name.
+ *
+ * \note Please note that in order for the specified index to correspond to the
+ * creation order index, \p order must be set to #H5_ITER_INC or
+ * #H5_ITER_DEC when calling H5Lget_name_by_idx(). \note The index \p n
+ * passed to H5Lget_name_by_idx() is the index of the link within the
+ * link table, sorted according to \p order and \p idx_type. If order is
+ * #H5_ITER_NATIVE, then the link table is not sorted, and it does not
+ * matter what \p idx_type is. Specifying #H5_ITER_NATIVE does not
+ * guarantee any particular order, only that it remains consistent.
+ *
+ * \since 1.8.0
+ *
+ */
H5_DLL ssize_t H5Lget_name_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type,
H5_iter_order_t order, hsize_t n, char *name /*out*/, size_t size,
hid_t lapl_id);
+/**
+ * \ingroup TRAV
+ *
+ * \brief Iterates over links in a group, with user callback routine,
+ * according to the order within an index.
+ *
+ * \group_id{grp_id}
+ * \idx_type
+ * \order
+ * \param[in,out] idx Pointer to an iteration index to allow
+ * continuing a previous iteration
+ * \op
+ * \op_data
+ * \return \success{The return value of the first operator that returns
+ * non-zero, or zero if all members were processed with no
+ * operator returning non-zero.}
+ * \return \failure{Negative if an error occurs in the library, or the negative
+ * value returned by one of the operators.}
+ *
+ * \details H5Literate2() iterates through the links in a file or
+ * group, \p group_id, in the order of the specified
+ * index, \p idx_type, using a user-defined callback routine
+ * \p op. H5Literate2() does not recursively follow links into
+ * subgroups of the specified group.
+ *
+ * Three parameters are used to manage progress of the iteration:
+ * \p idx_type, \p order, and \p idx_p.
+ *
+ * \p idx_type specifies the index to be used. If the links have
+ * not been indexed by the index type, they will first be sorted by
+ * that index then the iteration will begin; if the links have been
+ * so indexed, the sorting step will be unnecessary, so the iteration
+ * may begin more quickly.
+ *
+ * \p order specifies the order in which objects are to be inspected
+ * along the index \p idx_type.
+ *
+ * \p idx_p tracks the iteration and allows an iteration to be
+ * resumed if it was stopped before all members were processed. It is
+ * passed in by the application with a starting point and returned by
+ * the library with the point at which the iteration stopped.
+ *
+ * \p op_data is a user-defined pointer to the data required to
+ * process links in the course of the iteration. This pointer is
+ * passed back to each step of the iteration in the \p op callback
+ * function's \p op_data parameter. \p op is invoked for each link
+ * encounter.
+ *
+ * \p op_data is passed to and from each iteration and can be used to
+ * supply or aggregate information across iterations.
+ *
+ * \remark Same pattern of behavior as H5Giterate().
+ *
+ * \note This function is also available through the H5Literate() macro.
+ *
+ * \warning The behavior of H5Literate2() is undefined if the link
+ * membership of \p group_id changes during the iteration.
+ * This does not limit the ability to change link destinations
+ * while iterating, but caution is advised.
+ *
+ *
+ * \since 1.12.0
+ *
+ * \see H5Literate_by_name2(), H5Lvisit2(), H5Lvisit_by_name2()
+ *
+ */
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 TRAV
+ *
+ * \brief Iterates through links in a group
+ *
+ * \loc_id
+ * \param[in] group_name Group name
+ * \idx_type
+ * \order
+ * \param[in,out] idx iteration position at which to start (\Emph{IN}) or
+ * position at which an interrupted iteration may be restarted
+ * (\Emph{OUT})
+ * \op
+ * \op_data
+ * \lapl_id
+ * \return \success{The return value of the first operator that returns
+ * non-zero, or zero if all members were processed with no
+ * operator returning non-zero.}
+ * \return \failure{Negative if an error occurs in the library, or the negative
+ * value returned by one of the operators.}
+ *
+ * \details H5Literate_by_name2() iterates through the links in a group
+ * specified by \p loc_id and \p group_name, in the order of the
+ * specified index, \p idx_type, using a user-defined callback routine
+ * \p op. H5Literate_by_name2() does not recursively follow links into
+ * subgroups of the specified group.
+ *
+ * \p idx_type specifies the index to be used. If the links have not
+ * been indexed by the index type, they will first be sorted by that
+ * index then the iteration will begin; if the links have been so
+ * indexed, the sorting step will be unnecessary, so the iteration may
+ * begin more quickly. Valid values include the following:
+ * \indexes
+ *
+ * \p order specifies the order in which objects are to be inspected
+ * along the index specified in \p idx_type. Valid values include the
+ * following:
+ * \orders
+ *
+ * \p idx_p allows an interrupted iteration to be resumed; it is
+ * passed in by the application with a starting point and returned by
+ * the library with the point at which the iteration stopped.
+ *
+ * \note H5Literate_by_name2() is not recursive. In particular, if a member of
+ * \p group_name is found to be a group, call it \c subgroup_a,
+ * H5Literate_by_name2() does not examine the members of \c subgroup_a.
+ * When recursive iteration is required, the application must handle the
+ * recursion, explicitly calling H5Literate_by_name2() on discovered
+ * subgroups.
+ *
+ * \note H5Literate_by_name2() assumes that the membership of the group being
+ * iterated over remains unchanged through the iteration; if any of the
+ * links in the group change during the iteration, the function’s
+ * behavior is undefined. Note, however, that objects pointed to by the
+ * links can be modified.
+ *
+ * \note H5Literate_by_name2() is the same as H5Literate2(), except that
+ * H5Literate2() always proceeds in alphanumeric order.
+ *
+ * \since 1.12.0
+ *
+ * \see H5Literate(), H5Lvisit()
+ *
+ */
H5_DLL herr_t H5Literate_by_name2(hid_t loc_id, const char *group_name, H5_index_t idx_type,
H5_iter_order_t order, hsize_t *idx, H5L_iterate2_t op, void *op_data,
hid_t lapl_id);
+/**
+ * \ingroup TRAV
+ *
+ * \brief Recursively visits all links starting from a specified group
+ *
+ * \group_id{grp_id}
+ * \idx_type
+ * \order
+ * \op
+ * \op_data
+ * \return \success{The return value of the first operator that returns
+ * non-zero, or zero if all members were processed with no
+ * operator returning non-zero.}
+ * \return \failure{Negative if an error occurs in the library, or the negative
+ * value returned by one of the operators.}
+ *
+ * \details H5Lvisit2() is a recursive iteration function to visit all links in
+ * and below a group in an HDF5 file, thus providing a mechanism for
+ * an application to perform a common set of operations across all of
+ * those links or a dynamically selected subset. For non-recursive
+ * iteration across the members of a group, see H5Literate2().
+ *
+ * The group serving as the root of the iteration is specified by its
+ * group or file identifier, \p group_id.
+ *
+ * Two parameters are used to establish the iteration: \p idx_type and
+ * \p order.
+ *
+ * \p idx_type specifies the index to be used. If the links have not
+ * been indexed by the index type, they will first be sorted by that
+ * index then the iteration will begin; if the links have been so
+ * indexed, the sorting step will be unnecessary, so the iteration may
+ * begin more quickly. Valid values include the following:
+ * \indexes
+ *
+ * Note that the index type passed in \p idx_type is a best effort
+ * setting. If the application passes in a value indicating iteration
+ * in creation order and a group is encountered that was not tracked
+ * in creation order, that group will be iterated over in
+ * lexicographic order by name, or name order. (Name order is the
+ * native order used by the HDF5 library and is always available.)
+ *
+ * \p order specifies the order in which objects are to be inspected
+ * along the index specified in \p idx_type. Valid values include the
+ * following:
+ * \orders
+ *
+ * \p op is a callback function of type \ref H5L_iterate2_t that is invoked
+ * for each link encountered.
+ * \snippet this H5L_iterate2_t_snip
+ *
+ * The \ref H5L_info2_t struct is defined (in H5Lpublic.h) as follows:
+ * \snippet this H5L_info2_t_snip
+ *
+ * The possible return values from the callback function, and the
+ * effect of each, are as follows:
+ * \li Zero causes the visit iterator to continue, returning zero when
+ * all group members have been processed.
+ * \li A positive value causes the visit iterator to immediately
+ * return that positive value, indicating short-circuit success.
+ * \li A negative value causes the visit iterator to immediately
+ * return that value, indicating failure.
+ *
+ * The H5Lvisit2() \p op_data parameter is a user-defined pointer to
+ * the data required to process links in the course of the iteration.
+ * This pointer is passed back to each step of the iteration in the
+ * \p op callback function's \p op_data parameter.
+ *
+ * H5Lvisit2() and H5Ovisit2() are companion functions: one for
+ * examining and operating on links; the other for examining and
+ * operating on the objects that those links point to. Both functions
+ * ensure that by the time the function completes successfully, every
+ * link or object below the specified point in the file has been
+ * presented to the application for whatever processing the
+ * application requires.
+ *
+ * \since 1.12.0
+ *
+ * \see H5Literate()
+ *
+ */
H5_DLL herr_t H5Lvisit2(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate2_t op,
void *op_data);
+/**
+ * \ingroup TRAV
+ *
+ * \brief Recursively visits all links starting from a specified group
+ *
+ * \loc_id
+ * \param[in] group_name Group name
+ * \idx_type
+ * \order
+ * \op
+ * \op_data
+ * \lapl_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Lvisit_by_name2() is a recursive iteration function to visit all
+ * links in and below a group in an HDF5 file, thus providing a
+ * mechanism for an application to perform a common set of operations
+ * across all of those links or a dynamically selected subset. For
+ * non-recursive iteration across the members of a group, see
+ * H5Literate2().
+ *
+ * The group serving as the root of the iteration is specified by the
+ * \p loc_id / \p group_name parameter pair. \p loc_id specifies a
+ * file or group; group_name specifies either a group in the file
+ * (with an absolute name based in the file’s root group) or a group
+ * relative to \p loc_id. If \p loc_id fully specifies the group that
+ * is to serve as the root of the iteration, group_name should be '.'
+ * (a dot). (Note that when \p loc_id fully specifies the the group
+ * that is to serve as the root of the iteration, the user may wish to
+ * consider using H5Lvisit2() instead of H5Lvisit_by_name2().)
+ *
+ * Two parameters are used to establish the iteration: \p idx_type and
+ * \p order.
+ *
+ * \p idx_type specifies the index to be used. If the links have not
+ * been indexed by the index type, they will first be sorted by that
+ * index then the iteration will begin; if the links have been so
+ * indexed, the sorting step will be unnecesary, so the iteration may
+ * begin more quickly. Valid values include the following:
+ * \indexes
+ *
+ * Note that the index type passed in \p idx_type is a best effort
+ * setting. If the application passes in a value indicating iteration
+ * in creation order and a group is encountered that was not tracked
+ * in creation order, that group will be iterated over in
+ * lexicographic order by name, or name order. (Name order is the
+ * native order used by the HDF5 library and is always available.)
+ *
+ * \p order specifies the order in which objects are to be inspected
+ * along the index specified in \p idx_type. Valid values include the
+ * following:
+ * \orders
+ *
+ * The \p op callback function, the related \ref H5L_info2_t
+ * \c struct, and the effect that the callback function's return value
+ * has on the application are described in H5Lvisit2().
+ *
+ * The H5Lvisit_by_name2() \p op_data parameter is a user-defined
+ * pointer to the data required to process links in the course of the
+ * iteration. This pointer is passed back to each step of the
+ * iteration in the callback function's \p op_data parameter.
+ *
+ * \p lapl_id is a link access property list. In the general case,
+ * when default link access properties are acceptable, this can be
+ * passed in as #H5P_DEFAULT. An example of a situation that requires
+ * a non-default link access property list is when the link is an
+ * external link; an external link may require that a link prefix be
+ * set in a link access property list (see H5Pset_elink_prefix()).
+ *
+ * H5Lvisit_by_name2() and H5Ovisit_by_name2() are companion
+ * functions: one for examining and operating on links; the other for
+ * examining and operating on the objects that those links point to.
+ * Both functions ensure that by the time the function completes
+ * successfully, every link or object below the specified point in the
+ * file has been presented to the application for whatever processing
+ * the application requires.
+ *
+ * \since 1.12.0
+ *
+ */
H5_DLL herr_t H5Lvisit_by_name2(hid_t loc_id, const char *group_name, H5_index_t idx_type,
H5_iter_order_t order, H5L_iterate2_t op, void *op_data, hid_t lapl_id);
/* UD link functions */
+/**
+ * \ingroup H5L
+ *
+ * \brief Creates a link of a user-defined type
+ *
+ * \loc_id{link_loc_id}
+ * \param[in] link_name Link name
+ * \param[in] link_type User-defined link class
+ * \param[in] udata User-supplied link information
+ * \param[in] udata_size Size of udata buffer
+ * \lcpl_id
+ * \lapl_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Lcreate_ud() creates a link of user-defined type \p link_type
+ * named \p link_name at the location specified in \p link_loc_id with
+ * user-specified data \p udata.
+ *
+ * \p link_name is interpreted relative to \p link_loc_id.
+ *
+ * Valid values for the link class of the new link, \p link_type,
+ * include #H5L_TYPE_EXTERNAL and any user-defined link classes that
+ * have been registered with the library. See H5Lregister() for
+ * further information.
+ *
+ * The format of the information pointed to by \p udata is defined by
+ * the user. \p udata_size specifies the size of the \p udata buffer.
+ * \p udata may be NULL if \p udata_size is zero (0).
+ *
+ * The property lists specified by \p lcpl_id and \p lapl_id specify
+ * properties used to create and access the link.
+ *
+ * \note The external link type, #H5L_TYPE_EXTERNAL, included in the HDF5
+ * library distribution, is implemented as a user-defined link type. This
+ * was done, in part, to provide a model for the implementation of other
+ * user-defined links.
+ *
+ * \since 1.8.0
+ *
+ */
H5_DLL herr_t H5Lcreate_ud(hid_t link_loc_id, const char *link_name, H5L_type_t link_type, const void *udata,
size_t udata_size, hid_t lcpl_id, hid_t lapl_id);
+/**
+ * \ingroup H5LA
+ *
+ * \brief Registers a user-defined link class or changes behavior of an
+ * existing class
+ *
+ * \param[in] cls Pointer to a buffer containing the struct describing the
+ * user-defined link class
+ *
+ * \return \herr_t
+ *
+ * \details H5Lregister() registers a class of user-defined links, or changes
+ * the behavior of an existing class.
+ *
+ * \p cls is a pointer to a buffer containing a copy of the
+ * H5L_class_t struct. This struct is defined in H5Lpublic.h as
+ * follows:
+ * \snippet this H5L_class_t_snip
+ *
+ * The class definition passed with \p cls must include at least the
+ * following:
+ * \li An H5L_class_t version (which should be #H5L_LINK_CLASS_T_VERS)
+ * \li A link class identifier, \c class_id
+ * \li A traversal function, \c trav_func
+ *
+ * Remaining \c struct members are optional and may be passed as NULL.
+ *
+ * The link class passed in \c class_id must be in the user-definable
+ * range between #H5L_TYPE_UD_MIN and #H5L_TYPE_UD_MAX
+ * (see the table below) and will override
+ * any existing link class with that identifier.
+ *
+ * As distributed, valid values of \c class_id used in HDF5 include
+ * the following (defined in H5Lpublic.h):
+ * \link_types
+ *
+ * The hard and soft link class identifiers cannot be modified or
+ * reassigned, but the external link class is implemented as an
+ * example in the user-definable link class identifier range.
+ * H5Lregister() is used to register additional link classes. It could
+ * also be used to modify the behavior of the external link class,
+ * though that is not recommended.
+ *
+ * The following table summarizes existing link types and values and
+ * the reserved and user-definable link class identifier value ranges.
+ * <table>
+ * <tr>
+ * <th>Link class identifier or Value range</th>
+ * <th>Description</th>
+ * <th>Link class or label</th>
+ * </tr>
+ * <tr>
+ * <td>0 to 63</td>
+ * <td>Reserved range</td>
+ * <td></td>
+ * </tr>
+ * <tr>
+ * <td>64 to 255</td>
+ * <td>User-definable range</td>
+ * <td></td>
+ * </tr>
+ * <tr>
+ * <td>64</td>
+ * <td>Minimum user-defined value</td>
+ * <td>#H5L_TYPE_UD_MIN</td>
+ * </tr>
+ * <tr>
+ * <td>64</td>
+ * <td>External link</td>
+ * <td>#H5L_TYPE_EXTERNAL</td>
+ * </tr>
+ * <tr>
+ * <td>255</td>
+ * <td>Maximum user-defined value</td>
+ * <td>#H5L_TYPE_UD_MAX</td>
+ * </tr>
+ * <tr>
+ * <td>255</td>
+ * <td>Maximum value</td>
+ * <td>#H5L_TYPE_MAX</td>
+ * </tr>
+ * <tr>
+ * <td>-1</td>
+ * <td>Error</td>
+ * <td>#H5L_TYPE_ERROR</td>
+ * </tr>
+ * </table>
+ *
+ * Note that HDF5 internally registers user-defined link classes only
+ * by the numeric value of the link class identifier. An application,
+ * on the other hand, will generally use a name for a user-defined
+ * class, if for no other purpose than as a variable name. Assume,
+ * for example, that a complex link type is registered with the link
+ * class identifier 73 and that the code includes the following
+ * assignment:
+ * \code
+ * H5L_TYPE_COMPLEX_A = 73
+ * \endcode
+ * The application can refer to the link class with a term,
+ * \c H5L_TYPE_COMPLEX_A, that conveys meaning to a human reviewing
+ * the code, while HDF5 recognizes it by the more cryptic numeric
+ * identifier, 73.
+ *
+ * \attention Important details and considerations include the following:
+ * \li If you plan to distribute files or software with a
+ * user-defined link class, please contact the Help Desk at
+ * The HDF Group to help prevent collisions between \c class_id
+ * values. See below.
+ * \li As distributed with HDF5, the external link class is
+ * implemented as an example of a user-defined link class with
+ * #H5L_TYPE_EXTERNAL equal to #H5L_TYPE_UD_MIN. \c class_id in
+ * the H5L_class_t \c struct must not equal #H5L_TYPE_UD_MIN
+ * unless you intend to overwrite or modify the behavior of
+ * external links.
+ * \li H5Lregister() can be used only with link class identifiers
+ * in the user-definable range (see table above).
+ * \li The hard and soft links defined by the HDF5 library,
+ * #H5L_TYPE_HARD and #H5L_TYPE_SOFT, reside in the reserved
+ * range below #H5L_TYPE_UD_MIN and cannot be redefined or
+ * modified.
+ * \li H5Lis_registered() can be used to determine whether a desired
+ * link class identifier is available. \Emph{Note that this
+ * function will tell you only whether the link class identifier
+ * has been registered with the installed copy of HDF5; it
+ * cannot tell you whether the link class has been registered
+ * with The HDF Group.}
+ * \li #H5L_TYPE_MAX is the maximum allowed value for a link type
+ * identifier.
+ * \li #H5L_TYPE_UD_MIN equals #H5L_TYPE_EXTERNAL.
+ * \li #H5L_TYPE_UD_MAX equals #H5L_TYPE_MAX.
+ * \li #H5L_TYPE_ERROR indicates that an error has occurred.
+ *
+ * \note \Bold{Registration with The HDF Group:}\n
+ * There are sometimes reasons to take a broader approach to registering
+ * a user-defined link class than just invoking H5Lregister(). For
+ * example:
+ * \li A user-defined link class is intended for use across an
+ * organization, among collaborators, or across a community of users.
+ * \li An application or library overlying HDF5 invokes a user-defined
+ * link class that must be shipped with the software.
+ * \li Files are distributed that make use of a user-defined link class.
+ * \li Or simply, a specific user-defined link class is thought to be
+ * widely useful.
+ *
+ * In such cases, you are encouraged to register that link class with
+ * The HDF Group's Helpdesk. The HDF Group maintains a registry of known
+ * user-defined link classes and tracks the selected link class
+ * identifiers. This registry is intended to reduce the risk of
+ * collisions between \c class_id values and to help coordinate the use
+ * of specialized link classes.
+ *
+ * \since 1.8.0
+ *
+ */
H5_DLL herr_t H5Lregister(const H5L_class_t *cls);
+/**
+ * \ingroup H5LA
+ *
+ * \brief Unregisters a class of user-defined links
+ *
+ * \param[in] id User-defined link class identifier
+ *
+ * \return \herr_t
+ *
+ * \details H5Lunregister() unregisters a class of user-defined links,
+ * preventing them from being traversed, queried, moved, etc.
+ *
+ * \note A link class can be re-registered using H5Lregister().
+ *
+ * \since 1.8.0
+ *
+ */
H5_DLL herr_t H5Lunregister(H5L_type_t id);
+/**
+ * \ingroup H5LA
+ *
+ * \brief Determines whether a class of user-defined links is registered
+ *
+ * \param[in] id User-defined link class identifier
+ *
+ * \return \htri_t
+ *
+ * \details H5Lis_registered() tests whether a user-defined link class is
+ * currently registered, either by the HDF5 library or by the user
+ * through the use of H5Lregister().
+ *
+ * \note A link class must be registered to create new links of that type or to
+ * traverse existing links of that type.
+ *
+ * \since 1.8.0
+ *
+ */
H5_DLL htri_t H5Lis_registered(H5L_type_t id);
/* External link functions */
+/**
+ * \ingroup H5L
+ *
+ * \brief Decodes external link information
+ *
+ * \param[in] ext_linkval Buffer containing external link information
+ * \param[in] link_size Size, in bytes, of the \p ext_linkval buffer
+ * \param[out] flags External link flags, packed as a bitmap (\Emph{Reserved as
+ * a bitmap for flags; no flags are currently defined, so the
+ * only valid value * is 0.})
+ * \param[out] filename Returned filename \param[out] obj_path Returned
+ * object path, relative to \p filename
+ *
+ * \return \herr_t
+ *
+ * \details H5Lunpack_elink_val() decodes the external link information
+ * returned by H5Lget_val() in the \p ext_linkval buffer.
+ *
+ * \p ext_linkval should be the buffer set by H5Lget_val() and will
+ * consist of two NULL-terminated strings, the filename and object
+ * path, one after the other.
+ *
+ * Given this buffer, H5Lunpack_elink_val() creates pointers to the
+ * filename and object path within the buffer and returns them in
+ * \p filename and \p obj_path, unless they are passed in as NULL.
+ *
+ * H5Lunpack_elink_val() requires that \p ext_linkval contain a
+ * concatenated pair of null-terminated strings, so use of this
+ * function on a string that is not an external link \p udata buffer
+ * may result in a segmentation fault. This failure can be avoided by
+ * adhering to the following procedure:
+ * <ol>
+ * <li>Call H5Lget_info() to get the link type and the size of the
+ * link value.<li>
+ * <li>Verify that the link is an external link, i.e., that its link
+ * type is #H5L_TYPE_EXTERNAL.</li>
+ * <li>Call H5Lget_val() to get the link value.</li>
+ * <li>Call H5Lunpack_elink_val() to unpack that value.</li>
+ * </ol>
+ *
+ * \since 1.8.0
+ *
+ */
H5_DLL herr_t H5Lunpack_elink_val(const void *ext_linkval /*in*/, size_t link_size, unsigned *flags,
const char **filename /*out*/, const char **obj_path /*out*/);
+/**
+ * \ingroup H5L
+ *
+ * \brief Creates an external link, a soft link to an object in a different file.
+ *
+ * \param[in] file_name Name of the target file containing the target object.
+ * \param[in] obj_name Path within the target file to the target object
+ * \fgdt_loc_id{link_loc_id}
+ * \param[in] link_name Name of the new link, relative to \p link_loc_id
+ * \lcpl_id
+ * \lapl_id
+ * \return \herr_t
+ *
+ * \details H5Lcreate_external() creates a new external link. An external link
+ * is a soft link to an object in a different HDF5 file from the
+ * location of the link, i.e., to an external object.
+ *
+ * \p file_name identifies the target file containing the target
+ * object; \p obj_name specifies the path of the target object within
+ * that file. \p obj_name must be an absolute pathname in
+ * \p file_name, i.e., it must start at the target file’s root group,
+ * but it is not interpreted until an application attempts to traverse
+ * it.
+ *
+ * \p link_loc_id and \p link_name specify the location and name,
+ * respectively, of the new link. \p link_name is interpreted relative
+ * to \p link_loc_id.
+ *
+ * \p lcpl_id is the link creation property list used in creating the
+ * new link.
+ *
+ * \p lapl_id is the link access property list used in traversing the
+ * new link. Note that an external file opened by the traversal of an
+ * external link is always opened with the weak file close degree
+ * property setting, #H5F_CLOSE_WEAK (see H5Pset_fclose_degree());
+ * any file close degree property setting in \p lapl_id is ignored.
+ *
+ * An external link behaves similarly to a soft link, and like a soft
+ * link in an HDF5 file, it may dangle: the target file and object
+ * need not exist at the time that the external link is created.
+ *
+ * When the external link \p link_name is accessed, the library will
+ * search for the target file \p file_name as described below:
+ *
+ * - If \p file_name is a relative pathname, the following steps are
+ * performed:
+ * - The library will get the prefix(es) set in the environment
+ * variable \c HDF5_EXT_PREFIX and will try to prepend each prefix
+ * to \p file_name to form a new \p file_name.
+ * - If the new \p file_name does not exist or if \c HDF5_EXT_PREFIX
+ * is not set, the library will get the prefix set via
+ * H5Pset_elink_prefix() and prepend it to \p file_name to form a
+ * new \p file_name.
+ * - If the new \p file_name does not exist or no prefix is being
+ * set by H5Pset_elink_prefix(), then the path of the file
+ * associated with \p link_loc_id is obtained. This path can be
+ * the absolute path or the current working directory plus the
+ * relative path of that file when it is created/opened. The
+ * library will prepend this path to \p file_name to form a new
+ * \p file_name.
+ * - If the new \p file_name does not exist, then the library will
+ * look for \p file_name and will return failure/success
+ * accordingly.
+ * - If \p file_name is an absolute pathname, the library will first
+ * try to find \p file_name. If \p file_name does not exist,
+ * \p file_name is stripped of directory paths to form a new
+ * \p file_name. The search for the new \p file_name then follows
+ * the same steps as described above for a relative pathname. See
+ * examples below illustrating how target_file_name is stripped to
+ * form a new \p file_name.
+ *
+ * Note that \p file_name is considered to be an absolute pathname
+ * when the following condition is true:
+ *
+ * - For Unix, the first character of \p file_name is a slash (\c /).
+ * For example, consider a \p file_name of \c /tmp/A.h5.
+ * If that target file does not exist, the new \p file_name after
+ * stripping will be \c A.h5.
+ * - For Windows, there are 6 cases:
+ * -# \p file_name is an absolute drive with absolute pathname.
+ * For example, consider a \p file_name of \c /tmp/A.h5. If that
+ * target file does not exist, the new \p file_name after
+ * stripping will be \c A.h5.
+ * -# \p file_name is an absolute pathname without specifying drive
+ * name. For example, consider a \p file_name of \c /tmp/A.h5.
+ * If that target file does not exist, the new \p file_name after
+ * stripping will be \c A.h5.
+ * -# \p file_name is an absolute drive with relative pathname.
+ * For example, consider a \p file_name of \c /tmp/A.h5. If that
+ * target file does not exist, the new \p file_name after
+ * stripping will be \c tmp\A.h5.
+ * -# \p file_name is in UNC (Uniform Naming Convention) format with
+ * server name, share name, and pathname. For example, consider
+ * a \p file_name of \c /tmp/A.h5. If that target file does not
+ * exist, the new \p file_name after stripping will be \c A.h5.
+ * -# \p file_name is in Long UNC (Uniform Naming Convention) format
+ * with server name, share name, and pathname. For example,
+ * consider a \p file_name of \c /tmp/A.h5. If that target file
+ * does not exist, the new \p file_name after stripping will be
+ * \c A.h5.
+ * -# \p file_name is in Long UNC (Uniform Naming Convention) format
+ * with an absolute drive and an absolute pathname. For example,
+ * consider a \p file_name of \c /tmp/A.h5. If that target file
+ * does not exist, the new \p file_name after stripping will be
+ * \c A.h5.
+ *
+ * The library opens target file \p file_name with the file access
+ * property list that is set via H5Pset_elink_fapl() when the external
+ * link link_name is accessed. If no such property list is set, the
+ * library uses the file access property list associated with the file
+ * of \p link_loc_id to open the target file.
+ *
+ * If an application requires additional control over file access
+ * flags or the file access property list, see H5Pset_elink_cb(); this
+ * function enables the use of an external link callback function as
+ * described in H5L_elink_traverse_t().
+ *
+ * \attention A file close degree property setting (H5Pset_fclose_degree()) in
+ * the external link file access property list or in the external
+ * link callback function will be ignored. A file opened by means of
+ * traversing an external link is always opened with the weak file
+ * close degree property setting, #H5F_CLOSE_WEAK .
+ *
+ * \see H5Lcreate_hard(), H5Lcreate_soft(), H5Lcreate_ud()
+ *
+ * \since 1.8.0
+ */
H5_DLL herr_t H5Lcreate_external(const char *file_name, const char *obj_name, hid_t link_loc_id,
const char *link_name, hid_t lcpl_id, hid_t lapl_id);
@@ -205,49 +1609,508 @@ 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]
typedef struct {
- H5L_type_t type; /* Type of link */
- hbool_t corder_valid; /* Indicate if creation order is valid */
- int64_t corder; /* Creation order */
- H5T_cset_t cset; /* Character set of link name */
+ H5L_type_t type; /**< Type of link */
+ hbool_t corder_valid; /**< Indicate if creation order is valid */
+ int64_t corder; /**< Creation order */
+ H5T_cset_t cset; /**< Character set of link name */
union {
- haddr_t address; /* Address hard link points to */
- size_t val_size; /* Size of a soft link or UD link value */
+ haddr_t address; /**< Address hard link points to */
+ size_t val_size; /**< Size of a soft link or UD link value */
} u;
} H5L_info1_t;
+//! [H5L_info1_t_snip]
-/* Callback during link traversal */
+/** Callback during link traversal */
typedef hid_t (*H5L_traverse_0_func_t)(const char *link_name, hid_t cur_group, const void *lnkdata,
size_t lnkdata_size, hid_t lapl_id);
-/* User-defined link types */
+/** User-defined link types */
typedef struct {
- int version; /* Version number of this struct */
- H5L_type_t id; /* Link type ID */
- const char * comment; /* Comment for debugging */
- H5L_create_func_t create_func; /* Callback during link creation */
- H5L_move_func_t move_func; /* Callback after moving link */
- H5L_copy_func_t copy_func; /* Callback after copying link */
- H5L_traverse_0_func_t trav_func; /* Callback during link traversal */
- H5L_delete_func_t del_func; /* Callback for link deletion */
- H5L_query_func_t query_func; /* Callback for queries */
+ int version; /**< Version number of this struct */
+ H5L_type_t id; /**< Link type ID */
+ const char *comment; /**< Comment for debugging */
+ H5L_create_func_t create_func; /**< Callback during link creation */
+ H5L_move_func_t move_func; /**< Callback after moving link */
+ H5L_copy_func_t copy_func; /**< Callback after copying link */
+ H5L_traverse_0_func_t trav_func; /**< Callback during link traversal */
+ H5L_delete_func_t del_func; /**< Callback for link deletion */
+ H5L_query_func_t query_func; /**< Callback for queries */
} H5L_class_0_t;
-/* Prototype for H5Literate1/H5Literate_by_name1() operator */
-typedef herr_t (*H5L_iterate1_t)(hid_t group, const char *name, const H5L_info1_t *info, void *op_data);
+/** Prototype for H5Literate1() / H5Literate_by_name1() operator */
+//! [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]
/* Function prototypes */
+/**
+ * \ingroup H5L
+ *
+ * \brief Returns information about a link
+ *
+ * \fgdta_loc_id
+ * \param[in] name Link name
+ * \param[out] linfo Buffer in which link information is returned
+ * \lapl_id
+ *
+ * \return \herr_t
+ *
+ * \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.
+ *
+ * The location identifier, \p loc_id, specifies the location of the
+ * link. A link name, \p name, interpreted relative to \p loc_id,
+ * specifies the link being queried.
+ *
+ * \p lapl_id is the link access property list associated with the
+ * link \p name. In the general case, when default link access
+ * properties are acceptable, this can be passed in as #H5P_DEFAULT.
+ * An example of a situation that requires a non-default link access
+ * property list is when the link is an external link; an external
+ * link may require that a link prefix be set in a link access
+ * property list (see H5Pset_elink_prefix()).
+ *
+ * H5Lget_info1() returns information about name in the data structure
+ * \ref H5L_info1_t, which is described below and defined in
+ * H5Lpublic.h. This structure is returned in the buffer \p linfo.
+ * \snippet this H5L_info1_t_snip
+ * In the above struct, type specifies the link class. Valid values
+ * include the following:
+ * \link_types
+ * There will be additional valid values if user-defined links have
+ * been registered.
+ *
+ * \c corder specifies the link’s creation order position while
+ * \c corder_valid indicates whether the value in \c corder is valid.
+ *
+ * If \c corder_valid is \c TRUE, the value in \c corder is known to
+ * be valid; if \c corder_valid is \c FALSE, the value in \c corder is
+ * presumed to be invalid;
+ *
+ * \c corder starts at zero (0) and is incremented by one (1) as new
+ * links are created. But higher-numbered entries are not adjusted
+ * when a lower-numbered link is deleted; the deleted link’s creation
+ * order position is simply left vacant. In such situations, the value
+ * of \c corder for the last link created will be larger than the
+ * number of links remaining in the group.
+ *
+ * \c cset specifies the character set in which the link name is
+ * encoded. Valid values include the following:
+ * \csets
+ * This value is set with H5Pset_char_encoding().
+ *
+ * \c address and \c val_size are returned for hard and symbolic
+ * links, respectively. Symbolic links include soft and external links
+ * and some user-defined links.
+ *
+ * If the link is a hard link, \c address specifies the file address
+ * that the link points to.
+ *
+ * If the link is a symbolic link, \c val_size will be the length of
+ * the link value, e.g., the length of the HDF5 path name with a null
+ * terminator.
+ *
+ * \version 1.12.0 Function was deprecated.
+ * \version 1.8.2 Fortran subroutine added in this release.
+ * \version 1.8.4 Fortran subroutine syntax changed in this release.
+ *
+ * \since 1.8.0
+ *
+ */
H5_DLL herr_t H5Lget_info1(hid_t loc_id, const char *name, H5L_info1_t *linfo /*out*/, hid_t lapl_id);
+/**
+ * \ingroup H5L
+ *
+ * \brief Retrieves metadata for a link in a group, according to the order
+ * within a field or index
+ *
+ * \loc_id
+ * \param[in] group_name Group name
+ * \idx_type
+ * \order
+ * \param[in] n Link position for which to retrieve information
+ * \param[out] linfo Buffer in which link information is returned
+ * \lapl_id
+ *
+ * \return \herr_t
+ *
+ * \deprecated As of HDF5-1.12 this function has been deprecated in favor of
+ * the function H5Lget_info_by_idx2() and the macro
+ * H5Lget_info_by_idx().
+ *
+ * \details H5get_info_by_idx1() returns the metadata for a link in a group
+ * according to a specified field or index and a specified order.
+ *
+ * The link for which information is to be returned is specified by \p
+ * idx_type, \p order, and \p n as follows:
+ *
+ * - \p idx_type specifies the field by which the links in \p
+ * group_name are ordered. The links may be indexed on this field,
+ * in which case operations seeking specific links are likely to
+ * complete more quickly.
+ * - \p order specifies the order in which
+ * the links are to be referenced for the purposes of this function.
+ * - \p n specifies the position of the subject link. Note that this
+ * count is zero-based; 0 (zero) indicates that the function will
+ * return the value of the first link; if \p n is 5, the function
+ * will return the value of the sixth link; etc.
+ *
+ * For example, assume that \p idx_type, \p order, and \p n are
+ * #H5_INDEX_NAME, #H5_ITER_DEC, and 5, respectively. #H5_INDEX_NAME
+ * indicates that the links are accessed in lexicographic order by
+ * their names. #H5_ITER_DEC specifies that the list be traversed in
+ * reverse order, or in decremented order. And 5 specifies that this
+ * call to the function will return the metadata for the 6th link
+ * (\c n + 1) from the end.
+ *
+ * See H5Literate1() for a list of valid values and further discussion
+ * regarding \p idx_type and \p order.
+ *
+ * If \p loc_id specifies the group in which the link resides,
+ * \p group_name can be a dot (\c .).
+ *
+ * \version 1.12.0 Function was renamed to H5Lget_index_by_idx1() and deprecated.
+ * \version 1.8.4 Fortran subroutine syntax changed in this release.
+ * \version 1.8.2 Fortran subroutine added in this release.
+ *
+ * \since 1.8.0
+ *
+ */
H5_DLL herr_t H5Lget_info_by_idx1(hid_t loc_id, const char *group_name, H5_index_t idx_type,
H5_iter_order_t order, hsize_t n, H5L_info1_t *linfo /*out*/,
hid_t lapl_id);
+/**
+ * \ingroup TRAV
+ *
+ * \brief Iterates over links in a group, with user callback routine,
+ * according to the order within an index.
+ *
+ * \group_id{grp_id}
+ * \idx_type
+ * \order
+ * \param[in,out] idx Pointer to an iteration index to allow
+ * continuing a previous iteration
+ * \op
+ * \op_data
+ * \return \success{The return value of the first operator that returns
+ * non-zero, or zero if all members were processed with no
+ * operator returning non-zero.}
+ * \return \failure{Negative if an error occurs in the library, or the negative
+ * value returned by one of the operators.}
+ *
+ * \deprecated Deprecated in favor of H5Literate2().
+ *
+ * \details H5Literate1() iterates through the links in a file or
+ * group, \p group_id, in the order of the specified
+ * index, \p idx_type, using a user-defined callback routine
+ * \p op. H5Literate1() does not recursively follow links into
+ * subgroups of the specified group.
+ *
+ * Three parameters are used to manage progress of the iteration:
+ * \p idx_type, \p order, and \p idx_p.
+ *
+ * \p idx_type specifies the index to be used. If the links have
+ * not been indexed by the index type, they will first be sorted by
+ * that index then the iteration will begin; if the links have been
+ * so indexed, the sorting step will be unnecessary, so the iteration
+ * may begin more quickly.
+ *
+ * \p order specifies the order in which objects are to be inspected
+ * along the index \p idx_type.
+ *
+ * \p idx_p tracks the iteration and allows an iteration to be
+ * resumed if it was stopped before all members were processed. It is
+ * passed in by the application with a starting point and returned by
+ * the library with the point at which the iteration stopped.
+ *
+ * \p op_data is a user-defined pointer to the data required to
+ * process links in the course of the iteration. This pointer is
+ * passed back to each step of the iteration in the \p op callback
+ * function's \p op_data parameter. \p op is invoked for each link
+ * encounter.
+ *
+ * \p op_data is passed to and from each iteration and can be used to
+ * supply or aggregate information across iterations.
+ *
+ * \remark Same pattern of behavior as H5Giterate().
+ *
+ * \note This function is also available through the H5Literate() macro.
+ *
+ * \warning The behavior of H5Literate1() is undefined if the link
+ * membership of \p group_id changes during the iteration.
+ * This does not limit the ability to change link destinations
+ * while iterating, but caution is advised.
+ *
+ *
+ * \version 1.12.0 Function was deprecated in this release.
+ * \since 1.8.0
+ *
+ * \see H5Literate_by_name2(), H5Lvisit2(), H5Lvisit_by_name2()
+ *
+ */
H5_DLL herr_t H5Literate1(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx,
H5L_iterate1_t op, void *op_data);
+/**
+ * \ingroup TRAV
+ *
+ * \brief Iterates through links in a group by its name
+ *
+ * \loc_id
+ * \param[in] group_name Group name
+ * \idx_type
+ * \order
+ * \param[in,out] idx iteration position at which to start (\Emph{IN}) or
+ * position at which an interrupted iteration may be restarted
+ * (\Emph{OUT})
+ * \op
+ * \op_data
+ * \lapl_id
+ *
+ * \return \success{The return value of the first operator that returns
+ * non-zero, or zero if all members were processed with no
+ * operator returning non-zero.}
+ * \return \failure{Negative if an error occurs in the library, or the negative
+ * value returned by one of the operators.}
+ *
+ * \deprecated As of HDF5-1.12 this function has been deprecated in favor of
+ * the function H5Literate_by_name2() or the macro
+ * H5Literate_by_name().
+ *
+ * \details H5Literate_by_name1() iterates through the links in a group
+ * specified by \p loc_id and \p group_name, in the order of the
+ * specified index, \p idx_type, using a user-defined callback routine
+ * \p op. H5Literate_by_name1() does not recursively follow links into
+ * subgroups of the specified group.
+ *
+ * \p idx_type specifies the index to be used. If the links have not
+ * been indexed by the index type, they will first be sorted by that
+ * index then the iteration will begin; if the links have been so
+ * indexed, the sorting step will be unnecessary, so the iteration may
+ * begin more quickly. Valid values include the following:
+ * \indexes
+ *
+ * \p order specifies the order in which objects are to be inspected
+ * along the index specified in \p idx_type. Valid values include the
+ * following:
+ * \orders
+ *
+ * \p idx allows an interrupted iteration to be resumed; it is
+ * passed in by the application with a starting point and returned by
+ * the library with the point at which the iteration stopped.
+ *
+ * \note H5Literate_by_name1() is not recursive. In particular, if a member of
+ * \p group_name is found to be a group, call it \c subgroup_a,
+ * H5Literate_by_name1() does not examine the members of \c subgroup_a.
+ * When recursive iteration is required, the application must handle the
+ * recursion, explicitly calling H5Literate_by_name1() on discovered
+ * subgroups.
+ *
+ * \note H5Literate_by_name1() assumes that the membership of the group being
+ * iterated over remains unchanged through the iteration; if any of the
+ * links in the group change during the iteration, the function’s
+ * behavior is undefined. Note, however, that objects pointed to by the
+ * links can be modified.
+ *
+ * \note H5Literate_by_name1() is the same as H5Giterate(), except that
+ * H5Giterate() always proceeds in lexicographic order.
+ *
+ * \version 1.12.0 Function H5Literate_by_name() was renamed to
+ * H5Literate_by_name1() and deprecated.
+ * \version 1.8.8 Fortran subroutine added.
+ *
+ * \since 1.8.0
+ *
+ */
H5_DLL herr_t H5Literate_by_name1(hid_t loc_id, const char *group_name, H5_index_t idx_type,
H5_iter_order_t order, hsize_t *idx, H5L_iterate1_t op, void *op_data,
hid_t lapl_id);
+/**
+ * \ingroup TRAV
+ *
+ * \brief Recursively visits all links starting from a specified group
+ *
+ * \group_id{grp_id}
+ * \idx_type
+ * \order
+ * \op
+ * \op_data
+ *
+ * \return \success{The return value of the first operator that returns
+ * non-zero, or zero if all members were processed with no
+ * operator returning non-zero.}
+ * \return \failure{Negative if an error occurs in the library, or the negative
+ * value returned by one of the operators.}
+ *
+ * \deprecated As of HDF5-1.12 this function has been deprecated in favor of
+ * the function H5Lvisit2() or the macro H5Lvisit().
+ *
+ * \details H5Lvisit1() is a recursive iteration function to visit all links in
+ * and below a group in an HDF5 file, thus providing a mechanism for
+ * an application to perform a common set of operations across all of
+ * those links or a dynamically selected subset. For non-recursive
+ * iteration across the members of a group, see H5Literate1().
+ *
+ * The group serving as the root of the iteration is specified by its
+ * group or file identifier, \p group_id.
+ *
+ * Two parameters are used to establish the iteration: \p idx_type and
+ * \p order.
+ *
+ * \p idx_type specifies the index to be used. If the links have not
+ * been indexed by the index type, they will first be sorted by that
+ * index then the iteration will begin; if the links have been so
+ * indexed, the sorting step will be unnecessary, so the iteration may
+ * begin more quickly. Valid values include the following:
+ * \indexes
+ *
+ * Note that the index type passed in \p idx_type is a best effort
+ * setting. If the application passes in a value indicating iteration
+ * in creation order and a group is encountered that was not tracked
+ * in creation order, that group will be iterated over in
+ * lexicographic order by name, or name order. (Name order is the
+ * native order used by the HDF5 library and is always available.)
+ *
+ * \p order specifies the order in which objects are to be inspected
+ * along the index specified in \p idx_type. Valid values include the
+ * following:
+ * \orders
+ *
+ * \p op is a callback function of type \ref H5L_iterate1_t that is invoked
+ * for each link encountered.
+ * \snippet this H5L_iterate1_t_snip
+ *
+ * The \ref H5L_info1_t struct is defined (in H5Lpublic.h) as follows:
+ * \snippet this H5L_info1_t_snip
+ *
+ * The possible return values from the callback function, and the
+ * effect of each, are as follows:
+ * \li Zero causes the visit iterator to continue, returning zero when
+ * all group members have been processed.
+ * \li A positive value causes the visit iterator to immediately
+ * return that positive value, indicating short-circuit success.
+ * \li A negative value causes the visit iterator to immediately
+ * return that value, indicating failure.
+ *
+ * The H5Lvisit1() \p op_data parameter is a user-defined pointer to
+ * the data required to process links in the course of the iteration.
+ * This pointer is passed back to each step of the iteration in the
+ * \p op callback function's \p op_data parameter.
+ *
+ * H5Lvisit1() and H5Ovisit1() are companion functions: one for
+ * examining and operating on links; the other for examining and
+ * operating on the objects that those links point to. Both functions
+ * ensure that by the time the function completes successfully, every
+ * link or object below the specified point in the file has been
+ * presented to the application for whatever processing the
+ * application requires.
+ *
+ * \version 1.12.0 Function was renamed from H5Lvisit() to H5Lvisit1() and
+ * deprecated.
+ *
+ * \since 1.8.0
+ *
+ */
H5_DLL herr_t H5Lvisit1(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate1_t op,
void *op_data);
+/**
+ * \ingroup TRAV
+ *
+ * \brief Recursively visits all links starting from a specified group
+ *
+ * \loc_id
+ * \param[in] group_name Group name
+ * \idx_type
+ * \order
+ * \op
+ * \op_data
+ * \lapl_id
+ *
+ * \return \success{The return value of the first operator that returns
+ * non-zero, or zero if all members were processed with no
+ * operator returning non-zero.}
+ * \return \failure{Negative if an error occurs in the library, or the negative
+ * value returned by one of the operators.}
+ *
+ * \deprecated As of HDF5-1.12 this function has been deprecated in favor of
+ * the function H5Lvisit_by_name2() or the macro H5Lvisit_by_name().
+ *
+ * \details H5Lvisit_by_name1() is a recursive iteration function to visit all
+ * links in and below a group in an HDF5 file, thus providing a
+ * mechanism for an application to perform a common set of operations
+ * across all of those links or a dynamically selected subset. For
+ * non-recursive iteration across the members of a group, see
+ * H5Literate1().
+ *
+ * The group serving as the root of the iteration is specified by the
+ * \p loc_id / \p group_name parameter pair. \p loc_id specifies a
+ * file or group; group_name specifies either a group in the file
+ * (with an absolute name based in the file’s root group) or a group
+ * relative to \p loc_id. If \p loc_id fully specifies the group that
+ * is to serve as the root of the iteration, group_name should be '.'
+ * (a dot). (Note that when \p loc_id fully specifies the the group
+ * that is to serve as the root of the iteration, the user may wish to
+ * consider using H5Lvisit1() instead of H5Lvisit_by_name1().)
+ *
+ * Two parameters are used to establish the iteration: \p idx_type and
+ * \p order.
+ *
+ * \p idx_type specifies the index to be used. If the links have not
+ * been indexed by the index type, they will first be sorted by that
+ * index then the iteration will begin; if the links have been so
+ * indexed, the sorting step will be unnecesary, so the iteration may
+ * begin more quickly. Valid values include the following:
+ * \indexes
+ *
+ * Note that the index type passed in \p idx_type is a best effort
+ * setting. If the application passes in a value indicating iteration
+ * in creation order and a group is encountered that was not tracked
+ * in creation order, that group will be iterated over in
+ * lexicographic order by name, or name order. (Name order is the
+ * native order used by the HDF5 library and is always available.)
+ *
+ * \p order specifies the order in which objects are to be inspected
+ * along the index specified in \p idx_type. Valid values include the
+ * following:
+ * \orders
+ *
+ * The \p op callback function, the related \ref H5L_info1_t
+ * \c struct, and the effect that the callback function's return value
+ * has on the application are described in H5Lvisit1().
+ *
+ * The H5Lvisit_by_name1() \p op_data parameter is a user-defined
+ * pointer to the data required to process links in the course of the
+ * iteration. This pointer is passed back to each step of the
+ * iteration in the callback function's \p op_data parameter.
+ *
+ * \p lapl_id is a link access property list. In the general case,
+ * when default link access properties are acceptable, this can be
+ * passed in as #H5P_DEFAULT. An example of a situation that requires
+ * a non-default link access property list is when the link is an
+ * external link; an external link may require that a link prefix be
+ * set in a link access property list (see H5Pset_elink_prefix()).
+ *
+ * H5Lvisit_by_name1() and H5Ovisit_by_name1() are companion
+ * functions: one for examining and operating on links; the other for
+ * examining and operating on the objects that those links point to.
+ * Both functions ensure that by the time the function completes
+ * successfully, every link or object below the specified point in the
+ * file has been presented to the application for whatever processing
+ * the application requires.
+ *
+ * \version 1.12.0 Function renamed from H5Lvisit_by_name() to
+ * H5Lvisit_by_name1() and deprecated.
+ *
+ * \since 1.8.0
+ *
+ */
H5_DLL herr_t H5Lvisit_by_name1(hid_t loc_id, const char *group_name, H5_index_t idx_type,
H5_iter_order_t order, H5L_iterate1_t op, void *op_data, hid_t lapl_id);
diff --git a/src/H5PLmodule.h b/src/H5PLmodule.h
index 8bf11ce..6e6a088 100644
--- a/src/H5PLmodule.h
+++ b/src/H5PLmodule.h
@@ -27,4 +27,9 @@
#define H5_MY_PKG_ERR H5E_PLUGIN
#define H5_MY_PKG_INIT YES
+/**\defgroup H5PL H5PL
+ * \brief Plugins
+ * \todo Describe what programmatically controlling dynamically loaded plugins (H5PL) is all about
+ */
+
#endif /* _H5PLmodule_H */
diff --git a/src/H5PLpublic.h b/src/H5PLpublic.h
index a54cce0..b345188 100644
--- a/src/H5PLpublic.h
+++ b/src/H5PLpublic.h
@@ -28,14 +28,20 @@
*/
#define H5PL_NO_PLUGIN "::"
-/* Plugin type used by the plugin library */
+//! [H5PL_type_t_snip]
+
+/**
+ * Plugin type (bit-position) used by the plugin library
+ */
typedef enum H5PL_type_t {
- H5PL_TYPE_ERROR = -1, /* Error */
- H5PL_TYPE_FILTER = 0, /* Filter */
- H5PL_TYPE_VOL = 1, /* VOL driver */
- H5PL_TYPE_NONE = 2 /* This must be last! */
+ H5PL_TYPE_ERROR = -1, /**< Error */
+ H5PL_TYPE_FILTER = 0, /**< Filter */
+ H5PL_TYPE_VOL = 1, /**< VOL driver */
+ H5PL_TYPE_NONE = 2 /**< Sentinel: This must be last! */
} H5PL_type_t;
+//! [H5PL_type_t_snip]
+
/* Common dynamic plugin type flags used by the set/get_loading_state functions */
#define H5PL_FILTER_PLUGIN 0x0001
#define H5PL_VOL_PLUGIN 0x0002
@@ -46,14 +52,174 @@ extern "C" {
#endif
/* plugin state */
+/**
+ * \ingroup H5PL
+ * \brief Controls the loadability of dynamic plugin types
+ *
+ * \param[in] plugin_control_mask The list of dynamic plugin types to enable or disable.\n
+ * A plugin bit set to 0 (zero) prevents use of that dynamic plugin.\n
+ * A plugin bit set to 1 (one) enables use of that dynamic plugin.\n
+ * Setting \p plugin_control_mask to a negative value enables all dynamic
+ * plugin types.\n
+ * Setting \p plugin_control_mask to 0 (zero) disables all dynamic plugin\n
+ * types.
+ * \return \herr_t
+ *
+ * \details H5PLset_loading_state() uses one argument to enable or disable individual plugin types.
+ *
+ * \details The \p plugin_control_mask parameter is an encoded integer in which each bit controls a specific
+ * plugin type. Bit positions allocated to date are specified in \ref H5PL_type_t as follows:
+ * \snippet this H5PL_type_t_snip
+ *
+ * A plugin bit set to 0 (zero) prevents the use of the dynamic plugin type corresponding to that bit
+ * position. A plugin bit set to 1 (one) allows the use of that dynamic plugin type.
+ *
+ * All dynamic plugin types can be enabled by setting \p plugin_control_mask to a negative value. A
+ * value of 0 (zero) will disable all dynamic plugin types.
+ *
+ * The loading of external dynamic plugins can be controlled during runtime with an environment
+ * variable, \c HDF5_PLUGIN_PRELOAD. H5PLset_loading_state() inspects the \c HDF5_PLUGIN_PRELOAD
+ * environment variable every time it is called. If the environment variable is set to the special
+ * \c :: string, all dynamic plugins are disabled.
+ *
+ * \warning The environment variable \c HDF5_PLUGIN_PRELOAD controls the loading of dynamic plugin types at
+ * runtime. If it is set to disable all plugin types, then it will disable them for \Emph{all}
+ * running programs that access the same variable instance.
+ *
+ * \since 1.8.15
+ *
+ */
H5_DLL herr_t H5PLset_loading_state(unsigned int plugin_control_mask);
+/**
+ * \ingroup H5PL
+ * \brief Queries the loadability of dynamic plugin types
+ *
+ * \param[out] plugin_control_mask List of dynamic plugin types that are enabled or disabled.\n
+ * A plugin bit set to 0 (zero) indicates that that the dynamic plugin type is
+ * disabled.\n
+ * A plugin bit set to 1 (one) indicates that that the dynamic plugin type is
+ * enabled.\n
+ * If the value of \p plugin_control_mask is negative, all dynamic plugin types
+ * are enabled.\n
+ * If the value of \p plugin_control_mask is 0 (zero), all dynamic plugins
+ * are disabled.
+ * \return \herr_t
+ *
+ * \details H5PLget_loading_state() retrieves the bitmask that controls whether a certain type of plugins
+ * (e.g.: filters, VOL drivers) will be loaded by the HDF5 library.
+ *
+ * Bit positions allocated to date are specified in \ref H5PL_type_t as follows:
+ * \snippet this H5PL_type_t_snip
+ *
+ * \since 1.8.15
+ *
+ */
H5_DLL herr_t H5PLget_loading_state(unsigned int *plugin_control_mask /*out*/);
+/**
+ * \ingroup H5PL
+ * \brief Inserts a plugin path at the end of the plugin search path list
+ *
+ * \param[in] search_path A plugin path
+ * \return \herr_t
+ *
+ * \details H5PLappend() inserts a plugin path at the end of the plugin search path list.
+ *
+ * \since 1.10.1
+ *
+ */
H5_DLL herr_t H5PLappend(const char *search_path);
+/**
+ * \ingroup H5PL
+ * \brief Inserts a plugin path at the beginning of the plugin search path list
+ *
+ * \param[in] search_path A plugin path
+ * \return \herr_t
+ *
+ * \details H5PLprepend() inserts a plugin path at the end of the plugin search path list.
+ *
+ * \since 1.10.1
+ *
+ */
H5_DLL herr_t H5PLprepend(const char *search_path);
+/**
+ * \ingroup H5PL
+ * \brief Replaces the path at the specified index in the plugin search path list
+ *
+ * \param[in] search_path A plugin path
+ * \param[in] index Index
+ * \return \herr_t
+ *
+ * \details H5PLreplace() replaces a plugin path at the specified index in the plugin search path list.
+ *
+ * \since 1.10.1
+ *
+ */
H5_DLL herr_t H5PLreplace(const char *search_path, unsigned int index);
+/**
+ * \ingroup H5PL
+ * \brief Inserts a path at the specified index in the plugin search path list
+ *
+ * \param[in] search_path A plugin path
+ * \param[in] index Index
+ * \return \herr_t
+ *
+ * \details H5PLinsert() inserts a plugin path at the specified index in the plugin search path list,
+ * moving other paths after \p index.
+ *
+ * \since 1.10.1
+ *
+ */
H5_DLL herr_t H5PLinsert(const char *search_path, unsigned int index);
+/**
+ * \ingroup H5PL
+ * \brief Removes a plugin path at a specified index from the plugin search path list
+ *
+ * \param[in] index Index
+ * \return \herr_t
+ *
+ * \details H5PLremove() removes a plugin path at the specified \p index and compacts the plugin search path
+ * list.
+ *
+ * \since 1.10.1
+ *
+ */
H5_DLL herr_t H5PLremove(unsigned int index);
+/**
+ * \ingroup H5PL
+ * \brief Queries the plugin search path list at the specified index
+ *
+ * \param[in] index Index
+ * \param[out] path_buf Pathname
+ * \param[in] buf_size Size of \p path_buf
+ * \return Returns the length of the path, a non-negative value, if successful; otherwise returns a negative
+ * value.
+ *
+ * \details H5PLget() queries the plugin path at a specified index. If \p path_buf is non-NULL then it writes
+ * up to \p buf_size bytes into that buffer and always returns the length of the path name.
+ *
+ * If \p path_buf is NULL, this function will simply return the number of characters required to
+ * store the path name, ignoring \p path_buf and \p buf_size.
+ *
+ * If an error occurs then the buffer pointed to by \p path_buf (NULL or non-NULL) is unchanged and
+ * the function returns a negative value. If a zero is returned for the name's length, then there is
+ * no path name associated with the index. and the \p path_buf buffer will be unchanged.
+ *
+ * \since 1.10.1
+ *
+ */
H5_DLL ssize_t H5PLget(unsigned int index, char *path_buf /*out*/, size_t buf_size);
+/**
+ * \ingroup H5PL
+ * \brief Retrieves the number of stored plugin paths
+ *
+ * \param[out] num_paths Current length of the plugin search path list
+ * \return \herr_t
+ *
+ * \details H5PLsize() retrieves the number of paths stored in the plugin search path list.
+ *
+ * \since 1.10.1
+ *
+ */
H5_DLL herr_t H5PLsize(unsigned int *num_paths /*out*/);
#ifdef __cplusplus
diff --git a/src/H5Pmodule.h b/src/H5Pmodule.h
index d8cc430..b9e1180 100644
--- a/src/H5Pmodule.h
+++ b/src/H5Pmodule.h
@@ -29,4 +29,47 @@
#define H5_MY_PKG_ERR H5E_PLIST
#define H5_MY_PKG_INIT YES
+/**\defgroup H5P H5P
+ * \brief Property List Interface
+ *
+ * \details The HDF5 Property List Interface provides a mechanism to take
+ * advantage of more powerful or unusual features in HDF5.
+ *
+ * HDF5 objects have properties or characteristics associated with
+ * them, and there are default properties that handle the most
+ * common needs. These default properties can be modified using the
+ * HDF5 Property List Interface. For example, the data storage
+ * layout property of a dataset is contiguous by default. For better
+ * performance, the layout can be modified to be chunked or chunked
+ * 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
+ * \defgroup GPLOA General Property List Operations (Advanced)
+ * \ingroup H5P
+ * \defgroup FCPL File Creation Properties
+ * \ingroup H5P
+ * \defgroup FAPL File Access Properties
+ * \ingroup H5P
+ * \defgroup GCPL Group Creation Properties
+ * \ingroup H5P
+ * \defgroup ALCAPL Attribute and Link Creation Properties
+ * \ingroup H5P
+ * \defgroup LAPL Link Access Properties
+ * \ingroup H5P
+ * \defgroup DCPL Dataset Creation Properties
+ * \ingroup H5P
+ * \defgroup DAPL Dataset Access Properties
+ * \ingroup H5P
+ * \defgroup DXPL Dataset Transfer Properties
+ * \ingroup H5P
+ * \defgroup OCPL Object Creation Properties
+ * \ingroup H5P
+ * \defgroup OCPPL Object Copy Properties
+ * \ingroup H5P
+ */
+
#endif /* _H5Pmodule_H */
diff --git a/src/H5Ppublic.h b/src/H5Ppublic.h
index ffcdd99..a978895 100644
--- a/src/H5Ppublic.h
+++ b/src/H5Ppublic.h
@@ -232,11 +232,153 @@ H5_DLLVAR hid_t H5P_LST_REFERENCE_ACCESS_ID_g;
/*********************/
/* Generic property list routines */
+
+/**
+ * \ingroup GPLO
+ *
+ * \brief Terminates access to a property list
+ *
+ * \plist_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Pclose() terminates access to a property list. All property
+ * lists should be closed when the application is finished
+ * accessing them. This frees resources used by the property
+ * list.
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Pclose(hid_t plist_id);
+/**
+ * \ingroup GPLO
+ *
+ * \brief Creates a new property list as an instance of a property list class
+ *
+ * \plistcls_id{cls_id}
+ *
+ * \return \hid_t{property list}
+ *
+ * \details H5Pcreate() creates a new property list as an instance of
+ * some property list class. The new property list is initialized
+ * with default values for the specified class. The classes are as
+ * follows:
+ *
+ * <table>
+ * <tr>
+ * <th>Class Identifier</th>
+ * <th>Class Name</th>
+ * <th>Comments</th>
+ * </tr>
+ * <tr>
+ * <td>#H5P_ATTRIBUTE_CREATE</td>
+ * <td>attribute create</td>
+ * <td>Properties for attribute creation</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_DATASET_ACCESS</td>
+ * <td>dataset access</td>
+ * <td>Properties for dataset access</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_DATASET_CREATE</td>
+ * <td>dataset create</td>
+ * <td>Properties for dataset creation</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_DATASET_XFER</td>
+ * <td>data transfer</td>
+ * <td>Properties for raw data transfer</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_DATATYPE_ACCESS</td>
+ * <td>datatype access</td>
+ * <td>Properties for datatype access</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_DATATYPE_CREATE</td>
+ * <td>datatype create</td>
+ * <td>Properties for datatype creation</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_FILE_ACCESS</td>
+ * <td>file access</td>
+ * <td>Properties for file access</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_FILE_CREATE</td>
+ * <td>file create</td>
+ * <td>Properties for file creation</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_FILE_MOUNT</td>
+ * <td>file mount</td>
+ * <td>Properties for file mounting</td>
+ * </tr>
+ * <tr valign="top">
+ * <td>#H5P_GROUP_ACCESS</td>
+ * <td>group access</td>
+ * <td>Properties for group access</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_GROUP_CREATE</td>
+ * <td>group create</td>
+ * <td>Properties for group creation</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_LINK_ACCESS</td>
+ * <td>link access</td>
+ * <td>Properties governing link traversal when accessing objects</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_LINK_CREATE</td>
+ * <td>link create</td>
+ * <td>Properties governing link creation</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_OBJECT_COPY</td>
+ * <td>object copy</td>
+ * <td>Properties governing the object copying process</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_OBJECT_CREATE</td>
+ * <td>object create</td>
+ * <td>Properties for object creation</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_STRING_CREATE</td>
+ * <td>string create</td>
+ * <td>Properties for character encoding when encoding strings or
+ * object names</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_VOL_INITIALIZE</td>
+ * <td>vol initialize</td>
+ * <td>Properties for VOL initialization</td>
+ * </tr>
+ * </table>
+ *
+ * This property list must eventually be closed with H5Pclose();
+ * otherwise, errors are likely to occur.
+ *
+ * \version 1.12.0 The #H5P_VOL_INITIALIZE property list class was added
+ * \version 1.8.15 For each class, the class name returned by
+ * H5Pget_class_name() was added.
+ * The list of possible Fortran values was updated.
+ * \version 1.8.0 The following property list classes were added at this
+ * release: #H5P_DATASET_ACCESS, #H5P_GROUP_CREATE,
+ * #H5P_GROUP_ACCESS, #H5P_DATATYPE_CREATE,
+ * #H5P_DATATYPE_ACCESS, #H5P_ATTRIBUTE_CREATE
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL hid_t H5Pcreate(hid_t cls_id);
H5_DLL hid_t H5Pcreate_class(hid_t parent, const char *name, H5P_cls_create_func_t cls_create,
void *create_data, H5P_cls_copy_func_t cls_copy, void *copy_data,
H5P_cls_close_func_t cls_close, void *close_data);
H5_DLL char * H5Pget_class_name(hid_t pclass_id);
-H5_DLL hid_t H5Pcreate(hid_t cls_id);
H5_DLL herr_t H5Pregister2(hid_t cls_id, const char *name, size_t size, void *def_value,
H5P_prp_create_func_t prp_create, H5P_prp_set_func_t prp_set,
H5P_prp_get_func_t prp_get, H5P_prp_delete_func_t prp_del,
@@ -262,10 +404,80 @@ H5_DLL herr_t H5Pcopy_prop(hid_t dst_id, hid_t src_id, const char *name);
H5_DLL herr_t H5Premove(hid_t plist_id, const char *name);
H5_DLL herr_t H5Punregister(hid_t pclass_id, const char *name);
H5_DLL herr_t H5Pclose_class(hid_t plist_id);
-H5_DLL herr_t H5Pclose(hid_t plist_id);
H5_DLL hid_t H5Pcopy(hid_t plist_id);
/* Object creation property list (OCPL) routines */
+
+/**
+ * \ingroup OCPL
+ *
+ * \brief Returns information about a filter in a pipeline
+ *
+ * \todo Signature for H5Pget_filter2 is different in H5Pocpl.c than in
+ * H5Ppublic.h
+ *
+ * \plist_id{plist_id}
+ * \param[in] idx Sequence number within the filter pipeline of the filter
+ * for which information is sought
+ * \param[out] flags Bit vector specifying certain general properties of the
+ * filter
+ * \param[in,out] cd_nelmts Number of elements in \p cd_values
+ * \param[out] cd_values Auxiliary data for the filter
+ * \param[in] namelen Anticipated number of characters in \p name
+ * \param[out] name Name of the filter
+ * \param[out] filter_config Bit field, as described in H5Zget_filter_info()
+ *
+ * \return Returns a negative value on failure, and the filter identifier
+ * if successful (see #H5Z_filter_t):
+ * - #H5Z_FILTER_DEFLATE Data compression filter,
+ * employing the gzip algorithm
+ * - #H5Z_FILTER_SHUFFLE Data shuffling filter
+ * - #H5Z_FILTER_FLETCHER32 Error detection filter, employing the
+ * Fletcher32 checksum algorithm
+ * - #H5Z_FILTER_SZIP Data compression filter, employing the
+ * SZIP algorithm
+ * - #H5Z_FILTER_NBIT Data compression filter, employing the
+ * N-bit algorithm
+ * - #H5Z_FILTER_SCALEOFFSET Data compression filter, employing the
+ * scale-offset algorithm
+ *
+ * \details H5Pget_filter2() returns information about a filter specified by
+ * its filter number, in a filter pipeline specified by the property
+ * list with which it is associated.
+ *
+ * \p plist_id must be a dataset or group creation property list.
+ *
+ * \p idx is a value between zero and N-1, as described in
+ * H5Pget_nfilters(). The function will return a negative value if
+ * the filter number is out of range.
+ *
+ * The structure of the \p flags argument is discussed in
+ * H5Pset_filter().
+ *
+ * On input, \p cd_nelmts indicates the number of entries in the
+ * \p cd_values array, as allocated by the caller; on return,
+ * \p cd_nelmts contains the number of values defined by the filter.
+ *
+ * If \p name is a pointer to an array of at least \p namelen bytes,
+ * the filter name will be copied into that array. The name will be
+ * null terminated if \p namelen is large enough. The filter name
+ * returned will be the name appearing in the file, the name
+ * registered for the filter, or an empty string.
+ *
+ * \p filter_config is the bit field described in
+ * H5Zget_filter_info().
+ *
+ * \version 1.8.5 Function extended to work with group creation property
+ * lists.
+ * \since 1.8.0
+ *
+ */
+H5_DLL H5Z_filter_t H5Pget_filter2(hid_t plist_id, unsigned idx,
+ unsigned int *flags/*out*/,
+ size_t *cd_nelmts/*out*/,
+ unsigned cd_values[]/*out*/,
+ size_t namelen, char name[],
+ unsigned *filter_config /*out*/);
H5_DLL herr_t H5Pset_attr_phase_change(hid_t plist_id, unsigned max_compact, unsigned min_dense);
H5_DLL herr_t H5Pget_attr_phase_change(hid_t plist_id, unsigned *max_compact, unsigned *min_dense);
H5_DLL herr_t H5Pset_attr_creation_order(hid_t plist_id, unsigned crt_order_flags);
@@ -277,9 +489,6 @@ H5_DLL herr_t H5Pmodify_filter(hid_t plist_id, H5Z_filter_t filter, unsigned int
H5_DLL herr_t H5Pset_filter(hid_t plist_id, H5Z_filter_t filter, unsigned int flags, size_t cd_nelmts,
const unsigned int c_values[]);
H5_DLL int H5Pget_nfilters(hid_t plist_id);
-H5_DLL H5Z_filter_t H5Pget_filter2(hid_t plist_id, unsigned filter, unsigned int *flags /*out*/,
- size_t *cd_nelmts /*out*/, unsigned cd_values[] /*out*/, size_t namelen,
- char name[], unsigned *filter_config /*out*/);
H5_DLL herr_t H5Pget_filter_by_id2(hid_t plist_id, H5Z_filter_t id, unsigned int *flags /*out*/,
size_t *cd_nelmts /*out*/, unsigned cd_values[] /*out*/, size_t namelen,
char name[] /*out*/, unsigned *filter_config /*out*/);
@@ -379,10 +588,592 @@ H5_DLL herr_t H5Pget_page_buffer_size(hid_t plist_id, size_t *buf_size, unsigned
unsigned *min_raw_per);
/* Dataset creation property list (DCPL) routines */
-H5_DLL herr_t H5Pset_layout(hid_t plist_id, H5D_layout_t layout);
+
+/**
+ * \ingroup DCPL
+ *
+ * \brief Retrieves the size of chunks for the raw data of a chunked
+ * layout dataset
+ *
+ * \dcpl_id{plist_id}
+ * \param[in] max_ndims Size of the \p dims array
+ * \param[out] dim Array to store the chunk dimensions
+ *
+ * \return Returns chunk dimensionality if successful;
+ * otherwise returns a negative value.
+ *
+ * \details H5Pget_chunk() retrieves the size of chunks for the raw data
+ * of a chunked layout dataset. This function is only valid for
+ * dataset creation property lists. At most, \p max_ndims elements
+ * of \p dim will be initialized.
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL int H5Pget_chunk(hid_t plist_id, int max_ndims, hsize_t dim[]/*out*/);
+/**
+ *-------------------------------------------------------------------------
+ *
+ * \ingroup DCPL
+ *
+ * \brief Retrieves the edge chunk option setting from a dataset creation
+ * property list
+ *
+ * \dcpl_id{plist_id}
+ * \param[out] opts Edge chunk option flag. Valid values are described in
+ * H5Pset_chunk_opts(). The option status can be
+ * retrieved using the bitwise AND operator ( & ). For
+ * example, the expression
+ * (opts&#H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS) will
+ * evaluate to #H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS if
+ * that option has been enabled. Otherwise, it will
+ * evaluate to 0 (zero).
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_chunk_opts() retrieves the edge chunk option setting
+ * stored in the dataset creation property list \p plist_id.
+ *
+ * \since 1.10.0
+ *
+ */
+H5_DLL herr_t H5Pget_chunk_opts(hid_t plist_id, unsigned *opts);
+/**
+ *-------------------------------------------------------------------------
+ *
+ * \ingroup DCPL
+ *
+ * \brief Retrieves the time when fill values are written to a dataset
+ *
+ * \dcpl_id{plist_id}
+ * \param[out] fill_time Setting for the timing of writing fill values to
+ * the dataset
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_fill_time() examines the dataset creation property list
+ * \p plist_id to determine when fill values are to be written to
+ * a dataset. Valid values returned in \p fill_time are as
+ * follows:
+ *
+ * <table>
+ * <tr>
+ * <td>#H5D_FILL_TIME_IFSET</td>
+ * <td>Fill values are written to the dataset when storage
+ * space is allocated only if there is a user-defined fill
+ * value, i.e., one set with H5Pset_fill_value(). (Default)
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>#H5D_FILL_TIME_ALLOC</td>
+ * <td>Fill values are written to the dataset when storage
+ * space is allocated.</td>
+ * </tr>
+ * <tr>
+ * <td>#H5D_FILL_TIME_NEVER</td>
+ * <td>Fill values are never written to the dataset.</td>
+ * </tr>
+ * </table>
+ *
+ * \note H5Pget_fill_time() is designed to work in coordination with the
+ * dataset fill value and dataset storage allocation time properties,
+ * retrieved with the functions H5Pget_fill_value() and
+ * H5Pget_alloc_time().
+ *
+ * \since 1.6.0
+ *
+ */
+H5_DLL herr_t H5Pget_fill_time(hid_t plist_id, H5D_fill_time_t
+ *fill_time/*out*/);
+/**
+ *-------------------------------------------------------------------------
+ *
+ * \ingroup DCPL
+ *
+ * \brief Retrieves a dataset fill value
+ *
+ * \dcpl_id{plist_id}
+ * \param[in] type_id Datatype identifier for the value passed via
+ * \p value
+ * \param[out] value Pointer to buffer to contain the returned
+ * fill value
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_fill_value() returns the dataset fill value defined in
+ * the dataset creation property list \p plist_id. The fill value
+ * is returned through the \p value pointer and will be converted
+ * to the datatype specified by \p type_id. This datatype may
+ * differ from the fill value datatype in the property list, but
+ * the HDF5 library must be able to convert between the two
+ * datatypes.
+ *
+ * If the fill value is undefined, i.e., set to NULL in the
+ * property list, H5Pget_fill_value() will return an error.
+ * H5Pfill_value_defined() should be used to check for this
+ * condition before H5Pget_fill_value() is called.
+ *
+ * Memory must be allocated by the calling application.
+ *
+ * \note H5Pget_fill_value() is designed to coordinate with the dataset
+ * storage allocation time and fill value write time properties,
+ * which can be retrieved with the functions H5Pget_alloc_time()
+ * and H5Pget_fill_time(), respectively.
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Pget_fill_value(hid_t plist_id, hid_t type_id,
+ void *value/*out*/);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup DCPL
+ *
+ * \brief Returns the layout of the raw data for a dataset
+ *
+ * \dcpl_id{plist_id}
+ *
+ * \return Returns the layout type (a non-negative value) of a dataset
+ * creation property list if successful. Valid return values are:
+ * - #H5D_COMPACT: Raw data is stored in the object header in the
+ * file.
+ * - #H5D_CONTIGUOUS: Raw data is stored separately from the object
+ * header in one contiguous chunk in the file.
+ * - #H5D_CHUNKED: Raw data is stored separately from the object
+ * header in chunks in separate locations in the
+ * file.
+ * - #H5D_VIRTUAL: Raw data is drawn from multiple datasets in
+ * different files.
+ * \return
+ * Otherwise, returns a negative value indicating failure.
+ *
+ * \details H5Pget_layout() returns the layout of the raw data for a
+ * dataset. This function is only valid for dataset creation
+ * property lists.
+ *
+ * Note that a compact storage layout may affect writing data to
+ * the dataset with parallel applications. See the H5Dwrite()
+ * documentation for details.
+ *
+ * \version 1.10.0 #H5D_VIRTUAL added in this release.
+ *
+ * \since 1.0.0
+ *
+ */
H5_DLL H5D_layout_t H5Pget_layout(hid_t plist_id);
-H5_DLL herr_t H5Pset_chunk(hid_t plist_id, int ndims, const hsize_t dim[/*ndims*/]);
-H5_DLL int H5Pget_chunk(hid_t plist_id, int max_ndims, hsize_t dim[] /*out*/);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup DCPL
+ *
+ * \brief Sets the size of the chunks used to store a chunked layout
+ * dataset
+ *
+ * \dcpl_id{plist_id}
+ * \param[in] ndims The number of dimensions of each chunk
+ * \param[in] dim An array defining the size, in dataset elements, of
+ * each chunk
+ *
+ * \return \herr_t
+ * \details H5Pset_chunk() sets the size of the chunks used to store a
+ * chunked layout dataset. This function is only valid for dataset
+ * creation property lists.
+ *
+ * The \p ndims parameter currently must be the same size as the
+ * rank of the dataset.
+ *
+ * The values of the \p dim array define the size of the chunks
+ * to store the dataset's raw data. The unit of measure for \p dim
+ * values is dataset elements.
+ *
+ * As a side-effect of this function, the layout of the dataset is
+ * changed to #H5D_CHUNKED, if it is not already so set.
+ *
+ * \note Chunk size cannot exceed the size of a fixed-size dataset. For
+ * example, a dataset consisting of a 5x4 fixed-size array cannot be
+ * defined with 10x10 chunks. Chunk maximums:
+ * - The maximum number of elements in a chunk is 2<sup>32</sup>-1 which
+ * is equal to 4,294,967,295. If the number of elements in a chunk is
+ * set via H5Pset_chunk() to a value greater than 2<sup>32</sup>-1,
+ * then H5Pset_chunk() will fail.
+ * - The maximum size for any chunk is 4GB. If a chunk that is larger
+ * than 4GB attempts to be written with H5Dwrite(), then H5Dwrite()
+ * will fail.
+ *
+ * \see H5Pset_layout(), H5Dwrite()
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Pset_chunk(hid_t plist_id, int ndims, const hsize_t dim[/*ndims*/]);
+/**
+ *-------------------------------------------------------------------------
+ *
+ * \ingroup DCPL
+ *
+ * \brief Sets the edge chunk option in a dataset creation property list
+ *
+ * \dcpl_id{plist_id}
+ * \param[in] opts Edge chunk option flag. Valid values are:
+ * \li #H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS
+ * When enabled, filters are not applied to partial
+ * edge chunks. When disabled, partial edge chunks are
+ * filtered. Enabling this option will improve
+ * performance when appending to the dataset and, when
+ * compression filters are used, prevent reallocation
+ * of these chunks. Datasets created with this option
+ * enabled will be inaccessible with HDF5 library
+ * versions before Release 1.10. Default: \e Disabled
+ * \li 0 (zero) Disables option; partial edge chunks
+ * will be compressed.
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_chunk_opts() sets the edge chunk option in the
+ * dataset creation property list \p dcpl_id.
+ *
+ * The available option is detailed in the parameters section.
+ * Only chunks that are not completely filled by the dataset’s
+ * dataspace are affected by this option. Such chunks are
+ * referred to as partial edge chunks.
+ *
+ * \note \b Motivation: H5Pset_chunk_opts() is used to specify storage
+ * options for chunks on the edge of a dataset’s dataspace. This
+ * capability allows the user to tune performance in cases where
+ * the dataset size may not be a multiple of the chunk size and
+ * the handling of partial edge chunks can impact performance.
+ *
+ * \since 1.10.0
+ *
+ */
+H5_DLL herr_t H5Pset_chunk_opts(hid_t plist_id, unsigned opts);
+/**
+ *-------------------------------------------------------------------------
+ *
+ * \ingroup DCPL
+ *
+ * \brief Sets the time when fill values are written to a dataset
+ *
+ * \dcpl_id{plist_id}
+ * \param[in] fill_time When to write fill values to a dataset
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_fill_time() sets up the timing for writing fill values
+ * to a dataset. This property is set in the dataset creation
+ * property list \p plist_id. Timing is specified in \p fill_time
+ * with one of the following values:
+ *
+ * <table>
+ * <tr>
+ * <td>#H5D_FILL_TIME_IFSET</td>
+ * <td>Write fill values to the dataset when storage space is
+ * allocated only if there is a user-defined fill value,
+ * i.e.,one set with H5Pset_fill_value(). (Default)</td>
+ * </tr>
+ * <tr>
+ * <td>#H5D_FILL_TIME_ALLOC</td>
+ * <td>Write fill values to the dataset when storage space is
+ * allocated.</td>
+ * </tr>
+ * <tr>
+ * <td>#H5D_FILL_TIME_NEVER</td>
+ * <td>Never write fill values to the dataset.</td>
+ * </tr>
+ * </table>
+ *
+ * \note H5Pset_fill_time() is designed for coordination with the dataset
+ * fill value and dataset storage allocation time properties, set
+ * with the functions H5Pset_fill_value() and H5Pset_alloc_time().
+ * See H5Dcreate() for further cross-references.
+ *
+ * \since 1.6.0
+ *
+ */
+H5_DLL herr_t H5Pset_fill_time(hid_t plist_id, H5D_fill_time_t fill_time);
+/**
+ *-------------------------------------------------------------------------
+ *
+ * \ingroup DCPL
+ *
+ * \brief Sets the fill value for a dataset
+ *
+ * \dcpl_id{plist_id}
+ * \param[in] type_id Datatype of \p value
+ * \param[in] value Pointer to buffer containing value to use as
+ * fill value
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_fill_value() sets the fill value for a dataset in the
+ * dataset creation property list. \p value is interpreted as
+ * being of datatype \p type_id. This datatype may differ from
+ * that of the dataset, but the HDF5 library must be able to
+ * convert \p value to the dataset datatype when the dataset is
+ * created.
+ *
+ * The default fill value is 0 (zero), which is interpreted
+ * according to the actual dataset datatype.
+ *
+ * Setting \p value to NULL indicates that the fill value is to
+ * be undefined.
+ *
+ * \note Applications sometimes write data only to portions of an allocated
+ * dataset. It is often useful in such cases to fill the unused space
+ * with a known fill value. This function allows the user application
+ * to set that fill value; the functions H5Dfill() and
+ * H5Pset_fill_time(), respectively, provide the ability to apply the
+ * fill value on demand or to set up its automatic application.
+ *
+ * \note A fill value should be defined so that it is appropriate for the
+ * application. While the HDF5 default fill value is 0 (zero), it is
+ * often appropriate to use another value. It might be useful, for
+ * example, to use a value that is known to be impossible for the
+ * application to legitimately generate.
+ *
+ * \note H5Pset_fill_value() is designed to work in concert with
+ * H5Pset_alloc_time() and H5Pset_fill_time(). H5Pset_alloc_time()
+ * and H5Pset_fill_time() govern the timing of dataset storage
+ * allocation and fill value write operations and can be important in
+ * tuning application performance.
+ *
+ * \note See H5Dcreate() for further cross-references.
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Pset_fill_value(hid_t plist_id, hid_t type_id,
+ const void *value);
+/**
+ *-------------------------------------------------------------------------
+ *
+ * \ingroup DCPL
+ *
+ * \brief Sets up use of the shuffle filter
+ *
+ * \dcpl_id{plist_id}
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_shuffle() sets the shuffle filter, #H5Z_FILTER_SHUFFLE,
+ * in the dataset creation property list \p plist_id. The shuffle
+ * filter de-interlaces a block of data by reordering the bytes.
+ * All the bytes from one consistent byte position of each data
+ * element are placed together in one block; all bytes from a
+ * second consistent byte position of each data element are placed
+ * together a second block; etc. For example, given three data
+ * elements of a 4-byte datatype stored as 012301230123, shuffling
+ * will re-order data as 000111222333. This can be a valuable step
+ * in an effective compression algorithm because the bytes in each
+ * byte position are often closely related to each other and
+ * putting them together can increase the compression ratio.
+ *
+ * As implied above, the primary value of the shuffle filter lies
+ * in its coordinated use with a compression filter; it does not
+ * provide data compression when used alone. When the shuffle
+ * filter is applied to a dataset immediately prior to the use of
+ * a compression filter, the compression ratio achieved is often
+ * superior to that achieved by the use of a compression filter
+ * without the shuffle filter.
+ *
+ * \since 1.6.0
+ *
+ */
+H5_DLL herr_t H5Pset_shuffle(hid_t plist_id);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup DCPL
+ *
+ * \brief Sets the type of storage used to store the raw data for a dataset
+ *
+ * \dcpl_id{plist_id}
+ * \param[in] layout Type of storage layout for raw data
+ *
+ * \return \herr_t
+ * \details H5Pset_layout() sets the type of storage used to store the raw
+ * data for a dataset. This function is only valid for dataset
+ * creation property lists.
+ *
+ * Valid values for \p layout are:
+ * - #H5D_COMPACT: Store raw data in the dataset object header
+ * in file. This should only be used for datasets
+ * with small amounts of raw data. The raw data
+ * size limit is 64K (65520 bytes). Attempting
+ * to create a dataset with raw data larger than
+ * this limit will cause the H5Dcreate() call to
+ * fail.
+ * - #H5D_CONTIGUOUS: Store raw data separately from the object
+ * header in one large chunk in the file.
+ * - #H5D_CHUNKED: Store raw data separately from the object header
+ * as chunks of data in separate locations in
+ * the file.
+ * - #H5D_VIRTUAL: Draw raw data from multiple datasets in
+ * different files.
+ *
+ * Note that a compact storage layout may affect writing data to
+ * the dataset with parallel applications. See the note in
+ * H5Dwrite() documentation for details.
+ * \version 1.10.0 #H5D_VIRTUAL added in this release.
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Pset_layout(hid_t plist_id, H5D_layout_t layout);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup DCPL
+ *
+ * \brief Sets up use of the SZIP compression filter
+ *
+ * \dcpl_id{plist_id}
+ * \param[in] options_mask A bit-mask conveying the desired SZIP options;
+ * Valid values are #H5_SZIP_EC_OPTION_MASK and
+ * #H5_SZIP_NN_OPTION_MASK.
+ * \param[in] pixels_per_block The number of pixels or data elements in each
+ * data block
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_szip() sets an SZIP compression filter, #H5Z_FILTER_SZIP,
+ * for a dataset. SZIP is a compression method designed for use with
+ * scientific data.
+ *
+ * Before proceeding, all users should review the “Limitations”
+ * section below.
+ *
+ * Users familiar with SZIP outside the HDF5 context may benefit
+ * from reviewing the Note “For Users Familiar with SZIP in Other
+ * Contexts” below.
+ *
+ * In the text below, the term pixel refers to an HDF5 data element.
+ * This terminology derives from SZIP compression's use with image
+ * data, where pixel referred to an image pixel.
+ *
+ * The SZIP \p bits_per_pixel value (see Note, below) is automatically
+ * set, based on the HDF5 datatype. SZIP can be used with atomic
+ * datatypes that may have size of 8, 16, 32, or 64 bits.
+ * Specifically, a dataset with a datatype that is 8-, 16-, 32-, or
+ * 64-bit signed or unsigned integer; char; or 32- or 64-bit float
+ * can be compressed with SZIP. See Note, below, for further
+ * discussion of the the SZIP \p bits_per_pixel setting.
+ *
+ * SZIP options are passed in an options mask, \p options_mask,
+ * as follows.
+ *
+ * <table>
+ * <tr>
+ * <th>Option</th>
+ * <th>Description (Mutually exclusive; select one.)</th>
+ * </tr>
+ * <tr>
+ * <td>#H5_SZIP_EC_OPTION_MASK</td>
+ * <td>Selects entropy coding method</td>
+ * </tr>
+ * <tr>
+ * <td>#H5_SZIP_NN_OPTION_MASK</td>
+ * <td>Selects nearest neighbor coding method</td>
+ * </tr>
+ * </table>
+ *
+ * The following guidelines can be used in determining which
+ * option to select:
+ *
+ * - The entropy coding method, the EC option specified by
+ * #H5_SZIP_EC_OPTION_MASK, is best suited for data that has been
+ * processed. The EC method works best for small numbers.
+ * - The nearest neighbor coding method, the NN option specified
+ * by #H5_SZIP_NN_OPTION_MASK, preprocesses the data then the
+ * applies EC method as above.
+ *
+ * Other factors may affect results, but the above criteria
+ * provides a good starting point for optimizing data compression.
+ *
+ * SZIP compresses data block by block, with a user-tunable block
+ * size. This block size is passed in the parameter
+ * \p pixels_per_block and must be even and not greater than 32,
+ * with typical values being 8, 10, 16, or 32. This parameter
+ * affects compression ratio; the more pixel values vary, the
+ * smaller this number should be to achieve better performance.
+ *
+ * In HDF5, compression can be applied only to chunked datasets.
+ * If \p pixels_per_block is bigger than the total number of
+ * elements in a dataset chunk, H5Pset_szip() will succeed but
+ * the subsequent call to H5Dcreate() will fail; the conflict
+ * can be detected only when the property list is used.
+ *
+ * To achieve optimal performance for SZIP compression, it is
+ * recommended that a chunk's fastest-changing dimension be equal
+ * to N times \p pixels_per_block where N is the maximum number of
+ * blocks per scan line allowed by the SZIP library. In the
+ * current version of SZIP, N is set to 128.
+ *
+ * SZIP compression is an optional HDF5 filter.
+ *
+ * \b Limitations:
+ *
+ * - SZIP compression cannot be applied to compound, array,
+ * variable-length, enumeration, or any other user-defined
+ * datatypes. If an SZIP filter is set in a dataset creation
+ * property list used to create a dataset containing a
+ * non-allowed datatype, the call to H5Dcreate() will fail; the
+ * conflict can be detected only when the property list is used.
+ * - Users should be aware that there are factors that affect one’s
+ * rights and ability to use SZIP compression by reviewing the
+ * SZIP copyright notice.
+ *
+ * \note \b For \b Users \b Familiar \b with \b SZIP \b in \b Other \b Contexts:
+ *
+ * \note The following notes are of interest primarily to those who have
+ * used SZIP compression outside of the HDF5 context.
+ * In non-HDF5 applications, SZIP typically requires that the user
+ * application supply additional parameters:
+ * - \p pixels_in_object, the number of pixels in the object to
+ * be compressed
+ * - \p bits_per_pixel, the number of bits per pixel
+ * - \p pixels_per_scanline, the number of pixels per scan line
+ *
+ * \note These values need not be independently supplied in the HDF5
+ * environment as they are derived from the datatype and dataspace,
+ * which are already known. In particular, HDF5 sets
+ * \p pixels_in_object to the number of elements in a chunk and
+ * \p bits_per_pixel to the size of the element or pixel datatype.
+ *
+ * \note The following algorithm is used to set \p pixels_per_scanline:
+ * - If the size of a chunk's fastest-changing dimension, size,
+ * is greater than 4K, set \p pixels_per_scanline to 128 times
+ * \p pixels_per_block.
+ * - If size is less than 4K but greater than \p pixels_per_block,
+ * set \p pixels_per_scanline to the minimum of size and 128
+ * times \p pixels_per_block.
+ * - If size is less than \p pixels_per_block but greater than the
+ * number elements in the chunk, set \p pixels_per_scanline to
+ * the minimum of the number elements in the chunk and 128 times
+ * \p pixels_per_block.
+ *
+ * \note The HDF5 datatype may have precision that is less than the full
+ * size of the data element, e.g., an 11-bit integer can be defined
+ * using H5Tset_precision(). To a certain extent, SZIP can take
+ * advantage of the precision of the datatype to improve compression:
+ * - If the HDF5 datatype size is 24-bit or less and the offset of
+ * the bits in the HDF5 datatype is zero (see H5Tset_offset() or
+ * H5Tget_offset()), the data is the in lowest N bits of the data
+ * element. In this case, the SZIP \p bits_per_pixel is set to the
+ * precision of the HDF5 datatype.
+ * - If the offset is not zero, the SZIP \p bits_per_pixel will be
+ * set to the number of bits in the full size of the data element.
+ * - If the HDF5 datatype precision is 25-bit to 32-bit, the SZIP
+ * \p bits_per_pixel will be set to 32.
+ * - If the HDF5 datatype precision is 33-bit to 64-bit, the SZIP
+ * \p bits_per_pixel will be set to 64.
+ *
+ * \note HDF5 always modifies the options mask provided by the user to set up
+ * usage of RAW_OPTION_MASK, ALLOW_K13_OPTION_MASK, and one of
+ * LSB_OPTION_MASK or MSB_OPTION_MASK, depending on endianness of the
+ * datatype.
+ *
+ * \since 1.6.0
+ *
+ *--------------------------------------------------------------------------
+ */
+H5_DLL herr_t H5Pset_szip(hid_t plist_id, unsigned options_mask, unsigned pixels_per_block);
H5_DLL herr_t H5Pset_virtual(hid_t dcpl_id, hid_t vspace_id, const char *src_file_name,
const char *src_dset_name, hid_t src_space_id);
H5_DLL herr_t H5Pget_virtual_count(hid_t dcpl_id, size_t *count /*out*/);
@@ -391,22 +1182,14 @@ H5_DLL hid_t H5Pget_virtual_srcspace(hid_t dcpl_id, size_t index);
H5_DLL ssize_t H5Pget_virtual_filename(hid_t dcpl_id, size_t index, char *name /*out*/, size_t size);
H5_DLL ssize_t H5Pget_virtual_dsetname(hid_t dcpl_id, size_t index, char *name /*out*/, size_t size);
H5_DLL herr_t H5Pset_external(hid_t plist_id, const char *name, off_t offset, hsize_t size);
-H5_DLL herr_t H5Pset_chunk_opts(hid_t plist_id, unsigned opts);
-H5_DLL herr_t H5Pget_chunk_opts(hid_t plist_id, unsigned *opts);
H5_DLL int H5Pget_external_count(hid_t plist_id);
H5_DLL herr_t H5Pget_external(hid_t plist_id, unsigned idx, size_t name_size, char *name /*out*/,
off_t *offset /*out*/, hsize_t *size /*out*/);
-H5_DLL herr_t H5Pset_szip(hid_t plist_id, unsigned options_mask, unsigned pixels_per_block);
-H5_DLL herr_t H5Pset_shuffle(hid_t plist_id);
H5_DLL herr_t H5Pset_nbit(hid_t plist_id);
H5_DLL herr_t H5Pset_scaleoffset(hid_t plist_id, H5Z_SO_scale_type_t scale_type, int scale_factor);
-H5_DLL herr_t H5Pset_fill_value(hid_t plist_id, hid_t type_id, const void *value);
-H5_DLL herr_t H5Pget_fill_value(hid_t plist_id, hid_t type_id, void *value /*out*/);
H5_DLL herr_t H5Pfill_value_defined(hid_t plist, H5D_fill_value_t *status);
H5_DLL herr_t H5Pset_alloc_time(hid_t plist_id, H5D_alloc_time_t alloc_time);
H5_DLL herr_t H5Pget_alloc_time(hid_t plist_id, H5D_alloc_time_t *alloc_time /*out*/);
-H5_DLL herr_t H5Pset_fill_time(hid_t plist_id, H5D_fill_time_t fill_time);
-H5_DLL herr_t H5Pget_fill_time(hid_t plist_id, H5D_fill_time_t *fill_time /*out*/);
H5_DLL herr_t H5Pget_dset_no_attrs_hint(hid_t dcpl_id, hbool_t *minimize);
H5_DLL herr_t H5Pset_dset_no_attrs_hint(hid_t dcpl_id, hbool_t minimize);
@@ -526,6 +1309,59 @@ H5_DLL herr_t H5Pinsert1(hid_t plist_id, const char *name, size_t size, vo
H5P_prp_delete_func_t prp_delete, H5P_prp_copy_func_t prp_copy,
H5P_prp_close_func_t prp_close);
H5_DLL herr_t H5Pencode1(hid_t plist_id, void *buf, size_t *nalloc);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup OCPL
+ *
+ * \brief Returns information about a filter in a pipeline (DEPRECATED)
+ *
+ * \todo H5Pget_filter1() prototype does not match source in H5Pocpl.c.
+ * Also, it is not in a deprecated file. Is that okay?
+ *
+ * \plist_id{plist_id}
+ * \param[in] filter Sequence number within the filter pipeline of the filter
+ * for which information is sought
+ * \param[out] flags Bit vector specifying certain general properties of
+ * the filter
+ * \param[in,out] cd_nelmts Number of elements in \p cd_values
+ * \param[out] cd_values Auxiliary data for the filter
+ * \param[in] namelen Anticipated number of characters in \p name
+ * \param[out] name Name of the filter
+ *
+ * \return Returns the filter identifier if successful; Otherwise returns
+ * a negative value. See: #H5Z_filter_t
+ *
+ * \details H5Pget_filter1() returns information about a filter, specified
+ * by its filter number, in a filter pipeline, specified by the
+ * property list with which it is associated.
+ *
+ * \p plist_id must be a dataset or group creation property list.
+ *
+ * \p filter is a value between zero and N-1, as described in
+ * H5Pget_nfilters(). The function will return a negative value
+ * if the filter number is out of range.
+ *
+ * The structure of the \p flags argument is discussed in
+ * H5Pset_filter().
+ *
+ * On input, \p cd_nelmts indicates the number of entries in the
+ * \p cd_values array, as allocated by the caller; on return,
+ * \p cd_nelmts contains the number of values defined by the filter.
+ *
+ * If \p name is a pointer to an array of at least \p namelen
+ * bytes, the filter name will be copied into that array. The name
+ * will be null terminated if \p namelen is large enough. The
+ * filter name returned will be the name appearing in the file, the
+ * name registered for the filter, or an empty string.
+ *
+ * \version 1.8.5 Function extended to work with group creation property
+ * lists.
+ * \version 1.8.0 N-bit and scale-offset filters added.
+ * \version 1.8.0 Function H5Pget_filter() renamed to H5Pget_filter1() and
+ * deprecated in this release.
+ * \version 1.6.4 \p filter parameter type changed to unsigned.
+ *
+ */
H5_DLL H5Z_filter_t H5Pget_filter1(hid_t plist_id, unsigned filter, unsigned int *flags /*out*/,
size_t *cd_nelmts /*out*/, unsigned cd_values[] /*out*/, size_t namelen,
char name[]);
diff --git a/src/H5Smodule.h b/src/H5Smodule.h
index 11494ee..6e8208b 100644
--- a/src/H5Smodule.h
+++ b/src/H5Smodule.h
@@ -29,4 +29,31 @@
#define H5_MY_PKG_ERR H5E_DATASPACE
#define H5_MY_PKG_INIT YES
+/**\defgroup H5S H5S
+ * \brief Dataspace Interface
+ *
+ * \details The Dataspace Interface provides functions for creating and
+ * working with dataspaces.
+ *
+ * A dataspace has two roles:
+ *
+ * \li It contains the spatial information (logical layout) of a
+ * dataset stored in a file.
+ * \li It describes an application’s data buffers and data elements
+ * participating in I/O. In other words, it can be used to
+ * select a portion or subset of a dataset.
+ *
+ * The spatial information of a dataset in a file includes the
+ * rank and dimensions of the dataset, which are a permanent part
+ * of the dataset definition. It can have dimensions that are fixed
+ * (unchanging) or unlimited, which means they can grow in size
+ * (or are extendible).
+ *
+ * A dataspace can consist of:
+ * \li no elements (NULL)
+ * \li a single element (scalar), or
+ * \li a simple array.
+ *
+ */
+
#endif /* _H5Smodule_H */
diff --git a/src/H5Spublic.h b/src/H5Spublic.h
index f0aa6dc..c16af93 100644
--- a/src/H5Spublic.h
+++ b/src/H5Spublic.h
@@ -120,17 +120,288 @@ typedef enum {
extern "C" {
#endif
-/* Operations on dataspaces */
+/* Operations on dataspaces and dataspace selections */
+
+/**
+ * \ingroup H5S
+ *
+ * \brief Releases and terminates access to a dataspace
+ *
+ * \space_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Sclose() releases a dataspace. Further access through the
+ * dataspace identifier is illegal. Failure to release a dataspace with this
+ * call will result in resource leaks.
+ *
+ * \version 1.4.0 Fortran subroutine introduced in this release.
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Sclose(hid_t space_id);
+/**
+ * \ingroup H5S
+ *
+ * \brief Creates a new dataspace of a specified type
+ *
+ * \param[in] type Type of dataspace to be created
+ *
+ * \return \hid_t{dataspace}
+ *
+ * \details H5Screate() creates a new dataspace of a particular type. Currently
+ * supported types are #H5S_SCALAR, #H5S_SIMPLE, and #H5S_NULL.
+ *
+ * Further dataspace types may be added later.
+ *
+ * A scalar dataspace, #H5S_SCALAR, has a single element, though that
+ * element may be of a complex datatype, such as a compound or array
+ * datatype. By convention, the rank of a scalar dataspace is always \p 0
+ * (zero); think of it geometrically as a single, dimensionless point,
+ * though that point can be complex.
+ *
+ * A simple dataspace, #H5S_SIMPLE, consists of a regular array of elements.
+ *
+ * A null dataspace, #H5S_NULL, has no data elements.
+ *
+ * The dataspace identifier returned by this function can be released with
+ * H5Sclose() so that resource leaks will not occur.
+ *
+ * \version 1.4.0 Fortran subroutine introduced.
+ * \since 1.0.0
+ *
+ */
H5_DLL hid_t H5Screate(H5S_class_t type);
+/**
+ * \ingroup H5S
+ * \brief Creates a new simple dataspace and opens it for access
+ *
+ * \param[in] rank Number of dimensions of dataspace
+ * \param[in] dims Array specifying the size of each dimension
+ * \param[in] maxdims Array specifying the maximum size of each dimension
+ *
+ * \return \hid_t{dataspace}
+ *
+ * \details H5Screate_simple() creates a new simple dataspace and opens it
+ * for access, returning a dataspace identifier.
+ *
+ * \p rank is the number of dimensions used in the dataspace.
+ *
+ * \p dims is a one-dimensional array of size rank specifying the
+ * size of each dimension of the dataset. \p maxdims is an array of the
+ * same size specifying the upper limit on the size of each dimension.
+ *
+ * Any element of \p dims can be \p 0 (zero). Note that no data can
+ * be written to a dataset if the size of any dimension of its current
+ * dataspace is \p 0. This is sometimes a useful initial state for a dataset.
+ *
+ * \p maxdims may be the null pointer, in which case the upper limit is
+ * the same as \p dims. Otherwise, no element of \p maxdims
+ * should be smaller than the corresponding element of \p dims.
+ *
+ * If an element of \p maxdims is #H5S_UNLIMITED, the maximum size of the
+ * corresponding dimension is unlimited.
+ *
+ * Any dataset with an unlimited dimension must also be chunked; see
+ * H5Pset_chunk(). Similarly, a dataset must be chunked if \p dims does
+ * not equal \p maxdims.
+ *
+ * The dataspace identifier returned from this function must be released with
+ * H5Sclose() or resource leaks will occur.
+ *
+ * \note Once a dataspace has been created, specific regions or elements in
+ * the dataspace can be selected and selections can be removed, as well.
+ * For example, H5Sselect_hyperslab() selects a region in a dataspace and
+ * H5Sselect_elements() selects array elements in a dataspace. These
+ * functions are used for subsetting. H5Sselect_none() removes all
+ * selections from a dataspace and is used in Parallel HDF5 when a process
+ * does not have or need to write data.
+ *
+ * \version 1.4.0 Fortran subroutine introduced.
+ *
+ * \since 1.0.0
+ *
+ */
H5_DLL hid_t H5Screate_simple(int rank, const hsize_t dims[], const hsize_t maxdims[]);
+/*--------------------------------------------------------------------------*/
+/**\ingroup H5S
+ *
+ * \brief Determines the number of elements in a dataspace selection
+ *
+ * \space_id{spaceid}
+ *
+ * \return Returns the number of elements in the selection if successful;
+ * otherwise returns a negative value.
+ *
+ * \details H5Sget_select_npoints() determines the number of elements in
+ * the current selection of a dataspace. It works with any
+ * selection type, and is the correct way to retrieve the number
+ * of elements in a selection.
+ *
+ * \version 1.4.0 Fortran subroutine introduced in this release.
+ * \since 1.0.0
+ *
+ */
+H5_DLL hssize_t H5Sget_select_npoints(hid_t spaceid);
+/*-------------------------------------------------------------------------*/
+/**\ingroup H5S
+ *
+ * \brief Retrieves dataspace dimension size and maximum size
+ *
+ * \space_id
+ * \param[out] dims Pointer to array to store the size of each dimension
+ * \param[out] maxdims Pointer to array to store the maximum size of each
+ * dimension
+ *
+ * \return Returns the number of dimensions in the dataspace if successful;
+ * otherwise returns a negative value.
+ *
+ * \details H5Sget_simple_extent_dims() returns the size and maximum sizes
+ * of each dimension of a dataspace \p space_id through the \p dims
+ * and \p maxdims parameters.
+ *
+ * Either or both of \p dims and \p maxdims may be NULL.
+ *
+ * If a value in the returned array \p maxdims is #H5S_UNLIMITED (-1),
+ * the maximum size of that dimension is unlimited.
+ *
+ * \version 1.4.0 Fortran subroutine introduced.
+ * \since 1.0.0
+ *
+ */
+H5_DLL int H5Sget_simple_extent_dims(hid_t space_id, hsize_t dims[],
+ hsize_t maxdims[]);
+/*-------------------------------------------------------------------------*/
+/**\ingroup H5S
+ *
+ * \brief Determines the dimensionality of a dataspace
+ *
+ * \space_id
+ *
+ * \return Returns the number of dimensions in the dataspace if successful;
+ * otherwise returns a negative value.
+ *
+ * \details H5Sget_simple_extent_ndims() determines the dimensionality (or
+ * rank) of a dataspace.
+ *
+ * \version 1.4.0 Fortran subroutine introduced.
+ * \since 1.0.0
+ *
+ */
+H5_DLL int H5Sget_simple_extent_ndims(hid_t space_id);
+/*--------------------------------------------------------------------------*/
+/**\ingroup H5S
+ *
+ * \brief Selects a hyperslab region to add to the current selected region
+ *
+ * \space_id
+ * \param[in] op Operation to perform on current selection
+ * \param[in] start Offset of start of hyperslab
+ * \param[in] stride Hyperslab stride
+ * \param[in] count Number of blocks included in hyperslab
+ * \param[in] block Size of block in hyperslab
+ *
+ * \return \herr_t
+ *
+ * \details H5Sselect_hyperslab() selects a hyperslab region to add to the
+ * current selected region for the dataspace specified by
+ * \p space_id.
+ *
+ * The \p start, \p stride, \p count, and \p block arrays must be the
+ * same size as the rank of the dataspace. For example, if the
+ * dataspace is 4-dimensional, each of these parameters must be a
+ * 1-dimensional array of size 4.
+ *
+ * The selection operator \p op determines how the new selection
+ * is to be combined with the already existing selection for the
+ * dataspace. The following operators are supported:
+ *
+ * <table>
+ * <tr>
+ * <td>#H5S_SELECT_SET</td>
+ * <td>Replaces the existing selection with the
+ * parameters from this call. Overlapping blocks
+ * are not supported with this operator.</td>
+ * </tr>
+ * <tr>
+ * <td>#H5S_SELECT_OR</td>
+ * <td>Adds the new selection to the existing selection.
+ * (Binary OR)</td>
+ * </tr>
+ * <tr>
+ * <td>#H5S_SELECT_AND</td>
+ * <td>Retains only the overlapping portions of the
+ * new selection and the existing selection.
+ * (Binary AND)</td>
+ * </tr>
+ * <tr>
+ * <td>#H5S_SELECT_XOR</td>
+ * <td>Retains only the elements that are members of
+ * the new selection or the existing selection,
+ * excluding elements that are members of both
+ * selections. (Binary exclusive-OR, XOR)
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>#H5S_SELECT_NOTB</td>
+ * <td>Retains only elements of the existing selection
+ * that are not in the new selection.</td>
+ * </tr>
+ * <tr>
+ * <td>#H5S_SELECT_NOTA</td>
+ * <td>Retains only elements of the new selection that
+ * are not in the existing selection.</td>
+ * </tr>
+ * </table>
+ *
+ * The \p start array specifies the offset of the starting element
+ * of the specified hyperslab.
+ *
+ * The \p stride array chooses array locations from the dataspace with
+ * each value in the \p stride array determining how many elements to
+ * move in each dimension. Setting a value in the \p stride array to
+ * \p 1 moves to each element in that dimension of the dataspace;
+ * setting a value of \p 2 in allocation in the \p stride array moves
+ * to every other element in that dimension of the dataspace. In
+ * other words, the \p stride determines the number of elements to
+ * move from the \p start location in each dimension. Stride values
+ * of \p 0 are not allowed. If the \p stride parameter is NULL, a
+ * contiguous hyperslab is selected (as if each value in the \p stride
+ * array were set to \p 1).
+ *
+ * The \p count array determines how many blocks to select from the
+ * dataspace, in each dimension.
+ *
+ * The \p block array determines the size of the element block
+ * selected from the dataspace. If the \p block parameter is set to
+ * NULL, the block size defaults to a single element in each dimension
+ * (as if each value in the \p block array were set to \p 1).
+ *
+ * For example, consider a 2-dimensional dataspace with hyperslab
+ * selection settings as follows: the \p start offset is specified as
+ * [1,1], \p stride is [4,4], \p count is [3,7], and \p block is [2,2].
+ * In C, these settings will specify a hyperslab consisting of 21
+ * 2x2 blocks of array elements starting with location (1,1) with the
+ * selected blocks at locations (1,1), (5,1), (9,1), (1,5), (5,5), etc.;
+ * in Fortran, they will specify a hyperslab consisting of 21 2x2
+ * blocks of array elements starting with location (2,2) with the
+ * selected blocks at locations (2,2), (6,2), (10,2), (2,6), (6,6), etc.
+ *
+ * Regions selected with this function call default to C order
+ * iteration when I/O is performed.
+ *
+ * \version 1.4.0 Fortran subroutine introduced in this release.
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Sselect_hyperslab(hid_t space_id, H5S_seloper_t op,
+ const hsize_t start[], const hsize_t stride[], const hsize_t count[],
+ const hsize_t block[]);
H5_DLL herr_t H5Sset_extent_simple(hid_t space_id, int rank, const hsize_t dims[], const hsize_t max[]);
H5_DLL hid_t H5Scopy(hid_t space_id);
-H5_DLL herr_t H5Sclose(hid_t space_id);
H5_DLL herr_t H5Sencode2(hid_t obj_id, void *buf, size_t *nalloc, hid_t fapl);
H5_DLL hid_t H5Sdecode(const void *buf);
H5_DLL hssize_t H5Sget_simple_extent_npoints(hid_t space_id);
-H5_DLL int H5Sget_simple_extent_ndims(hid_t space_id);
-H5_DLL int H5Sget_simple_extent_dims(hid_t space_id, hsize_t dims[], hsize_t maxdims[]);
H5_DLL htri_t H5Sis_simple(hid_t space_id);
H5_DLL H5S_class_t H5Sget_simple_extent_type(hid_t space_id);
H5_DLL herr_t H5Sset_extent_none(hid_t space_id);
@@ -139,7 +410,6 @@ H5_DLL htri_t H5Sextent_equal(hid_t sid1, hid_t sid2);
/* Operations on dataspace selections */
H5_DLL H5S_sel_type H5Sget_select_type(hid_t spaceid);
-H5_DLL hssize_t H5Sget_select_npoints(hid_t spaceid);
H5_DLL herr_t H5Sselect_copy(hid_t dst_id, hid_t src_id);
H5_DLL htri_t H5Sselect_valid(hid_t spaceid);
H5_DLL herr_t H5Sselect_adjust(hid_t spaceid, const hssize_t *offset);
@@ -153,8 +423,6 @@ H5_DLL herr_t H5Sselect_elements(hid_t space_id, H5S_seloper_t op, size_t num_
H5_DLL hssize_t H5Sget_select_elem_npoints(hid_t spaceid);
H5_DLL herr_t H5Sget_select_elem_pointlist(hid_t spaceid, hsize_t startpoint, hsize_t numpoints,
hsize_t buf[/*numpoints*/]);
-H5_DLL herr_t H5Sselect_hyperslab(hid_t space_id, H5S_seloper_t op, const hsize_t start[],
- const hsize_t _stride[], const hsize_t count[], const hsize_t _block[]);
H5_DLL hid_t H5Scombine_hyperslab(hid_t space_id, H5S_seloper_t op, const hsize_t start[],
const hsize_t _stride[], const hsize_t count[], const hsize_t _block[]);
H5_DLL herr_t H5Smodify_select(hid_t space1_id, H5S_seloper_t op, hid_t space2_id);
diff --git a/src/H5Tmodule.h b/src/H5Tmodule.h
index b508dfd..fd545c2 100644
--- a/src/H5Tmodule.h
+++ b/src/H5Tmodule.h
@@ -29,4 +29,80 @@
#define H5_MY_PKG_ERR H5E_DATATYPE
#define H5_MY_PKG_INIT YES
+/**
+ * \defgroup H5T H5T
+ * \brief Datatype Interface
+ * \todo Describe concisely what the functions in this module are about.
+ *
+ * \defgroup ARRAY Array Datatypes
+ * \ingroup H5T
+ * \defgroup ATOM Atomic Datatypes
+ * \ingroup H5T
+ * \defgroup COMPOUND Compound Datatypes
+ * \ingroup H5T
+ * \defgroup CONV Conversion Function
+ * \ingroup H5T
+ * \defgroup ENUM Enumeration Datatypes
+ * \ingroup H5T
+ * \defgroup GTO General Datatype Operations
+ * \ingroup H5T
+ * \defgroup OPAQUE Opaque Datatypes
+ * \ingroup H5T
+ * \defgroup STRING String Datatypes
+ * \ingroup H5T
+ * \defgroup VLEN Variable-length Sequence Datatypes
+ * \ingroup H5T
+ *
+ * \defgroup PDT Predefined Datatypes
+ * \ingroup H5T
+ * \details What is a predefined HDF5 datatype?
+ * \todo Fill in the blanks!
+ *
+ * \defgroup PDTCPU By CPU
+ * \ingroup PDT
+ * \details CPU-specific datatypes
+ * \defgroup PDTALPHA DEC Alpha
+ * \ingroup PDTCPU
+ * \defgroup PDTX86 AMD & INTEL
+ * \ingroup PDTCPU
+ * \defgroup PDTMIPS SGI MIPS
+ * \ingroup PDTCPU
+ *
+ * \defgroup PDTIEEE IEEE
+ * \ingroup PDT
+ * \details The IEEE floating point types in big- and little-endian byte orders.
+ *
+ * \defgroup PDTSTD Standard Datatypes
+ * \ingroup PDT
+ * \details These are "standard" types. For instance, signed (2's complement)
+ * and unsigned integers of various sizes in big- and little-endian
+ * byte orders.
+ *
+ * \defgroup PDTUNIX UNIX-specific Datatypes
+ * \ingroup PDT
+ * \details Types which are particular to Unix.
+ * \todo Fill in the blanks!
+ *
+ * \defgroup PDTNAT Native Datatypes
+ * \ingroup PDT
+ * \details These are the datatypes detected during library \Emph{compilation}
+ * by \c H5detect(). Their names differ from other HDF5 datatype names
+ * as follows:
+ * \li Instead of a class name, precision and byte order as the last
+ * component, they have a C-like type name.
+ * \li If the type begins with \c U then it is the unsigned version of
+ * the integer type; other integer types are signed.
+ * \li The datatype \c LLONG corresponds C's \Code{long long} and
+ * \c LDOUBLE is \Code{long double}. These types might be the same
+ * as \c LONG and \c DOUBLE, respectively.
+ * \defgroup PDTC9x C9x Integer Datatypes
+ * \ingroup PDTNAT
+ * \details C9x integer types
+ * \todo Fill in the blanks!
+ *
+ * \defgroup PDTS Strings
+ * \ingroup PDT
+ *
+ */
+
#endif /* _H5Tmodule_H */
diff --git a/src/H5Tpublic.h b/src/H5Tpublic.h
index 73a00b6..8bebb98 100644
--- a/src/H5Tpublic.h
+++ b/src/H5Tpublic.h
@@ -23,197 +23,249 @@
#define HOFFSET(S, M) (offsetof(S, M))
-/* These are the various classes of datatypes */
-/* If this goes over 16 types (0-15), the file format will need to change) */
+/**
+ * These are the various classes of datatypes
+ * internal If this goes over 16 types (0-15), the file format will need to
+ * change.
+ */
+//! [H5T_class_t_snip]
typedef enum H5T_class_t {
- H5T_NO_CLASS = -1, /*error */
- H5T_INTEGER = 0, /*integer types */
- H5T_FLOAT = 1, /*floating-point types */
- H5T_TIME = 2, /*date and time types */
- H5T_STRING = 3, /*character string types */
- H5T_BITFIELD = 4, /*bit field types */
- H5T_OPAQUE = 5, /*opaque types */
- H5T_COMPOUND = 6, /*compound types */
- H5T_REFERENCE = 7, /*reference types */
- H5T_ENUM = 8, /*enumeration types */
- H5T_VLEN = 9, /*Variable-Length types */
- H5T_ARRAY = 10, /*Array types */
-
- H5T_NCLASSES /*this must be last */
+ H5T_NO_CLASS = -1, /**< error */
+ H5T_INTEGER = 0, /**< integer types */
+ H5T_FLOAT = 1, /**< floating-point types */
+ H5T_TIME = 2, /**< date and time types */
+ H5T_STRING = 3, /**< character string types */
+ H5T_BITFIELD = 4, /**< bit field types */
+ H5T_OPAQUE = 5, /**< opaque types */
+ H5T_COMPOUND = 6, /**< compound types */
+ H5T_REFERENCE = 7, /**< reference types */
+ H5T_ENUM = 8, /**< enumeration types */
+ H5T_VLEN = 9, /**< variable-Length types */
+ H5T_ARRAY = 10, /**< array types */
+
+ H5T_NCLASSES /**< sentinel: this must be last */
} H5T_class_t;
+//! [H5T_class_t_snip]
-/* Byte orders */
+/**
+ * Byte orders
+ */
+//! [H5T_order_t_snip]
typedef enum H5T_order_t {
- H5T_ORDER_ERROR = -1, /*error */
- H5T_ORDER_LE = 0, /*little endian */
- H5T_ORDER_BE = 1, /*bit endian */
- H5T_ORDER_VAX = 2, /*VAX mixed endian */
- H5T_ORDER_MIXED = 3, /*Compound type with mixed member orders */
- H5T_ORDER_NONE = 4 /*no particular order (strings, bits,..) */
+ H5T_ORDER_ERROR = -1, /**< error */
+ H5T_ORDER_LE = 0, /**< little endian */
+ H5T_ORDER_BE = 1, /**< bit endian */
+ H5T_ORDER_VAX = 2, /**< VAX mixed endian */
+ H5T_ORDER_MIXED = 3, /**< Compound type with mixed member orders */
+ H5T_ORDER_NONE = 4 /**< no particular order (strings, bits,..) */
/*H5T_ORDER_NONE must be last */
} H5T_order_t;
+//! [H5T_order_t_snip]
-/* Types of integer sign schemes */
+/**
+ * Types of integer sign schemes
+ */
+//! [H5T_sign_t_snip]
typedef enum H5T_sign_t {
- H5T_SGN_ERROR = -1, /*error */
- H5T_SGN_NONE = 0, /*this is an unsigned type */
- H5T_SGN_2 = 1, /*two's complement */
+ H5T_SGN_ERROR = -1, /**< error */
+ H5T_SGN_NONE = 0, /**< this is an unsigned type */
+ H5T_SGN_2 = 1, /**< two's complement */
- H5T_NSGN = 2 /*this must be last! */
+ H5T_NSGN = 2 /** sentinel: this must be last! */
} H5T_sign_t;
+//! [H5T_sign_t_snip]
-/* Floating-point normalization schemes */
+/**
+ * Floating-point normalization schemes
+ */
+//! [H5T_norm_t_snip]
typedef enum H5T_norm_t {
- H5T_NORM_ERROR = -1, /*error */
- H5T_NORM_IMPLIED = 0, /*msb of mantissa isn't stored, always 1 */
- H5T_NORM_MSBSET = 1, /*msb of mantissa is always 1 */
- H5T_NORM_NONE = 2 /*not normalized */
+ H5T_NORM_ERROR = -1, /**< error */
+ H5T_NORM_IMPLIED = 0, /**< msb of mantissa isn't stored, always 1 */
+ H5T_NORM_MSBSET = 1, /**< msb of mantissa is always 1 */
+ H5T_NORM_NONE = 2 /**< not normalized */
/*H5T_NORM_NONE must be last */
} H5T_norm_t;
+//! [H5T_norm_t_snip]
-/*
- * Character set to use for text strings. Do not change these values since
- * they appear in HDF5 files!
+/**
+ * Character set to use for text strings.
+ * \internal Do not change these values since they appear in HDF5 files!
*/
typedef enum H5T_cset_t {
- H5T_CSET_ERROR = -1, /*error */
- H5T_CSET_ASCII = 0, /*US ASCII */
- H5T_CSET_UTF8 = 1, /*UTF-8 Unicode encoding */
- H5T_CSET_RESERVED_2 = 2, /*reserved for later use */
- H5T_CSET_RESERVED_3 = 3, /*reserved for later use */
- H5T_CSET_RESERVED_4 = 4, /*reserved for later use */
- H5T_CSET_RESERVED_5 = 5, /*reserved for later use */
- H5T_CSET_RESERVED_6 = 6, /*reserved for later use */
- H5T_CSET_RESERVED_7 = 7, /*reserved for later use */
- H5T_CSET_RESERVED_8 = 8, /*reserved for later use */
- H5T_CSET_RESERVED_9 = 9, /*reserved for later use */
- H5T_CSET_RESERVED_10 = 10, /*reserved for later use */
- H5T_CSET_RESERVED_11 = 11, /*reserved for later use */
- H5T_CSET_RESERVED_12 = 12, /*reserved for later use */
- H5T_CSET_RESERVED_13 = 13, /*reserved for later use */
- H5T_CSET_RESERVED_14 = 14, /*reserved for later use */
- H5T_CSET_RESERVED_15 = 15 /*reserved for later use */
+ H5T_CSET_ERROR = -1, /**< error */
+ H5T_CSET_ASCII = 0, /**< US ASCII */
+ H5T_CSET_UTF8 = 1, /**< UTF-8 Unicode encoding */
+ H5T_CSET_RESERVED_2 = 2, /**< reserved for later use */
+ H5T_CSET_RESERVED_3 = 3, /**< reserved for later use */
+ H5T_CSET_RESERVED_4 = 4, /**< reserved for later use */
+ H5T_CSET_RESERVED_5 = 5, /**< reserved for later use */
+ H5T_CSET_RESERVED_6 = 6, /**< reserved for later use */
+ H5T_CSET_RESERVED_7 = 7, /**< reserved for later use */
+ H5T_CSET_RESERVED_8 = 8, /**< reserved for later use */
+ H5T_CSET_RESERVED_9 = 9, /**< reserved for later use */
+ H5T_CSET_RESERVED_10 = 10, /**< reserved for later use */
+ H5T_CSET_RESERVED_11 = 11, /**< reserved for later use */
+ H5T_CSET_RESERVED_12 = 12, /**< reserved for later use */
+ H5T_CSET_RESERVED_13 = 13, /**< reserved for later use */
+ H5T_CSET_RESERVED_14 = 14, /**< reserved for later use */
+ H5T_CSET_RESERVED_15 = 15 /**< reserved for later use */
} H5T_cset_t;
-#define H5T_NCSET H5T_CSET_RESERVED_2 /*Number of character sets actually defined */
+#define H5T_NCSET H5T_CSET_RESERVED_2 /*Number of character sets actually defined */
-/*
- * Type of padding to use in character strings. Do not change these values
- * since they appear in HDF5 files!
+/**
+ * Type of padding to use in character strings.
+ * \internal Do not change these values since they appear in HDF5 files!
*/
typedef enum H5T_str_t {
- H5T_STR_ERROR = -1, /*error */
- H5T_STR_NULLTERM = 0, /*null terminate like in C */
- H5T_STR_NULLPAD = 1, /*pad with nulls */
- H5T_STR_SPACEPAD = 2, /*pad with spaces like in Fortran */
- H5T_STR_RESERVED_3 = 3, /*reserved for later use */
- H5T_STR_RESERVED_4 = 4, /*reserved for later use */
- H5T_STR_RESERVED_5 = 5, /*reserved for later use */
- H5T_STR_RESERVED_6 = 6, /*reserved for later use */
- H5T_STR_RESERVED_7 = 7, /*reserved for later use */
- H5T_STR_RESERVED_8 = 8, /*reserved for later use */
- H5T_STR_RESERVED_9 = 9, /*reserved for later use */
- H5T_STR_RESERVED_10 = 10, /*reserved for later use */
- H5T_STR_RESERVED_11 = 11, /*reserved for later use */
- H5T_STR_RESERVED_12 = 12, /*reserved for later use */
- H5T_STR_RESERVED_13 = 13, /*reserved for later use */
- H5T_STR_RESERVED_14 = 14, /*reserved for later use */
- H5T_STR_RESERVED_15 = 15 /*reserved for later use */
+ H5T_STR_ERROR = -1, /**< error */
+ H5T_STR_NULLTERM = 0, /**< null terminate like in C */
+ H5T_STR_NULLPAD = 1, /**< pad with nulls */
+ H5T_STR_SPACEPAD = 2, /**< pad with spaces like in Fortran */
+ H5T_STR_RESERVED_3 = 3, /**< reserved for later use */
+ H5T_STR_RESERVED_4 = 4, /**< reserved for later use */
+ H5T_STR_RESERVED_5 = 5, /**< reserved for later use */
+ H5T_STR_RESERVED_6 = 6, /**< reserved for later use */
+ H5T_STR_RESERVED_7 = 7, /**< reserved for later use */
+ H5T_STR_RESERVED_8 = 8, /**< reserved for later use */
+ H5T_STR_RESERVED_9 = 9, /**< reserved for later use */
+ H5T_STR_RESERVED_10 = 10, /**< reserved for later use */
+ H5T_STR_RESERVED_11 = 11, /**< reserved for later use */
+ H5T_STR_RESERVED_12 = 12, /**< reserved for later use */
+ H5T_STR_RESERVED_13 = 13, /**< reserved for later use */
+ H5T_STR_RESERVED_14 = 14, /**< reserved for later use */
+ H5T_STR_RESERVED_15 = 15 /**< reserved for later use */
} H5T_str_t;
-#define H5T_NSTR H5T_STR_RESERVED_3 /*num H5T_str_t types actually defined */
+#define H5T_NSTR H5T_STR_RESERVED_3 /*num H5T_str_t types actually defined */
-/* Type of padding to use in other atomic types */
+/**
+ * Type of padding to use in other atomic types
+ */
+//! [H5T_pad_t_snip]
typedef enum H5T_pad_t {
- H5T_PAD_ERROR = -1, /*error */
- H5T_PAD_ZERO = 0, /*always set to zero */
- H5T_PAD_ONE = 1, /*always set to one */
- H5T_PAD_BACKGROUND = 2, /*set to background value */
+ H5T_PAD_ERROR = -1, /**< error */
+ H5T_PAD_ZERO = 0, /**< always set to zero */
+ H5T_PAD_ONE = 1, /**< always set to one */
+ H5T_PAD_BACKGROUND = 2, /**< set to background value */
- H5T_NPAD = 3 /*THIS MUST BE LAST */
+ H5T_NPAD = 3 /**< sentinal: THIS MUST BE LAST */
} H5T_pad_t;
+//! [H5T_pad_t_snip]
-/* Commands sent to conversion functions */
+/**
+ * Commands sent to conversion functions
+ */
typedef enum H5T_cmd_t {
- H5T_CONV_INIT = 0, /*query and/or initialize private data */
- H5T_CONV_CONV = 1, /*convert data from source to dest datatype */
- H5T_CONV_FREE = 2 /*function is being removed from path */
+ H5T_CONV_INIT = 0, /**< query and/or initialize private data */
+ H5T_CONV_CONV = 1, /**< convert data from source to dest datatype */
+ H5T_CONV_FREE = 2 /**< function is being removed from path */
} H5T_cmd_t;
-/* How is the `bkg' buffer used by the conversion function? */
+/**
+ * How is the `bkg' buffer used by the conversion function?
+ */
typedef enum H5T_bkg_t {
- H5T_BKG_NO = 0, /*background buffer is not needed, send NULL */
- H5T_BKG_TEMP = 1, /*bkg buffer used as temp storage only */
- H5T_BKG_YES = 2 /*init bkg buf with data before conversion */
+ H5T_BKG_NO = 0, /**< background buffer is not needed, send NULL */
+ H5T_BKG_TEMP = 1, /**< bkg buffer used as temp storage only */
+ H5T_BKG_YES = 2 /**< init bkg buf with data before conversion */
} H5T_bkg_t;
-/* Type conversion client data */
+/**
+ * Type conversion client data
+ */
+//! [H5T_cdata_t_snip]
typedef struct H5T_cdata_t {
- H5T_cmd_t command; /*what should the conversion function do? */
- H5T_bkg_t need_bkg; /*is the background buffer needed? */
- hbool_t recalc; /*recalculate private data */
- void * priv; /*private data */
+ H5T_cmd_t command;/**< what should the conversion function do? */
+ H5T_bkg_t need_bkg;/**< is the background buffer needed? */
+ hbool_t recalc; /**< recalculate private data */
+ void *priv; /**< private data */
} H5T_cdata_t;
+//! [H5T_cdata_t_snip]
-/* Conversion function persistence */
+/**
+ * Conversion function persistence
+ */
typedef enum H5T_pers_t {
- H5T_PERS_DONTCARE = -1, /*wild card */
- H5T_PERS_HARD = 0, /*hard conversion function */
- H5T_PERS_SOFT = 1 /*soft conversion function */
+ H5T_PERS_DONTCARE = -1, /**< wild card */
+ H5T_PERS_HARD = 0, /**< hard conversion function */
+ H5T_PERS_SOFT = 1 /**< soft conversion function */
} H5T_pers_t;
-/* The order to retrieve atomic native datatype */
+/**
+ * The order to retrieve atomic native datatype
+ */
+//! [H5T_direction_t_snip]
typedef enum H5T_direction_t {
- H5T_DIR_DEFAULT = 0, /*default direction is inscendent */
- H5T_DIR_ASCEND = 1, /*in inscendent order */
- H5T_DIR_DESCEND = 2 /*in descendent order */
+ H5T_DIR_DEFAULT = 0, /**< default direction is inscendent */
+ H5T_DIR_ASCEND = 1, /**< in inscendent order */
+ H5T_DIR_DESCEND = 2 /**< in descendent order */
} H5T_direction_t;
+//! [H5T_direction_t_snip]
-/* The exception type passed into the conversion callback function */
+/**
+ * The exception type passed into the conversion callback function
+ */
typedef enum H5T_conv_except_t {
- H5T_CONV_EXCEPT_RANGE_HI = 0, /*source value is greater than destination's range */
- H5T_CONV_EXCEPT_RANGE_LOW = 1, /*source value is less than destination's range */
- H5T_CONV_EXCEPT_PRECISION = 2, /*source value loses precision in destination */
- H5T_CONV_EXCEPT_TRUNCATE = 3, /*source value is truncated in destination */
- H5T_CONV_EXCEPT_PINF = 4, /*source value is positive infinity(floating number) */
- H5T_CONV_EXCEPT_NINF = 5, /*source value is negative infinity(floating number) */
- H5T_CONV_EXCEPT_NAN = 6 /*source value is NaN(floating number) */
+ H5T_CONV_EXCEPT_RANGE_HI = 0, /**< source value is greater than destination's range */
+ H5T_CONV_EXCEPT_RANGE_LOW = 1, /**< source value is less than destination's range */
+ H5T_CONV_EXCEPT_PRECISION = 2, /**< source value loses precision in destination */
+ H5T_CONV_EXCEPT_TRUNCATE = 3, /**< source value is truncated in destination */
+ H5T_CONV_EXCEPT_PINF = 4, /**< source value is positive infinity(floating number) */
+ H5T_CONV_EXCEPT_NINF = 5, /**< source value is negative infinity(floating number) */
+ H5T_CONV_EXCEPT_NAN = 6 /**< source value is NaN(floating number) */
} H5T_conv_except_t;
-/* The return value from conversion callback function H5T_conv_except_func_t */
+/**
+ * The return value from conversion callback function H5T_conv_except_func_t()
+ */
typedef enum H5T_conv_ret_t {
- H5T_CONV_ABORT = -1, /*abort conversion */
- H5T_CONV_UNHANDLED = 0, /*callback function failed to handle the exception */
- H5T_CONV_HANDLED = 1 /*callback function handled the exception successfully */
+ H5T_CONV_ABORT = -1, /**< abort conversion */
+ H5T_CONV_UNHANDLED = 0, /**< callback function failed to handle the exception */
+ H5T_CONV_HANDLED = 1 /**< callback function handled the exception successfully */
} H5T_conv_ret_t;
-/* Variable Length Datatype struct in memory */
-/* (This is only used for VL sequences, not VL strings, which are stored in char *'s) */
+/**
+ * Variable Length Datatype struct in memory (This is only used for VL
+ * sequences, not VL strings, which are stored in char *'s)
+ */
typedef struct {
- size_t len; /* Length of VL data (in base type units) */
- void * p; /* Pointer to VL data */
+ size_t len; /**< Length of VL data (in base type units) */
+ void *p; /**< Pointer to VL data */
} hvl_t;
/* Variable Length String information */
-#define H5T_VARIABLE \
- ((size_t)( \
- -1)) /* Indicate that a string is variable length (null-terminated in C, instead of fixed length) */
+/**
+ * Indicate that a string is variable length (null-terminated in C, instead of
+ * fixed length)
+ */
+#define H5T_VARIABLE ((size_t)(-1))
/* Opaque information */
-#define H5T_OPAQUE_TAG_MAX 256 /* Maximum length of an opaque tag */
- /* This could be raised without too much difficulty */
+/**
+ * Maximum length of an opaque tag
+ * \internal This could be raised without too much difficulty
+ */
+#define H5T_OPAQUE_TAG_MAX 256
#ifdef __cplusplus
extern "C" {
#endif
-/* All datatype conversion functions are... */
-typedef herr_t (*H5T_conv_t)(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride,
- size_t bkg_stride, void *buf, void *bkg, hid_t dset_xfer_plist);
+/**
+ * All datatype conversion functions are...
+ */
+//! [H5T_conv_t_snip]
+typedef herr_t (*H5T_conv_t) (hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata,
+ size_t nelmts, size_t buf_stride, size_t bkg_stride, void *buf,
+ void *bkg, hid_t dset_xfer_plist);
+//! [H5T_conv_t_snip]
-/* Exception handler. If an exception like overflow happenes during conversion,
- * this function is called if it's registered through H5Pset_type_conv_cb.
+/**
+ * Exception handler. If an exception like overflow happenes during conversion,
+ * this function is called if it's registered through H5Pset_type_conv_cb().
*/
-typedef H5T_conv_ret_t (*H5T_conv_except_func_t)(H5T_conv_except_t except_type, hid_t src_id, hid_t dst_id,
- void *src_buf, void *dst_buf, void *user_data);
+typedef H5T_conv_ret_t (*H5T_conv_except_func_t)(H5T_conv_except_t except_type,
+ hid_t src_id, hid_t dst_id, void *src_buf, void *dst_buf, void *user_data);
/* When this header is included from a private header, don't make calls to H5open() */
#undef H5OPEN
@@ -226,10 +278,26 @@ typedef H5T_conv_ret_t (*H5T_conv_except_func_t)(H5T_conv_except_t except_type,
/*
* The IEEE floating point types in various byte orders.
*/
-#define H5T_IEEE_F32BE (H5OPEN H5T_IEEE_F32BE_g)
-#define H5T_IEEE_F32LE (H5OPEN H5T_IEEE_F32LE_g)
-#define H5T_IEEE_F64BE (H5OPEN H5T_IEEE_F64BE_g)
-#define H5T_IEEE_F64LE (H5OPEN H5T_IEEE_F64LE_g)
+/**
+ * \ingroup PDTIEEE
+ * 32-bit big-endian IEEE floating-point numbers
+ */
+#define H5T_IEEE_F32BE (H5OPEN H5T_IEEE_F32BE_g)
+/**
+ * \ingroup PDTIEEE
+ * 32-bit little-endian IEEE floating-point numbers
+ */
+#define H5T_IEEE_F32LE (H5OPEN H5T_IEEE_F32LE_g)
+/**
+ * \ingroup PDTIEEE
+ * 64-bit big-endian IEEE floating-point numbers
+ */
+#define H5T_IEEE_F64BE (H5OPEN H5T_IEEE_F64BE_g)
+/**
+ * \ingroup PDTIEEE
+ * 64-bit little-endian IEEE floating-point numbers
+ */
+#define H5T_IEEE_F64LE (H5OPEN H5T_IEEE_F64LE_g)
H5_DLLVAR hid_t H5T_IEEE_F32BE_g;
H5_DLLVAR hid_t H5T_IEEE_F32LE_g;
H5_DLLVAR hid_t H5T_IEEE_F64BE_g;
@@ -239,33 +307,141 @@ H5_DLLVAR hid_t H5T_IEEE_F64LE_g;
* These are "standard" types. For instance, signed (2's complement) and
* unsigned integers of various sizes and byte orders.
*/
-#define H5T_STD_I8BE (H5OPEN H5T_STD_I8BE_g)
-#define H5T_STD_I8LE (H5OPEN H5T_STD_I8LE_g)
-#define H5T_STD_I16BE (H5OPEN H5T_STD_I16BE_g)
-#define H5T_STD_I16LE (H5OPEN H5T_STD_I16LE_g)
-#define H5T_STD_I32BE (H5OPEN H5T_STD_I32BE_g)
-#define H5T_STD_I32LE (H5OPEN H5T_STD_I32LE_g)
-#define H5T_STD_I64BE (H5OPEN H5T_STD_I64BE_g)
-#define H5T_STD_I64LE (H5OPEN H5T_STD_I64LE_g)
-#define H5T_STD_U8BE (H5OPEN H5T_STD_U8BE_g)
-#define H5T_STD_U8LE (H5OPEN H5T_STD_U8LE_g)
-#define H5T_STD_U16BE (H5OPEN H5T_STD_U16BE_g)
-#define H5T_STD_U16LE (H5OPEN H5T_STD_U16LE_g)
-#define H5T_STD_U32BE (H5OPEN H5T_STD_U32BE_g)
-#define H5T_STD_U32LE (H5OPEN H5T_STD_U32LE_g)
-#define H5T_STD_U64BE (H5OPEN H5T_STD_U64BE_g)
-#define H5T_STD_U64LE (H5OPEN H5T_STD_U64LE_g)
-#define H5T_STD_B8BE (H5OPEN H5T_STD_B8BE_g)
-#define H5T_STD_B8LE (H5OPEN H5T_STD_B8LE_g)
-#define H5T_STD_B16BE (H5OPEN H5T_STD_B16BE_g)
-#define H5T_STD_B16LE (H5OPEN H5T_STD_B16LE_g)
-#define H5T_STD_B32BE (H5OPEN H5T_STD_B32BE_g)
-#define H5T_STD_B32LE (H5OPEN H5T_STD_B32LE_g)
-#define H5T_STD_B64BE (H5OPEN H5T_STD_B64BE_g)
-#define H5T_STD_B64LE (H5OPEN H5T_STD_B64LE_g)
-#define H5T_STD_REF_OBJ (H5OPEN H5T_STD_REF_OBJ_g)
-#define H5T_STD_REF_DSETREG (H5OPEN H5T_STD_REF_DSETREG_g)
-#define H5T_STD_REF (H5OPEN H5T_STD_REF_g)
+/**
+ * \ingroup PDTSTD
+ * 8-bit big-endian signed integers
+ */
+#define H5T_STD_I8BE (H5OPEN H5T_STD_I8BE_g)
+/**
+ * \ingroup PDTSTD
+ * 8-bit little-endian signed integers
+ */
+#define H5T_STD_I8LE (H5OPEN H5T_STD_I8LE_g)
+/**
+ * \ingroup PDTSTD
+ * 16-bit big-endian signed integers
+ */
+#define H5T_STD_I16BE (H5OPEN H5T_STD_I16BE_g)
+/**
+ * \ingroup PDTSTD
+ * 16-bit little-endian signed integers
+ */
+#define H5T_STD_I16LE (H5OPEN H5T_STD_I16LE_g)
+/**
+ * \ingroup PDTSTD
+ * 32-bit big-endian signed integers
+ */
+#define H5T_STD_I32BE (H5OPEN H5T_STD_I32BE_g)
+/**
+ * \ingroup PDTSTD
+ * 32-bit little-endian signed integers
+ */
+#define H5T_STD_I32LE (H5OPEN H5T_STD_I32LE_g)
+/**
+ * \ingroup PDTSTD
+ * 64-bit big-endian signed integers
+ */
+#define H5T_STD_I64BE (H5OPEN H5T_STD_I64BE_g)
+/**
+ * \ingroup PDTSTD
+ * 64-bit little-endian signed integers
+ */
+#define H5T_STD_I64LE (H5OPEN H5T_STD_I64LE_g)
+/**
+ * \ingroup PDTSTD
+ * 8-bit big-endian unsigned integers
+ */
+#define H5T_STD_U8BE (H5OPEN H5T_STD_U8BE_g)
+/**
+ * \ingroup PDTSTD
+ * 8-bit little-endian unsigned integers
+ */
+#define H5T_STD_U8LE (H5OPEN H5T_STD_U8LE_g)
+/**
+ * \ingroup PDTSTD
+ * 16-bit big-endian unsigned integers
+ */
+#define H5T_STD_U16BE (H5OPEN H5T_STD_U16BE_g)
+/**
+ * \ingroup PDTSTD
+ * 16-bit little-endian unsigned integers
+ */
+#define H5T_STD_U16LE (H5OPEN H5T_STD_U16LE_g)
+/**
+ * \ingroup PDTSTD
+ * 32-bit big-endian unsigned integers
+ */
+#define H5T_STD_U32BE (H5OPEN H5T_STD_U32BE_g)
+/**
+ * \ingroup PDTSTD
+ * 32-bit little-endian unsigned integers
+ */
+#define H5T_STD_U32LE (H5OPEN H5T_STD_U32LE_g)
+/**
+ * \ingroup PDTSTD
+ * 64-bit big-endian unsigned integers
+ */
+#define H5T_STD_U64BE (H5OPEN H5T_STD_U64BE_g)
+/**
+ * \ingroup PDTSTD
+ * 64-bit little-endian unsigned integers
+ */
+#define H5T_STD_U64LE (H5OPEN H5T_STD_U64LE_g)
+/**
+ * \ingroup PDTSTD
+ * 8-bit big-endian bitfield
+ */
+#define H5T_STD_B8BE (H5OPEN H5T_STD_B8BE_g)
+/**
+ * \ingroup PDTSTD
+ * 8-bit little-endian bitfield
+ */
+#define H5T_STD_B8LE (H5OPEN H5T_STD_B8LE_g)
+/**
+ * \ingroup PDTSTD
+ * 16-bit big-endian bitfield
+ */
+#define H5T_STD_B16BE (H5OPEN H5T_STD_B16BE_g)
+/**
+ * \ingroup PDTSTD
+ * 16-bit little-endian bitfield
+ */
+#define H5T_STD_B16LE (H5OPEN H5T_STD_B16LE_g)
+/**
+ * \ingroup PDTSTD
+ * 32-bit big-endian bitfield
+ */
+#define H5T_STD_B32BE (H5OPEN H5T_STD_B32BE_g)
+/**
+ * \ingroup PDTSTD
+ * 32-bit little-endian bitfield
+ */
+#define H5T_STD_B32LE (H5OPEN H5T_STD_B32LE_g)
+/**
+ * \ingroup PDTSTD
+ * 64-bit big-endian bitfield
+ */
+#define H5T_STD_B64BE (H5OPEN H5T_STD_B64BE_g)
+/**
+ * \ingroup PDTSTD
+ * 64-bit little-endian bitfield
+ */
+#define H5T_STD_B64LE (H5OPEN H5T_STD_B64LE_g)
+/**
+ * \ingroup PDTSTD
+ * Object reference
+ */
+#define H5T_STD_REF_OBJ (H5OPEN H5T_STD_REF_OBJ_g)
+/**
+ * \ingroup PDTSTD
+ * Dataset region reference
+ */
+#define H5T_STD_REF_DSETREG (H5OPEN H5T_STD_REF_DSETREG_g)
+/**
+ * \ingroup PDTSTD
+ * Generic reference
+ */
+#define H5T_STD_REF (H5OPEN H5T_STD_REF_g)
H5_DLLVAR hid_t H5T_STD_I8BE_g;
H5_DLLVAR hid_t H5T_STD_I8LE_g;
H5_DLLVAR hid_t H5T_STD_I16BE_g;
@@ -297,10 +473,22 @@ H5_DLLVAR hid_t H5T_STD_REF_g;
/*
* Types which are particular to Unix.
*/
-#define H5T_UNIX_D32BE (H5OPEN H5T_UNIX_D32BE_g)
-#define H5T_UNIX_D32LE (H5OPEN H5T_UNIX_D32LE_g)
-#define H5T_UNIX_D64BE (H5OPEN H5T_UNIX_D64BE_g)
-#define H5T_UNIX_D64LE (H5OPEN H5T_UNIX_D64LE_g)
+/**
+ * \ingroup PDTUNIX
+ */
+#define H5T_UNIX_D32BE (H5OPEN H5T_UNIX_D32BE_g)
+/**
+ * \ingroup PDTUNIX
+ */
+#define H5T_UNIX_D32LE (H5OPEN H5T_UNIX_D32LE_g)
+/**
+ * \ingroup PDTUNIX
+ */
+#define H5T_UNIX_D64BE (H5OPEN H5T_UNIX_D64BE_g)
+/**
+ * \ingroup PDTUNIX
+ */
+#define H5T_UNIX_D64LE (H5OPEN H5T_UNIX_D64LE_g)
H5_DLLVAR hid_t H5T_UNIX_D32BE_g;
H5_DLLVAR hid_t H5T_UNIX_D32LE_g;
H5_DLLVAR hid_t H5T_UNIX_D64BE_g;
@@ -310,12 +498,20 @@ H5_DLLVAR hid_t H5T_UNIX_D64LE_g;
* Types particular to the C language. String types use `bytes' instead
* of `bits' as their size.
*/
+/**
+ * \ingroup PDTS
+ * String datatype in C (size defined in bytes rather than in bits)
+ */
#define H5T_C_S1 (H5OPEN H5T_C_S1_g)
H5_DLLVAR hid_t H5T_C_S1_g;
/*
* Types particular to Fortran.
*/
+/**
+ * \ingroup PDTS
+ * String datatype in Fortran (as defined for the HDF5 C library)
+ */
#define H5T_FORTRAN_S1 (H5OPEN H5T_FORTRAN_S1_g)
H5_DLLVAR hid_t H5T_FORTRAN_S1_g;
@@ -323,63 +519,239 @@ H5_DLLVAR hid_t H5T_FORTRAN_S1_g;
* These types are for Intel CPU's. They are little endian with IEEE
* floating point.
*/
-#define H5T_INTEL_I8 H5T_STD_I8LE
-#define H5T_INTEL_I16 H5T_STD_I16LE
-#define H5T_INTEL_I32 H5T_STD_I32LE
-#define H5T_INTEL_I64 H5T_STD_I64LE
-#define H5T_INTEL_U8 H5T_STD_U8LE
-#define H5T_INTEL_U16 H5T_STD_U16LE
-#define H5T_INTEL_U32 H5T_STD_U32LE
-#define H5T_INTEL_U64 H5T_STD_U64LE
-#define H5T_INTEL_B8 H5T_STD_B8LE
-#define H5T_INTEL_B16 H5T_STD_B16LE
-#define H5T_INTEL_B32 H5T_STD_B32LE
-#define H5T_INTEL_B64 H5T_STD_B64LE
-#define H5T_INTEL_F32 H5T_IEEE_F32LE
-#define H5T_INTEL_F64 H5T_IEEE_F64LE
+/**
+ * \ingroup PDTX86
+ * 8-bit little-endian signed (2's complement) integers for Intel CPUs
+ */
+#define H5T_INTEL_I8 H5T_STD_I8LE
+/**
+ * \ingroup PDTX86
+ * 16-bit little-endian signed (2's complement) integers for Intel CPUs
+ */
+#define H5T_INTEL_I16 H5T_STD_I16LE
+/**
+ * \ingroup PDTX86
+ * 32-bit little-endian signed (2's complement) integers for Intel CPUs
+ */
+#define H5T_INTEL_I32 H5T_STD_I32LE
+/**
+ * \ingroup PDTX86
+ * 64-bit little-endian signed (2's complement) integers for Intel CPUs
+ */
+#define H5T_INTEL_I64 H5T_STD_I64LE
+/**
+ * \ingroup PDTX86
+ * 8-bit little-endian unsigned integers for Intel CPUs
+ */
+#define H5T_INTEL_U8 H5T_STD_U8LE
+/**
+ * \ingroup PDTX86
+ * 16-bit little-endian unsigned integers for Intel CPUs
+ */
+#define H5T_INTEL_U16 H5T_STD_U16LE
+/**
+ * \ingroup PDTX86
+ * 32-bit little-endian unsigned integers for Intel CPUs
+ */
+#define H5T_INTEL_U32 H5T_STD_U32LE
+/**
+ * \ingroup PDTX86
+ * 64-bit little-endian unsigned integers for Intel CPUs
+ */
+#define H5T_INTEL_U64 H5T_STD_U64LE
+/**
+ * \ingroup PDTX86
+ * 8-bit little-endian bitfield for Intel CPUs
+ */
+#define H5T_INTEL_B8 H5T_STD_B8LE
+/**
+ * \ingroup PDTX86
+ * 16-bit little-endian bitfield for Intel CPUs
+ */
+#define H5T_INTEL_B16 H5T_STD_B16LE
+/**
+ * \ingroup PDTX86
+ * 32-bit little-endian bitfield for Intel CPUs
+ */
+#define H5T_INTEL_B32 H5T_STD_B32LE
+/**
+ * \ingroup PDTX86
+ * 64-bit little-endian bitfield for Intel CPUs
+ */
+#define H5T_INTEL_B64 H5T_STD_B64LE
+/**
+ * \ingroup PDTX86
+ * 32-bit little-endian IEEE floating-point numbers for Intel CPUs
+ */
+#define H5T_INTEL_F32 H5T_IEEE_F32LE
+/**
+ * \ingroup PDTX86
+ * 64-bit little-endian IEEE floating-point numbers for Intel CPUs
+ */
+#define H5T_INTEL_F64 H5T_IEEE_F64LE
/*
* These types are for DEC Alpha CPU's. They are little endian with IEEE
* floating point.
*/
-#define H5T_ALPHA_I8 H5T_STD_I8LE
-#define H5T_ALPHA_I16 H5T_STD_I16LE
-#define H5T_ALPHA_I32 H5T_STD_I32LE
-#define H5T_ALPHA_I64 H5T_STD_I64LE
-#define H5T_ALPHA_U8 H5T_STD_U8LE
-#define H5T_ALPHA_U16 H5T_STD_U16LE
-#define H5T_ALPHA_U32 H5T_STD_U32LE
-#define H5T_ALPHA_U64 H5T_STD_U64LE
-#define H5T_ALPHA_B8 H5T_STD_B8LE
-#define H5T_ALPHA_B16 H5T_STD_B16LE
-#define H5T_ALPHA_B32 H5T_STD_B32LE
-#define H5T_ALPHA_B64 H5T_STD_B64LE
-#define H5T_ALPHA_F32 H5T_IEEE_F32LE
-#define H5T_ALPHA_F64 H5T_IEEE_F64LE
+/**
+ * \ingroup PDTALPHA
+ * 8-bit little-endian signed (2's complement) integers for DEC Alpha CPUs
+ */
+#define H5T_ALPHA_I8 H5T_STD_I8LE
+/**
+ * \ingroup PDTALPHA
+ * 16-bit little-endian signed (2's complement) integers for DEC Alpha CPUs
+ */
+#define H5T_ALPHA_I16 H5T_STD_I16LE
+/**
+ * \ingroup PDTALPHA
+ * 32-bit little-endian signed (2's complement) integers for DEC Alpha CPUs
+ */
+#define H5T_ALPHA_I32 H5T_STD_I32LE
+/**
+ * \ingroup PDTALPHA
+ * 64-bit little-endian signed (2's complement) integers for DEC Alpha CPUs
+ */
+#define H5T_ALPHA_I64 H5T_STD_I64LE
+/**
+ * \ingroup PDTALPHA
+ * 8-bit little-endian unsigned integers for DEC Alpha CPUs
+ */
+#define H5T_ALPHA_U8 H5T_STD_U8LE
+/**
+ * \ingroup PDTALPHA
+ * 16-bit little-endian unsigned integers for DEC Alpha CPUs
+ */
+#define H5T_ALPHA_U16 H5T_STD_U16LE
+/**
+ * \ingroup PDTALPHA
+ * 32-bit little-endian unsigned integers for DEC Alpha CPUs
+ */
+#define H5T_ALPHA_U32 H5T_STD_U32LE
+/**
+ * \ingroup PDTALPHA
+ * 64-bit little-endian unsigned integers for DEC Alpha CPUs
+ */
+#define H5T_ALPHA_U64 H5T_STD_U64LE
+/**
+ * \ingroup PDTALPHA
+ * 8-bit little-endian bitfield for DEC Alpha CPUs
+ */
+#define H5T_ALPHA_B8 H5T_STD_B8LE
+/**
+ * \ingroup PDTALPHA
+ * 16-bit little-endian bitfield for DEC Alpha CPUs
+ */
+#define H5T_ALPHA_B16 H5T_STD_B16LE
+/**
+ * \ingroup PDTALPHA
+ * 32-bit little-endian bitfield for DEC Alpha CPUs
+ */
+#define H5T_ALPHA_B32 H5T_STD_B32LE
+/**
+ * \ingroup PDTALPHA
+ * 64-bit little-endian bitfield for DEC Alpha CPUs
+ */
+#define H5T_ALPHA_B64 H5T_STD_B64LE
+/**
+ * \ingroup PDTALPHA
+ * 32-bit little-endian IEEE floating-point numbers for DEC Alpha CPUs
+ */
+#define H5T_ALPHA_F32 H5T_IEEE_F32LE
+/**
+ * \ingroup PDTALPHA
+ * 64-bit little-endian IEEE floating-point numbers for DEC Alpha CPUs
+ */
+#define H5T_ALPHA_F64 H5T_IEEE_F64LE
/*
* These types are for MIPS cpu's commonly used in SGI systems. They are big
* endian with IEEE floating point.
*/
-#define H5T_MIPS_I8 H5T_STD_I8BE
-#define H5T_MIPS_I16 H5T_STD_I16BE
-#define H5T_MIPS_I32 H5T_STD_I32BE
-#define H5T_MIPS_I64 H5T_STD_I64BE
-#define H5T_MIPS_U8 H5T_STD_U8BE
-#define H5T_MIPS_U16 H5T_STD_U16BE
-#define H5T_MIPS_U32 H5T_STD_U32BE
-#define H5T_MIPS_U64 H5T_STD_U64BE
-#define H5T_MIPS_B8 H5T_STD_B8BE
-#define H5T_MIPS_B16 H5T_STD_B16BE
-#define H5T_MIPS_B32 H5T_STD_B32BE
-#define H5T_MIPS_B64 H5T_STD_B64BE
-#define H5T_MIPS_F32 H5T_IEEE_F32BE
-#define H5T_MIPS_F64 H5T_IEEE_F64BE
+/**
+ * \ingroup PDTMIPS
+ * 8-bit big-endian signed (2's complement) integers for SGI MIPS CPUs
+ */
+#define H5T_MIPS_I8 H5T_STD_I8BE
+/**
+ * \ingroup PDTMIPS
+ * 16-bit big-endian signed (2's complement) integers for SGI MIPS CPUs
+ */
+#define H5T_MIPS_I16 H5T_STD_I16BE
+/**
+ * \ingroup PDTMIPS
+ * 32-bit big-endian signed (2's complement) integers for SGI MIPS CPUs
+ */
+#define H5T_MIPS_I32 H5T_STD_I32BE
+/**
+ * \ingroup PDTMIPS
+ * 64-bit big-endian signed (2's complement) integers for SGI MIPS CPUs
+ */
+#define H5T_MIPS_I64 H5T_STD_I64BE
+/**
+ * \ingroup PDTMIPS
+ * 8-bit big-endian unsigned integers for SGI MIPS CPUs
+ */
+#define H5T_MIPS_U8 H5T_STD_U8BE
+/**
+ * \ingroup PDTMIPS
+ * 16-bit big-endian unsigned integers for SGI MIPS CPUs
+ */
+#define H5T_MIPS_U16 H5T_STD_U16BE
+/**
+ * \ingroup PDTMIPS
+ * 32-bit big-endian unsigned integers for SGI MIPS CPUs
+ */
+#define H5T_MIPS_U32 H5T_STD_U32BE
+/**
+ * \ingroup PDTMIPS
+ * 64-bit big-endian unsigned integers for SGI MIPS CPUs
+ */
+#define H5T_MIPS_U64 H5T_STD_U64BE
+/**
+ * \ingroup PDTMIPS
+ * 8-bit big-endian bitfield for SGI MIPS CPUs
+ */
+#define H5T_MIPS_B8 H5T_STD_B8BE
+/**
+ * \ingroup PDTMIPS
+ * 16-bit big-endian bitfield for SGI MIPS CPUs
+ */
+#define H5T_MIPS_B16 H5T_STD_B16BE
+/**
+ * \ingroup PDTMIPS
+ * 32-bit big-endian bitfield for SGI MIPS CPUs
+ */
+#define H5T_MIPS_B32 H5T_STD_B32BE
+/**
+ * \ingroup PDTMIPS
+ * 64-bit big-endian bitfield for SGI MIPS CPUs
+ */
+#define H5T_MIPS_B64 H5T_STD_B64BE
+/**
+ * \ingroup PDTMIPS
+ * 32-bit big-endian IEEE floating-point numbers for MIPS CPUs
+ */
+#define H5T_MIPS_F32 H5T_IEEE_F32BE
+/**
+ * \ingroup PDTMIPS
+ * 64-bit big-endian IEEE floating-point numbers for MIPS CPUs
+ */
+#define H5T_MIPS_F64 H5T_IEEE_F64BE
/*
* The VAX floating point types (i.e. in VAX byte order)
*/
+/**
+ * \ingroup PDTALPHA
+ * 32-bit VAX byte order floating-point numbers for OpenVMS on DEC Alpha CPUs
+ */
#define H5T_VAX_F32 (H5OPEN H5T_VAX_F32_g)
+/**
+ * \ingroup PDTALPHA
+ * 64-bit VAX byte order floating-point numbers for OpenVMS on DEC Alpha CPUs
+ */
#define H5T_VAX_F64 (H5OPEN H5T_VAX_F64_g)
H5_DLLVAR hid_t H5T_VAX_F32_g;
H5_DLLVAR hid_t H5T_VAX_F64_g;
@@ -393,32 +765,128 @@ H5_DLLVAR hid_t H5T_VAX_F64_g;
* to C's `long long' and LDOUBLE is `long double' (these types might be the
* same as `LONG' and `DOUBLE' respectively).
*/
-#define H5T_NATIVE_CHAR (CHAR_MIN ? H5T_NATIVE_SCHAR : H5T_NATIVE_UCHAR)
+/**
+ * \ingroup PDTNAT
+ * C-style \c char
+ */
+#define H5T_NATIVE_CHAR (CHAR_MIN?H5T_NATIVE_SCHAR:H5T_NATIVE_UCHAR)
+/**
+ * \ingroup PDTNAT
+ * C-style \Code{signed char}
+ */
#define H5T_NATIVE_SCHAR (H5OPEN H5T_NATIVE_SCHAR_g)
+/**
+ * \ingroup PDTNAT
+ * C-style \Code{unsigned char}
+ */
#define H5T_NATIVE_UCHAR (H5OPEN H5T_NATIVE_UCHAR_g)
+/**
+ * \ingroup PDTNAT
+ * C-style \Code{short}
+ */
#define H5T_NATIVE_SHORT (H5OPEN H5T_NATIVE_SHORT_g)
+/**
+ * \ingroup PDTNAT
+ * C-style \Code{unsigned short}
+ */
#define H5T_NATIVE_USHORT (H5OPEN H5T_NATIVE_USHORT_g)
+/**
+ * \ingroup PDTNAT
+ * C-style \Code{int}
+ */
#define H5T_NATIVE_INT (H5OPEN H5T_NATIVE_INT_g)
+/**
+ * \ingroup PDTNAT
+ * C-style \Code{unsigned int}
+ */
#define H5T_NATIVE_UINT (H5OPEN H5T_NATIVE_UINT_g)
+/**
+ * \ingroup PDTNAT
+ * C-style \Code{long}
+ */
#define H5T_NATIVE_LONG (H5OPEN H5T_NATIVE_LONG_g)
+/**
+ * \ingroup PDTNAT
+ * C-style \Code{unsigned long}
+ */
#define H5T_NATIVE_ULONG (H5OPEN H5T_NATIVE_ULONG_g)
+/**
+ * \ingroup PDTNAT
+ * C-style \Code{long long}
+ */
#define H5T_NATIVE_LLONG (H5OPEN H5T_NATIVE_LLONG_g)
+/**
+ * \ingroup PDTNAT
+ * C-style \Code{unsigned long long}
+ */
#define H5T_NATIVE_ULLONG (H5OPEN H5T_NATIVE_ULLONG_g)
+/**
+ * \ingroup PDTNAT
+ * C-style \Code{float}
+ */
#define H5T_NATIVE_FLOAT (H5OPEN H5T_NATIVE_FLOAT_g)
+/**
+ * \ingroup PDTNAT
+ * C-style \Code{double}
+ */
#define H5T_NATIVE_DOUBLE (H5OPEN H5T_NATIVE_DOUBLE_g)
-#if H5_SIZEOF_LONG_DOUBLE != 0
+#if H5_SIZEOF_LONG_DOUBLE !=0
+/**
+ * \ingroup PDTNAT
+ * C-style \Code{long double}
+ */
#define H5T_NATIVE_LDOUBLE (H5OPEN H5T_NATIVE_LDOUBLE_g)
#endif
+/**
+ * \ingroup PDTNAT
+ * HDF5 8-bit bitfield based on native types
+ */
#define H5T_NATIVE_B8 (H5OPEN H5T_NATIVE_B8_g)
+/**
+ * \ingroup PDTNAT
+ * HDF5 16-bit bitfield based on native types
+ */
#define H5T_NATIVE_B16 (H5OPEN H5T_NATIVE_B16_g)
+/**
+ * \ingroup PDTNAT
+ * HDF5 32-bit bitfield based on native types
+ */
#define H5T_NATIVE_B32 (H5OPEN H5T_NATIVE_B32_g)
-#define H5T_NATIVE_B64 (H5OPEN H5T_NATIVE_B64_g)
+/**
+ * \ingroup PDTNAT
+ * HDF5 64-bit bitfield based on native types
+ */
+#define H5T_NATIVE_B64 (H5OPEN H5T_NATIVE_B64_g)
+/**
+ * \ingroup PDTNAT
+ * HDF5 opaque unit based on native types
+ */
#define H5T_NATIVE_OPAQUE (H5OPEN H5T_NATIVE_OPAQUE_g)
+/**
+ * \ingroup PDTNAT
+ * HDF5 address type based on native types
+ */
#define H5T_NATIVE_HADDR (H5OPEN H5T_NATIVE_HADDR_g)
+/**
+ * \ingroup PDTNAT
+ * HDF5 size type based on native types
+ */
#define H5T_NATIVE_HSIZE (H5OPEN H5T_NATIVE_HSIZE_g)
+/**
+ * \ingroup PDTNAT
+ * HDF5 signed size type based on native types
+ */
#define H5T_NATIVE_HSSIZE (H5OPEN H5T_NATIVE_HSSIZE_g)
-#define H5T_NATIVE_HERR (H5OPEN H5T_NATIVE_HERR_g)
-#define H5T_NATIVE_HBOOL (H5OPEN H5T_NATIVE_HBOOL_g)
+/**
+ * \ingroup PDTNAT
+ * HDF5 error code type based on native types
+ */
+#define H5T_NATIVE_HERR (H5OPEN H5T_NATIVE_HERR_g)
+/**
+ * \ingroup PDTNAT
+ * HDF5 Boolean type based on native types
+ */
+#define H5T_NATIVE_HBOOL (H5OPEN H5T_NATIVE_HBOOL_g)
H5_DLLVAR hid_t H5T_NATIVE_SCHAR_g;
H5_DLLVAR hid_t H5T_NATIVE_UCHAR_g;
H5_DLLVAR hid_t H5T_NATIVE_SHORT_g;
@@ -446,12 +914,30 @@ H5_DLLVAR hid_t H5T_NATIVE_HERR_g;
H5_DLLVAR hid_t H5T_NATIVE_HBOOL_g;
/* C9x integer types */
-#define H5T_NATIVE_INT8 (H5OPEN H5T_NATIVE_INT8_g)
-#define H5T_NATIVE_UINT8 (H5OPEN H5T_NATIVE_UINT8_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_INT8 (H5OPEN H5T_NATIVE_INT8_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_UINT8 (H5OPEN H5T_NATIVE_UINT8_g)
+/**
+ * \ingroup PDTC9x
+ */
#define H5T_NATIVE_INT_LEAST8 (H5OPEN H5T_NATIVE_INT_LEAST8_g)
-#define H5T_NATIVE_UINT_LEAST8 (H5OPEN H5T_NATIVE_UINT_LEAST8_g)
-#define H5T_NATIVE_INT_FAST8 (H5OPEN H5T_NATIVE_INT_FAST8_g)
-#define H5T_NATIVE_UINT_FAST8 (H5OPEN H5T_NATIVE_UINT_FAST8_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_UINT_LEAST8 (H5OPEN H5T_NATIVE_UINT_LEAST8_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_INT_FAST8 (H5OPEN H5T_NATIVE_INT_FAST8_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_UINT_FAST8 (H5OPEN H5T_NATIVE_UINT_FAST8_g)
H5_DLLVAR hid_t H5T_NATIVE_INT8_g;
H5_DLLVAR hid_t H5T_NATIVE_UINT8_g;
H5_DLLVAR hid_t H5T_NATIVE_INT_LEAST8_g;
@@ -459,12 +945,30 @@ H5_DLLVAR hid_t H5T_NATIVE_UINT_LEAST8_g;
H5_DLLVAR hid_t H5T_NATIVE_INT_FAST8_g;
H5_DLLVAR hid_t H5T_NATIVE_UINT_FAST8_g;
-#define H5T_NATIVE_INT16 (H5OPEN H5T_NATIVE_INT16_g)
-#define H5T_NATIVE_UINT16 (H5OPEN H5T_NATIVE_UINT16_g)
-#define H5T_NATIVE_INT_LEAST16 (H5OPEN H5T_NATIVE_INT_LEAST16_g)
-#define H5T_NATIVE_UINT_LEAST16 (H5OPEN H5T_NATIVE_UINT_LEAST16_g)
-#define H5T_NATIVE_INT_FAST16 (H5OPEN H5T_NATIVE_INT_FAST16_g)
-#define H5T_NATIVE_UINT_FAST16 (H5OPEN H5T_NATIVE_UINT_FAST16_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_INT16 (H5OPEN H5T_NATIVE_INT16_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_UINT16 (H5OPEN H5T_NATIVE_UINT16_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_INT_LEAST16 (H5OPEN H5T_NATIVE_INT_LEAST16_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_UINT_LEAST16 (H5OPEN H5T_NATIVE_UINT_LEAST16_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_INT_FAST16 (H5OPEN H5T_NATIVE_INT_FAST16_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_UINT_FAST16 (H5OPEN H5T_NATIVE_UINT_FAST16_g)
H5_DLLVAR hid_t H5T_NATIVE_INT16_g;
H5_DLLVAR hid_t H5T_NATIVE_UINT16_g;
H5_DLLVAR hid_t H5T_NATIVE_INT_LEAST16_g;
@@ -472,12 +976,30 @@ H5_DLLVAR hid_t H5T_NATIVE_UINT_LEAST16_g;
H5_DLLVAR hid_t H5T_NATIVE_INT_FAST16_g;
H5_DLLVAR hid_t H5T_NATIVE_UINT_FAST16_g;
-#define H5T_NATIVE_INT32 (H5OPEN H5T_NATIVE_INT32_g)
-#define H5T_NATIVE_UINT32 (H5OPEN H5T_NATIVE_UINT32_g)
-#define H5T_NATIVE_INT_LEAST32 (H5OPEN H5T_NATIVE_INT_LEAST32_g)
-#define H5T_NATIVE_UINT_LEAST32 (H5OPEN H5T_NATIVE_UINT_LEAST32_g)
-#define H5T_NATIVE_INT_FAST32 (H5OPEN H5T_NATIVE_INT_FAST32_g)
-#define H5T_NATIVE_UINT_FAST32 (H5OPEN H5T_NATIVE_UINT_FAST32_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_INT32 (H5OPEN H5T_NATIVE_INT32_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_UINT32 (H5OPEN H5T_NATIVE_UINT32_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_INT_LEAST32 (H5OPEN H5T_NATIVE_INT_LEAST32_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_UINT_LEAST32 (H5OPEN H5T_NATIVE_UINT_LEAST32_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_INT_FAST32 (H5OPEN H5T_NATIVE_INT_FAST32_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_UINT_FAST32 (H5OPEN H5T_NATIVE_UINT_FAST32_g)
H5_DLLVAR hid_t H5T_NATIVE_INT32_g;
H5_DLLVAR hid_t H5T_NATIVE_UINT32_g;
H5_DLLVAR hid_t H5T_NATIVE_INT_LEAST32_g;
@@ -485,12 +1007,30 @@ H5_DLLVAR hid_t H5T_NATIVE_UINT_LEAST32_g;
H5_DLLVAR hid_t H5T_NATIVE_INT_FAST32_g;
H5_DLLVAR hid_t H5T_NATIVE_UINT_FAST32_g;
-#define H5T_NATIVE_INT64 (H5OPEN H5T_NATIVE_INT64_g)
-#define H5T_NATIVE_UINT64 (H5OPEN H5T_NATIVE_UINT64_g)
-#define H5T_NATIVE_INT_LEAST64 (H5OPEN H5T_NATIVE_INT_LEAST64_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_INT64 (H5OPEN H5T_NATIVE_INT64_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_UINT64 (H5OPEN H5T_NATIVE_UINT64_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_INT_LEAST64 (H5OPEN H5T_NATIVE_INT_LEAST64_g)
+/**
+ * \ingroup PDTC9x
+ */
#define H5T_NATIVE_UINT_LEAST64 (H5OPEN H5T_NATIVE_UINT_LEAST64_g)
-#define H5T_NATIVE_INT_FAST64 (H5OPEN H5T_NATIVE_INT_FAST64_g)
-#define H5T_NATIVE_UINT_FAST64 (H5OPEN H5T_NATIVE_UINT_FAST64_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_INT_FAST64 (H5OPEN H5T_NATIVE_INT_FAST64_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_UINT_FAST64 (H5OPEN H5T_NATIVE_UINT_FAST64_g)
H5_DLLVAR hid_t H5T_NATIVE_INT64_g;
H5_DLLVAR hid_t H5T_NATIVE_UINT64_g;
H5_DLLVAR hid_t H5T_NATIVE_INT_LEAST64_g;
@@ -499,92 +1039,1837 @@ H5_DLLVAR hid_t H5T_NATIVE_INT_FAST64_g;
H5_DLLVAR hid_t H5T_NATIVE_UINT_FAST64_g;
/* Operations defined on all datatypes */
+/**
+ * \ingroup H5T
+ *
+ * \brief Creates a new datatype.
+ *
+ * \param[in] type Class of datatype to create
+ * \param[in] size Size, in bytes, of the datatype being created
+ *
+ * \return \hid_t{datatype}
+ *
+ * \details H5Tcreate() creates a new datatype of the specified class with the
+ * specified number of bytes. This function is used only with the
+ * following datatype classes:
+ * - #H5T_COMPOUND
+ * - #H5T_OPAQUE
+ * - #H5T_ENUM
+ * - #H5T_STRING
+ *
+ * Other datatypes, including integer and floating-point datatypes,
+ * are typically created by using H5Tcopy() to copy and modify a
+ * predefined datatype.
+ *
+ * When creating a variable-length string datatype, \p size must
+ * be #H5T_VARIABLE.
+ *
+ * When creating a fixed-length string datatype, \p size will
+ * be the length of the string in bytes. The length of the
+ * string in characters will depend on i the encoding used; see
+ * H5Pset_char_encoding().
+ *
+ * ENUMs created with this function have a signed native integer
+ * base datatype. Use H5Tenum_create() if a different integer base
+ * datatype is required.
+ *
+ * The datatype identifier returned from this function should be
+ * released with H5Tclose or resource leaks will result.
+ *
+ * \since 1.2.0
+ *
+ * \see H5Tclose()
+ *
+ * \todo Original has a reference to “Creating variable-length string
+ * datatypes”.
+ * \todo Create an example for H5Tcreate.
+ *
+ */
H5_DLL hid_t H5Tcreate(H5T_class_t type, size_t size);
+/**
+ * \ingroup H5T
+ *
+ * \brief Copies an existing datatype.
+ *
+ * \type_id
+ *
+ * \return \hid_t{datatype}
+ *
+ * \details H5Tcopy() makes a copy of an existing datatype. The returned type
+ * is always transient and unlocked.
+ *
+ * The \p type_id argument can be either a datatype identifier,
+ * a predefined datatype (defined in H5Tpublic.h), or a dataset
+ * identifier. If \p type_id is a dataset identifier, this function
+ * returns a transient, modifiable datatype which is a copy of the
+ * dataset's datatype.
+ *
+ * The returned datatype identifier should be released with H5Tclose()
+ * to prevent resource leak.
+ *
+ * \todo Create an example for H5Tcopy().
+ *
+ */
H5_DLL hid_t H5Tcopy(hid_t type_id);
+/**
+ * \ingroup H5T
+ *
+ * \brief Releases a datatype
+ *
+ * \type_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Tclose() releases the datatype \p dtype_id. Further access
+ * through this datatype identifier is illegal. Failure to release
+ * a datatype with this call will result in resource leaks.
+ *
+ */
H5_DLL herr_t H5Tclose(hid_t type_id);
+/**
+ * \ingroup H5T
+ *
+ * \brief Determines whether two datatype identifiers refer to the same datatype
+ *
+ * \type_id{type1_id}
+ * \type_id{type2_id}
+ *
+ * \return \htri_t
+ *
+ * \details H5Tequal() determines whether two datatype identifiers refer to
+ * the same datatype.
+ *
+ * \since 1.6 or earlier
+ *
+ */
H5_DLL htri_t H5Tequal(hid_t type1_id, hid_t type2_id);
+/**
+ * \ingroup H5T
+ *
+ * \brief Locks a datatype
+ *
+ * \type_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Tlock() locks the datatype specified by the dtype_id identifier,
+ * making it read-only and non-destructible. This is normally done by
+ * the library for predefined datatypes so the application does not
+ * inadvertently change or delete a predefined type. Once a datatype
+ * is locked it can never be unlocked.
+ *
+ */
H5_DLL herr_t H5Tlock(hid_t type_id);
+/**
+ * \ingroup H5T
+ *
+ * \brief Commits a transient datatype, linking it into the file and creating
+ * a new committed datatype
+ *
+ * \fg_loc_id
+ * \param[in] name Name given to committed datatype
+ * \type_id Identifier of datatype to be committed and, upon function’s
+ * return, identifier for the committed datatype
+ * \lcpl_id
+ * \tcpl_id
+ * \tapl_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Tcommit2() saves a transient datatype as an immutable committed
+ * datatype in a file. The datatype specified by \p dtype_id is
+ * committed to the file with the name name at the location specified
+ * by \p loc_id and with the datatype creation and access property
+ * lists \p tcpl_id and \p tapl_id, respectively.
+ *
+ * \p loc_id may be a file identifier, or a group identifier within
+ * that file. \p name may be either an absolute path in the file or
+ * a relative path from \p loc_id naming the newly-commited datatype.
+ *
+ * The link creation property list, \p lcpl_id, governs creation of
+ * the link(s) by which the new committed datatype is accessed and
+ * the creation of any intermediate groups that may be missing.
+ *
+ * Once commited, this datatype may be used to define the datatype
+ * of any other dataset or attribute in the file.
+ *
+ * This function will not accept a datatype that cannot actually hold
+ * information. This currently includes compound datatypes with no
+ * fields and enumerated datatypes with no members.
+ *
+ * Committed datatypes are sometimes referred to as named datatypes.
+ *
+ * \version 1.8.7 Function modified in this release to reject datatypes that
+ * will not accomodate actual data, such as a compound datatype
+ * with no fields or an enumerated datatype with no members.
+ *
+ * \since 1.8.0
+ *
+ */
H5_DLL herr_t H5Tcommit2(hid_t loc_id, const char *name, hid_t type_id, hid_t lcpl_id, hid_t tcpl_id,
hid_t tapl_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5T
+ *
+ * \brief Opens a committed (named) datatype
+ *
+ * \fgdta_loc_id
+ * \param[in] name Name of the datatype to open
+ * \tapl_id
+ *
+ * \return \hid_t{datatype}
+ *
+ * \details H5Topen2() opens a committed datatype at the location specified
+ * by \p loc_id and returns an identifier for the datatype. \p
+ * loc_id is either a file or group identifier. The identifier should
+ * eventually be closed by calling H5Tclose() to release resources.
+ *
+ * The committed datatype is opened with the datatype access property
+ * list tapl_id.
+ *
+ * \since 1.8.0
+ *
+ */
H5_DLL hid_t H5Topen2(hid_t loc_id, const char *name, hid_t tapl_id);
+/**
+ * \ingroup H5T
+ *
+ * \brief Commits a transient datatype to a file, creating a new named
+ * datatype, but does not link it into the file structure
+ *
+ * \fg_loc_id
+ * \type_id
+ * \tcpl_id
+ * \tapl_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Tcommit_anon() commits a transient datatype (not immutable)
+ * to a file, turning it into a named datatype with the specified
+ * creation and property lists. With default property lists,
+ * #H5P_DEFAULT, H5Tcommit_anon() provides similar functionality to
+ * that of H5Tcommit(), with the differences described below.
+ *
+ * #H5P_DEFAULT can be passed in for the datatype creation property
+ * list identifier, \p tcpl_id. The datatype access property list
+ * identifier, \p tapl_id, is provided for future functionality and
+ * is not used at this time. This parameter should always be passed
+ * as the value #H5P_DEFAULT.
+ *
+ * Note that H5Tcommit_anon() does not link this newly-committed
+ * datatype into the file. After the H5Tcommit_anon() call, the
+ * datatype identifier \p type_id must be linked into the HDF5 file
+ * structure with H5Olink() or it will be deleted from the file when
+ * the file is closed.
+ *
+ * The differences between this function and H5Tcommit() are as follows:
+ * \li H5Tcommit_anon() explicitly includes property lists,
+ * which provides for greater control of the creation process
+ * and of the properties of the new named datatype. H5Tcommit()
+ * always uses default properties.
+ * \li H5Tcommit_anon() neither provides the new named datatype’s
+ * name nor links it into the HDF5 file structure; those actions
+ * must be performed separately through a call to H5Olink(),
+ * which offers greater control over linking.
+ *
+ * This function will not accept a datatype that cannot actually
+ * hold data. This currently includes compound datatypes with no
+ * fields and enumerated datatypes with no members.
+ *
+ * \version 1.8.7 Function modified in this release to reject datatypes that
+ * will not accomodate actual data, such as a compound datatype
+ * with no fields or an enumerated datatype with no members.
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL herr_t H5Tcommit_anon(hid_t loc_id, hid_t type_id, hid_t tcpl_id, hid_t tapl_id);
+/**
+ * \ingroup H5T
+ *
+ * \brief Returns a copy of a datatype's creation property list
+ *
+ * \type_id
+ *
+ * \return \hid_t{datatype creation property list}
+ *
+ * \details H5Tget_create_plist() returns a property list identifier
+ * for the datatype creation property list associated with the datatype
+ * specified by \p type_id.
+ *
+ * The creation property list identifier should be released with
+ * H5Pclose() to prevent memory leaks.
+ *
+ * \since 1.8.0
+ *
+ */
H5_DLL hid_t H5Tget_create_plist(hid_t type_id);
+/**
+ * \ingroup H5T
+ *
+ * \brief Determines whether a datatype is a committed type or a transient type
+ *
+ * \type_id
+ *
+ * \return \htri_t
+ *
+ * \details H5Tcommitted() queries a type to determine whether the type
+ * specified by the \p dtype_id identifier is a committed (formerly
+ * known as a \Emph{named}) type or a transient type. If this function returns
+ * a positive value, then the type is committed (that is, it has been
+ * committed, perhaps by some other application). Datasets which
+ * return committed datatypes with H5Dget_type() are able to share
+ * the datatype with other datasets in the same file.
+ *
+ * \version 1.8.0 Fortran API was added
+ *
+ * \since 1.6 or earlier
+ *
+ */
H5_DLL htri_t H5Tcommitted(hid_t type_id);
+/**
+ * \ingroup H5T
+ *
+ * \brief Encodes a datatype object description into a binary buffer
+ *
+ * \param[in] obj_id Identifier of the object to be encoded
+ * \param[in,out] buf Buffer for the object to be encoded into.
+ * \param[in,out] nalloc IN: The size of the allocated buffer
+ * OUT: The size of the buffer needed
+ *
+ * \return \herr_t
+ *
+ * \details H5Tencode() Given datatype identifier, H5Tencode() converts a
+ * datatype description into binary form in a buffer. Using this
+ * binary form in the buffer, a datatype object can be reconstructed
+ * using H5Tdecode() to return a new object handle (\ref hid_t) for
+ * this datatype.
+ *
+ * If the provided buffer is NULL, only the size of buffer needed is
+ * returned through \p nalloc.
+ *
+ * A preliminary H5Tencode() call can be made to find out the size
+ * of the buffer needed. This value is returned as \p nalloc. That
+ * value can then be assigned to \p nalloc for a second H5Tencode()
+ * call, which will retrieve the actual encoded object.
+ *
+ * If the library finds that \p nalloc is not big enough for the
+ * object, it simply returns the size of the buffer needed through
+ * \p nalloc without encoding the provided buffer.
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL herr_t H5Tencode(hid_t obj_id, void *buf, size_t *nalloc);
+/**
+ * \ingroup H5T
+ *
+ * \brief Decodes a binary object description of datatype and return a new
+ * object handle
+ *
+ * \param[in] buf Buffer for the datatype object to be decoded
+ *
+ * \return \hid_t{datatype}
+ *
+ * \details H5Tdecode() Given an object description of datatype in binary in a
+ * buffer, H5Tdecode() reconstructs the HDF5 datatype object and
+ * returns a new object handle for it. The binary description of
+ * the object is encoded by H5Tencode(). User is responsible for
+ * passing in the right buffer.
+ *
+ * The datatype identifier returned by this function can be released
+ * with H5Tclose() when the identifier is no longer needed so that
+ * resource leaks will not develop.
+ *
+ */
H5_DLL hid_t H5Tdecode(const void *buf);
+/**
+ * \ingroup H5T
+ *
+ * \brief Flushes all buffers associated with a committed datatype to disk
+ *
+ * \type_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Tflush() causes all buffers associated with a committed datatype
+ * \p type_id to be immediately flushed to disk without removing the
+ * data from the cache.
+ *
+ * HDF5 does not possess full control over buffering. H5Tflush()
+ * flushes the internal HDF5 buffers and then asks the operating
+ * system (the OS) to flush the system buffers for the open
+ * files. After that, the OS is responsible for ensuring that the
+ * data is actually flushed to disk.
+ *
+ * \return \herr_t
+ *
+ * \since 1.10.0 C function introduced with this release.
+ *
+ * \see H5Dflush()
+ * H5Drefresh()
+ * H5Tflush()
+ * H5Grefresh()
+ * H5Oflush()
+ * H5Orefresh()
+ * H5Tflush()
+ * H5Trefresh()
+ * H5Fstart_swmr_write()
+ * H5Pget_append_flush()
+ * H5Pget_object_flush_cb()
+ * H5Pset_append_flush()
+ * H5Pset_object_flush_cb()
+ *
+ */
H5_DLL herr_t H5Tflush(hid_t type_id);
+/**
+ * \ingroup H5T
+ *
+ * \brief Refreshes all buffers associated with a committed datatype
+ *
+ * \type_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Trefresh() causes all buffers associated with a committed
+ * datatype to be cleared and immediately re-loaded with updated
+ * contents from disk.
+ *
+ * This function essentially closes the datatype, evicts all
+ * metadata associated with it from the cache, and then re-opens the
+ * datatype. The reopened datatype is automatically re-registered
+ * with the same identifier.
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL herr_t H5Trefresh(hid_t type_id);
/* Operations defined on compound datatypes */
+/**
+ * \ingroup COMPOUND
+ *
+ * \brief Adds a new member to a compound datatype.
+ *
+ * \type_id{parent_id}
+ * \param[in] name Name of the field to insert
+ * \param[in] offset Offset in memory structure of the field to insert
+ * \param[in] member_id Datatype identifier of the field to insert
+ *
+ * \return \herr_t
+ *
+ * \details H5Tinsert() adds another member to the compound datatype, specified
+ * \p type_id.
+ *
+ * The new member has a \p name which must be unique within the
+ * compound datatype. The \p offset argument defines the start of the
+ * member in an instance of the compound datatype, and \p member_id
+ * is the datatype identifier of the new member.
+ *
+ * \note Members of a compound datatype do not have to be atomic
+ * datatypes; a compound datatype can have a member which is a
+ * compound datatype.
+ *
+ * \since 1.2.0
+ *
+ * \todo Create example for H5Tinsert
+ *
+ */
H5_DLL herr_t H5Tinsert(hid_t parent_id, const char *name, size_t offset, hid_t member_id);
+/**
+ * \ingroup COMPOUND
+ *
+ * \brief Recursively removes padding from within a compound datatype
+ *
+ * \type_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Tpack() recursively removes padding from within a compound
+ * datatype to make it more efficient (space-wise) to store that data.
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL herr_t H5Tpack(hid_t type_id);
/* Operations defined on enumeration datatypes */
+/**
+ * \ingroup ENUM
+ *
+ * \brief Creates a new enumeration datatype
+ *
+ * \param[in] base_id Datatype identifier for the base datatype. Must be an
+ * integer datatype
+ *
+ * \return \hid_t{enumeration datatype}
+ *
+ * \details H5Tenum_create() creates a new enumeration datatype based on the
+ * specified base datatype, dtype_id, which must be an integer datatype.
+ *
+ * If a particular architecture datatype is required, a little endian
+ * or big endian datatype for example, use a native datatype as the
+ * base datatype and use H5Tconvert() on values as they are read
+ * from or written to a dataset.
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL hid_t H5Tenum_create(hid_t base_id);
+/**
+ * \ingroup ENUM
+ *
+ * \brief Inserts a new enumeration datatype member
+ *
+ * \type_id{type}
+ * \param[in] name Name of the new member
+ * \param[in] value Pointer to the value of the new member
+ *
+ * \return \herr_t
+ *
+ * \details H5Tenum_insert() inserts a new enumeration datatype member into an
+ * enumeration datatype.
+ *
+ * \p type_id is the datatype identifier for the enumeration datatype,
+ * \p name is the name of the new member, and \p value points to the
+ * value of the new member.
+ *
+ * \p name and \p value must both be unique within \p dtype_id.
+ *
+ * \p value points to data which must be of the integer base datatype
+ * used when the enumeration datatype was created. If a particular
+ * architecture datatype is required, a little endian or big endian
+ * datatype for example, use a native datatype as the base datatype
+ * and use H5Tconvert() on values as they are read from or written
+ * to a dataset.
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL herr_t H5Tenum_insert(hid_t type, const char *name, const void *value);
+/**
+ * \ingroup ENUM
+ *
+ * \brief Returns the symbol name corresponding to a specified member of an
+ * enumeration datatype
+ *
+ * \type_id{type}
+ * \param[in] value Value of the enumeration datatype
+ * \param[out] name Buffer for output of the symbol name
+ * \param[in] size Anticipated size of the symbol name, in bytes
+ *
+ * \return Returns a non-negative value if successful. Otherwise returns a
+ * negative value
+ *
+ * \details H5Tenum_nameof() finds the symbol name that corresponds to the
+ * specified \p value of the enumeration datatype \p type.
+ *
+ * At most \p size characters of the symbol \p name are copied into
+ * the \p name buffer. If the entire symbol name and null terminator
+ * do not fit in the name buffer, then as many characters as possible
+ * are copied (not null terminated) and the function fails.
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL herr_t H5Tenum_nameof(hid_t type, const void *value, char *name /*out*/, size_t size);
+/**
+ * \ingroup ENUM
+ *
+ * \brief Returns the value corresponding to a specified member of an
+ * enumeration datatype
+ *
+ * \type_id{type}
+ * \param[in] name Symbol name of the enumeration datatype
+ * \param[out] value Buffer for the value of the enumeration datatype
+ *
+ * \return \herr_t
+ *
+ * \details H5Tenum_valueof() finds the value that corresponds to the
+ * specified name of the enumeration datatype \p dtype_id.
+ *
+ * Values returned in \p value will be of the enumerated type’s
+ * base type, that is, the datatype used by H5Tenum_create() when
+ * the enumerated type was created.
+ *
+ * The \p value buffer must be at least large enough to hold a value
+ * of that base type. If the size is unknown, you can determine it
+ * with H5Tget_size().
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL herr_t H5Tenum_valueof(hid_t type, const char *name, void *value /*out*/);
/* Operations defined on variable-length datatypes */
+/**
+ * \ingroup VLEN
+ *
+ * \brief Creates a new variable-length array datatype
+ *
+ * \type_id{base_id}, the element type of the datatype to create
+ *
+ * \return \hid_t{variable-length datatype}
+ *
+ * \details H5Tvlen_create() creates a new one-dimensional array datatype of
+ * variable-length (VL) with the base datatype \p base_id.
+ *
+ * This one-dimensional array often represents a data sequence of the
+ * base datatype, such as characters for character sequences or vertex
+ * coordinates for polygon lists. The base type specified for the VL
+ * datatype can be any HDF5 datatype, including another VL datatype, a
+ * compound datatype, or an atomic datatype.
+ *
+ * When necessary, use H5Tget_super() to determine the base type of
+ * the VL datatype.
+ *
+ * The datatype identifier returned from this function should be
+ * released with H5Tclose() or resource leaks will result. Under
+ * certain circumstances, H5Dvlen_reclaim() must also be used.
+ *
+ * \attention H5Tvlen_create() cannot be used to create a variable-length
+ * string datatype. H5Tvlen_create() called with a string or
+ * character base type creates a variable-length sequence of strings
+ * (a variable-length, 1-dimensional array), with each element of
+ * the array being of the string or character base type.\n
+ * To create a variable-length string datatype, see "Creating
+ * variable-length string datatypes."
+ *
+ * \todo Fix the reference.
+ *
+ */
H5_DLL hid_t H5Tvlen_create(hid_t base_id);
/* Operations defined on array datatypes */
+/**
+ * \ingroup ARRAY
+ *
+ * \brief Creates an array datatype object
+ *
+ * \param[in] base_id Datatype identifier for the array base datatype
+ * \param[in] ndims Rank of the array
+ * \param[in] dim Size of each array dimension
+ *
+ * \return \hid_t{array datatype}
+ *
+ * \details H5Tarray_create2() creates a new array datatype object.\n\n
+ * \p base_id is the datatype of every element of the array, i.e.,
+ * of the number at each position in the array.
+ *
+ * \p ndims is the number of dimensions and the size of each dimension
+ * is specified in the array \p dim. The value of \p rank is
+ * currently limited to #H5S_MAX_RANK and must be greater than 0
+ * (zero). All dimension sizes specified in \p dim must be greater
+ * than 0 (zero).
+ *
+ * \since 1.8.0
+ *
+ */
H5_DLL hid_t H5Tarray_create2(hid_t base_id, unsigned ndims, const hsize_t dim[/* ndims */]);
+/**
+ * \ingroup ARRAY
+ *
+ * \brief Returns the rank of an array datatype
+ *
+ * \type_id
+ *
+ * \return Returns the rank of the array if successful; otherwise returns a
+ * negative value.
+ *
+ * \details H5Tget_array_ndims() returns the rank, i.e., the number of
+ * dimensions, of an array datatype object.
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL int H5Tget_array_ndims(hid_t type_id);
+/**
+ * \ingroup ARRAY
+ *
+ * \brief Retrieves sizes of array dimensions
+ *
+ * \type_id
+ * \param[out] dims Sizes of array dimensions
+ *
+ * \return Returns the non-negative number of dimensions of the array type
+ * if successful; otherwise returns a negative value.
+ *
+ * \details H5Tget_array_dims2() returns the sizes of the dimensions of the
+ * specified array datatype object in the array \p dims.
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL int H5Tget_array_dims2(hid_t type_id, hsize_t dims[]);
/* Operations defined on opaque datatypes */
+/**
+ * \ingroup OPAQUE
+ *
+ * \brief Tags an opaque datatype
+ *
+ * \type_id{type} of an opaque datatype
+ * \param[in] tag Descriptive ASCII string with which the opaque datatype is
+ * to be tagged
+ *
+ * \return \herr_t
+ *
+ * \details H5Tset_tag() tags an opaque datatype \p type with a descriptive
+ * ASCII identifier, \p tag.
+ *
+ * \p tag is intended to provide a concise description; the maximum
+ * size is hard-coded in the HDF5 library as 256 bytes
+ * (#H5T_OPAQUE_TAG_MAX).
+ *
+ * \version 1.6.5 The #H5T_OPAQUE_TAG_MAX macro constant, specifying the
+ * maximum size of an opaque datatype tag, was added in
+ * H5Tpublic.h.
+ *
+ */
H5_DLL herr_t H5Tset_tag(hid_t type, const char *tag);
+/**
+ * \ingroup OPAQUE
+ *
+ * \brief Gets the tag associated with an opaque datatype
+ *
+ * \type_id{type} of an opaque datatype
+ *
+ * \return Returns a pointer to an allocated string if successful; otherwise
+ * returns NULL.
+ *
+ * \details H5Tget_tag() returns the tag associated with the opaque datatype
+ * \p type.
+ *
+ * \attention The tag is returned via a pointer to an allocated string, which
+ * the caller must free.
+ *
+ */
H5_DLL char * H5Tget_tag(hid_t type);
/* Querying property values */
+/**
+ * \ingroup H5T
+ *
+ * \brief Returns the base datatype from which a datatype is derived
+ *
+ * \type_id{type}
+ *
+ * \return \hid_t{datatype}
+ *
+ * \details H5Tget_super() returns the base datatype from which the datatype
+ * \p type_id is derived. In the case of an enumeration type, the
+ * return value is an integer type.
+ *
+ * The datatype identifier returned by this function must be released
+ * with H5Tclose() when the identifier is no longer needed so that
+ * resource leaks will not develop.
+ *
+ */
H5_DLL hid_t H5Tget_super(hid_t type);
+/**
+ * \ingroup H5T
+ *
+ * \brief Returns a datatype class
+ *
+ * \type_id
+ *
+ * \return Returns the datatype class if successful; otherwise #H5T_NO_CLASS.
+ *
+ * \details H5Tget_class() returns the class of the datatype \p type_id.
+ * Valid class identifiers, as defined in H5Tpublic.h, are:
+ * \snippet this H5T_class_t_snip
+ *
+ * \note The library returns #H5T_STRING for both fixed-length and
+ * variable-length strings.
+ *
+ * \note Unsupported datatype: The time datatype class, #H5T_TIME,
+ * is not supported. If #H5T_TIME is used, the resulting data will
+ * be readable and modifiable only on the originating computing
+ * platform; it will not be portable to other platforms.
+ *
+ */
H5_DLL H5T_class_t H5Tget_class(hid_t type_id);
+/**
+ * \ingroup H5T
+ *
+ * \brief Determines whether a datatype contains any datatypes of the given
+ * datatype class
+ *
+ * \type_id
+ * \param[in] cls Datatype class
+ *
+ * \return \htri_t
+ *
+ * \details H5Tdetect_class() determines whether the datatype specified in
+ * \p type_id contains any datatypes of the datatype class specified
+ * in \p dtype_class.
+ *
+ * This function is useful primarily in recursively examining all the
+ * fields and/or base types of compound, array, and variable-length
+ * datatypes.
+ *
+ * Valid class identifiers, as defined in H5Tpublic.h, are:
+ * \snippet this H5T_class_t_snip
+ *
+ * \since 1.6.0
+ *
+ */
H5_DLL htri_t H5Tdetect_class(hid_t type_id, H5T_class_t cls);
+/**
+ * \ingroup H5T
+ *
+ * \brief Returns the size of a datatype
+ *
+ * \type_id
+ *
+ * \return Returns the size of the datatype in bytes if successful; otherwise,
+ * returns 0.
+ *
+ * \details H5Tget_size() returns the size of a datatype in bytes.
+ * \li For atomic datatypes, array datatypes, compound datatypes, and
+ * other datatypes of a constant size, the returned value is the
+ * size of the actual datatype in bytes.
+ * \li For variable-length string datatypes the returned value is
+ * the size of the pointer to the actual string, or \c sizeof(\c
+ * char \c *). This function does not return the size of actual
+ * variable-length string data.
+ * \li For variable-length sequence datatypes (see H5Tvlen_create()),
+ * the returned value is the size of the \p hvl_t struct, or \c
+ * sizeof(\p hvl_t). The \p hvl_t struct contains a pointer to the
+ * actual data and a size value. This function does not return the
+ * size of actual variable-length sequence data.
+ *
+ * \since 1.2.0
+ *
+ * \see H5Tset_size()
+ *
+ * \todo Original has a reference to “Creating variable-length string datatypes”.
+ * \todo Create an example for H5Tget_size().
+ *
+ */
H5_DLL size_t H5Tget_size(hid_t type_id);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Returns the byte order of an atomic datatype
+ *
+ * \type_id
+ *
+ * \return Returns a byte order constant if successful; otherwise returns
+ * #H5T_ORDER_ERROR (-1)
+ *
+ * \details H5Tget_order() returns the byte order of an atomic datatype.
+ * Possible return values are:
+ * \snippet this H5T_order_t_snip
+ * Members of a compound datatype need not have the same byte
+ * order. If members of a compound datatype have more than one of
+ * little endian, big endian, or VAX byte order, H5Tget_order() will
+ * return #H5T_ORDER_MIXED for the compound datatype. A byte order of
+ * #H5T_ORDER_NONE will, however, be ignored; for example, if one or
+ * more members of a compound datatype have byte order #H5T_ORDER_NONE
+ * but all other members have byte order #H5T_ORDER_LE, H5Tget_order()
+ * will return #H5T_ORDER_LE for the compound datatype.
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL H5T_order_t H5Tget_order(hid_t type_id);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Returns the precision of an atomic datatype
+ *
+ * \type_id
+ *
+ * \return Returns the number of significant bits if successful; otherwise 0
+ *
+ * \details H5Tget_precision() returns the precision of an atomic datatype
+ * (for example, integer or float) or a datatype whose base (parent)
+ * type is an atomic type (for example, array, enum and variable
+ * length). The precision is the number of significant bits which,
+ * unless padding is present, is 8 times larger than the value
+ * returned by H5Tget_size().
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL size_t H5Tget_precision(hid_t type_id);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Retrieves the bit offset of the first significant bit
+ *
+ * \type_id
+ *
+ * \return Returns an offset value if successful; otherwise returns a
+ * negative value.
+ *
+ * \details H5Tget_offset() retrieves the bit offset of the first significant
+ * bit. The significant bits of an atomic datum can be offset from the
+ * beginning of the memory for that datum by an amount of padding. The
+ * 'offset' property specifies the number of bits of padding that
+ * appear to the "right of" the value. That is, if we have a 32-bit
+ * datum with 16-bits of precision having the value 0x1122 then it
+ * will be laid out in memory as (from small byte address toward
+ * larger byte addresses):
+ * \code{.unparsed}
+ * 0: [ pad] [0x11] [0x22] [ pad]
+ * 1: [ pad] [0x22] [0x11] [ pad]
+ * 2: [0x11] [ pad] [ pad] [0x22]
+ * 3: [0x22] [ pad] [ pad] [0x11]
+ * \endcode
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL int H5Tget_offset(hid_t type_id);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Retrieves the padding type of the least and most-significant bit padding
+ *
+ * \type_id
+ * \param[out] lsb Buffer for the least-significant bit padding type
+ * \param[out] msb Buffer for the most-significant bit padding type
+ *
+ * \return \herr_t
+ *
+ * \details H5Tget_pad() retrieves the padding type of the least and
+ * most-significant bit padding. Valid padding types are:
+ * \snippet this H5T_pad_t_snip
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL herr_t H5Tget_pad(hid_t type_id, H5T_pad_t *lsb /*out*/, H5T_pad_t *msb /*out*/);
-H5_DLL H5T_sign_t H5Tget_sign(hid_t type_id);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Retrieves the sign type for an integer type
+ *
+ * \type_id
+ *
+ * \return Returns a valid sign type if successful; otherwise #H5T_SGN_ERROR (-1)
+ *
+ * \details H5Tget_sign() retrieves the sign type for an integer type.
+ * Valid types are:
+ * \snippet this H5T_sign_t_snip
+ *
+ * \since 1.2.0
+ *
+ */
+H5_DLL H5T_sign_t H5Tget_sign(hid_t type_id);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Retrieves floating point datatype bit field information
+ *
+ * \type_id
+ * \param[out] spos Pointer to location to return floating-point sign bit
+ * \param[out] epos Pointer to location to return exponent bit-position
+ * \param[out] esize Pointer to location to return size of exponent in bits
+ * \param[out] mpos Pointer to location to return mantissa bit-position
+ * \param[out] msize Pointer to location to return size of mantissa in bits
+ *
+ * \return \herr_t
+ *
+ * \details H5Tget_fields() retrieves information about the locations of
+ * the various bit fields of a floating point datatype. The field
+ * positions are bit positions in the significant region of the
+ * datatype. Bits are numbered with the least significant bit number
+ * zero. Any (or even all) of the arguments can be null pointers.
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL herr_t H5Tget_fields(hid_t type_id, size_t *spos /*out*/, size_t *epos /*out*/, size_t *esize /*out*/,
size_t *mpos /*out*/, size_t *msize /*out*/);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Retrieves the exponent bias of a floating-point type
+ *
+ * \type_id
+ *
+ * \return Returns the bias if successful and 0, otherwise.
+ *
+ * \details H5Tget_ebias() retrieves the exponent bias of a floating-point type.
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL size_t H5Tget_ebias(hid_t type_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup ATOM
+ *
+ * \brief Retrieves mantissa normalization of a floating-point datatype
+ *
+ * \type_id
+ *
+ * \return Returns a valid normalization type if successful; otherwise
+ * returns #H5T_NORM_ERROR (-1)
+ *
+ * \details H5Tget_norm() retrieves the mantissa normalization of a
+ * floating-point datatype. Valid normalization types are:
+ * \snippet this H5T_norm_t_snip
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL H5T_norm_t H5Tget_norm(hid_t type_id);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Retrieves the internal padding type for unused bits in floating-point
+ * datatypes
+ *
+ * \type_id
+ *
+ * \return Returns a valid padding type if successful; otherwise returns
+ * #H5T_PAD_ERROR (-1).
+ *
+ * \details H5Tget_inpad() retrieves the internal padding type for unused
+ * bits in floating-point datatypes. Valid padding types are:
+ * \snippet this H5T_pad_t_snip
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL H5T_pad_t H5Tget_inpad(hid_t type_id);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Retrieves the type of padding used for a string datatype
+ *
+ * \type_id
+ *
+ * \return Returns a valid string of the padding if successful; otherwise
+ * returns #H5T_STR_ERROR (-1)
+ *
+ * \details H5Tget_strpad() retrieves the type of padding used for a string
+ * datatype.
+ *
+ * The string padding type is set with H5Tset_strpad(). Possible
+ * values returned are:
+ * \str_pad_type
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL H5T_str_t H5Tget_strpad(hid_t type_id);
+/**
+ * \ingroup COMPOUND
+ *
+ * \brief Retrieves the number of elements in a compound or enumeration datatype
+ *
+ * \type_id
+ *
+ * \return Returns the number of elements if successful; otherwise returns a
+ * negative value.
+ *
+ * \details H5Tget_nmembers() retrieves the number of fields in a compound
+ * datatype or the number of members of an enumeration datatype.
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL int H5Tget_nmembers(hid_t type_id);
+/**
+ * \ingroup COMPOUND
+ *
+ * \brief Retrieves the name of a compound or enumeration datatype member
+ *
+ * \type_id
+ * \param[in] membno Zero-based index of the field or element
+ *
+ * \return Returns a valid pointer to a string allocated with malloc() if
+ * successful; otherwise returns NULL.
+ *
+ * \details H5Tget_member_name() retrieves the name of a field of a compound
+ * datatype or an element of an enumeration datatype.
+ *
+ * The index of the target field or element is specified in \p
+ * member_no. Compound datatype fields and enumeration datatype
+ * elements are stored in no particular order with index values of
+ * 0 through N-1, where N is the value returned by H5Tget_nmembers().
+ *
+ * The HDF5 library allocates a buffer to receive the name of
+ * the field. The caller must subsequently free the buffer with
+ * H5free_memory().
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL char * H5Tget_member_name(hid_t type_id, unsigned membno);
+/**
+ * \ingroup COMPOUND
+ *
+ * \brief Retrieves the index of a compound or enumeration datatype member
+ *
+ * \type_id
+ * \param[in] name Name of the field or member
+ *
+ * \return \herr_t
+ *
+ * \details H5Tget_member_index() retrieves the index of a field of a compound
+ * datatype or an element of an enumeration datatype.
+ *
+ * The name of the target field or element is specified by \p name.
+ *
+ * Fields are stored in no particular order with index values of 0
+ * through N-1, where N is the value returned by H5Tget_nmembers() .
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL int H5Tget_member_index(hid_t type_id, const char *name);
+/**
+ * \ingroup COMPOUND
+ *
+ * \brief Retrieves the offset of a field of a compound datatype
+ *
+ * \type_id
+ * \param[in] membno Zero-based index of the field or element
+ *
+ * \return Returns the byte offset of the field if successful; otherwise
+ * returns 0 (zero).
+ *
+ * \details H5Tget_member_offset() retrieves the byte offset of the beginning
+ * of a field within a compound datatype with respect to the beginning
+ * of the compound datatype datum.
+ *
+ * Note that zero is a valid offset and that this function will fail
+ * only if a call to H5Tget_member_class() fails with the same arguments.
+ *
+ * \version 1.6.4 \p member_no parameter type changed to unsigned.
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL size_t H5Tget_member_offset(hid_t type_id, unsigned membno);
+/**
+ * \ingroup COMPOUND
+ *
+ * \brief Returns datatype class of compound datatype member
+ *
+ * \type_id
+ * \param[in] membno Zero-based index of the field or element
+ *
+ * \return Returns the datatype class, a non-negative value, if successful;
+ * otherwise returns a negative value.
+ *
+ * \details Given a compound datatype, \p dtype_id, H5Tget_member_class()
+ * returns the datatype class of the member specified by \p member_no.
+ *
+ * Valid class identifiers, as defined in H5Tpublic.h, are:
+ * \snippet this H5T_class_t_snip
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL H5T_class_t H5Tget_member_class(hid_t type_id, unsigned membno);
+/**
+ * \ingroup COMPOUND
+ *
+ * \brief Returns the datatype of the specified member
+ *
+ * \type_id
+ * \param[in] membno Zero-based index of the field or element
+ *
+ * \return Returns the identifier of a copy of the datatype of the field if
+ * successful; otherwise returns a negative value.
+ *
+ * \details H5Tget_member_type() returns the datatype of the specified member.
+ * The caller should invoke H5Tclose() to release resources associated
+ * with the type.
+ *
+ * \version 1.6.4 \p membno parameter type changed to unsigned.
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL hid_t H5Tget_member_type(hid_t type_id, unsigned membno);
+/**
+ * \ingroup ENUM
+ *
+ * \brief Returns the value of an enumeration datatype member
+ *
+ * \type_id
+ * \param[in] membno Number of the enumeration datatype member
+ * \param[out] value Buffer for the value of the enumeration datatype member
+ *
+ * \return \herr_t
+ *
+ * \details H5Tget_member_value() returns the value of the enumeration datatype
+ * member \p member_no.
+ *
+ * The member value is returned in a user-supplied buffer pointed to
+ * by \p value. Values returned in \p value will be of the enumerated
+ * type’s base type, that is, the datatype used by H5Tenum_create()
+ * when the enumerated type was created.
+ *
+ * The value buffer must be at least large enough to hold a value
+ * of that base type. If the size is unknown, you can determine it
+ * with H5Tget_size().
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL herr_t H5Tget_member_value(hid_t type_id, unsigned membno, void *value /*out*/);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Retrieves the character set type of a string datatype
+ *
+ * \type_id
+ *
+ * \return Returns a valid character set type if successful; otherwise
+ * #H5T_CSET_ERROR (-1).
+ *
+ * \details H5Tget_cset() retrieves the character set type of a string datatype.
+ * Valid character set types are:
+ * \csets
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL H5T_cset_t H5Tget_cset(hid_t type_id);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Determines whether datatype is a variable-length string
+ *
+ * \type_id
+ *
+ * \return Returns:
+ * \li a positive value if the specified datatype is a variable-length
+ * string
+ * \li 0 if the specified datatype is not a variable-length string
+ * \li a negative value when the function fails
+ *
+ * \details H5Tis_variable_str() determines whether the datatype identified
+ * by \p dtype_id is a variable-length string.
+ *
+ * This function can be used to distinguish between fixed and
+ * variable-length string datatypes.
+ *
+ * \since 1.6.0
+ *
+ */
H5_DLL htri_t H5Tis_variable_str(hid_t type_id);
+/**
+ * \ingroup H5T
+ *
+ * \brief Returns the native datatype identifier of a specified datatype
+ *
+ * \type_id
+ * \param[in] direction Direction of search
+ *
+ * \return \hid_t{native datatype}
+ *
+ * \details H5Tget_native_type() returns the equivalent native datatype
+ * identifier for the datatype specified by \p type_id.
+ *
+ * H5Tget_native_type() is designed primarily to facilitate use of
+ * the H5Dread() function, for which users otherwise must undertake a
+ * multi-step process to determine the native datatype of a dataset
+ * prior to reading it into memory. This function can be used for
+ * the following purposes:
+ *
+ * \li To determine the native datatype of an atomic datatype
+ * \li To determine the base datatype of an array, enumerated, or
+ * variable-length datatype
+ * \li To determine the native atomic datatypes of the individual
+ * components of a compound datatype
+ *
+ * For example, if \p type_id is a compound datatype, the returned
+ * datatype identifier will be for a similar compound datatype with
+ * each element converted to the corresponding native datatype;
+ * nested compound datatypes will be unwound. If \p type_id is an
+ * array, the returned datatype identifier will be for the native
+ * datatype of a single array element.
+ *
+ * H5Tget_native_type() selects the first matching native datatype
+ * from the following list:
+ *
+ * \li #H5T_NATIVE_CHAR
+ * \li #H5T_NATIVE_SHORT
+ * \li #H5T_NATIVE_INT
+ * \li #H5T_NATIVE_LONG
+ * \li #H5T_NATIVE_LLONG
+ *
+ * \li #H5T_NATIVE_UCHAR
+ * \li #H5T_NATIVE_USHORT
+ * \li #H5T_NATIVE_UINT
+ * \li #H5T_NATIVE_ULONG
+ * \li #H5T_NATIVE_ULLONG
+ *
+ * \li #H5T_NATIVE_FLOAT
+ * \li #H5T_NATIVE_DOUBLE
+ * \li #H5T_NATIVE_LDOUBLE
+ *
+ * \li #H5T_NATIVE_B8
+ * \li #H5T_NATIVE_B16
+ * \li #H5T_NATIVE_B32
+ * \li #H5T_NATIVE_B64
+ *
+ * The direction parameter indicates the order in which the library
+ * searches for a native datatype match. Valid values for direction
+ * are as follows:
+ * \snippet this H5T_direction_t_snip
+ *
+ * H5Tget_native_type() is designed primarily for use with integer,
+ * floating point, and bitfield datatypes. String, time, opaque, and
+ * reference datatypes are returned as a copy of dtype_id. See above
+ * for compound, array, enumerated, and variable-length datatypes.
+ *
+ * The identifier returned by H5Tget_native_type() should eventually
+ * be closed by calling H5Tclose() to release resources.
+ *
+ * \note Please note that a datatype is actually an object
+ * identifier or handle returned from opening the datatype. It
+ * is not persistent and its value can be different from one HDF5
+ * session to the next.
+ *
+ * \note H5Tequal() can be used to compare datatypes.
+ *
+ * \note HDF5 High Level APIs that may also be of interest are: H5LTdtype_to_text()
+ * creates a text description of a datatype. H5LTtext_to_dtype() creates an
+ * HDF5 datatype given a text description.
+ *
+ * \since 1.6.0
+ *
+ */
H5_DLL hid_t H5Tget_native_type(hid_t type_id, H5T_direction_t direction);
/* Setting property values */
+/**
+ * \ingroup H5T
+ *
+ * \brief Sets size for a datatype.
+ *
+ * \type_id
+ * \param[in] size New datatype size is bytes or #H5T_VARIABLE
+ *
+ * \return \herr_t
+ *
+ * \details H5Tset_size() sets the total size, \p size, in bytes, for a
+ * datatype.
+ *
+ * \p size must have a positive value, unless it is passed in as
+ * #H5T_VARIABLE and the datatype is a string datatype.
+ *
+ * \li Numeric datatypes: If the datatype is atomic and the size
+ * is decreased so that significant bits of the datatype extend
+ * beyond the edge of the new size, then the offset property of the
+ * datatype is decreased toward zero. If the offset becomes zero
+ * and the significant bits of the datatype still hang over the edge
+ * of the new size, then the number of significant bits is decreased.
+ *
+ * \li String or character datatypes: The size set for a string
+ * datatype should include space for the null-terminator character,
+ * otherwise it will not be stored on (or retrieved from)
+ * disk. Adjusting the size of a string automatically sets the
+ * precision to \p 8*size.
+ *
+ * \li Variable-length string datatypes: If \p dtype_id is a
+ * variable-length string, size must normally be set to #H5T_VARIABLE.
+ *
+ * \li Compound datatypes: This function may be used to increase or
+ * decrease the size of a compound datatype, but the function will
+ * fail if the new size is too small to accommodate all member fields.
+ *
+ * \li Ineligible datatypes: This function cannot be used with
+ * enumerated datatypes (#H5T_ENUM), array datatypes (#H5T_ARRAY),
+ * variable-length array datatypes (#H5T_VLEN), or reference datatypes
+ * (#H5T_REFERENCE).
+ *
+ * \since 1.2.0
+ *
+ * \see H5Tget_size()
+ *
+ *\todo Create an example for H5Tset_size().
+ *\todo Original has a reference to “Creating variable-length string datatypes”.
+ *
+ */
H5_DLL herr_t H5Tset_size(hid_t type_id, size_t size);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Sets the byte order of a datatype
+ *
+ * \type_id
+ * \param[in] order Byte order constant
+ *
+ * \return \herr_t
+ *
+ * \details H5Tset_order() sets the byte order of a datatype.\n
+ * Byte order can currently be set to any of the following:
+ * \snippet this H5T_order_t_snip
+ * #H5T_ORDER_MIXED (3) is a valid value for order only when
+ * returned by the function H5Tget_order(); it cannot be set with
+ * H5Tset_order().
+ *
+ * #H5T_ORDER_NONE (4) is a valid value for order, but it has no
+ * effect. It is valid only for fixed-length strings and object and
+ * region references and specifies “no particular order.”
+ *
+ * The byte order of a derived datatype is initially the same as
+ * that of the parent type, but can be changed with H5Tset_order().
+ *
+ * This function cannot be used with a datatype after it has been
+ * committed.
+ *
+ * \note Special considerations:
+ * \li ENUM datatypes: Byte order must be set before any member on
+ * an ENUM is defined.
+ * \li Compound datatypes: Byte order is set individually on each member
+ * of a compound datatype; members of a compound datatype need not
+ * have the same byte order.
+ * \li Opaque datatypes: Byte order can be set but has no effect.
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL herr_t H5Tset_order(hid_t type_id, H5T_order_t order);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Sets the precision of an atomic datatype
+ *
+ * \type_id
+ * \param[in] prec Number of bits of precision for datatype
+ *
+ * \return \herr_t
+ *
+ * \details H5Tset_precision() sets the precision of an atomic datatype. The
+ * precision is the number of significant bits which, unless
+ * padding is present, is 8 times larger than the value returned
+ * by H5Tget_size().
+ *
+ * If the precision is increased then the offset is decreased and
+ * then the size is increased to insure that significant bits do not
+ * "hang over" the edge of the datatype.
+ *
+ * Changing the precision of an #H5T_STRING automatically changes
+ * the size as well. The precision must be a multiple of 8.
+ *
+ * When decreasing the precision of a floating point type, set the
+ * locations and sizes of the sign, mantissa, and exponent fields
+ * first.
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL herr_t H5Tset_precision(hid_t type_id, size_t prec);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Sets the bit offset of the first significant bit
+ *
+ * \type_id
+ * \param[in] offset Offset of first significant bit
+ *
+ * \return \herr_t
+ *
+ * \details H5Tset_offset() sets the bit offset of the first significant
+ * bit. The significant bits of an atomic datum can be offset from
+ * the beginning of the memory for that datum by an amount of
+ * padding. The offset property specifies the number of bits of
+ * padding that appear “to the right of” the value. That is,
+ * if we have a 32-bit datum with 16-bits of precision having the
+ * value 0x1122, then it will be laid out in memory as (from small
+ * byte address toward larger byte addresses):
+ * \code{.unparsed}
+ * 0: [ pad] [0x11] [0x22] [ pad]
+ * 1: [ pad] [0x22] [0x11] [ pad]
+ * 2: [0x11] [ pad] [ pad] [0x22]
+ * 3: [0x22] [ pad] [ pad] [0x11]
+ * \endcode
+ * If the offset is incremented then the total size is incremented
+ * also if necessary to prevent significant bits of the value from
+ * hanging over the edge of the datatype.
+ *
+ * The offset of an #H5T_STRING cannot be set to anything but zero.
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL herr_t H5Tset_offset(hid_t type_id, size_t offset);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Sets the least and most-significant bits padding types
+ *
+ * \type_id
+ * \param[in] lsb Padding type for least-significant bits
+ * \param[in] msb Padding type for most-significant bits
+ *
+ * \return \herr_t
+ *
+ * \details H5Tset_pad() sets the least and most-significant bits padding types.
+ * Available values are:
+ * \padding_type
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL herr_t H5Tset_pad(hid_t type_id, H5T_pad_t lsb, H5T_pad_t msb);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Sets the sign property for an integer type
+ *
+ * \type_id
+ * \param[in] sign Sign type
+ *
+ * \return \herr_t
+ *
+ * \details H5Tset_sign() sets the sign property for an integer type:
+ * \sign_prop
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL herr_t H5Tset_sign(hid_t type_id, H5T_sign_t sign);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Sets locations and sizes of floating point bit fields
+ *
+ * \type_id
+ * \param[in] spos Sign position, i.e., the bit offset of the floating-point
+ * sign bit
+ * \param[in] epos Exponent bit position
+ * \param[in] esize Size of exponent in bits
+ * \param[in] mpos Mantissa bit position
+ * \param[in] msize Size of mantissa in bits
+ *
+ * \return \herr_t
+ *
+ * \details H5Tset_fields() sets the locations and sizes of the various
+ * floating-point bit fields. The field positions are bit positions
+ * in the significant region of the datatype. Bits are numbered with
+ * the least significant bit number zero.
+ *
+ * Fields are not allowed to extend beyond the number of bits of
+ * precision, nor are they allowed to overlap with one another.
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL herr_t H5Tset_fields(hid_t type_id, size_t spos, size_t epos, size_t esize, size_t mpos, size_t msize);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Sets the exponent bias of a floating-point type
+ *
+ * \type_id
+ * \param[in] ebias Exponent bias value
+ *
+ * \return \herr_t
+ *
+ * \details H5Tset_ebias() sets the exponent bias of a floating-point type.
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL herr_t H5Tset_ebias(hid_t type_id, size_t ebias);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Sets the mantissa normalization of a floating-point datatype
+ *
+ * \type_id
+ * \param[in] norm Mantissa normalization type
+ *
+ * \return \herr_t
+ *
+ * \details H5Tset_norm() sets the mantissa normalization of a floating-point
+ * datatype. Valid normalization types are:
+ * \snippet this H5T_norm_t_snip
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL herr_t H5Tset_norm(hid_t type_id, H5T_norm_t norm);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Fills unused internal floating-point bits
+ *
+ * \type_id
+ * \param[in] pad Padding type
+ *
+ * \return \herr_t
+ *
+ * \details H5Tset_inpad() If any internal bits of a floating point-type are
+ * unused (that is, those significant bits which are not part of the
+ * sign, exponent, or mantissa), then H5Tset_inpad() will be filled
+ * according to the value of the padding value property inpad. Valid
+ * padding types are:
+ * \snippet this H5T_pad_t_snip
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL herr_t H5Tset_inpad(hid_t type_id, H5T_pad_t pad);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Sets character set to be used in a string or character datatype
+ *
+ * \type_id
+ * \param[in] cset Character set type
+ *
+ * \return \herr_t
+ *
+ * \details H5Tset_cset() sets the character set to be used in a dataset with
+ * a string or character datatype.
+ *
+ * Valid values for cset include the following:
+ * \csets
+ * For example, if the character set for the datatype \p type_id is set
+ * to #H5T_CSET_UTF8, string or character data of datatype dtype_id
+ * will be encoded using the UTF-8 Unicode character set.
+ *
+ * ASCII and UTF-8 Unicode are the only currently supported character
+ * encodings. Extended ASCII encodings (for example, ISO 8859) are
+ * not supported. This encoding policy is not enforced by the HDF5
+ * library. Using encodings other than ASCII and UTF-8 can lead to
+ * compatibility and usability problems.
+ *
+ * Note that H5Tset_cset() sets the character set for a character or
+ * string datatype while H5Pset_char_encoding() sets the character
+ * set used for an HDF5 link or attribute name.
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL herr_t H5Tset_cset(hid_t type_id, H5T_cset_t cset);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Defines the type of padding used for character strings
+ *
+ * \type_id
+ * \param[in] strpad String padding type
+ *
+ * \return \herr_t
+ *
+ * \details H5Tset_strpad() defines the type of padding used for a string
+ * datatype.
+ *
+ * The method used to store character strings differs with the
+ * programming language. C usually null terminates strings while
+ * Fortran left-justifies and space-pads strings.
+ *
+ * Valid values of \p strpad are as follows:
+ * \str_pad_type
+ * When converting from a longer string to a shorter string, the
+ * behavior is as follows. If the shorter string is #H5T_STR_NULLPAD
+ * or #H5T_STR_SPACEPAD, then the string is simply truncated. If
+ * the short string is #H5T_STR_NULLTERM, it is truncated and a null
+ * terminator is appended.
+ *
+ * When converting from a shorter string to a longer string, the
+ * longer string is padded on the end by appending nulls or spaces.
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL herr_t H5Tset_strpad(hid_t type_id, H5T_str_t strpad);
/* Type conversion database */
+/**
+ * \ingroup CONV
+ *
+ * \brief Registers a datatype conversion function
+ *
+ * \param[in] pers Conversion function type
+ * \param[in] name Name displayed in diagnostic output
+ * \type_id{src_id} of source datatype
+ * \type_id{dst_id} of destination datatype
+ * \param[in] func Function to convert between source and destination datatypes
+ *
+ * \return \herr_t
+ *
+ * \details H5Tregister() registers a hard or soft conversion function for a
+ * datatype conversion path. The parameter \p pers indicates whether a
+ * conversion function is hard (#H5T_PERS_HARD) or soft
+ * (#H5T_PERS_SOFT). User-defined functions employing compiler casting
+ * are designated as \Emph{hard}; other user-defined conversion
+ * functions registered with the HDF5 library (with H5Tregister() )
+ * are designated as \Emph{soft}. The HDF5 library also has its own
+ * hard and soft conversion functions.
+ *
+ * A conversion path can have only one hard function. When type is
+ * #H5T_PERS_HARD, \p func replaces any previous hard function.
+ *
+ * When type is #H5T_PERS_SOFT, H5Tregister() adds the function to the
+ * end of the master soft list and replaces the soft function in all
+ * applicable existing conversion paths. Soft functions are used when
+ * determining which conversion function is appropriate for this path.
+ *
+ * The \p name is used only for debugging and should be a short
+ * identifier for the function.
+ *
+ * The path is specified by the source and destination datatypes \p
+ * src_id and \p dst_id. For soft conversion functions, only the class
+ * of these types is important.
+ *
+ * The type of the conversion function pointer is declared as:
+ * \snippet this H5T_conv_t_snip
+ *
+ * The \ref H5T_cdata_t \c struct is declared as:
+ * \snippet this H5T_cdata_t_snip
+ *
+ * \since 1.6.3 The following change occurred in the \ref H5T_conv_t function:
+ * the \c nelmts parameter type changed to size_t.
+ *
+ */
H5_DLL herr_t H5Tregister(H5T_pers_t pers, const char *name, hid_t src_id, hid_t dst_id, H5T_conv_t func);
+/**
+ * \ingroup CONV
+ *
+ * \brief Removes a conversion function
+ *
+ * \param[in] pers Conversion function type
+ * \param[in] name Name displayed in diagnostic output
+ * \type_id{src_id} of source datatype
+ * \type_id{dst_id} of destination datatype
+ * \param[in] func Function to convert between source and destination datatypes
+ *
+ * \return \herr_t
+ *
+ * \details H5Tunregister() removes a conversion function matching criteria
+ * such as soft or hard conversion, source and destination types, and
+ * the conversion function.
+ *
+ * If a user is trying to remove a conversion function he registered,
+ * all parameters can be used. If he is trying to remove a library’s
+ * default conversion function, there is no guarantee the \p name and
+ * \p func parameters will match the user’s chosen values. Passing in
+ * some values may cause this function to fail. A good practice is to
+ * pass in NULL as their values.
+ *
+ * All parameters are optional. The missing parameters will be used to
+ * generalize the search criteria.
+ *
+ * The conversion function pointer type declaration is described in
+ * H5Tregister().
+ *
+ * \version 1.6.3 The following change occurred in the \ref H5T_conv_t function:
+ * the \c nelmts parameter type changed to size_t.
+ *
+ */
H5_DLL herr_t H5Tunregister(H5T_pers_t pers, const char *name, hid_t src_id, hid_t dst_id, H5T_conv_t func);
+/**
+ * \ingroup CONV
+ *
+ * \brief Finds a conversion function
+ *
+ * \type_id{src_id} of source datatype
+ * \type_id{dst_id} of destination datatype
+ * \param[out] pcdata Pointer to type conversion data
+ *
+ * \return Returns a pointer to a suitable conversion function if successful.
+ * Otherwise returns NULL.
+ *
+ * \details H5Tfind() finds a conversion function that can handle a conversion
+ * from type \p src_id to type \p dst_id. The \p pcdata argument is a
+ * pointer to a pointer to type conversion data which was created and
+ * initialized by the soft type conversion function of this path when
+ * the conversion function was installed on the path.
+ *
+ */
H5_DLL H5T_conv_t H5Tfind(hid_t src_id, hid_t dst_id, H5T_cdata_t **pcdata);
+/**
+ * \ingroup CONV
+ *
+ * \brief Check whether the library’s default conversion is hard conversion
+ *
+ * \type_id{src_id} of source datatype
+ * \type_id{dst_id} of destination datatype
+ *
+ * \return \htri_t
+ *
+ * \details H5Tcompiler_conv() determines whether the library’s conversion
+ * function from type \p src_id to type \p dst_id is a compiler (hard)
+ * conversion or not. A compiler conversion uses compiler’s casting; a
+ * library (soft) conversion uses the library’s own conversion
+ * function.
+ *
+ * \since 1.8.0
+ *
+ */
H5_DLL htri_t H5Tcompiler_conv(hid_t src_id, hid_t dst_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup CONV
+ *
+ * \brief Converts data from one specified datatype to another
+ *
+ * \type_id{src_id} of source datatype
+ * \type_id{dst_id} of destination datatype
+ * \param[in] nelmts Size of array \p buf
+ * \param[in,out] buf Array containing pre- and post-conversion values
+ * \param[in] background Optional background buffer
+ * \dxpl_id{plist_id}
+ *
+ * \return \herr_t
+ *
+ * \details H5Tconvert() converts \p nelmts elements from a source datatype,
+ * specified by \p src_id, to a destination datatype, \p dst_id. The
+ * source elements are packed in \p buf and on return the destination
+ * elements will be packed in \p buf. That is, the conversion is
+ * performed in place.
+ *
+ * The optional background buffer is for use with compound datatypes.
+ * It is an array of \p nelmts values for the destination datatype
+ * which can then be merged with the converted values to recreate the
+ * compound datatype. For instance, background might be an array of
+ * structs with the \c a and \c b fields already initialized and the
+ * conversion of buf supplies the \c c and \c d field values.
+ *
+ * The parameter \p plist_id contains the dataset transfer property list
+ * identifier which is passed to the conversion functions. As of
+ * Release 1.2, this parameter is only used to pass along the
+ * variable-length datatype custom allocation information.
+ *
+ * \note H5Tconvert() will not resize the buffer \p buf; it must be large
+ * enough to hold the larger of the input and output data.
+ *
+ * \version 1.6.3 \p nelmts parameter type changed to size_t.
+ * \version 1.4.0 \p nelmts parameter type changed to \ref hsize_t.
+ *
+ */
H5_DLL herr_t H5Tconvert(hid_t src_id, hid_t dst_id, size_t nelmts, void *buf, void *background,
hid_t plist_id);
+/**
+ * \ingroup VLEN
+ *
+ * \brief Reclaims the variable length (VL) datatype memory buffers
+ *
+ * \type_id
+ * \space_id
+ * \dxpl_id{plist_id} used to create the buffer
+ * \param[in] buf Pointer to the buffer to be reclaimed
+ *
+ * \return \herr_t
+ *
+ * \details H5Treclaim() reclaims memory buffers created to store VL datatypes.
+ * It only frees the variable length data in the selection defined in
+ * the dataspace specified by \p space_id. The dataset transfer
+ * property list \p plist_id is required to find the correct
+ * allocation and/or free methods for the variable-length data in the
+ * buffer.
+ *
+ * \since 1.12.0
+ *
+ */
H5_DLL herr_t H5Treclaim(hid_t type_id, hid_t space_id, hid_t plist_id, void *buf);
/* Symbols defined for compatibility with previous versions of the HDF5 API.
@@ -598,10 +2883,139 @@ H5_DLL herr_t H5Treclaim(hid_t type_id, hid_t space_id, hid_t plist_id, void
/* Typedefs */
/* Function prototypes */
+/**
+ * \ingroup H5T
+ *
+ * \brief Commits a transient datatype to a file, creating a new named datatype
+ *
+ * \fg_loc_id
+ * \param[in] name Name given to committed datatype
+ * \param[in] type_id Identifier of datatype to be committed
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function has been renamed from H5Tcommit() and is
+ * deprecated in favor of the macro #H5Tcommit or the function
+ * H5Tcommit2().
+ *
+ * \details H5Tcommit1() commits the transient datatype (not immutable) to
+ * a file, turning it into a named datatype.
+ *
+ * The datatype \p dtype_id is committed as a named datatype at the
+ * location \p loc_id, which is either a file or group identifier,
+ * with the name \p name.
+ *
+ * \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.
+ *
+ * As is the case for any object in a group, the length of the name
+ * of a named datatype is not limited.
+ *
+ * See H5Tcommit_anon() for a discussion of the differences between
+ * H5Tcommit() and H5Tcommit_anon().
+ *
+ * This function will not accept a datatype that cannot actually
+ * hold data. This currently includes compound datatypes with no
+ * fields and enumerated datatypes with no members.
+ *
+ * \version 1.8.7 Function modified in this release to reject datatypes that
+ * will not accommodate actual data, such as a compound datatype with
+ * no fields or an enumerated datatype with no members.
+ * \version 1.8.0 C function H5Tcommit() renamed to H5Tcommit1() and deprecated
+ * in this release.
+ * \since 1.2.0
+ *
+ */
H5_DLL herr_t H5Tcommit1(hid_t loc_id, const char *name, hid_t type_id);
+/**
+ * \ingroup H5T
+ *
+ * \brief Opens a named datatype
+ *
+ * \fg_loc_id
+ * \param[in] name A datatype name, defined within the specified file or group
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function has been renamed from H5Topen() and is
+ * deprecated in favor of the macro #H5Topen or the function
+ * H5Topen2().
+ *
+ * \details H5Topen1() opens a named datatype at the location specified by
+ * \p loc_id and returns an identifier for the datatype. \p loc_id
+ * can be either a file or group identifier. The identifier should
+ * eventually be closed by calling H5Tclose() to release resources.
+ *
+ * \version 1.8.0 Function H5Topen() renamed to H5Topen1() and deprecated in
+ * this release.
+ *
+ * \since 1.2.0
+ *
+ */
H5_DLL hid_t H5Topen1(hid_t loc_id, const char *name);
+/**
+ * \ingroup ARRAY
+ *
+ * \brief Creates an array datatype object
+ *
+ * \param[in] base_id Datatype identifier for the array base datatype
+ * \param[in] ndims Rank of the array
+ * \param[in] dim Size of each array dimension
+ * \param[in] perm Dimension permutation (Currently not implemented.)
+ *
+ * \return \hid_t{array datatype}
+ *
+ * \deprecated This function has been renamed from H5Tarray_create() and is
+ * deprecated in favor of the macro #H5Tarray_create or the function
+ * H5Tarray_create2().
+ *
+ * \details H5Tarray_create1() creates a new array datatype object.\n\n
+ * \p base_id is the datatype of every element of the array, i.e.,
+ * of the number at each position in the array.
+ *
+ * \p rank is the number of dimensions and the size of each dimension
+ * is specified in the array dims. The value of rank is currently
+ * limited to #H5S_MAX_RANK and must be greater than 0 (zero). All
+ * dimension sizes specified in dims must be greater than 0 (zero).
+ *
+ * The array \p perm is designed to contain the dimension permutation,
+ * i.e. C versus FORTRAN array order. (The parameter perm is
+ * currently unused and is not yet implemented.)
+ *
+ * \version 1.8.0 Function H5Tarray_create() renamed to H5Tarray_create1()
+ * and deprecated in this release.
+ * \since 1.4.0
+ *
+ */
H5_DLL hid_t H5Tarray_create1(hid_t base_id, int ndims, const hsize_t dim[/* ndims */],
const int perm[/* ndims */]);
+/**
+ * \ingroup ARRAY
+ *
+ * \brief Retrieves sizes of array dimensions
+ *
+ * \type_id
+ * \param[out] dims Sizes of array dimensions
+ * \param[out] perm Dimension permutations (This parameter is not used.)
+ *
+ * \return Returns the non-negative number of dimensions of the array type
+ * if successful; otherwise, returns a negative value.
+ *
+ * \deprecated This function has been renamed from H5Tget_array_dims() and is
+ * deprecated in favor of the macro #H5Tget_array_dims or the
+ * function H5Tget_array_dims2().
+ *
+ * \details H5Tget_array_dims1() returns the sizes of the dimensions and
+ * the dimension permutations of the specified array datatype object.
+ *
+ * The sizes of the dimensions are returned in the array \p dims.
+ *
+ * \version 1.8.0 Function H5Tarray_create() renamed to H5Tarray_create1()
+ * and deprecated in this release.
+ * \since 1.2.0
+ *
+ */
H5_DLL int H5Tget_array_dims1(hid_t type_id, hsize_t dims[], int perm[]);
#endif /* H5_NO_DEPRECATED_SYMBOLS */
diff --git a/src/H5VLconnector.h b/src/H5VLconnector.h
index 63ac910..2abdca3 100644
--- a/src/H5VLconnector.h
+++ b/src/H5VLconnector.h
@@ -438,39 +438,44 @@ typedef struct H5VL_token_class_t {
herr_t (*from_str)(void *obj, H5I_type_t obj_type, const char *token_str, H5O_token_t *token);
} H5VL_token_class_t;
-/* Class information for each VOL connector */
+/**
+ * \ingroup H5VLDEV
+ * Class information for each VOL connector
+ */
+//! [H5VL_class_t_snip]
typedef struct H5VL_class_t {
/* Overall connector fields & callbacks */
- unsigned int version; /* VOL connector class struct version # */
- H5VL_class_value_t value; /* Value to identify connector */
- const char * name; /* Connector name (MUST be unique!) */
- unsigned cap_flags; /* Capability flags for connector */
- herr_t (*initialize)(hid_t vipl_id); /* Connector initialization callback */
- herr_t (*terminate)(void); /* Connector termination callback */
+ unsigned int version; /**< VOL connector class struct version # */
+ H5VL_class_value_t value; /**< Value to identify connector */
+ const char * name; /**< Connector name (MUST be unique!) */
+ unsigned cap_flags; /**< Capability flags for connector */
+ herr_t (*initialize)(hid_t vipl_id); /**< Connector initialization callback */
+ herr_t (*terminate)(void); /**< Connector termination callback */
/* VOL framework */
- H5VL_info_class_t info_cls; /* VOL info fields & callbacks */
- H5VL_wrap_class_t wrap_cls; /* VOL object wrap / retrieval callbacks */
+ H5VL_info_class_t info_cls; /**< VOL info fields & callbacks */
+ H5VL_wrap_class_t wrap_cls; /**< VOL object wrap / retrieval callbacks */
/* Data Model */
- H5VL_attr_class_t attr_cls; /* Attribute (H5A*) class callbacks */
- H5VL_dataset_class_t dataset_cls; /* Dataset (H5D*) class callbacks */
- H5VL_datatype_class_t datatype_cls; /* Datatype (H5T*) class callbacks */
- H5VL_file_class_t file_cls; /* File (H5F*) class callbacks */
- H5VL_group_class_t group_cls; /* Group (H5G*) class callbacks */
- H5VL_link_class_t link_cls; /* Link (H5L*) class callbacks */
- H5VL_object_class_t object_cls; /* Object (H5O*) class callbacks */
+ H5VL_attr_class_t attr_cls; /**< Attribute (H5A*) class callbacks */
+ H5VL_dataset_class_t dataset_cls; /**< Dataset (H5D*) class callbacks */
+ H5VL_datatype_class_t datatype_cls; /**< Datatype (H5T*) class callbacks */
+ H5VL_file_class_t file_cls; /**< File (H5F*) class callbacks */
+ H5VL_group_class_t group_cls; /**< Group (H5G*) class callbacks */
+ H5VL_link_class_t link_cls; /**< Link (H5L*) class callbacks */
+ H5VL_object_class_t object_cls; /**< Object (H5O*) class callbacks */
/* Infrastructure / Services */
- H5VL_introspect_class_t introspect_cls; /* Container/connector introspection class callbacks */
- H5VL_request_class_t request_cls; /* Asynchronous request class callbacks */
- H5VL_blob_class_t blob_cls; /* 'Blob' class callbacks */
- H5VL_token_class_t token_cls; /* VOL connector object token class callbacks */
+ H5VL_introspect_class_t introspect_cls; /**< Container/connector introspection class callbacks */
+ H5VL_request_class_t request_cls; /**< Asynchronous request class callbacks */
+ H5VL_blob_class_t blob_cls; /**< 'Blob' class callbacks */
+ H5VL_token_class_t token_cls; /**< VOL connector object token class callbacks */
/* Catch-all */
herr_t (*optional)(void *obj, int op_type, hid_t dxpl_id, void **req,
- va_list arguments); /* Optional callback */
+ va_list arguments); /**< Optional callback */
} H5VL_class_t;
+//! [H5VL_class_t_snip]
/********************/
/* Public Variables */
@@ -485,10 +490,54 @@ extern "C" {
#endif
/* Helper routines for VOL connector authors */
+/**
+ * \ingroup H5VLDEV
+ * \brief Registers a new VOL connector
+ *
+ * \param[in] cls A pointer to the plugin structure to register
+ * \vipl_id
+ * \return \hid_t{VOL connector}
+ *
+ * \details H5VLregister_connector() registers a new VOL connector as a member
+ * of the virtual object layer class. This VOL connector identifier is
+ * good until the library is closed or the connector is unregistered.
+ *
+ * \p vipl_id is either #H5P_DEFAULT or the identifier of a VOL
+ * initialization property list of class #H5P_VOL_INITIALIZE created
+ * with H5Pcreate(). When created, this property list contains no
+ * library properties. If a VOL connector author decides that
+ * initialization-specific data are needed, they can be added to the
+ * empty list and retrieved by the connector in the VOL connector's
+ * initialize callback. Use of the VOL initialization property list is
+ * uncommon, as most VOL-specific properties are added to the file
+ * access property list via the connector's API calls which set the
+ * VOL connector for the file open/create. For more information, see
+ * the VOL documentation.
+ *
+ * H5VL_class_t is defined in H5VLconnector.h in the source code. It
+ * contains class information for each VOL connector:
+ * \snippet this H5VL_class_t_snip
+ *
+ * \todo Fix the reference to VOL documentation.
+ *
+ * \since 1.12.0
+ */
H5_DLL hid_t H5VLregister_connector(const H5VL_class_t *cls, hid_t vipl_id);
+/**
+ * \ingroup H5VLDEV
+ */
H5_DLL void *H5VLobject(hid_t obj_id);
+/**
+ * \ingroup H5VLDEV
+ */
H5_DLL hid_t H5VLget_file_type(void *file_obj, hid_t connector_id, hid_t dtype_id);
+/**
+ * \ingroup H5VLDEV
+ */
H5_DLL hid_t H5VLpeek_connector_id_by_name(const char *name);
+/**
+ * \ingroup H5VLDEV
+ */
H5_DLL hid_t H5VLpeek_connector_id_by_value(H5VL_class_value_t value);
#ifdef __cplusplus
diff --git a/src/H5VLmodule.h b/src/H5VLmodule.h
index 1ff9137..91d61c9 100644
--- a/src/H5VLmodule.h
+++ b/src/H5VLmodule.h
@@ -27,4 +27,19 @@
#define H5_MY_PKG_ERR H5E_VOL
#define H5_MY_PKG_INIT YES
+/**
+ * \defgroup H5VL H5VL
+ * \brief Virtual Object Layer Interface
+ * \todo Describe concisely what the functions in this module are about.
+ *
+ * \defgroup H5VLDEF Definitions
+ * \ingroup H5VL
+ * \defgroup H5VLDEV VOL Developer
+ * \ingroup H5VL
+ * \defgroup H5VLNAT Native VOL
+ * \ingroup H5VL
+ * \defgroup H5VLPT Pass-through VOL
+ * \ingroup H5VL
+ */
+
#endif /* _H5VLmodule_H */
diff --git a/src/H5VLnative.h b/src/H5VLnative.h
index b703c4f..b81f9c1 100644
--- a/src/H5VLnative.h
+++ b/src/H5VLnative.h
@@ -123,7 +123,13 @@ extern "C" {
#endif
/* Token <--> address converters */
+/**
+ * \ingroup H5VLNAT
+ */
H5_DLL herr_t H5VLnative_addr_to_token(hid_t loc_id, haddr_t addr, H5O_token_t *token);
+/**
+ * \ingroup H5VLNAT
+ */
H5_DLL herr_t H5VLnative_token_to_addr(hid_t loc_id, H5O_token_t token, haddr_t *addr);
/* Not really public but must be included here */
diff --git a/src/H5VLpublic.h b/src/H5VLpublic.h
index 919a4b8..19cd2b9 100644
--- a/src/H5VLpublic.h
+++ b/src/H5VLpublic.h
@@ -28,39 +28,64 @@
/* VOL connector identifier values
* These are H5VL_class_value_t values, NOT hid_t values!
*/
-#define H5_VOL_INVALID (-1) /* Invalid ID for VOL connector ID */
-#define H5_VOL_NATIVE 0 /* Native HDF5 file format VOL connector */
-#define H5_VOL_RESERVED 256 /* VOL connector IDs below this value are reserved for library use */
-#define H5_VOL_MAX 65535 /* Maximum VOL connector ID */
+/**
+ * \ingroup H5VLDEF
+ * Invalid ID for VOL connector ID
+ */
+#define H5_VOL_INVALID (-1)
+/**
+ * \ingroup H5VLDEF
+ * Native HDF5 file format VOL connector
+ */
+#define H5_VOL_NATIVE 0
+/**
+ * \ingroup H5VLDEF
+ * VOL connector IDs below this value are reserved for library use
+ */
+#define H5_VOL_RESERVED 256
+/**
+ * \ingroup H5VLDEF
+ * Maximum VOL connector ID
+ */
+#define H5_VOL_MAX 65535
/*******************/
/* Public Typedefs */
/*******************/
-/*
- * VOL connector identifiers. Values 0 through 255 are for connectors defined
- * by the HDF5 library. Values 256 through 511 are available for testing new
- * connectors. Subsequent values should be obtained from the HDF5 development
- * team at help@hdfgroup.org.
+/**
+ * \ingroup H5VLDEF
+ *
+ * \brief VOL connector identifiers.
+ *
+ * \details Values 0 through 255 are for connectors defined by the HDF5
+ * library. Values 256 through 511 are available for testing new
+ * connectors. Subsequent values should be obtained from the HDF5
+ * development team at mailto:help@hdfgroup.org.
*/
+//! [H5VL_class_value_t_snip]
typedef int H5VL_class_value_t;
+//! [H5VL_class_value_t_snip]
-/* Enum type for each VOL subclass */
-/* (Used for various queries, etc) */
+/**
+ * \ingroup H5VLDEF
+ * \details Enum type for each VOL subclass
+ * (Used for various queries, etc)
+ */
typedef enum H5VL_subclass_t {
- H5VL_SUBCLS_NONE, /* Operations outside of a subclass */
- H5VL_SUBCLS_INFO, /* 'Info' subclass */
- H5VL_SUBCLS_WRAP, /* 'Wrap' subclass */
- H5VL_SUBCLS_ATTR, /* 'Attribute' subclass */
- H5VL_SUBCLS_DATASET, /* 'Dataset' subclass */
- H5VL_SUBCLS_DATATYPE, /* 'Named datatype' subclass */
- H5VL_SUBCLS_FILE, /* 'File' subclass */
- H5VL_SUBCLS_GROUP, /* 'Group' subclass */
- H5VL_SUBCLS_LINK, /* 'Link' subclass */
- H5VL_SUBCLS_OBJECT, /* 'Object' subclass */
- H5VL_SUBCLS_REQUEST, /* 'Request' subclass */
- H5VL_SUBCLS_BLOB, /* 'Blob' subclass */
- H5VL_SUBCLS_TOKEN /* 'Token' subclass */
+ H5VL_SUBCLS_NONE, /**< Operations outside of a subclass */
+ H5VL_SUBCLS_INFO, /**< 'Info' subclass */
+ H5VL_SUBCLS_WRAP, /**< 'Wrap' subclass */
+ H5VL_SUBCLS_ATTR, /**< 'Attribute' subclass */
+ H5VL_SUBCLS_DATASET, /**< 'Dataset' subclass */
+ H5VL_SUBCLS_DATATYPE, /**< 'Named datatype' subclass */
+ H5VL_SUBCLS_FILE, /**< 'File' subclass */
+ H5VL_SUBCLS_GROUP, /**< 'Group' subclass */
+ H5VL_SUBCLS_LINK, /**< 'Link' subclass */
+ H5VL_SUBCLS_OBJECT, /**< 'Object' subclass */
+ H5VL_SUBCLS_REQUEST, /**< 'Request' subclass */
+ H5VL_SUBCLS_BLOB, /**< 'Blob' subclass */
+ H5VL_SUBCLS_TOKEN /**< 'Token' subclass */
} H5VL_subclass_t;
/********************/
@@ -75,16 +100,230 @@ typedef enum H5VL_subclass_t {
extern "C" {
#endif
+/**
+ * \ingroup H5VL
+ * \brief Registers a new VOL connector by name
+ *
+ * \param[in] connector_name Connector name
+ * \vipl_id
+ * \return \hid_t{VOL connector}
+ *
+ * \details H5VLregister_connector_by_name() registers a new VOL connector with
+ * the name \p connector_name as a member of the virtual object layer
+ * class. This VOL connector identifier is good until the library is
+ * closed or the connector is unregistered.
+ *
+ * \p vipl_id is either #H5P_DEFAULT or the identifier of a VOL
+ * initialization property list of class #H5P_VOL_INITIALIZE created
+ * with H5Pcreate(). When created, this property list contains no
+ * library properties. If a VOL connector author decides that
+ * initialization-specific data are needed, they can be added to the
+ * empty list and retrieved by the connector in the VOL connector's
+ * initialize callback. Use of the VOL initialization property list is
+ * uncommon, as most VOL-specific properties are added to the file
+ * access property list via the connector's API calls which set the
+ * VOL connector for the file open/create. For more information, see
+ * the VOL documentation.
+ *
+ * \todo Fix the reference to VOL documentation.
+ *
+ * \since 1.12.0
+ */
H5_DLL hid_t H5VLregister_connector_by_name(const char *connector_name, hid_t vipl_id);
+/**
+ * \ingroup H5VL
+ * \brief Registers a new VOL connector by value
+ *
+ * \param[in] connector_value Connector value
+ * \vipl_id
+ * \return \hid_t{VOL connector}
+ *
+ * \details H5VLregister_connector_by_value() registers a new VOL connector
+ * with value connector_value as a member of the virtual object layer
+ * class. This VOL connector identifier is good until the library is
+ * closed or the connector is unregistered.
+ *
+ * \p connector_value has a type of H5VL_class_value_t, which is
+ * defined in H5VLpublic.h as follows:
+ * \snippet this H5VL_class_value_t_snip
+ *
+ * Valid VOL connector identifiers can have values from 0 through 255
+ * for connectors defined by the HDF5 library. Values 256 through 511
+ * are available for testing new connectors. Subsequent values should
+ * be obtained by contacting the The HDF Help Desk.
+ *
+ * \p vipl_id is either #H5P_DEFAULT or the identifier of a VOL
+ * initialization property list of class #H5P_VOL_INITIALIZE created
+ * with H5Pcreate(). When created, this property list contains no
+ * library properties. If a VOL connector author decides that
+ * initialization-specific data are needed, they can be added to the
+ * empty list and retrieved by the connector in the VOL connector's
+ * initialize callback. Use of the VOL initialization property list is
+ * uncommon, as most VOL-specific properties are added to the file
+ * access property list via the connector's API calls which set the
+ * VOL connector for the file open/create. For more information, see
+ * the VOL documentation.
+ *
+ * \todo Fix the reference to VOL documentation.
+ *
+ * \since 1.12.0
+ */
H5_DLL hid_t H5VLregister_connector_by_value(H5VL_class_value_t connector_value, hid_t vipl_id);
+/**
+ * \ingroup H5VL
+ * \brief Tests whether a VOL class has been registered under a certain name
+ *
+ * \param[in] name Alleged name of connector
+ * \return \htri_t
+ *
+ * \details H5VLis_connector_registered_by_name() tests whether a VOL class has
+ * been registered or not, according to the supplied connector name
+ * \p name.
+ *
+ * \since 1.12.0
+ */
H5_DLL htri_t H5VLis_connector_registered_by_name(const char *name);
+/**
+ * \ingroup H5VL
+ * \brief Tests whether a VOL class has been registered for a given value
+ *
+ * \param[in] connector_value Connector value
+ * \return \htri_t
+ *
+ * \details H5VLis_connector_registered_by_value() tests whether a VOL class
+ * has been registered, according to the supplied connector value \p
+ * connector_value.
+ *
+ * \p connector_value has a type of H5VL_class_value_t, which is
+ * defined in H5VLpublic.h as follows:
+ * \snippet this H5VL_class_value_t_snip
+ *
+ * Valid VOL connector identifiers can have values from 0 through 255
+ * for connectors defined by the HDF5 library. Values 256 through 511
+ * are available for testing new connectors. Subsequent values should
+ * be obtained by contacting the The HDF Help Desk.
+ *
+ * \since 1.12.0
+ */
H5_DLL htri_t H5VLis_connector_registered_by_value(H5VL_class_value_t connector_value);
+/**
+ * \ingroup H5VL
+ * \brief Retrieves the VOL connector identifier for a given object identifier
+ *
+ * \obj_id
+ * \return \hid_t{VOL connector}
+ *
+ * \details H5VLget_connector_id() retrieves the registered VOL connector
+ * identifier for the specified object identifier \p obj_id. The VOL
+ * connector identifier must be closed with H5VLclose() when no longer
+ * in use.
+ *
+ * \since 1.12.0
+ */
H5_DLL hid_t H5VLget_connector_id(hid_t obj_id);
+/**
+ * \ingroup H5VL
+ * \brief Retrieves the identifier for a registered VOL connector name
+ *
+ * \param[in] name Connector name
+ * \return \hid_t{VOL connector}
+ *
+ * \details H5VLget_connector_id_by_name() retrieves the identifier for a
+ * registered VOL connector with the name \p name. The identifier must
+ * be closed with H5VLclose() when no longer in use.
+ *
+ * \since 1.12.0
+ */
H5_DLL hid_t H5VLget_connector_id_by_name(const char *name);
+/**
+ * \ingroup H5VL
+ * \brief Retrieves the identifier for a registered VOL connector value
+ *
+ * \param[in] connector_value Connector value
+ * \return \hid_t{VOL connector}
+ *
+ * \details H5VLget_connector_id_by_value() retrieves the identifier for a
+ * registered VOL connector with the value \p connector_value. The
+ * identifier will need to be closed by H5VLclose().
+ *
+ * \p connector_value has a type of H5VL_class_value_t, which is
+ * defined in H5VLpublic.h as follows:
+ * \snippet this H5VL_class_value_t_snip
+ *
+ * Valid VOL connector identifiers can have values from 0 through 255
+ * for connectors defined by the HDF5 library. Values 256 through 511
+ * are available for testing new connectors. Subsequent values should
+ * be obtained by contacting the The HDF Help Desk.
+ *
+ * \since 1.12.0
+ */
H5_DLL hid_t H5VLget_connector_id_by_value(H5VL_class_value_t connector_value);
+/**
+ * \ingroup H5VL
+ * \brief Retrieves a connector name for a VOL
+ *
+ * \obj_id{id} or file identifier
+ * \param[out] name Connector name
+ * \param[in] size Maximum length of the name to retrieve
+ * \return Returns the length of the connector name on success, and a negative value on failure.
+ *
+ * \details H5VLget_connector_name() retrieves up to \p size elements of the
+ * VOL name \p name associated with the object or file identifier \p
+ * id.
+ *
+ * Passing in a NULL pointer for size will return the size of the
+ * connector name. This can be used to determine the size of the
+ * buffer to allocate for the name.
+ *
+ * \since 1.12.0
+ */
H5_DLL ssize_t H5VLget_connector_name(hid_t id, char *name /*out*/, size_t size);
+/**
+ * \ingroup H5VL
+ * \brief Closes a VOL connector identifier
+ *
+ * \param[in] connector_id Connector identifier
+ * \return \herr_t
+ *
+ * \details H5VLclose() closes a VOL connector identifier. This does not affect
+ * the file access property lists which have been defined to use this
+ * VOL connector or files which are already opened under this
+ * connector.
+ *
+ * \since 1.12.0
+ */
H5_DLL herr_t H5VLclose(hid_t connector_id);
+/**
+ * \ingroup H5VL
+ * \brief Removes a VOL connector identifier from the library
+ *
+ * \param[in] connector_id Connector identifier
+ * \return \herr_t
+ *
+ * \details H5VLunregister_connector() removes a VOL connector identifier from
+ * the library. This does not affect the file access property lists
+ * which have been defined to use the VOL connector or any files which
+ * are already opened with this connector.
+ *
+ * \attention H5VLunregister_connector() will fail if attempting to unregister
+ * the native VOL connector.
+ *
+ * \since 1.12.0
+ */
H5_DLL herr_t H5VLunregister_connector(hid_t connector_id);
+/**
+ * \ingroup H5VL
+ * \brief Determine if a VOL connector supports a particular
+ * optional callback operation.
+ *
+ * \obj_id
+ * \param[in] subcls VOL subclass
+ * \param[in] opt_type Option type
+ * \param[out] supported Flag
+ * \return \herr_t
+ *
+ * \since 1.12.0
+ */
H5_DLL herr_t H5VLquery_optional(hid_t obj_id, H5VL_subclass_t subcls, int opt_type, hbool_t *supported);
#ifdef __cplusplus
diff --git a/src/H5Zmodule.h b/src/H5Zmodule.h
index d83f338..3be2629 100644
--- a/src/H5Zmodule.h
+++ b/src/H5Zmodule.h
@@ -29,4 +29,71 @@
#define H5_MY_PKG_ERR H5E_PLINE
#define H5_MY_PKG_INIT YES
+/**
+ * \defgroup H5Z H5Z
+ *
+ *
+ * \brief Filter and Compression Interface
+ *
+ * \details The functions in this module let you configure filters that process
+ * data during I/O operation.
+ *
+ * HDF5 supports a filter pipeline that provides the capability for
+ * standard and customized raw data processing during I/O operations.
+ * HDF5 is distributed with a small set of standard filters such as
+ * compression (gzip, SZIP, and a shuffling algorithm) and error
+ * checking (Fletcher32 checksum). For further flexibility, the
+ * library allows a user application to extend the pipeline through
+ * the creation and registration of customized filters.
+ *
+ * The flexibility of the filter pipeline implementation enables the
+ * definition of additional filters by a user application. A filter
+ * \li is associated with a dataset when the dataset is created,
+ * \li can be used only with chunked data (i.e., datasets stored in
+ * the #H5D_CHUNKED storage layout), and
+ * \li is applied independently to each chunk of the dataset.
+ *
+ * The HDF5 library does not support filters for contiguous datasets
+ * because of the difficulty of implementing random access for partial
+ * I/O. Compact dataset filters are not supported because it would not
+ * produce significant results.
+ *
+ * Filter identifiers for the filters distributed with the HDF5
+ * Library are as follows:
+ * <table>
+ * <tr><td>#H5Z_FILTER_DEFLATE</td><td>The gzip compression, or
+ * deflation, filter</td></tr>
+ * <tr><td>#H5Z_FILTER_SZIP</td><td>The SZIP compression
+ * filter</td></tr>
+ * <tr><td>#H5Z_FILTER_NBIT</td><td>The N-bit compression
+ * filter</td></tr>
+ * <tr><td>#H5Z_FILTER_SCALEOFFSET</td><td>The scale-offset
+ * compression filter</td></tr>
+ * <tr><td>#H5Z_FILTER_SHUFFLE</td><td>The shuffle algorithm
+ * filter</td></tr>
+ * <tr><td>#H5Z_FILTER_FLETCHER32</td><td>The Fletcher32 checksum,
+ * or error checking, filter</td></tr>
+ * </table>
+ * Custom filters that have been registered with the library will have
+ * additional unique identifiers.
+ *
+ * See \Emph{HDF5 Dynamically Loaded Filters} for more information on
+ * how an HDF5 application can apply a filter that is not registered
+ * with the HDF5 library.
+ *
+ * \todo Fix the reference.
+ *
+ * \defgroup H5ZPRE Predefined Filters
+ * \ingroup H5Z
+ * \defgroup FLETCHER32 Checksum Filter
+ * \ingroup H5ZPRE
+ * \defgroup SCALEOFFSET Scale-Offset Filter
+ * \ingroup H5ZPRE
+ * \defgroup SHUFFLE Shuffle Filter
+ * \ingroup H5ZPRE
+ * \defgroup SZIP Szip Filter
+ * \ingroup H5ZPRE
+ *
+ */
+
#endif /* _H5Zmodule_H */
diff --git a/src/H5Zpublic.h b/src/H5Zpublic.h
index 97da13c..709e5fd 100644
--- a/src/H5Zpublic.h
+++ b/src/H5Zpublic.h
@@ -21,201 +21,610 @@
/* Public headers needed by this file */
#include "H5public.h"
-/*
- * Filter identifiers. Values 0 through 255 are for filters defined by the
- * HDF5 library. Values 256 through 511 are available for testing new
- * filters. Subsequent values should be obtained from the HDF5 development
- * team at help@hdfgroup.org. These values will never change because they
- * appear in the HDF5 files.
+/**
+ * \brief Filter identifiers
+ *
+ * \details Values 0 through 255 are for filters defined by the HDF5 library.
+ * Values 256 through 511 are available for testing new filters.
+ * Subsequent values should be obtained from the HDF5 development team
+ * at mailto:help@hdfgroup.org. These values will never change because
+ * they appear in the HDF5 files.
*/
typedef int H5Z_filter_t;
/* Filter IDs */
-#define H5Z_FILTER_ERROR (-1) /*no filter */
-#define H5Z_FILTER_NONE 0 /*reserved indefinitely */
-#define H5Z_FILTER_DEFLATE 1 /*deflation like gzip */
-#define H5Z_FILTER_SHUFFLE 2 /*shuffle the data */
-#define H5Z_FILTER_FLETCHER32 3 /*fletcher32 checksum of EDC */
-#define H5Z_FILTER_SZIP 4 /*szip compression */
-#define H5Z_FILTER_NBIT 5 /*nbit compression */
-#define H5Z_FILTER_SCALEOFFSET 6 /*scale+offset compression */
-#define H5Z_FILTER_RESERVED 256 /*filter ids below this value are reserved for library use */
-
-#define H5Z_FILTER_MAX 65535 /*maximum filter id */
+/**
+ * no filter
+ */
+#define H5Z_FILTER_ERROR (-1)
+/**
+ * reserved indefinitely
+*/
+#define H5Z_FILTER_NONE 0
+/**
+ * deflation like gzip
+ */
+#define H5Z_FILTER_DEFLATE 1
+/**
+ * shuffle the data
+ */
+#define H5Z_FILTER_SHUFFLE 2
+/**
+ * fletcher32 checksum of EDC
+*/
+#define H5Z_FILTER_FLETCHER32 3
+/**
+ * szip compression
+ */
+#define H5Z_FILTER_SZIP 4
+/**
+ * nbit compression
+ */
+#define H5Z_FILTER_NBIT 5
+/**
+ * scale+offset compression
+ */
+#define H5Z_FILTER_SCALEOFFSET 6
+/**
+ * filter ids below this value are reserved for library use
+ */
+#define H5Z_FILTER_RESERVED 256
+/**
+ * maximum filter id
+ */
+#define H5Z_FILTER_MAX 65535
/* General macros */
-#define H5Z_FILTER_ALL 0 /* Symbol to remove all filters in H5Premove_filter */
-#define H5Z_MAX_NFILTERS 32 /* Maximum number of filters allowed in a pipeline */
- /* (should probably be allowed to be an
- * unlimited amount, but currently each
- * filter uses a bit in a 32-bit field,
- * so the format would have to be
- * changed to accommodate that)
- */
+/**
+ * Symbol to remove all filters in H5Premove_filter()
+ */
+#define H5Z_FILTER_ALL 0
+/**
+ * Maximum number of filters allowed in a pipeline
+ *
+ * \internal (should probably be allowed to be an unlimited amount, but
+ * currently each filter uses a bit in a 32-bit field, so the format
+ * would have to be changed to accommodate that)
+ */
+#define H5Z_MAX_NFILTERS 32
/* Flags for filter definition (stored) */
-#define H5Z_FLAG_DEFMASK 0x00ff /*definition flag mask */
-#define H5Z_FLAG_MANDATORY 0x0000 /*filter is mandatory */
-#define H5Z_FLAG_OPTIONAL 0x0001 /*filter is optional */
+/**
+ * definition flag mask
+ */
+#define H5Z_FLAG_DEFMASK 0x00ff
+/**
+ * filter is mandatory
+ */
+#define H5Z_FLAG_MANDATORY 0x0000
+/**
+ * filter is optional
+ */
+#define H5Z_FLAG_OPTIONAL 0x0001
/* Additional flags for filter invocation (not stored) */
-#define H5Z_FLAG_INVMASK 0xff00 /*invocation flag mask */
-#define H5Z_FLAG_REVERSE 0x0100 /*reverse direction; read */
-#define H5Z_FLAG_SKIP_EDC 0x0200 /*skip EDC filters for read */
+/**
+ * invocation flag mask
+ */
+#define H5Z_FLAG_INVMASK 0xff00
+/**
+ * reverse direction; read
+ */
+#define H5Z_FLAG_REVERSE 0x0100
+/**
+ * skip EDC filters for read
+ */
+#define H5Z_FLAG_SKIP_EDC 0x0200
/* Special parameters for szip compression */
/* [These are aliases for the similar definitions in szlib.h, which we can't
* include directly due to the duplication of various symbols with the zlib.h
* header file] */
-#define H5_SZIP_ALLOW_K13_OPTION_MASK 1
-#define H5_SZIP_CHIP_OPTION_MASK 2
-#define H5_SZIP_EC_OPTION_MASK 4
-#define H5_SZIP_NN_OPTION_MASK 32
-#define H5_SZIP_MAX_PIXELS_PER_BLOCK 32
+/**
+ * \ingroup SZIP */
+#define H5_SZIP_ALLOW_K13_OPTION_MASK 1
+/**
+ * \ingroup SZIP */
+#define H5_SZIP_CHIP_OPTION_MASK 2
+/**
+ * \ingroup SZIP */
+#define H5_SZIP_EC_OPTION_MASK 4
+/**
+ * \ingroup SZIP */
+#define H5_SZIP_NN_OPTION_MASK 32
+/**
+ * \ingroup SZIP */
+#define H5_SZIP_MAX_PIXELS_PER_BLOCK 32
/* Macros for the shuffle filter */
-#define H5Z_SHUFFLE_USER_NPARMS 0 /* Number of parameters that users can set */
-#define H5Z_SHUFFLE_TOTAL_NPARMS 1 /* Total number of parameters for filter */
+/**
+ * \ingroup SHUFFLE
+ * Number of parameters that users can set for the shuffle filter
+*/
+#define H5Z_SHUFFLE_USER_NPARMS 0
+/**
+ * \ingroup SHUFFLE
+ * Total number of parameters for the shuffle filter
+ */
+#define H5Z_SHUFFLE_TOTAL_NPARMS 1
/* Macros for the szip filter */
-#define H5Z_SZIP_USER_NPARMS 2 /* Number of parameters that users can set */
-#define H5Z_SZIP_TOTAL_NPARMS 4 /* Total number of parameters for filter */
-#define H5Z_SZIP_PARM_MASK 0 /* "User" parameter for option mask */
-#define H5Z_SZIP_PARM_PPB 1 /* "User" parameter for pixels-per-block */
-#define H5Z_SZIP_PARM_BPP 2 /* "Local" parameter for bits-per-pixel */
-#define H5Z_SZIP_PARM_PPS 3 /* "Local" parameter for pixels-per-scanline */
+/**
+ * \ingroup SZIP
+ * Number of parameters that users can set for SZIP
+ */
+#define H5Z_SZIP_USER_NPARMS 2
+/**
+ * \ingroup SZIP
+ * Total number of parameters for SZIP filter
+ */
+#define H5Z_SZIP_TOTAL_NPARMS 4
+/**
+ * \ingroup SZIP
+ * "User" parameter for option mask
+ */
+#define H5Z_SZIP_PARM_MASK 0
+/**
+ * \ingroup SZIP
+ * "User" parameter for pixels-per-block
+ */
+#define H5Z_SZIP_PARM_PPB 1
+/**
+ * \ingroup SZIP
+ * "Local" parameter for bits-per-pixel
+ */
+#define H5Z_SZIP_PARM_BPP 2
+/**
+ * \ingroup SZIP
+ * "Local" parameter for pixels-per-scanline
+ */
+#define H5Z_SZIP_PARM_PPS 3
/* Macros for the nbit filter */
-#define H5Z_NBIT_USER_NPARMS 0 /* Number of parameters that users can set */
+/**
+ * \ingroup NBIT
+ * Number of parameters that users can set for the N-bit filter
+ */
+#define H5Z_NBIT_USER_NPARMS 0 /* Number of parameters that users can set */
/* Macros for the scale offset filter */
-#define H5Z_SCALEOFFSET_USER_NPARMS 2 /* Number of parameters that users can set */
+/**
+ * \ingroup SCALEOFFSET
+ * Number of parameters that users can set for the scale-offset filter
+ */
+#define H5Z_SCALEOFFSET_USER_NPARMS 2
+
/* Special parameters for ScaleOffset filter*/
+/**
+ * \ingroup SCALEOFFSET */
#define H5Z_SO_INT_MINBITS_DEFAULT 0
+/**
+ * \ingroup SCALEOFFSET */
typedef enum H5Z_SO_scale_type_t {
H5Z_SO_FLOAT_DSCALE = 0,
H5Z_SO_FLOAT_ESCALE = 1,
H5Z_SO_INT = 2
} H5Z_SO_scale_type_t;
-/* Current version of the H5Z_class_t struct */
+/**
+ * Current version of the H5Z_class_t struct
+ */
#define H5Z_CLASS_T_VERS (1)
-/* Values to decide if EDC is enabled for reading data */
+/**
+ * \ingroup FLETCHER32
+ * Values to decide if EDC is enabled for reading data
+ */
typedef enum H5Z_EDC_t {
- H5Z_ERROR_EDC = -1, /* error value */
- H5Z_DISABLE_EDC = 0,
- H5Z_ENABLE_EDC = 1,
- H5Z_NO_EDC = 2 /* must be the last */
+ H5Z_ERROR_EDC = -1, /**< error value */
+ H5Z_DISABLE_EDC = 0,
+ H5Z_ENABLE_EDC = 1,
+ H5Z_NO_EDC = 2 /**< sentinel */
} H5Z_EDC_t;
/* Bit flags for H5Zget_filter_info */
#define H5Z_FILTER_CONFIG_ENCODE_ENABLED (0x0001)
#define H5Z_FILTER_CONFIG_DECODE_ENABLED (0x0002)
-/* Return values for filter callback function */
+/**
+ * Return values for filter callback function
+ */
typedef enum H5Z_cb_return_t {
- H5Z_CB_ERROR = -1,
- H5Z_CB_FAIL = 0, /* I/O should fail if filter fails. */
- H5Z_CB_CONT = 1, /* I/O continues if filter fails. */
- H5Z_CB_NO = 2
+ H5Z_CB_ERROR = -1,
+ H5Z_CB_FAIL = 0, /**< I/O should fail if filter fails. */
+ H5Z_CB_CONT = 1, /**< I/O continues if filter fails. */
+ H5Z_CB_NO = 2
} H5Z_cb_return_t;
-/* Filter callback function definition */
-typedef H5Z_cb_return_t (*H5Z_filter_func_t)(H5Z_filter_t filter, void *buf, size_t buf_size, void *op_data);
+/**
+ * Filter callback function definition
+ */
+typedef H5Z_cb_return_t (*H5Z_filter_func_t)(H5Z_filter_t filter, void* buf,
+ size_t buf_size, void* op_data);
-/* Structure for filter callback property */
+/**
+ * Structure for filter callback property
+ */
typedef struct H5Z_cb_t {
- H5Z_filter_func_t func;
- void * op_data;
+ H5Z_filter_func_t func;
+ void *op_data;
} H5Z_cb_t;
#ifdef __cplusplus
extern "C" {
#endif
-/*
- * Before a dataset gets created, the "can_apply" callbacks for any filters used
- * in the dataset creation property list are called
- * with the dataset's dataset creation property list, the dataset's datatype and
- * a dataspace describing a chunk (for chunked dataset storage).
+/**
+ * \details Before a dataset gets created, the \c can_apply callbacks for any
+ * filters used in the dataset creation property list are called with
+ * the dataset's dataset creation property list, the dataset's
+ * datatype and a dataspace describing a chunk (for chunked dataset
+ * storage).
*
- * The "can_apply" callback must determine if the combination of the dataset
- * creation property list setting, the datatype and the dataspace represent a
- * valid combination to apply this filter to. For example, some cases of
- * invalid combinations may involve the filter not operating correctly on
- * certain datatypes (or certain datatype sizes), or certain sizes of the chunk
- * dataspace.
+ * The \c can_apply callback must determine if the combination of the
+ * dataset creation property list setting, the datatype and the
+ * dataspace represent a valid combination to apply this filter to.
+ * For example, some cases of invalid combinations may involve the
+ * filter not operating correctly on certain datatypes (or certain
+ * datatype sizes), or certain sizes of the chunk dataspace.
*
- * The "can_apply" callback can be the NULL pointer, in which case, the library
- * will assume that it can apply to any combination of dataset creation
- * property list values, datatypes and dataspaces.
+ * The \c can_apply callback can be the NULL pointer, in which case,
+ * the library will assume that it can apply to any combination of
+ * dataset creation property list values, datatypes and dataspaces.
*
- * The "can_apply" callback returns positive a valid combination, zero for an
- * invalid combination and negative for an error.
+ * The \c can_apply callback returns positive a valid combination,
+ * zero for an invalid combination and negative for an error.
*/
+//! [H5Z_can_apply_func_t_snip]
typedef htri_t (*H5Z_can_apply_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id);
-
-/*
- * After the "can_apply" callbacks are checked for new datasets, the "set_local"
- * callbacks for any filters used in the dataset creation property list are
- * called. These callbacks receive the dataset's private copy of the dataset
- * creation property list passed in to H5Dcreate (i.e. not the actual property
- * list passed in to H5Dcreate) and the datatype ID passed in to H5Dcreate
- * (which is not copied and should not be modified) and a dataspace describing
- * the chunk (for chunked dataset storage) (which should also not be modified).
+//! [H5Z_can_apply_func_t_snip]
+/**
+ * \details After the "can_apply" callbacks are checked for new datasets, the
+ * \c set_local callbacks for any filters used in the dataset creation
+ * property list are called. These callbacks receive the dataset's
+ * private copy of the dataset creation property list passed in to
+ * H5Dcreate() (i.e. not the actual property list passed in to
+ * H5Dcreate()) and the datatype ID passed in to H5Dcreate() (which is
+ * not copied and should not be modified) and a dataspace describing
+ * the chunk (for chunked dataset storage) (which should also not be
+ * modified).
*
- * The "set_local" callback must set any parameters that are specific to this
- * dataset, based on the combination of the dataset creation property list
- * values, the datatype and the dataspace. For example, some filters perform
- * different actions based on different datatypes (or datatype sizes) or
- * different number of dimensions or dataspace sizes.
+ * The \c set_local callback must set any parameters that are specific
+ * to this dataset, based on the combination of the dataset creation
+ * property list values, the datatype and the dataspace. For example,
+ * some filters perform different actions based on different datatypes
+ * (or datatype sizes) or different number of dimensions or dataspace
+ * sizes.
*
- * The "set_local" callback can be the NULL pointer, in which case, the library
- * will assume that there are no dataset-specific settings for this filter.
+ * The \c set_local callback can be the NULL pointer, in which case,
+ * the library will assume that there are no dataset-specific settings
+ * for this filter.
*
- * The "set_local" callback must return non-negative on success and negative
- * for an error.
+ * The \c set_local callback must return non-negative on success and
+ * negative for an error.
*/
+//! [H5Z_set_local_func_t_snip]
typedef herr_t (*H5Z_set_local_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id);
-
-/*
- * A filter gets definition flags and invocation flags (defined above), the
- * client data array and size defined when the filter was added to the
- * pipeline, the size in bytes of the data on which to operate, and pointers
- * to a buffer and its allocated size.
+//! [H5Z_set_local_func_t_snip]
+/**
+ * \details A filter gets definition flags and invocation flags (defined
+ * above), the client data array and size defined when the filter was
+ * added to the pipeline, the size in bytes of the data on which to
+ * operate, and pointers to a buffer and its allocated size.
*
- * The filter should store the result in the supplied buffer if possible,
- * otherwise it can allocate a new buffer, freeing the original. The
- * allocated size of the new buffer should be returned through the BUF_SIZE
- * pointer and the new buffer through the BUF pointer.
+ * The filter should store the result in the supplied buffer if
+ * possible, otherwise it can allocate a new buffer, freeing the
+ * original. The allocated size of the new buffer should be returned
+ * through the \p buf_size pointer and the new buffer through the \p
+ * buf pointer.
*
- * The return value from the filter is the number of bytes in the output
- * buffer. If an error occurs then the function should return zero and leave
- * all pointer arguments unchanged.
+ * The return value from the filter is the number of bytes in the
+ * output buffer. If an error occurs then the function should return
+ * zero and leave all pointer arguments unchanged.
*/
+//! [H5Z_func_t_snip]
typedef size_t (*H5Z_func_t)(unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[],
size_t nbytes, size_t *buf_size, void **buf);
-
-/*
+//! [H5Z_func_t_snip]
+/**
* The filter table maps filter identification numbers to structs that
* contain a pointers to the filter function and timing statistics.
*/
+//! [H5Z_class2_t_snip]
typedef struct H5Z_class2_t {
- int version; /* Version number of the H5Z_class_t struct */
- H5Z_filter_t id; /* Filter ID number */
- unsigned encoder_present; /* Does this filter have an encoder? */
- unsigned decoder_present; /* Does this filter have a decoder? */
- const char * name; /* Comment for debugging */
- H5Z_can_apply_func_t can_apply; /* The "can apply" callback for a filter */
- H5Z_set_local_func_t set_local; /* The "set local" callback for a filter */
- H5Z_func_t filter; /* The actual filter function */
+ int version; /**< Version number of the H5Z_class_t struct */
+ H5Z_filter_t id; /**< Filter ID number */
+ unsigned encoder_present; /**< Does this filter have an encoder? */
+ unsigned decoder_present; /**< Does this filter have a decoder? */
+ const char *name; /**< Comment for debugging */
+ H5Z_can_apply_func_t can_apply; /**< The "can apply" callback for a filter */
+ H5Z_set_local_func_t set_local; /**< The "set local" callback for a filter */
+ H5Z_func_t filter; /**< The actual filter function */
} H5Z_class2_t;
+//! [H5Z_class2_t_snip]
+/**
+ * \ingroup H5Z
+ *
+ * \brief Registers a new filter with the HDF5 library
+ *
+ * \param[in] cls A pointer to a buffer for the struct containing the
+ * filter-definition
+ *
+ * \return \herr_t
+ *
+ * \details H5Zregister() registers a new filter with the HDF5 library.
+ *
+ * \details Making a new filter available to an application is a two-step
+ * process. The first step is to write the three filter callback
+ * functions described below: \c can_apply, \c set_local, and \c
+ * filter. This call to H5Zregister(), registering the filter with the
+ * library, is the second step. The can_apply and set_local fields can
+ * be set to NULL if they are not required for the filter being
+ * registered.
+ *
+ * H5Zregister() accepts a single parameter, a pointer to a buffer for
+ * the \p cls data structure. That data structure must conform to one
+ * of the following definitions:
+ * \snippet this H5Z_class1_t_snip
+ * or
+ * \snippet this H5Z_class2_t_snip
+ *
+ * \c version is a library-defined value reporting the version number
+ * of the #H5Z_class_t struct. This currently must be set to
+ * #H5Z_CLASS_T_VERS.
+ *
+ * \c id is the identifier for the new filter. This is a user-defined
+ * value between #H5Z_FILTER_RESERVED and #H5Z_FILTER_MAX. These
+ * values are defined in the HDF5 source file H5Zpublic.h, but the
+ * symbols #H5Z_FILTER_RESERVED and #H5Z_FILTER_MAX should always be
+ * used instead of the literal values.
+ *
+ * \c encoder_present is a library-defined value indicating whether
+ * the filter’s encoding capability is available to the application.
+ *
+ * \c decoder_present is a library-defined value indicating whether
+ * the filter’s encoding capability is available to the application.
+ *
+ * \c name is a descriptive comment used for debugging, may contain a
+ * descriptive name for the filter, and may be the null pointer.
+ *
+ * \c can_apply, described in detail below, is a user-defined callback
+ * function which determines whether the combination of the dataset
+ * creation property list values, the datatype, and the dataspace
+ * represent a valid combination to apply this filter to.
+ *
+ * \c set_local, described in detail below, is a user-defined callback
+ * function which sets any parameters that are specific to this
+ * dataset, based on the combination of the dataset creation property
+ * list values, the datatype, and the dataspace.
+ *
+ * \c filter, described in detail below, is a user-defined callback
+ * function which performs the action of the filter.
+ *
+ * The statistics associated with a filter are not reset by this
+ * function; they accumulate over the life of the library.
+ *
+ * #H5Z_class_t is a macro which maps to either H5Z_class1_t or
+ * H5Z_class2_t, depending on the needs of the application. To affect
+ * only this macro, H5Z_class_t_vers may be defined to either 1 or 2.
+ * Otherwise, it will behave in the same manner as other API
+ * compatibility macros. See API Compatibility Macros in HDF5 for more
+ * information. H5Z_class1_t matches the #H5Z_class_t structure that is
+ * used in the 1.6.x versions of the HDF5 library.
+ *
+ * H5Zregister() will automatically detect which structure type has
+ * been passed in, regardless of the mapping of the #H5Z_class_t macro.
+ * However, the application must make sure that the fields are filled
+ * in according to the correct structure definition if the macro is
+ * used to declare the structure.
+ *
+ * \Bold{The callback functions:}\n Before H5Zregister() can link a
+ * filter into an application, three callback functions must be
+ * defined as described in the HDF5 library header file H5Zpublic.h.
+ *
+ * When a filter is applied to the fractal heap for a group (e.g.,
+ * when compressing group metadata) and if the can apply and set local
+ * callback functions have been defined for that filter, HDF5 passes
+ * the value -1 for all parameters for those callback functions. This
+ * is done to ensure that the filter will not be applied to groups if
+ * it relies on these parameters, as they are not applicable to group
+ * fractal heaps; to operate on group fractal heaps, a filter must be
+ * capable of operating on an opaque block of binary data.
+ *
+ * The \Emph{can apply} callback function must return a positive value
+ * for a valid combination, zero for an invalid combination, and a
+ * negative value for an error.
+ * \snippet this H5Z_can_apply_func_t_snip
+ *
+ * Before a dataset is created, the \Emph{can apply} callbacks for any
+ * filters used in the dataset creation property list are called with
+ * the dataset's dataset creation property list, \c dcpl_id, the
+ * dataset's datatype, \p type_id, and a dataspace describing a chunk,
+ * \p space_id, (for chunked dataset storage).
+ *
+ * This callback must determine whether the combination of the dataset
+ * creation property list settings, the datatype, and the dataspace
+ * represent a valid combination to which to apply this filter. For
+ * example, an invalid combination may involve the filter not
+ * operating correctly on certain datatypes, on certain datatype
+ * sizes, or on certain sizes of the chunk dataspace. If this filter
+ * is enabled through H5Pset_filter() as optional and the can apply
+ * function returns 0, the library will skip the filter in the filter
+ * pipeline.
+ *
+ * This callback can be the NULL pointer, in which case the library
+ * will assume that the filter can be applied to a dataset with any
+ * combination of dataset creation property list values, datatypes,
+ * and dataspaces.
+ *
+ * The \Emph{set local} callback function is defined as follows:
+ * \snippet this H5Z_set_local_func_t_snip
+ *
+ * After the can apply callbacks are checked for a new dataset, the
+ * \Emph{set local} callback functions for any filters used in the
+ * dataset creation property list are called. These callbacks receive
+ * \c dcpl_id, the dataset's private copy of the dataset creation
+ * property list passed in to H5Dcreate() (i.e. not the actual
+ * property list passed in to H5Dcreate()); \c type_id, the datatype
+ * identifier passed in to H5Dcreate(), which is not copied and should
+ * not be modified; and \c space_id, a dataspace describing the chunk
+ * (for chunked dataset storage), which should also not be modified.
+ *
+ * The set local callback must set any filter parameters that are
+ * specific to this dataset, based on the combination of the dataset
+ * creation property list values, the datatype, and the dataspace. For
+ * example, some filters perform different actions based on different
+ * datatypes, datatype sizes, numbers of dimensions, or dataspace
+ * sizes.
+ *
+ * The \Emph{set local} callback may be the NULL pointer, in which
+ * case, the library will assume that there are no dataset-specific
+ * settings for this filter.
+ *
+ * The \Emph{set local} callback function must return a non-negative
+ * value on success and a negative value for an error.
+ *
+ * The \Emph{filter operation} callback function, defining the
+ * filter's operation on the data, is defined as follows:
+ * \snippet this H5Z_func_t_snip
+ *
+ * The parameters \c flags, \c cd_nelmts, and \c cd_values are the
+ * same as for the function H5Pset_filter(). The one exception is that
+ * an additional flag, #H5Z_FLAG_REVERSE, is set when the filter is
+ * called as part of the input pipeline.
+ *
+ * The parameter \c buf points to the input buffer which has a size of
+ * \c buf_size bytes, \c nbytes of which are valid data.
+ *
+ * The filter should perform the transformation in place if possible.
+ * If the transformation cannot be done in place, then the filter
+ * should allocate a new buffer with malloc() and assign it to \c buf,
+ * assigning the allocated size of that buffer to \c buf_size. The old
+ * buffer should be freed by calling free().
+ *
+ * If successful, the \Emph{filter operation} callback function
+ * returns the number of valid bytes of data contained in \c buf. In
+ * the case of failure, the return value is 0 (zero) and all pointer
+ * arguments are left unchanged.
+ *
+ * \version 1.8.6 Return type for the \Emph{can apply} callback function,
+ * \ref H5Z_can_apply_func_t, changed to \ref htri_t.
+ * \version 1.8.5 Semantics of the \Emph{can apply} and \Emph{set local}
+ * callback functions changed to accommodate the use of filters
+ * with group fractal heaps.
+ * \version 1.8.3 #H5Z_class_t renamed to H5Z_class2_t, H5Z_class1_t structure
+ * introduced for backwards compatibility with release 1.6.x,
+ * and #H5Z_class_t macro introduced in this release. Function
+ * modified to accept either structure type.
+ * \version 1.8.0 The fields \c version, \c encoder_present, and
+ * \c decoder_present were added to the #H5Z_class_t \c struct
+ * in this release.
+ * \version 1.6.0 This function was substantially revised in Release 1.6.0 with
+ * a new #H5Z_class_t struct and new set local and can apply
+ * callback functions.
+ *
+ */
H5_DLL herr_t H5Zregister(const void *cls);
+/**
+ * \ingroup H5Z
+ *
+ * \brief Unregisters a filter.
+ *
+ * \param[in] id Identifier of the filter to be unregistered.
+ * \return \herr_t
+ *
+ * \details H5Zunregister() unregisters the filter specified in \p id.
+ *
+ * \details This function first iterates through all opened datasets and
+ * groups. If an open object that uses this filter is found, the
+ * function will fail with a message indicating that an object using
+ * the filter is still open. All open files are then flushed to make
+ * sure that all cached data that may use this filter are written out.
+ *
+ * If the application is a parallel program, all processes that
+ * participate in collective data write should call this function to
+ * ensure that all data is flushed.
+ *
+ * After a call to H5Zunregister(), the filter specified in filter
+ * will no longer be available to the application.
+ *
+ * \version 1.8.12 Function modified to check for open objects using the
+ * filter.
+ * \since 1.6.0
+ */
H5_DLL herr_t H5Zunregister(H5Z_filter_t id);
+/**
+ * \ingroup H5Z
+ *
+ * \brief Determines whether a filter is available
+ *
+ * \param[in] id Filter identifier
+ * \return \htri_t
+ *
+ * \details H5Zfilter_avail() determines whether the filter specified in \p id
+ * is available to the application.
+ *
+ * \since 1.6.0
+ */
H5_DLL htri_t H5Zfilter_avail(H5Z_filter_t id);
+/**
+ * \ingroup H5Z
+ *
+ * \brief Retrieves information about a filter
+ *
+ * \param[in] filter Filter identifier
+ * \param[out] filter_config_flags A bit field encoding the returned filter
+ * information
+ * \return \herr_t
+ *
+ * \details H5Zget_filter_info() retrieves information about a filter. At
+ * present, this means that the function retrieves a filter's
+ * configuration flags, indicating whether the filter is configured to
+ * decode data, to encode data, neither, or both.
+ *
+ * If \p filter_config_flags is not set to NULL prior to the function
+ * call, the returned parameter contains a bit field specifying the
+ * available filter configuration. The configuration flag values can
+ * then be determined through a series of bitwise AND operations, as
+ * described below.
+ *
+ * Valid filter configuration flags include the following:
+ * <table>
+ * <tr><td>#H5Z_FILTER_CONFIG_ENCODE_ENABLED</td>
+ * <td>Encoding is enabled for this filter</td></tr>
+ * <tr><td>#H5Z_FILTER_CONFIG_DECODE_ENABLED</td>
+ * <td>Decoding is enabled for this filter</td></tr>
+ * </table>
+ *
+ * A bitwise AND of the returned \p filter_config_flags and a valid
+ * filter configuration flag will reveal whether the related
+ * configuration option is available. For example, if the value of
+ * \code
+ * H5Z_FILTER_CONFIG_ENCODE_ENABLED & filter_config_flags
+ * \endcode
+ * is true, i.e., greater than 0 (zero), the queried filter
+ * is configured to encode data; if the value is \c FALSE, i.e., equal to
+ * 0 (zero), the filter is not so configured.
+ *
+ * If a filter is not encode-enabled, the corresponding \c H5Pset_*
+ * function will return an error if the filter is added to a dataset
+ * creation property list (which is required if the filter is to be
+ * used to encode that dataset). For example, if the
+ * #H5Z_FILTER_CONFIG_ENCODE_ENABLED flag is not returned for the SZIP
+ * filter, #H5Z_FILTER_SZIP, a call to H5Pset_szip() will fail.
+ *
+ * If a filter is not decode-enabled, the application will not be able
+ * to read an existing file encoded with that filter.
+ *
+ * This function should be called, and the returned \p
+ * filter_config_flags analyzed, before calling any other function,
+ * such as H5Pset_szip() , that might require a particular filter
+ * configuration.
+ *
+ * \since 1.6.3
+ */
H5_DLL herr_t H5Zget_filter_info(H5Z_filter_t filter, unsigned int *filter_config_flags);
/* Symbols defined for compatibility with previous versions of the HDF5 API.
@@ -224,17 +633,19 @@ H5_DLL herr_t H5Zget_filter_info(H5Z_filter_t filter, unsigned int *filter_confi
*/
#ifndef H5_NO_DEPRECATED_SYMBOLS
-/*
+/**
* The filter table maps filter identification numbers to structs that
* contain a pointers to the filter function and timing statistics.
*/
+//! [H5Z_class1_t_snip]
typedef struct H5Z_class1_t {
- H5Z_filter_t id; /* Filter ID number */
- const char * name; /* Comment for debugging */
- H5Z_can_apply_func_t can_apply; /* The "can apply" callback for a filter */
- H5Z_set_local_func_t set_local; /* The "set local" callback for a filter */
- H5Z_func_t filter; /* The actual filter function */
+ H5Z_filter_t id; /**< Filter ID number */
+ const char *name; /**< Comment for debugging */
+ H5Z_can_apply_func_t can_apply; /**< The "can apply" callback for a filter */
+ H5Z_set_local_func_t set_local; /**< The "set local" callback for a filter */
+ H5Z_func_t filter; /**< The actual filter function */
} H5Z_class1_t;
+//! [H5Z_class1_t_snip]
#endif /* H5_NO_DEPRECATED_SYMBOLS */
diff --git a/src/H5checksum.c b/src/H5checksum.c
index bc36bb9..82964d9 100644
--- a/src/H5checksum.c
+++ b/src/H5checksum.c
@@ -25,6 +25,7 @@
/****************/
/* Module Setup */
/****************/
+#include "H5module.h" /* This source code file is part of the H5 module */
/***********/
/* Headers */
@@ -379,7 +380,7 @@ uint32_t
H5_checksum_lookup3(const void *key, size_t length, uint32_t initval)
{
const uint8_t *k = (const uint8_t *)key;
- uint32_t a, b, c; /* internal state */
+ uint32_t a, b, c = 0; /* internal state */
FUNC_ENTER_NOAPI_NOINIT_NOERR
diff --git a/src/H5dbg.c b/src/H5dbg.c
index 1b64d2c..5d38efc 100644
--- a/src/H5dbg.c
+++ b/src/H5dbg.c
@@ -25,6 +25,7 @@
/****************/
/* Module Setup */
/****************/
+#include "H5module.h" /* This source code file is part of the H5 module */
/***********/
/* Headers */
diff --git a/src/H5err.txt b/src/H5err.txt
index 24ac2ac..05476e5 100644
--- a/src/H5err.txt
+++ b/src/H5err.txt
@@ -46,6 +46,7 @@
MAJOR, H5E_ARGS, Invalid arguments to routine
MAJOR, H5E_RESOURCE, Resource unavailable
MAJOR, H5E_INTERNAL, Internal error (too specific to document in detail)
+MAJOR, H5E_LIB, General library infrastructure
MAJOR, H5E_FILE, File accessibility
MAJOR, H5E_IO, Low-level I/O
MAJOR, H5E_FUNC, Function entry/exit
diff --git a/src/H5module.h b/src/H5module.h
new file mode 100644
index 0000000..f6884b1
--- /dev/null
+++ b/src/H5module.h
@@ -0,0 +1,34 @@
+/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+ * Copyright by The HDF Group. *
+ * All rights reserved. *
+ * *
+ * This file is part of HDF5. The full HDF5 copyright notice, including *
+ * terms governing use, modification, and redistribution, is contained in *
+ * the COPYING file, which can be found at the root of the source code *
+ * distribution tree, or in https://support.hdfgroup.org/ftp/HDF5/releases. *
+ * If you do not have access to either file, you may request a copy from *
+ * help@hdfgroup.org. *
+ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+
+/*
+ * Purpose: This file contains declarations which define macros for the
+ * H5 package. Including this header means that the source file
+ * is part of the H5 package.
+ */
+#ifndef _H5module_H
+#define _H5module_H
+
+/* Define the proper control macros for the generic FUNC_ENTER/LEAVE and error
+ * reporting macros.
+ */
+#define H5_MODULE
+#define H5_MY_PKG H5
+#define H5_MY_PKG_ERR H5E_LIB
+#define H5_MY_PKG_INIT YES
+
+/**\defgroup H5 H5
+ * \brief General Library Functions
+ * \todo Describe concisely what the functions in this module are about.
+ */
+
+#endif /* _H5module_H */
diff --git a/src/H5private.h b/src/H5private.h
index 1390b3f..600089d 100644
--- a/src/H5private.h
+++ b/src/H5private.h
@@ -2160,7 +2160,6 @@ H5_DLL herr_t H5CX_pop(void);
#define FUNC_ENTER_API_INIT(err) \
/* Initialize the library */ \
if (!H5_INIT_GLOBAL && !H5_TERM_GLOBAL) { \
- H5_INIT_GLOBAL = TRUE; \
if (H5_init_library() < 0) \
HGOTO_ERROR(H5E_FUNC, H5E_CANTINIT, err, "library initialization failed") \
} /* end if */ \
@@ -2603,7 +2602,6 @@ extern hbool_t H5_api_entered_g; /* Has library already been entered through API
\
/* Initialize the library or bust */ \
if (!H5_INIT_GLOBAL && !H5_TERM_GLOBAL) { \
- H5_INIT_GLOBAL = TRUE; \
if (H5_init_library() < 0) { \
/* (Can't use H5E_THROW here) */ \
H5E_PRINTF(H5E_CANTINIT, "interface initialization failed"); \
diff --git a/src/H5public.h b/src/H5public.h
index 9202be4..44e0d94 100644
--- a/src/H5public.h
+++ b/src/H5public.h
@@ -304,15 +304,21 @@ typedef unsigned long uint32_t;
#error "nothing appropriate for uint32_t"
#endif
-/* Common iteration orders */
+//! [H5_iter_order_t_snip]
+
+/**
+ * Common iteration orders
+ */
typedef enum {
- H5_ITER_UNKNOWN = -1, /* Unknown order */
- H5_ITER_INC, /* Increasing order */
- H5_ITER_DEC, /* Decreasing order */
- H5_ITER_NATIVE, /* No particular order, whatever is fastest */
- H5_ITER_N /* Number of iteration orders */
+ H5_ITER_UNKNOWN = -1, /**< Unknown order */
+ H5_ITER_INC, /**< Increasing order */
+ H5_ITER_DEC, /**< Decreasing order */
+ H5_ITER_NATIVE, /**< No particular order, whatever is fastest */
+ H5_ITER_N /**< Number of iteration orders */
} H5_iter_order_t;
+//! [H5_iter_order_t_snip]
+
/* Iteration callback values */
/* (Actually, any positive value will cause the iterator to stop and pass back
* that positive value to the function that called the iterator)
@@ -321,18 +327,22 @@ typedef enum {
#define H5_ITER_CONT (0)
#define H5_ITER_STOP (1)
-/*
+//! [H5_index_t_snip]
+
+/**
* The types of indices on links in groups/attributes on objects.
* Primarily used for "<do> <foo> by index" routines and for iterating over
* links in groups/attributes on objects.
*/
typedef enum H5_index_t {
- H5_INDEX_UNKNOWN = -1, /* Unknown index type */
- H5_INDEX_NAME, /* Index on names */
- H5_INDEX_CRT_ORDER, /* Index on creation order */
- H5_INDEX_N /* Number of indices defined */
+ H5_INDEX_UNKNOWN = -1, /**< Unknown index type */
+ H5_INDEX_NAME, /**< Index on names */
+ H5_INDEX_CRT_ORDER, /**< Index on creation order */
+ H5_INDEX_N /**< Number of indices defined */
} H5_index_t;
+//! [H5_index_t_snip]
+
/**
* Storage info struct used by H5O_info_t and H5F_info_t
*/
@@ -343,45 +353,446 @@ typedef struct H5_ih_info_t {
} H5_ih_info_t;
//! [H5_ih_info_t_snip]
-/* Tokens are unique and permanent identifiers that are
- * used to reference HDF5 objects in a container. */
+/**
+ * The maximum size allowed for tokens
+ * \details Tokens are unique and permanent identifiers that are
+ * used to reference HDF5 objects in a container. This allows
+ * for 128-bit tokens
+ */
+#define H5O_MAX_TOKEN_SIZE (16)
-/* The maximum size allowed for tokens */
-#define H5O_MAX_TOKEN_SIZE (16) /* Allows for 128-bit tokens */
+//! [H5O_token_t_snip]
+/**
+ * \internal (Hoisted here, since it's used by both the
+ * H5Lpublic.h and H5Opublic.h headers) */
/* Type for object tokens */
-/* (Hoisted here, since it's used by both the H5Lpublic.h and H5Opublic.h headers) */
typedef struct H5O_token_t {
uint8_t __data[H5O_MAX_TOKEN_SIZE];
} H5O_token_t;
-/*
+//! [H5O_token_t_snip]
+
+/**
* Allocation statistics info struct
*/
typedef struct H5_alloc_stats_t {
- unsigned long long total_alloc_bytes; /* Running count of total # of bytes allocated */
- size_t curr_alloc_bytes; /* Current # of bytes allocated */
- size_t peak_alloc_bytes; /* Peak # of bytes allocated */
- size_t max_block_size; /* Largest block allocated */
- size_t total_alloc_blocks_count; /* Running count of total # of blocks allocated */
- size_t curr_alloc_blocks_count; /* Current # of blocks allocated */
- size_t peak_alloc_blocks_count; /* Peak # of blocks allocated */
+ unsigned long long total_alloc_bytes; /**< Running count of total # of bytes allocated */
+ size_t curr_alloc_bytes; /**< Current # of bytes allocated */
+ size_t peak_alloc_bytes; /**< Peak # of bytes allocated */
+ size_t max_block_size; /**< Largest block allocated */
+ size_t total_alloc_blocks_count; /**< Running count of total # of blocks allocated */
+ size_t curr_alloc_blocks_count; /**< Current # of blocks allocated */
+ size_t peak_alloc_blocks_count; /**< Peak # of blocks allocated */
} H5_alloc_stats_t;
/* Functions in H5.c */
+/**
+ * \ingroup H5
+ * \brief Initializes the HDF5 library
+ * \return \herr_t
+ *
+ * \details H5open() initializes the HDF5 library.
+ *
+ * \details When the HDF5 library is used in a C application, the library is
+ * automatically initialized when the first HDf5 function call is
+ * issued. If one finds that an HDF5 library function is failing
+ * inexplicably, H5open() can be called first. It is safe to call
+ * H5open() before an application issues any other function calls to
+ * the HDF5 library as there are no damaging side effects in calling
+ * it more than once.
+ */
H5_DLL herr_t H5open(void);
+/**
+ * \ingroup H5
+ * \brief Flushes all data to disk, closes all open objects, and releases memory
+ * \return \herr_t
+ *
+ * \details H5close() flushes all data to disk, closes all open HDF5 objects,
+ * and cleans up all memory used by the HDF5 library. This function is
+ * generally called when the application calls exit(), but may be
+ * called earlier in the event of an emergency shutdown or out of a
+ * desire to free all resources used by the HDF5 library.
+ */
H5_DLL herr_t H5close(void);
+/**
+ * \ingroup H5
+ * \brief Instructs library not to install atexit() cleanup routine
+ * \return \herr_t
+ *
+ * \details H5dont_atexit() indicates to the library that an atexit() cleanup
+ * routine should not be installed. The major purpose for using this
+ * function is in situations where the library is dynamically linked
+ * into an application and is un-linked from the application before
+ * exit() gets called. In those situations, a routine installed with
+ * atexit() would jump to a routine which was no longer in memory,
+ * causing errors.
+ *
+ * \attention In order to be effective, this routine \Emph{must} be called
+ * before any other HDF5 function calls, and must be called each
+ * time the library is loaded/linked into the application (the first
+ * time and after it's been un-loaded).
+ */
H5_DLL herr_t H5dont_atexit(void);
+/**
+ * \ingroup H5
+ * \brief Garbage collects on all free-lists of all types
+ * \return \herr_t
+ *
+ * \details H5garbage_collect() walks through all garbage collection routines
+ * of the library, freeing any unused memory.
+ *
+ * It is not required that H5garbage_collect() be called at any
+ * particular time; it is only necessary in certain situations where
+ * the application has performed actions that cause the library to
+ * allocate many objects. The application should call
+ * H5garbage_collect() if it eventually releases those objects and
+ * wants to reduce the memory used by the library from the peak usage
+ * required.
+ *
+ * \note The library automatically garbage collects all the free lists when the
+ * application ends.
+ */
H5_DLL herr_t H5garbage_collect(void);
+/**
+ * \ingroup H5
+ * \brief Sets free-list size limits
+ *
+ * \param[in] reg_global_lim The cumulative limit, in bytes, on memory used for
+ * all regular free lists (Default: 1MB)
+ * \param[in] reg_list_lim The limit, in bytes, on memory used for each regular
+ * free list (Default: 64KB)
+ * \param[in] arr_global_lim The cumulative limit, in bytes, on memory used for
+ * all array free lists (Default: 4MB)
+ * \param[in] arr_list_lim The limit, in bytes, on memory used for each array
+ * free list (Default: 256KB)
+ * \param[in] blk_global_lim The cumulative limit, in bytes, on memory used for
+ * all block free lists and, separately, for all
+ * factory free lists (Default: 16MB)
+ * \param[in] blk_list_lim The limit, in bytes, on memory used for each block
+ * or factory free list (Default: 1MB)
+ * \return \herr_t
+ *
+ * \details H5set_free_list_limits() sets size limits on all types of free
+ * lists. The HDF5 library uses free lists internally to manage
+ * memory. The types of free lists used are as follows:
+ * \li Regular free lists manage memory for single internal data
+ * structures.
+ * \li Array free lists manage memory for arrays of internal
+ * data structures.
+ * \li Block free lists manage memory for arbitrarily-sized blocks
+ * of bytes.
+ * \li Factory free lists manage memory for fixed-size blocks of
+ * bytes.
+ *
+ * The parameters specify global and per-list limits; for example, \p
+ * reg_global_limit and \p reg_list_limit limit the accumulated size
+ * of all regular free lists and the size of each individual regular
+ * free list, respectively. Therefore, if an application sets a 1Mb
+ * limit on each of the global lists, up to 4Mb of total storage might
+ * be allocated, 1Mb for each of the regular, array, block, and
+ * factory type lists.
+ *
+ * The settings specified for block free lists are duplicated for
+ * factory free lists. Therefore, increasing the global limit on block
+ * free lists by x bytes will increase the potential free list memory
+ * usage by 2x bytes.
+ *
+ * Using a value of -1 for a limit means that no limit is set for the
+ * specified type of free list.
+ *
+ * \version 1.8.3 Function changed in this release to set factory free list
+ * memory limits.
+ *
+ * \since 1.6.0
+ */
H5_DLL herr_t H5set_free_list_limits(int reg_global_lim, int reg_list_lim, int arr_global_lim,
int arr_list_lim, int blk_global_lim, int blk_list_lim);
+/**
+ * \ingroup H5
+ * \brief Gets the current size of the free lists used to manage memory
+ *
+ * \param[out] reg_size The current size of all "regular" free list memory used
+ * \param[out] arr_size The current size of all "array" free list memory used
+ * \param[out] blk_size The current size of all "block" free list memory used
+ * \param[out] fac_size The current size of all "factory" free list memory used
+ * \return \herr_t
+ *
+ * \details H5get_free_list_sizes() obtains the current size of the different
+ * kinds of free lists that the library uses to manage memory. The
+ * free list sizes can be set with H5set_free_list_limits() and
+ * garbage collected with H5garbage_collect(). These lists are global
+ * for the entire library.
+ *
+ * \since 1.12.1
+ */
H5_DLL herr_t H5get_free_list_sizes(size_t *reg_size, size_t *arr_size, size_t *blk_size, size_t *fac_size);
+/**
+ * \ingroup H5
+ * \brief Gets the memory allocation statistics for the library
+ *
+ * \param[out] stats Memory allocation statistics
+ * \return \herr_t
+ *
+ * \details H5get_alloc_stats() gets the memory allocation statistics for the
+ * library, if the \c --enable-memory-alloc-sanity-check option was
+ * given when building the library. Applications can check whether
+ * this option was enabled detecting if the
+ * \c H5_MEMORY_ALLOC_SANITY_CHECK macro is defined. This option is
+ * enabled by default for debug builds of the library and disabled by
+ * default for non-debug builds. If the option is not enabled, all the
+ * values returned with be 0. These statistics are global for the
+ * entire library, but do not include allocations from chunked dataset
+ * I/O filters or non-native VOL connectors.
+ *
+ * \since 1.12.1
+ */
H5_DLL herr_t H5get_alloc_stats(H5_alloc_stats_t *stats);
+/**
+ * \ingroup H5
+ * \brief Returns the HDF library release number
+ *
+ * \param[out] majnum The major version number of the library
+ * \param[out] minnum The minor version number of the library
+ * \param[out] relnum The release version number of the library
+ * \return \herr_t
+ *
+ * \details H5get_libversion() retrieves the major, minor, and release numbers
+ * of the version of the HDF5 library which is linked to the
+ * application.
+ *
+ */
H5_DLL herr_t H5get_libversion(unsigned *majnum, unsigned *minnum, unsigned *relnum);
+/**
+ * \ingroup H5
+ * \brief Verifies that HDF5 library versions are consistent
+ *
+ * \param[in] majnum HDF5 library major version number
+ * \param[in] minnum HDF5 library minor version number
+ * \param[in] relnum HDF5 library release number
+ * \return \herr_t
+ *
+ * \details H5check_version() verifies that the version of the HDF5 library
+ * with which an application was compiled, as indicated by the passed
+ * parameters, matches the version of the HDF5 library against which
+ * the application is currently linked.
+ *
+ * \p majnum is the major version number of the HDF library with which
+ * the application was compiled, \p minnum is the minor version
+ * number, and \p relnum is the release number. Consider the following
+ * example:
+ *
+ * An official HDF5 release is labelled as follows:
+ * HDF5 Release \Code{\<majnum\>.\<minnum\>.\<relnum\>}\n
+ * For example, in HDF5 Release 1.8.5:
+ * \li 1 is the major version number, \p majnum.
+ * \li 8 is the minor version number, \p minnum.
+ * \li 5 is the release number, \p relnum.
+ *
+ * As stated above, H5check_version() first verifies that the version
+ * of the HDF5 library with which an application was compiled matches
+ * the version of the HDF5 library against which the application is
+ * currently linked. If this check fails, H5check_version() causes the
+ * application to abort (by means of a standard C abort() call) and
+ * prints information that is usually useful for debugging. This
+ * precaution is is taken to avoid the risks of data corruption or
+ * segmentation faults.
+ *
+ * The most common cause of this failure is that an application was
+ * compiled with one version of HDF5 and is dynamically linked with a
+ * different version different version.
+ *
+ * If the above test passes, H5check_version() proceeds to verify the
+ * consistency of additional library version information. This is
+ * designed to catch source code inconsistencies that do not normally
+ * cause failures; if this check reveals an inconsistency, an
+ * informational warning is printed but the application is allowed to
+ * run.
+ *
+ */
H5_DLL herr_t H5check_version(unsigned majnum, unsigned minnum, unsigned relnum);
+/**
+ * \ingroup H5
+ * \brief Determines whether the HDF5 library was built with the thread-safety
+ * feature enabled
+ *
+ * \param[out] is_ts Boolean value indicating whether the library was built
+ * with thread-safety enabled
+ * \return \herr_t
+ *
+ * \details The HDF5 library, although not internally multi-threaded, can be
+ * built with a thread-safety feature enabled that protects internal
+ * data structures with a mutex. In certain circumstances, it may be
+ * useful to determine, at run-time, whether the linked HDF5 library
+ * was built with the thread-safety feature enabled.
+ */
H5_DLL herr_t H5is_library_threadsafe(hbool_t *is_ts);
+/**
+ * \ingroup H5
+ * \brief Frees memory allocated by the HDF5 library
+ *
+ * \param[in] mem Buffer to be freed. Can be NULL
+ * \return \herr_t
+ *
+ * \details H5free_memory() frees memory that has been allocated by the caller
+ * with H5allocate_memory() or by the HDF5 library on behalf of the
+ * caller.
+ *
+ * H5Tget_member_name() provides an example of memory allocation on
+ * behalf of the caller: The function returns a buffer containing the
+ * name of a compound datatype member. It is the caller’s
+ * responsibility to eventually free that buffer with H5free_memory().
+ *
+ * \attention It is especially important to use this function to free memory
+ * allocated by the library on Windows. The C standard library is
+ * implemented in dynamic link libraries (DLLs) known as the C
+ * run-time (CRT). Each version of Visual Studio comes with two CRT
+ * DLLs (debug and release) and allocating and freeing across DLL
+ * boundaries can cause resource leaks and subtle bugs due to heap
+ * corruption.\n
+ * Only use this function to free memory allocated by the HDF5
+ * Library. It will generally not be safe to use this function to
+ * free memory allocated by any other means.\n
+ * Even when using this function, it is still best to ensure that
+ * all components of a C application are built with the same version
+ * of Visual Studio and build (debug or release) and thus linked
+ * against the same CRT.
+ *
+ * \see H5allocate_memory(), H5resize_memory()
+ *
+ * \since 1.8.13
+ *
+ */
H5_DLL herr_t H5free_memory(void *mem);
+/**
+ * \ingroup H5
+ * \brief Frees memory allocated by the HDF5 library
+ *
+ * \param[in] size The size in bytes of the buffer to be allocated
+ * \param[in] clear Flag whether the new buffer is to be initialized with 0
+ *
+ * \return On success, returns pointer to newly allocated buffer or returns
+ * NULL if size is 0 (zero).\n
+ * Returns NULL on failure.
+ *
+ * \details H5allocate_memory() allocates a memory buffer of size bytes that
+ * will later be freed internally by the HDF5 library.
+ *
+ * The boolean \p clear parameter specifies whether the buffer should
+ * be initialized. If clear is \c TRUE, all bits in the buffer are to be
+ * set to 0 (zero); if clear is \c FALSE, the buffer will not be
+ * initialized.
+ *
+ * This function is intended to have the semantics of malloc() and
+ * calloc(). However, unlike malloc() and calloc() which allow for a
+ * "special" pointer to be returned instead of NULL, this function
+ * always returns NULL on failure or when size is set to 0 (zero).
+ *
+ * \note At this time, the only intended use for this function is to allocate
+ * memory that will be returned to the library as a data buffer from a
+ * third-party filter.
+ *
+ * \attention To avoid heap corruption, allocated memory should be freed using
+ * the same library that initially allocated it. In most cases, the
+ * HDF5 API uses resources that are allocated and freed either
+ * entirely by the user or entirely by the library, so this is not a
+ * problem. In rare cases, however, HDF5 API calls will free memory
+ * that the user allocated. This function allows the user to safely
+ * allocate this memory.\n
+ * It is particularly important to use this function to allocate
+ * memory in Microsoft Windows environments. In Windows, the C
+ * standard library is implemented in dynamic link libraries (DLLs)
+ * known as the C run-time (CRT). Each version of Visual Studio
+ * comes with multiple versions of the CRT DLLs (debug, release, et
+ * cetera) and allocating and freeing memory across DLL boundaries
+ * can cause resource leaks and subtle bugs due to heap corruption.\n
+ * Even when using this function, it is best where possible to
+ * ensure that all components of a C application are built with the
+ * same version of Visual Studio and configuration (Debug or
+ * Release), and thus linked against the same CRT.\n
+ * Use this function only to allocate memory inside third-party HDF5
+ * filters. It will generally not be safe to use this function to
+ * allocate memory for any other purpose.
+ *
+ * \see H5free_memory(), H5resize_memory()
+ *
+ * \since 1.8.15
+ *
+ */
H5_DLL void * H5allocate_memory(size_t size, hbool_t clear);
+/**
+ * \ingroup H5
+ * \brief Resizes and, if required, re-allocates memory that will later be
+ * freed internally by the HDF5 library
+ *
+ * \param[in] mem Pointer to a buffer to be resized. May be NULL
+ * \param[in] size New size of the buffer, in bytes
+
+ *
+ * \return On success, returns pointer to resized or reallocated buffer
+ * or returns NULL if size is 0 (zero).\n
+ * Returns NULL on failure.
+ *
+ * \details H5resize_memory() takes a pointer to an existing buffer and resizes
+ * the buffer to match the value in \p size. If necessary, the buffer
+ * is reallocated. If \p size is 0, the buffer is released.
+ *
+ * The input buffer must either be NULL or have been allocated by
+ * H5allocate_memory() since the input buffer may be freed by the
+ * library.
+ *
+ * For certain behaviors, the pointer \p mem may be passed in as NULL.
+ *
+ * This function is intended to have the semantics of realloc():
+ *
+ * <table>
+ * <tr><td>\Code{H5resize_memory(buffer, size)}</td>
+ * <td>Resizes buffer. Returns pointer to resized buffer.</td></tr>
+ * <tr><td>\Code{H5resize_memory(NULL, size)}</td>
+ * <td>Allocates memory using HDF5 Library allocator.
+ * Returns pointer to new buffer</td></tr>
+ * <tr><td>\Code{H5resize_memory(buffer, 0)}</td>
+ * <td>Frees memory using HDF5 Library allocator.
+ * Returns NULL.</td></tr>
+ * <tr><td>\Code{H5resize_memory(NULL, 0)}</td>
+ * <td>Returns NULL (undefined in C standard).</td></tr>
+ * </table>
+ *
+ * Unlike realloc(), which allows for a "special pointer to be
+ * returned instead of NULL, this function always returns NULL on
+ * failure or when size is 0 (zero).
+ *
+ * \note At this time, the only intended use for this function is to resize or
+ * reallocate memory that will be returned to the library (and eventually
+ * to the user) as a data buffer from a third-party HDF5 filter.
+ *
+ * \attention To avoid heap corruption, allocated memory should be freed using
+ * the same library that initially allocated it. In most cases, the
+ * HDF5 API uses resources that are allocated and freed either
+ * entirely by the user or entirely by the library, so this is not a
+ * problem. In rare cases, however, HDF5 API calls will free memory
+ * that the user allocated. This function allows the user to safely
+ * allocate this memory.\n
+ * It is particularly important to use this function to resize
+ * memory on Microsoft Windows systems. In Windows, the C standard
+ * library is implemented in dynamic link libraries (DLLs) known as
+ * the C run-time (CRT). Each version of Visual Studio comes with
+ * multiple versions of the CRT DLLs (debug, release, et cetera) and
+ * allocating and freeing memory across DLL boundaries can cause
+ * resource leaks and subtle bugs due to heap corruption.\n
+ * Even when using this function, it is still best to ensure that
+ * all components of a C application are built with the same version
+ * of Visual Studio and the same configuration (Debug or Release),
+ * and thus linked against the same CRT.\n
+ * Only use this function to resize memory inside third-party HDF5
+ * filters. It will generally not be safe to use this function to
+ * resize memory for any other purpose.
+ *
+ * \see H5allocate_memory(), H5free_memory()
+ *
+ * \since 1.8.15
+ *
+ */
H5_DLL void * H5resize_memory(void *mem, size_t size);
#ifdef __cplusplus
diff --git a/src/H5system.c b/src/H5system.c
index b2a2668..a817b7c 100644
--- a/src/H5system.c
+++ b/src/H5system.c
@@ -25,6 +25,7 @@
/****************/
/* Module Setup */
/****************/
+#include "H5module.h" /* This source code file is part of the H5 module */
/***********/
/* Headers */
@@ -347,7 +348,7 @@ H5_make_time(struct tm *tm)
*/
long timezone = 0;
#endif /* defined(H5_HAVE_VISUAL_STUDIO) && (_MSC_VER >= 1900) */
- time_t ret_value; /* Return value */
+ time_t ret_value = 0; /* Return value */
FUNC_ENTER_NOAPI_NOINIT
diff --git a/src/H5timer.c b/src/H5timer.c
index 1df2d8d..b53c302 100644
--- a/src/H5timer.c
+++ b/src/H5timer.c
@@ -24,6 +24,7 @@
/****************/
/* Module Setup */
/****************/
+#include "H5module.h" /* This source code file is part of the H5 module */
/***********/
/* Headers */
diff --git a/src/H5trace.c b/src/H5trace.c
index 18c7f7e..0ffa0aa 100644
--- a/src/H5trace.c
+++ b/src/H5trace.c
@@ -25,6 +25,7 @@
/****************/
/* Module Setup */
/****************/
+#include "H5module.h" /* This source code file is part of the H5 module */
#define H5I_FRIEND /*suppress error about including H5Ipkg */
/***********/