summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--doxygen/aliases16
-rw-r--r--src/H5.c36
-rw-r--r--src/H5Imodule.h5
-rw-r--r--src/H5Ipublic.h619
-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/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
25 files changed, 6930 insertions, 562 deletions
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/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/H5Imodule.h b/src/H5Imodule.h
index 62b1406..4e08098 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 697777c..a7c4961 100644
--- a/src/H5Ipublic.h
+++ b/src/H5Ipublic.h
@@ -21,37 +21,41 @@
/* 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 atoms to return to users */
+/**
+ * Type of atoms to return to users
+ */
typedef int64_t hid_t;
#define PRIdHID PRId64
@@ -59,13 +63,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 +82,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 +102,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/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 1784a11..eb1f573 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 9f23d0a..9704fff 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 */
/***********/