summaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
Diffstat (limited to 'src')
-rw-r--r--src/H5Apublic.h872
-rw-r--r--src/H5Fpublic.h2
-rw-r--r--src/H5Ppublic.h5028
-rw-r--r--src/H5Spublic.h1096
4 files changed, 6673 insertions, 325 deletions
diff --git a/src/H5Apublic.h b/src/H5Apublic.h
index 847f053..993961f 100644
--- a/src/H5Apublic.h
+++ b/src/H5Apublic.h
@@ -23,12 +23,14 @@
#include "H5Tpublic.h" /* Datatypes */
/* Information struct for attribute (for H5Aget_info/H5Aget_info_by_idx) */
+//! [H5A_info_t_snip]
typedef struct {
hbool_t corder_valid; /* Indicate if creation order is valid */
H5O_msg_crt_idx_t corder; /* Creation order */
H5T_cset_t cset; /* Character set of attribute name */
hsize_t data_size; /* Size of raw data */
} H5A_info_t;
+//! [H5A_info_t_snip]
/* Typedef for H5Aiterate2() callbacks */
typedef herr_t (*H5A_operator2_t)(hid_t location_id /*in*/, const char *attr_name /*in*/,
@@ -45,6 +47,27 @@ typedef herr_t (*H5A_operator2_t)(hid_t location_id /*in*/, const char *attr_nam
extern "C" {
#endif
+/*-------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Closes the specified attribute
+ *
+ * \attr_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Aclose() terminates access to the attribute specified by
+ * \p attr_id by releasing the identifier.
+ *
+ * \attention Further use of a released attribute identifier is illegal; a
+ * function using such an identifier will generate an error.
+ *
+ * \since 1.0.0
+ *
+ * \see H5Acreate(), H5Aopen()
+ */
+H5_DLL herr_t H5Aclose(hid_t attr_id);
/* --------------------------------------------------------------------------*/
/**
* \ingroup H5A
@@ -92,8 +115,8 @@ extern "C" {
* \see H5Aclose()
*
*/
-H5_DLL hid_t H5Acreate2(hid_t loc_id, const char *attr_name, hid_t type_id, hid_t space_id, hid_t acpl_id,
- hid_t aapl_id);
+H5_DLL hid_t H5Acreate2(hid_t loc_id, const char *attr_name, hid_t type_id, hid_t space_id, hid_t acpl_id,
+ hid_t aapl_id);
H5_DLL hid_t H5Acreate_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
const char *attr_name, hid_t type_id, hid_t space_id, hid_t acpl_id,
hid_t aapl_id, hid_t es_id);
@@ -144,8 +167,626 @@ H5_DLL hid_t H5Acreate_async(const char *app_file, const char *app_func, unsigne
* \since 1.8.0
*
*/
-H5_DLL hid_t H5Acreate_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t type_id,
- hid_t space_id, hid_t acpl_id, hid_t aapl_id, hid_t lapl_id);
+H5_DLL hid_t H5Acreate_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t type_id,
+ hid_t space_id, hid_t acpl_id, hid_t aapl_id, hid_t lapl_id);
+/*-------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Deletes an attribute from a specified location
+ *
+ * \fgdt_loc_id
+ * \param[in] attr_name Name of the attribute to delete
+ *
+ * \return \herr_t
+ *
+ * \details H5Adelete() removes the attribute specified by its name,
+ * \p attr_name, from a file, dataset, group, or named datatype.
+ * This function should not be used when attribute identifiers
+ * are open on \p loc_id as it may cause the internal indexes of
+ * the attributes to change and future writes to the open
+ * attributes to produce incorrect results.
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Adelete(hid_t loc_id, const char *attr_name);
+/*-------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Deletes an attribute from an object according to index order
+ *
+ * \fgdt_loc_id
+ * \param[in] obj_name Name of object, relative to location, from which
+ * attribute is to be removed
+ * \param[in] idx_type Type of index
+ * \param[in] order Order in which to iterate over index
+ * \param[in] n Offset within index
+ * \lapl_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Adelete_by_idx() removes an attribute, specified by its
+ * location in an index, from an object.
+ *
+ * The object from which the attribute is to be removed is
+ * specified by a location identifier and name, \p loc_id and
+ * \p obj_name, respectively. If \p loc_id fully specifies the
+ * object from which the attribute is to be removed, \p obj_name
+ * should be '.' (a dot).
+ *
+ * The attribute to be removed is specified by a position in an
+ * index, \p n. The type of index is specified by \p idx_type and
+ * may be #H5_INDEX_NAME, for an alpha-numeric index by name, or
+ * #H5_INDEX_CRT_ORDER, for an index by creation order. The order
+ * in which the index is to be traversed is specified by \p order
+ * and may be #H5_ITER_INC (increment) for top-down iteration,
+ * #H5_ITER_DEC (decrement) for bottom-up iteration, or
+ * #H5_ITER_NATIVE, in which case HDF5 will iterate in the
+ * fastest-available order. For example, if \p idx_type, \p order,
+ * and \p n are set to #H5_INDEX_NAME, #H5_ITER_INC, and 5,
+ * respectively, the fifth attribute by alpha-numeric order of
+ * attribute names will be removed.
+ *
+ * For a discussion of \p idx_type and \p order, the valid values
+ * of those parameters, and the use of \p n, see the description
+ * of H5Aiterate2().
+ *
+ * The link access property list, \p lapl_id, may provide
+ * information regarding the properties of links required to access
+ * the object, \p obj_name.
+
+ * \since 1.8.0
+ *
+ */
+H5_DLL herr_t H5Adelete_by_idx(hid_t loc_id, const char *obj_name,
+ H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t lapl_id);
+/*-------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Removes an attribute from a specified location
+ *
+ * \fgdt_loc_id
+ * \param[in] obj_name Name of object, relative to location, from which
+ * attribute is to be removed
+ * \param[in] attr_name Name of attribute to delete
+ * \lapl_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Adelete_by_name() removes the attribute \p attr_name
+ * from an object specified by location and name, \p loc_id and
+ * \p obj_name, respectively.
+ *
+ * If \p loc_id fully specifies the object from which the
+ * attribute is to be removed, \p obj_name should be '.' (a dot).
+ *
+ * The link access property list, \p lapl_id, may provide
+ * information regarding the properties of links required to
+ * access the object, \p obj_name.
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL herr_t H5Adelete_by_name(hid_t loc_id, const char *obj_name,
+ const char *attr_name, hid_t lapl_id);
+/*-------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Determines whether an attribute with a given name exists on an
+ * object
+ *
+ * \fgdt_loc_id{obj_id}
+ * \param[in] attr_name Attribute name
+ *
+ * \return \htri_t
+ *
+ * \details H5Aexists() determines whether the attribute \p attr_name
+ * exists on the object specified by \p obj_id.
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL htri_t H5Aexists(hid_t obj_id, const char *attr_name);
+/*-------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Determines whether an attribute with a given name exists on an
+ * object
+ *
+ * \fgdt_loc_id{obj_id}
+ * \param[in] obj_name Object name
+ * \param[in] attr_name Attribute name
+ * \lapl_id
+ *
+ * \return \htri_t
+ *
+ * \details H5Aexists_by_name() determines whether the attribute
+ * \p attr_name exists on an object. That object is specified by
+ * its location and name, \p loc_id and \p obj_name, respectively.
+ *
+ * \p loc_id specifies a location in the file containing the object.
+ * \p obj_name is the name of the object to which the attribute is
+ * attached and can be a relative name, relative to \p loc_id,
+ * or an absolute name, based in the root group of the file. If
+ * \p loc_id fully specifies the object, \p obj_name should be '.'
+ * (a dot).
+ *
+ * The link access property list, \p lapl_id, may provide
+ * information regarding the properties of links required to access
+ * \p obj_name.
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL htri_t H5Aexists_by_name(hid_t obj_id, const char *obj_name,
+ const char *attr_name, hid_t lapl_id);
+/*-------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Gets an attribute creation property list identifier
+ *
+ * \attr_id
+ *
+ * \return \hid_tv{attribute's creation property list}
+ *
+ * \details H5Aget_create_plist() returns an identifier for the attribute
+ * creation property list associated with the attribute specified
+ * by \p attr_id.
+ *
+ * The creation property list identifier should be released with
+ * H5Pclose().
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL hid_t H5Aget_create_plist(hid_t attr_id);
+/*-------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Retrieves attribute information, by attribute identifier
+ *
+ * \attr_id
+ * \param[out] ainfo Attribute information struct
+ *
+ * \return \herr_t
+ *
+ * \details H5Aget_info() retrieves attribute information, locating the
+ * attribute with an attribute identifier, \p attr_id, which is
+ * the identifier returned by H5Aopen() or H5Aopen_by_idx(). The
+ * attribute information is returned in the \p ainfo struct.
+ *
+ * The \p ainfo struct is defined as follows:
+ * \snippet this H5A_info_t_snip
+ *
+ * \p corder_valid indicates whether the creation order data is
+ * valid for this attribute. Note that if creation order is not
+ * being tracked, no creation order data will be valid. Valid
+ * values are \c TRUE and \c FALSE.
+ *
+ * \p corder is a positive integer containing the creation
+ * order of the attribute. This value is 0-based, so, for
+ * example, the third attribute created will have a \p corder
+ * value of 2.
+ *
+ * \p cset indicates the character set used for the attribute’s
+ * name; valid values are defined in H5Tpublic.h and include
+ * the following:
+ * \csets
+ * This value is set with H5Pset_char_encoding().
+ *
+ * \p data_size indicates the size, in the number of characters,
+ * of the attribute.
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL herr_t H5Aget_info(hid_t attr_id, H5A_info_t *ainfo /*out*/);
+/*-------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Retrieves attribute information by attribute index position
+ *
+ * \fgdt_loc_id
+ * \param[in] obj_name Name of object to which attribute is attached,
+ * relative to location
+ * \param[in] idx_type Type of index
+ * \param[in] order Index traversal order
+ * \param[in] n Attribute’s position in index
+ * \param[out] ainfo Struct containing returned attribute information
+ * \lapl_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Aget_info_by_idx() retrieves information for an attribute
+ * that is attached to an object, which is specified by its
+ * location and name, \p loc_id and \p obj_name, respectively.
+ * The attribute is located by its index position and the attribute
+ * information is returned in the \p ainfo struct.
+ *
+ * If \p loc_id fully specifies the object to which the attribute
+ * is attached, \p obj_name should be '.' (a dot).
+ *
+ * The attribute is located by means of an index type, an index
+ * traversal order, and a position in the index, \p idx_type,
+ * \p order and \p n, respectively. These parameters and their
+ * valid values are discussed in the description of H5Aiterate2().
+ *
+ * The \p ainfo struct, which will contain the returned attribute
+ * information, is described in H5Aget_info().
+ *
+ * The link access property list, \p lapl_id, may provide
+ * information regarding the properties of links required to access
+ * the object, \p obj_name.
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL herr_t H5Aget_info_by_idx(hid_t loc_id, const char *obj_name,
+ H5_index_t idx_type, H5_iter_order_t order, hsize_t n,
+ H5A_info_t *ainfo /*out*/, hid_t lapl_id);
+/*-------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Retrieves attribute information, by attribute name
+ *
+ * \fgdt_loc_id
+ *
+ * \param[in] obj_name Name of object to which attribute is attached,
+ * relative to location
+ * \param[in] attr_name Attribute name
+ * \param[out] ainfo Struct containing returned attribute information
+ * \lapl_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Aget_info_by_name() retrieves information for an attribute,
+ * \p attr_name, that is attached to an object specified by its
+ * location and name, \p loc_id and \p obj_name, respectively.
+ * The attribute information is returned in the \p ainfo struct.
+ *
+ * If \p loc_id fully specifies the object to which the attribute
+ * is attached, \p obj_name should be '.' (a dot).
+ *
+ * The \p ainfo struct is described in H5Aget_info().
+ *
+ * The link access property list, \p lapl_id, may provide
+ * information regarding the properties of links required to
+ * access the object, \p obj_name.
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL herr_t H5Aget_info_by_name(hid_t loc_id, const char *obj_name,
+ const char *attr_name, H5A_info_t *ainfo /*out*/, hid_t lapl_id);
+/*-------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Gets an attribute name
+ *
+ * \attr_id
+ * \param[in] buf_size The size of the buffer to store the name in
+ * \param[out] buf Buffer to store name in
+ *
+ * \return Returns the length of the attribute's name, which may be longer
+ * than \p buf_size, if successful. Otherwise returns a negative
+ * value.
+ *
+ * \details H5Aget_name() retrieves the name of an attribute specified by
+ * the identifier, \p attr_id. Up to \p buf_size characters are
+ * stored in \p buf followed by a \0 string terminator. If the
+ * name of the attribute is longer than (\p buf_size -1), the
+ * string terminator is stored in the last position of the buffer
+ * to properly terminate the string.
+ *
+ * If the user only wants to find out the size of this name, the
+ * values 0 and NULL can be passed in for the parameters
+ * \p bufsize and \p buf.
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL ssize_t H5Aget_name(hid_t attr_id, size_t buf_size, char *buf);
+/*-------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Gets an attribute name, by attribute index position
+ *
+ * \fgdt_loc_id
+ * \param[in] obj_name Name of object to which attribute is attached,
+ * relative to location
+ * \param[in] idx_type Type of index
+ * \param[in] order Index traversal order
+ * \param[in] n Attribute’s position in index
+ * \param[out] name Attribute name
+ * \param[in] size Size, in bytes, of attribute name
+ * \lapl_id
+ *
+ * \return Returns attribute name size, in bytes, if successful;
+ * otherwise returns a negative value.
+ *
+ * \details H5Aget_name_by_idx() retrieves the name of an attribute that is
+ * attached to an object, which is specified by its location and
+ * name, \p loc_id and \p obj_name, respectively. The attribute is
+ * located by its index position, the size of the name is specified
+ * in \p size, and the attribute name is returned in \p name.
+ *
+ * If \p loc_id fully specifies the object to which the attribute
+ * is attached, \p obj_name should be '.' (a dot).
+ *
+ * The attribute is located by means of an index type, an index
+ * traversal order, and a position in the index, \p idx_type,
+ * \p order and \p n, respectively. These parameters and their
+ * valid values are discussed in the description of H5Aiterate2().
+ *
+ * If the attribute name’s size is unknown, the values 0 and NULL
+ * can be passed in for the parameters \p size and \p name. The
+ * function’s return value will provide the correct value for
+ * \p size.
+ *
+ * The link access property list, \p lapl_id, may provide
+ * information regarding the properties of links required to access
+ * the object, \p obj_name.
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL ssize_t H5Aget_name_by_idx(hid_t loc_id, const char *obj_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 H5A
+ *
+ * \brief Gets a copy of the dataspace for an attribute
+ *
+ * \attr_id
+ *
+ * \return \hid_tv{attribute dataspace}
+ *
+ * \details H5Aget_space() retrieves a copy of the dataspace for an
+ * attribute. The dataspace identifier returned from this
+ * function must be released with H5Sclose() or resource leaks
+ * will develop.
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL hid_t H5Aget_space(hid_t attr_id);
+/*-------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Returns the amount of storage required for an attribute
+ *
+ * \attr_id
+ *
+ * \return Returns the amount of storage size allocated for the attribute;
+ * otherwise returns 0 (zero).
+ *
+ * \details H5Aget_storage_size() returns the amount of storage that is
+ * required for the specified attribute, \p attr_id.
+ *
+ * \since 1.6.0
+ *
+ */
+H5_DLL hsize_t H5Aget_storage_size(hid_t attr_id);
+/*-------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Gets an attribute datatype
+ *
+ * \attr_id
+ *
+ * \return \hid_t{datatype}
+ *
+ * \details H5Aget_type() retrieves a copy of the datatype for an attribute.
+ * The datatype is reopened if it is a named type before returning
+ * it to the application. The datatypes returned by this function
+ * are always read-only. If an error occurs when atomizing the
+ * return datatype, then the datatype is closed.
+ *
+ * The datatype identifier returned from this function must be
+ * released with H5Tclose() or resource leaks will develop.
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL hid_t H5Aget_type(hid_t attr_id);
+/*-------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Calls user-defined function for each attribute on an object
+ *
+ * \fgdt_loc_id
+ * \param[in] idx_type Type of index
+ * \param[in] order Order in which to iterate over index
+ * \param[in,out] idx Initial and returned offset within index
+ * \param[in] op User-defined function to pass each attribute to
+ * \param[in,out] op_data User data to pass through to and to be returned
+ * by iterator operator function
+ *
+ * \return \herr_t
+ * Further note that this function returns the return value of the
+ * last operator if it was non-zero, which can be a negative value,
+ * zero if all attributes were processed, or a positive value
+ * indicating short-circuit success.
+ *
+ * \details H5Aiterate2() iterates over the attributes attached to a
+ * dataset, named datatype, or group, as specified by \p loc_id.
+ * For each attribute, user-provided data, \p op_data, with
+ * additional information as defined below, is passed to a
+ * user-defined function, \p op, which operates on that
+ * attribute.
+ *
+ * The order of the iteration and the attributes iterated over
+ * are specified by three parameters: the index type,
+ * \p idx_type; the order in which the index is to be traversed,
+ * \p order; and the attribute’s position in the index, \p idx.
+ *
+ * The type of index specified by \p idx_type can be one of the
+ * following:
+ *
+ * \indexes
+ *
+ * The order in which the index is to be traversed, as specified
+ * by \p order, can be one of the following:
+ *
+ * \orders
+ *
+ * The next attribute to be operated on is specified by \p idx,
+ * a position in the index.
+ *
+ * For example, if \p idx_type, \p order, and \p idx are set to
+ * #H5_INDEX_NAME, #H5_ITER_INC, and 5, respectively, the attribute
+ * in question is the fifth attribute from the beginning of the
+ * alpha-numeric index of attribute names. If \p order were set to
+ * #H5_ITER_DEC, it would be the fifth attribute from the end of
+ * the index.
+ *
+ * The parameter \p idx is passed in on an H5Aiterate2() call with
+ * one value and may be returned with another value. The value
+ * passed in identifies the parameter to be operated on first;
+ * the value returned identifies the parameter to be operated on
+ * in the next step of the iteration.
+ *
+ * The #H5A_operator2_t prototype for the \p op parameter is a
+ * user defined function where:
+ * The operation receives the location identifier for the group or
+ * dataset being iterated over, \p location_id; the name of the
+ * current object attribute, \p attr_name; the attribute’s info
+ * struct, \p ainfo; and a pointer to the operator data passed
+ * into H5Aiterate2(), \p op_data.
+ *
+ * Valid return values from an operator and the resulting
+ * H5Aiterate2() and \p op behavior are as follows:
+ *
+ * \li Zero causes the iterator to continue, returning zero when
+ * all attributes have been processed.
+ * \li A positive value causes the iterator to immediately return
+ * that positive value, indicating short-circuit success. The
+ * iterator can be restarted at the next attribute, as
+ * indicated by the return value of \p idx.
+ * \li A negative value causes the iterator to immediately return
+ * that value, indicating failure. The iterator can be
+ * restarted at the next attribute, as indicated by the return
+ * value of \p idx.
+ *
+ * \note This function is also available through the H5Aiterate() macro.
+ * \todo Add snippet for H5A_operator2_t
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type,
+ H5_iter_order_t order, hsize_t *idx, H5A_operator2_t op, void *op_data);
+/*--------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Calls user-defined function for each attribute on an object
+ *
+ * \fgdt_loc_id
+ * \param[in] obj_name Name of object, relative to location
+ * \param[in] idx_type Type of index
+ * \param[in] order Order in which to iterate over index
+ * \param[in,out] idx Initial and returned offset within index
+ * \param[in] op User-defined function to pass each attribute to
+ * \param[in,out] op_data User data to pass through to and to be returned
+ * by iterator operator function
+ * \lapl_id
+ *
+ * \return \herr_t
+ * Further note that this function returns the return value of
+ * the last operator if it was non-zero, which can be a negative
+ * value, zero if all attributes were processed, or a positive value
+ * indicating short-circuit success.
+ *
+ * \details H5Aiterate_by_name() iterates over the attributes attached
+ * to the dataset or group specified with \p loc_id and \p obj_name.
+ * For each attribute, user-provided data, \p op_data, with
+ * additional information as defined below, is passed to a
+ * user-defined function, \p op, which operates on that attribute.
+ *
+ * If \p loc_id fully specifies the object to which these
+ * attributes are attached, \p obj_name should be '.' (a dot).
+ *
+ * The order of the iteration and the attributes iterated over
+ * are specified by three parameters: the index type, \p idx_type;
+ * the order in which the index is to be traversed, \p order;
+ * and the attribute’s position in the index, \p idx.
+ *
+ * The type of index specified by \p idx_type can be one of the
+ * following:
+ *
+ * \indexes
+ *
+ * The order in which the index is to be traversed, as specified
+ * by \p order, can be one of the following:
+ *
+ * \orders
+ *
+ * The next attribute to be operated on is specified by \p idx,
+ * a position in the index.
+ *
+ * For example, if \p idx_type, \p order, and \p idx are set to
+ * #H5_INDEX_NAME, #H5_ITER_INC, and 5, respectively, the attribute
+ * in question is the fifth attribute from the beginning of the
+ * alpha-numeric index of attribute names. If \p order were set to
+ * #H5_ITER_DEC, it would be the fifth attribute from the end of
+ * the index.
+ *
+ * The parameter \p idx is passed in on an H5Aiterate_by_name()
+ * call with one value and may be returned with another value. The
+ * value passed in identifies the parameter to be operated on first;
+ * the value returned identifies the parameter to be operated on in
+ * the next step of the iteration.
+ *
+ * The #H5A_operator2_t prototype for the \p op parameter is a
+ * user defined function where:
+ * The operation receives the location identifier for the group or
+ * dataset being iterated over, \p location_id; the name of the
+ * current object attribute, \p attr_name; the attribute’s info
+ * struct, \p ainfo; and a pointer to the operator data passed
+ * into H5Aiterate_by_name(), \p op_data.
+ *
+ * Valid return values from an operator and the resulting
+ * H5Aiterate_by_name() and \p op behavior are as follows:
+ *
+ * \li Zero causes the iterator to continue, returning zero when
+ * all attributes have been processed.
+ * \li A positive value causes the iterator to immediately return
+ * that positive value, indicating short-circuit success.
+ * The iterator can be restarted at the next attribute, as
+ * indicated by the return value of \p idx.
+ * \li A negative value causes the iterator to immediately return
+ * that value, indicating failure. The iterator can be
+ * restarted at the next attribute, as indicated by the return
+ * value of \p idx.
+ *
+ * The link access property list, \p lapl_id, may provide
+ * information regarding the properties of links required to access
+ * the object, \p obj_name.
+ *
+ * \todo Add snippet to show H5Aoperator2_t.
+ * \since 1.8.0
+ *
+ */
+H5_DLL herr_t H5Aiterate_by_name(hid_t loc_id, const char *obj_name, H5_index_t idx_type,
+ H5_iter_order_t order, hsize_t *idx, H5A_operator2_t op, void *op_data,
+ hid_t lapl_id);
H5_DLL hid_t H5Acreate_by_name_async(const char *app_file, const char *app_func, unsigned app_line,
hid_t loc_id, const char *obj_name, const char *attr_name, hid_t type_id,
hid_t space_id, hid_t acpl_id, hid_t aapl_id, hid_t lapl_id,
@@ -180,7 +821,7 @@ H5_DLL hid_t H5Acreate_by_name_async(const char *app_file, const char *app_func,
*
* \see H5Aclose(), H5Acreate()
*/
-H5_DLL hid_t H5Aopen(hid_t obj_id, const char *attr_name, hid_t aapl_id);
+H5_DLL hid_t H5Aopen(hid_t obj_id, const char *attr_name, hid_t aapl_id);
H5_DLL hid_t H5Aopen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t obj_id,
const char *attr_name, hid_t aapl_id, hid_t es_id);
/*--------------------------------------------------------------------------*/
@@ -228,8 +869,8 @@ H5_DLL hid_t H5Aopen_async(const char *app_file, const char *app_func, unsigned
* \since 1.8.0
*
*/
-H5_DLL hid_t H5Aopen_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order,
- hsize_t n, hid_t aapl_id, hid_t lapl_id);
+H5_DLL hid_t H5Aopen_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order,
+ hsize_t n, hid_t aapl_id, hid_t lapl_id);
H5_DLL hid_t H5Aopen_by_idx_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n,
hid_t aapl_id, hid_t lapl_id, hid_t es_id);
@@ -274,8 +915,8 @@ H5_DLL hid_t H5Aopen_by_idx_async(const char *app_file, const char *app_func, un
* \since 1.8.0
*
*/
-H5_DLL hid_t H5Aopen_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t aapl_id,
- hid_t lapl_id);
+H5_DLL hid_t H5Aopen_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t aapl_id,
+ hid_t lapl_id);
H5_DLL hid_t H5Aopen_by_name_async(const char *app_file, const char *app_func, unsigned app_line,
hid_t loc_id, const char *obj_name, const char *attr_name, hid_t aapl_id,
hid_t lapl_id, hid_t es_id);
@@ -305,8 +946,30 @@ H5_DLL hid_t H5Aopen_by_name_async(const char *app_file, const char *app_func, u
*
* \see H5Awrite()
*
+*/
+H5_DLL herr_t H5Aread(hid_t attr_id, hid_t type_id, void *buf);
+/*-------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Renames an attribute
+ *
+ * \fgdt_loc_id
+ * \param[in] old_name Name of the attribute to be changed
+ * \param[in] new_name New name for the attribute
+ *
+ * \return \herr_t
+ *
+ * \details H5Arename() changes the name of the attribute located at
+ * \p loc_id.
+ *
+ * The old name, \p old_name, is changed to the new name,
+ * \p new_name.
+ *
+ * \since 1.6.0
+ *
*/
-H5_DLL herr_t H5Aread(hid_t attr_id, hid_t type_id, void *buf);
+H5_DLL herr_t H5Arename(hid_t loc_id, const char *old_name, const char *new_name);
H5_DLL herr_t H5Aread_async(const char *app_file, const char *app_func, unsigned app_line, hid_t attr_id,
hid_t dtype_id, void *buf, hid_t es_id);
/*--------------------------------------------------------------------------*/
@@ -343,40 +1006,13 @@ H5_DLL herr_t H5Aread_async(const char *app_file, const char *app_func, unsigned
H5_DLL herr_t H5Awrite(hid_t attr_id, hid_t type_id, const void *buf);
H5_DLL herr_t H5Awrite_async(const char *app_file, const char *app_func, unsigned app_line, hid_t attr_id,
hid_t type_id, const void *buf, hid_t es_id);
-H5_DLL hid_t H5Aget_space(hid_t attr_id);
-H5_DLL hid_t H5Aget_type(hid_t attr_id);
-H5_DLL hid_t H5Aget_create_plist(hid_t attr_id);
-H5_DLL ssize_t H5Aget_name(hid_t attr_id, size_t buf_size, char *buf);
-H5_DLL ssize_t H5Aget_name_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_type,
- H5_iter_order_t order, hsize_t n, char *name /*out*/, size_t size,
- hid_t lapl_id);
-H5_DLL hsize_t H5Aget_storage_size(hid_t attr_id);
-H5_DLL herr_t H5Aget_info(hid_t attr_id, H5A_info_t *ainfo /*out*/);
-H5_DLL herr_t H5Aget_info_by_name(hid_t loc_id, const char *obj_name, const char *attr_name,
- H5A_info_t *ainfo /*out*/, hid_t lapl_id);
-H5_DLL herr_t H5Aget_info_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_type,
- H5_iter_order_t order, hsize_t n, H5A_info_t *ainfo /*out*/, hid_t lapl_id);
-H5_DLL herr_t H5Arename(hid_t loc_id, const char *old_name, const char *new_name);
H5_DLL herr_t H5Arename_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
const char *old_name, const char *new_name, hid_t es_id);
-H5_DLL herr_t H5Arename_by_name(hid_t loc_id, const char *obj_name, const char *old_attr_name,
- const char *new_attr_name, hid_t lapl_id);
H5_DLL herr_t H5Arename_by_name_async(const char *app_file, const char *app_func, unsigned app_line,
hid_t loc_id, const char *obj_name, const char *old_attr_name,
const char *new_attr_name, hid_t lapl_id, hid_t es_id);
-H5_DLL herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx,
- H5A_operator2_t op, void *op_data);
-H5_DLL herr_t H5Aiterate_by_name(hid_t loc_id, const char *obj_name, H5_index_t idx_type,
- H5_iter_order_t order, hsize_t *idx, H5A_operator2_t op, void *op_data,
- hid_t lapd_id);
-H5_DLL herr_t H5Adelete(hid_t loc_id, const char *name);
-H5_DLL herr_t H5Adelete_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t lapl_id);
-H5_DLL herr_t H5Adelete_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order,
- hsize_t n, hid_t lapl_id);
-H5_DLL htri_t H5Aexists(hid_t obj_id, const char *attr_name);
H5_DLL herr_t H5Aexists_async(const char *app_file, const char *app_func, unsigned app_line, hid_t obj_id,
const char *attr_name, hbool_t *exists, hid_t es_id);
-H5_DLL htri_t H5Aexists_by_name(hid_t obj_id, const char *obj_name, const char *attr_name, hid_t lapl_id);
H5_DLL herr_t H5Aexists_by_name_async(const char *app_file, const char *app_func, unsigned app_line,
hid_t loc_id, const char *obj_name, const char *attr_name,
hbool_t *exists, hid_t lapl_id, hid_t es_id);
@@ -384,23 +1020,27 @@ H5_DLL herr_t H5Aexists_by_name_async(const char *app_file, const char *app_func
/**
* \ingroup H5A
*
- * \brief Closes the specified attribute
- *
- * \attr_id
- *
- * \return \herr_t
+ * \fgdt_loc_id
+ * \param[in] obj_name Name of object, relative to location, whose
+ * attribute is to be renamed
+ * \param[in] old_attr_name Prior attribute name
+ * \param[in] new_attr_name New attribute name
+ * \lapl_id
*
- * \details H5Aclose() terminates access to the attribute specified by
- * \p attr_id by releasing the identifier.
+ * \details H5Arename_by_name() changes the name of attribute that is
+ * attached to the object specified by \p loc_id and \p obj_name.
+ * The attribute named \p old_attr_name is renamed
+ * \p new_attr_name.
*
- * \attention Further use of a released attribute identifier is illegal; a
- * function using such an identifier will generate an error.
+ * The link access property list, \p lapl_id, may provide
+ * information regarding the properties of links required to
+ * access the object, \p obj_name.
*
- * \since 1.0.0
+ * \since 1.8.0
*
- * \see H5Acreate(), H5Aopen()
*/
-H5_DLL herr_t H5Aclose(hid_t attr_id);
+H5_DLL herr_t H5Arename_by_name(hid_t loc_id, const char *obj_name,
+ const char *old_attr_name, const char *new_attr_name, hid_t lapl_id);
H5_DLL herr_t H5Aclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t attr_id,
hid_t es_id);
@@ -499,10 +1139,136 @@ typedef herr_t (*H5A_operator1_t)(hid_t location_id /*in*/, const char *attr_nam
*
*/
H5_DLL hid_t H5Acreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t acpl_id);
-H5_DLL hid_t H5Aopen_name(hid_t loc_id, const char *name);
-H5_DLL hid_t H5Aopen_idx(hid_t loc_id, unsigned idx);
-H5_DLL int H5Aget_num_attrs(hid_t loc_id);
-H5_DLL herr_t H5Aiterate1(hid_t loc_id, unsigned *attr_num, H5A_operator1_t op, void *op_data);
+/* --------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Determines the number of attributes attached to an object
+ *
+ * \fgdt_loc_id
+ *
+ * \return Returns the number of attributes if successful; otherwise returns
+ * a negative value.
+ *
+ * \deprecated This function is deprecated in favor of the functions
+ * H5Oget_info(), H5Oget_info_by_name(), and H5Oget_info_by_idx().
+ *
+ * \details H5Aget_num_attrs() returns the number of attributes attached to
+ * the object specified by its identifier, \p loc_id.
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL int H5Aget_num_attrs(hid_t loc_id);
+/* --------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Calls a user’s function for each attribute on an object
+ *
+ * \todo make prototype parameter match function (idx vs attr_num)
+ *
+ * \loc_id
+ * \param[in,out] idx Starting (in) and ending (out) attribute index
+ * \param[in] op User's function to pass each attribute to
+ * \param[in,out] op_data User's data to pass through to iterator operator
+ * function
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function is deprecated in favor of the function
+ * H5Aiterate2().
+ *
+ * \details H5Aiterate1() iterates over the attributes of the object
+ * specified by its identifier, \p loc_id. The object can be a
+ * group, dataset, or named datatype. For each attribute of the
+ * object, the \p op_data and some additional information specified
+ * below are passed to the operator function \p op. The iteration
+ * begins with the attribute specified by its index, \p idx; the
+ * index for the next attribute to be processed by the operator,
+ * \p op, is returned in \p idx. If \p idx is the null pointer,
+ * then all attributes are processed.
+ *
+ * The prototype for #H5A_operator1_t is a user defined function
+ * where:
+ * The operation receives the identifier for the group, dataset
+ * or named datatype being iterated over, \p loc_id, the name of
+ * the current object attribute, \p attr_name, and the pointer to
+ * the operator data passed in to H5Aiterate1(), \p op_data.
+ *
+ * The return values from an operator are:
+ *
+ * \li Zero causes the iterator to continue, returning zero when
+ * all attributes have been processed.
+ * \li Positive causes the iterator to immediately return that
+ * positive value, indicating short-circuit success. The
+ * iterator can be restarted at the next attribute.
+ * \li Negative causes the iterator to immediately return that value,
+ * indicating failure. The iterator can be restarted at the next
+ * attribute.
+ *
+ * \todo Add snippet to show H5A_operator1_t.
+ *
+ * \version 1.8.0 The function \p H5Aiterate was renamed to H5Aiterate1()
+ * and deprecated in this release.
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Aiterate1(hid_t loc_id, unsigned *idx, H5A_operator1_t op,
+ void *op_data);
+/* --------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Opens the attribute specified by its index
+ *
+ * \loc_id
+ * \param[in] idx Index of the attribute to open
+ *
+ * \return \hid_tv{attribute}
+ *
+ * \deprecated This function is deprecated in favor of the function
+ * H5Aopen_by_idx().
+ *
+ * \details H5Aopen_idx() opens an attribute which is attached to the
+ * object specified with \p loc_id . The location object may be
+ * either a group, dataset, or named datatype, all of which may
+ * have any sort of attribute. The attribute specified by the index,
+ * \p idx , indicates the attribute to access. The value of \p idx
+ * is a 0-based, non-negative integer. The attribute identifier
+ * returned from this function must be released with H5Aclose()
+ * or resource leaks will develop.
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL hid_t H5Aopen_idx(hid_t loc_id, unsigned idx);
+/* --------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Opens an attribute specified by name
+ *
+ * \loc_id
+ * \param[in] name Attribute name
+ *
+ * \return \hid_tv{attribute}
+ *
+ * \deprecated This function is deprecated in favor of the function
+ * H5Aopen_by_name().
+ *
+ * \details H5Aopen_name() opens an attribute specified by its name,
+ * \p name, which is attached to the object specified with
+ * \p loc_id. The location object may be either a group, dataset,
+ * or named datatype, which may have any sort of attribute. The
+ * attribute identifier returned from this function must be
+ * released with H5Aclose() or resource leaks will develop.
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL hid_t H5Aopen_name(hid_t loc_id, const char *name);
#endif /* H5_NO_DEPRECATED_SYMBOLS */
diff --git a/src/H5Fpublic.h b/src/H5Fpublic.h
index 851d64d..9d6d349 100644
--- a/src/H5Fpublic.h
+++ b/src/H5Fpublic.h
@@ -201,6 +201,7 @@ typedef enum H5F_libver_t {
/**
* File space handling strategy
*/
+//! [H5F_fspace_strategy_t_snip]
typedef enum H5F_fspace_strategy_t {
H5F_FSPACE_STRATEGY_FSM_AGGR = 0, /**< Mechanisms: free-space managers, aggregators, and virtual file
drivers This is the library default when not set */
@@ -210,6 +211,7 @@ typedef enum H5F_fspace_strategy_t {
H5F_FSPACE_STRATEGY_NONE = 3, /**< Mechanisms: virtual file drivers */
H5F_FSPACE_STRATEGY_NTYPES /**< Sentinel */
} H5F_fspace_strategy_t;
+//! [H5F_fspace_strategy_t_snip]
/**
* File space handling strategy for release 1.10.0
diff --git a/src/H5Ppublic.h b/src/H5Ppublic.h
index 6493895..5624db9 100644
--- a/src/H5Ppublic.h
+++ b/src/H5Ppublic.h
@@ -111,13 +111,23 @@ extern "C" {
/*******************/
/* Define property list class callback function pointer types */
+//! [H5P_cls_create_func_t_snip]
typedef herr_t (*H5P_cls_create_func_t)(hid_t prop_id, void *create_data);
+//! [H5P_cls_create_func_t_snip]
+//! [H5P_cls_copy_func_t_snip]
typedef herr_t (*H5P_cls_copy_func_t)(hid_t new_prop_id, hid_t old_prop_id, void *copy_data);
+//! [H5P_cls_copy_func_t_snip]
+//! [H5P_cls_close_func_t_snip]
typedef herr_t (*H5P_cls_close_func_t)(hid_t prop_id, void *close_data);
+//! [H5P_cls_close_func_t_snip]
/* Define property list callback function pointer types */
+//! [H5P_prp_cb1_t_snip]
typedef herr_t (*H5P_prp_cb1_t)(const char *name, size_t size, void *value);
+//! [H5P_prp_cb1_t_snip]
+//! [H5P_prp_cb2_t_snip]
typedef herr_t (*H5P_prp_cb2_t)(hid_t prop_id, const char *name, size_t size, void *value);
+//! [H5P_prp_cb2_t_snip]
typedef H5P_prp_cb1_t H5P_prp_create_func_t;
typedef H5P_prp_cb2_t H5P_prp_set_func_t;
typedef H5P_prp_cb2_t H5P_prp_get_func_t;
@@ -125,11 +135,15 @@ typedef herr_t (*H5P_prp_encode_func_t)(const void *value, void **buf, size_t *s
typedef herr_t (*H5P_prp_decode_func_t)(const void **buf, void *value);
typedef H5P_prp_cb2_t H5P_prp_delete_func_t;
typedef H5P_prp_cb1_t H5P_prp_copy_func_t;
+//! [H5P_prp_compare_func_t_snip]
typedef int (*H5P_prp_compare_func_t)(const void *value1, const void *value2, size_t size);
+//! [H5P_prp_compare_func_t_snip]
typedef H5P_prp_cb1_t H5P_prp_close_func_t;
/* Define property list iteration function type */
+//! [H5P_iterate_t_snip]
typedef herr_t (*H5P_iterate_t)(hid_t id, const char *name, void *iter_data);
+//! [H5P_iterate_t_snip]
/* Actual IO mode property */
typedef enum H5D_mpio_actual_chunk_opt_mode_t {
@@ -252,6 +266,77 @@ H5_DLLVAR hid_t H5P_LST_REFERENCE_ACCESS_ID_g;
*/
H5_DLL herr_t H5Pclose(hid_t plist_id);
/**
+ * \ingroup GPLOA
+ *
+ * \brief Closes an existing property list class
+ *
+ * \plistcls_id{plist_id}
+ *
+ * \return \herr_t
+ *
+ * \details H5Pclose_class() removes a property list class from the library.
+ * Existing property lists of this class will continue to exist,
+ * but new ones are not able to be created.
+ *
+ * \since 1.4.0
+ *
+ */
+H5_DLL herr_t H5Pclose_class(hid_t plist_id);
+/**
+ * \ingroup GPLO
+ *
+ * \brief Copies an existing property list to create a new property list
+ *
+ * \plist_id
+ *
+ * \return \hid_t{property list}
+ *
+ * \details H5Pcopy() copies an existing property list to create a new
+ * property list. The new property list has the same properties
+ * and values as the original property list.
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL hid_t H5Pcopy(hid_t plist_id);
+/**
+ * \ingroup GPLOA
+ *
+ * \brief Copies a property from one list or class to another
+ *
+ * \param[in] dst_id Identifier of the destination property list or class
+ * \param[in] src_id Identifier of the source property list or class
+ * \param[in] name Name of the property to copy
+ *
+ * \return \herr_t
+ *
+ * \details H5Pcopy_prop() copies a property from one property list or
+ * class to another.
+ *
+ * If a property is copied from one class to another, all the
+ * property information will be first deleted from the destination
+ * class and then the property information will be copied from the
+ * source class into the destination class.
+ *
+ * If a property is copied from one list to another, the property
+ * will be first deleted from the destination list (generating a
+ * call to the close callback for the property, if one exists)
+ * and then the property is copied from the source list to the
+ * destination list (generating a call to the copy callback for
+ * the property, if one exists).
+ *
+ * If the property does not exist in the class or list, this
+ * call is equivalent to calling H5Pregister() or H5Pinsert() (for
+ * a class or list, as appropriate) and the create callback will
+ * be called in the case of the property being copied into a list
+ * (if such a callback exists for the property).
+ *
+ * \since 1.6.0
+ *
+ */
+H5_DLL herr_t H5Pcopy_prop(hid_t dst_id, hid_t src_id, const
+char *name);
+/**
* \ingroup GPLO
*
* \brief Creates a new property list as an instance of a property list class
@@ -374,43 +459,1352 @@ H5_DLL herr_t H5Pclose(hid_t plist_id);
* \since 1.0.0
*
*/
-H5_DLL hid_t H5Pcreate(hid_t cls_id);
-H5_DLL hid_t H5Pcreate_class(hid_t parent, const char *name, H5P_cls_create_func_t cls_create,
- void *create_data, H5P_cls_copy_func_t cls_copy, void *copy_data,
- H5P_cls_close_func_t cls_close, void *close_data);
-H5_DLL char * H5Pget_class_name(hid_t pclass_id);
-H5_DLL herr_t H5Pregister2(hid_t cls_id, const char *name, size_t size, void *def_value,
- H5P_prp_create_func_t prp_create, H5P_prp_set_func_t prp_set,
- H5P_prp_get_func_t prp_get, H5P_prp_delete_func_t prp_del,
- H5P_prp_copy_func_t prp_copy, H5P_prp_compare_func_t prp_cmp,
- H5P_prp_close_func_t prp_close);
-H5_DLL herr_t H5Pinsert2(hid_t plist_id, const char *name, size_t size, void *value,
- H5P_prp_set_func_t prp_set, H5P_prp_get_func_t prp_get,
- H5P_prp_delete_func_t prp_delete, H5P_prp_copy_func_t prp_copy,
- H5P_prp_compare_func_t prp_cmp, H5P_prp_close_func_t prp_close);
-H5_DLL herr_t H5Pset(hid_t plist_id, const char *name, const void *value);
-H5_DLL htri_t H5Pexist(hid_t plist_id, const char *name);
-H5_DLL herr_t H5Pencode2(hid_t plist_id, void *buf, size_t *nalloc, hid_t fapl_id);
+H5_DLL hid_t H5Pcreate(hid_t cls_id);
+/**
+ * \ingroup GPLOA
+ *
+ * \brief Creates a new property list class
+ *
+ * \plistcls_id{parent}
+ * \param[in] name Name of property list class to register
+ * \param[in] create Callback routine called when a property list is
+ * created
+ * \param[in] create_data Pointer to user-defined class create data, to be
+ * passed along to class create callback
+ * \param[in] copy Callback routine called when a property list is
+ * copied
+ * \param[in] copy_data Pointer to user-defined class copy data, to be
+ * passed along to class copy callback
+ * \param[in] close Callback routine called when a property list is
+ * being closed
+ * \param[in] close_data Pointer to user-defined class close data, to be
+ * passed along to class close callback
+ *
+ * \return \hid_t{property list class}
+ *
+ * \details H5Pcreate_class() registers a new property list class with the
+ * library. The new property list class can inherit from an
+ * existing property list class, \p parent, or may be derived
+ * from the default “empty” class, NULL. New classes with
+ * inherited properties from existing classes may not remove
+ * those existing properties, only add or remove their own class
+ * properties. Property list classes defined and supported in the
+ * HDF5 library distribution are listed and briefly described in
+ * H5Pcreate(). The \p create routine is called when a new property
+ * list of this class is being created. The #H5P_cls_create_func_t
+ * callback function is defined as follows:
+ *
+ * \todo fix snippets to work, when you click on them.
+ *
+ * \snippet this H5P_cls_create_func_t_snip
+ *
+ * The parameters to this callback function are defined as follows:
+ * <table>
+ * <tr>
+ * <td>\ref hid_t \c prop_id</td>
+ * <td>IN: The identifier of the property list being created</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{void * create_data}</td>
+ * <td>IN: User pointer to any class creation data required</td>
+ * </tr>
+ * </table>
+ *
+ * The \p create routine is called after any registered
+ * \p create function is called for each property value. If the
+ * \p create routine returns a negative value, the new list is not
+ * returned to the user and the property list creation routine returns
+ * an error value.
+ *
+ * The \p copy routine is called when an existing property
+ * list of this class is copied. The #H5P_cls_copy_func_t callback
+ * function is defined as follows:
+ * \snippet this H5P_cls_copy_func_t_snip
+ *
+ * The parameters to this callback function are defined as follows:
+ * <table>
+ * <tr>
+ * <td>\ref hid_t \c prop_id</td>
+ * <td>IN: The identifier of the property list created by copying</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{void * copy_data}</td>
+ * <td>IN: User pointer to any class copy data required</td>
+ * </tr>
+ * </table>
+ *
+ * The \p copy routine is called after any registered \p copy function
+ * is called for each property value. If the \p copy routine returns a
+ * negative value, the new list is not returned to the user and the
+ * property list \p copy routine returns an error value.
+ *
+ * The \p close routine is called when a property list of this class
+ * is being closed. The #H5P_cls_close_func_t callback function is
+ * defined as follows:
+ * \snippet this H5P_cls_close_func_t_snip
+ *
+ * The parameters to this callback function are defined as follows:
+ * <table>
+ * <tr>
+ * <td>\ref hid_t \c prop_id</td>
+ * <td>IN: The identifier of the property list being closed</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{void * close_data}</td>
+ * <td>IN: User pointer to any class close data required</td>
+ * </tr>
+ * </table>
+ *
+ * The \p close routine is called before any registered \p close
+ * function is called for each property value. If the \p close routine
+ * returns a negative value, the property list close routine returns
+ * an error value but the property list is still closed.
+ *
+ * H5Pclose_class() can be used to release the property list class
+ * identifier returned by this function so that resources leaks will
+ * not develop.
+ *
+ * \since 1.4.0
+ *
+ */
+H5_DLL hid_t H5Pcreate_class(hid_t parent, const char *name,
+ H5P_cls_create_func_t create, void *create_data,
+ H5P_cls_copy_func_t copy, void *copy_data,
+ H5P_cls_close_func_t close, void *close_data);
+/**
+ * \ingroup GPLO
+ *
+ * \brief Decodes property list received in a binary object buffer and
+ * returns a new property list identifier
+ *
+ * \param[in] buf Buffer holding the encoded property list
+ *
+ * \return \hid_tv{object}
+ *
+ * \details Given a binary property list description in a buffer, H5Pdecode()
+ * reconstructs the HDF5 property list and returns an identifier
+ * for the new property list. The binary description of the property
+ * list is encoded by H5Pencode().
+ *
+ * The user is responsible for passing in the correct buffer.
+ *
+ * The property list identifier returned by this function should be
+ * released with H5Pclose() when the identifier is no longer needed
+ * so that resource leaks will not develop.
+ *
+ * \note Some properties cannot be encoded and therefore will not be available
+ * in the decoded property list. These properties are discussed in
+ * H5Pencode().
+ *
+ * \since 1.10.0
+ *
+ */
H5_DLL hid_t H5Pdecode(const void *buf);
-H5_DLL herr_t H5Pget_size(hid_t id, const char *name, size_t *size);
-H5_DLL herr_t H5Pget_nprops(hid_t id, size_t *nprops);
-H5_DLL hid_t H5Pget_class(hid_t plist_id);
-H5_DLL hid_t H5Pget_class_parent(hid_t pclass_id);
-H5_DLL herr_t H5Pget(hid_t plist_id, const char *name, void *value);
+/**
+ * \ingroup GPLO
+ *
+ * \brief Encodes the property values in a property list into a binary
+ * buffer
+ *
+ * \plist_id
+ * \param[out] buf Buffer into which the property list will be encoded.
+ * If the provided buffer is NULL, the size of the
+ * buffer required is returned through \p nalloc; the
+ * function does nothing more.
+ * \param[out] nalloc The size of the required buffer
+ * \fapl_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Pencode2() encodes the property list \p plist_id into the
+ * binary buffer \p buf, according to the file format setting
+ * specified by the file access property list \p fapl_id.
+ *
+ * If the required buffer size is unknown, \p buf can be passed
+ * in as NULL and the function will set the required buffer size
+ * in \p nalloc. The buffer can then be created and the property
+ * list encoded with a subsequent H5Pencode2() call.
+ *
+ * If the buffer passed in is not big enough to hold the encoded
+ * properties, the H5Pencode2() call can be expected to fail with
+ * a segmentation fault.
+ *
+ * The file access property list \p fapl_id is used to
+ * control the encoding via the \a libver_bounds property
+ * (see H5Pset_libver_bounds()). If the \a libver_bounds
+ * property is missing, H5Pencode2() proceeds as if the \a
+ * libver_bounds property were set to (#H5F_LIBVER_EARLIEST,
+ * #H5F_LIBVER_LATEST). (Functionally, H5Pencode1() is identical to
+ * H5Pencode2() with \a libver_bounds set to (#H5F_LIBVER_EARLIEST,
+ * #H5F_LIBVER_LATEST).)
+ * Properties that do not have encode callbacks will be skipped.
+ * There is currently no mechanism to register an encode callback for
+ * a user-defined property, so user-defined properties cannot currently
+ * be encoded.
+ *
+ * Some properties cannot be encoded, particularly properties that are
+ * reliant on local context.
+ *
+ * \note \a Motivation:
+ * This function was introduced in HDF5-1.12 as part of the \a H5Sencode
+ * format change to enable 64-bit selection encodings and a dataspace
+ * selection that is tied to a file.
+ *
+ * \since 1.12.0
+ *
+ */
+H5_DLL herr_t H5Pencode2(hid_t plist_id, void *buf, size_t *nalloc, hid_t fapl_id);
+/**
+ * \ingroup GPLOA
+ *
+ * \brief Compares two property lists or classes for equality
+ *
+ * \param[in] id1 First property object to be compared
+ * \param[in] id2 Second property object to be compared
+ *
+ * \return \htri_t
+ *
+ * \details H5Pequal() compares two property lists or classes to determine
+ * whether they are equal to one another.
+ *
+ * Either both \p id1 and \p id2 must be property lists or both
+ * must be classes; comparing a list to a class is an error.
+ *
+ * \since 1.4.0
+ *
+ */
H5_DLL htri_t H5Pequal(hid_t id1, hid_t id2);
+/**
+ * \ingroup GPLOA
+ *
+ * \brief Queries whether a property name exists in a property list or
+ * class
+ *
+ * \param[in] plist_id Identifier for the property list or class to query
+ * \param[in] name Name of property to check for
+ *
+ * \return \htri_t
+ *
+ * \details H5Pexist() determines whether a property exists within a
+ * property list or class.
+ *
+ * \since 1.4.0
+ *
+ */
+H5_DLL htri_t H5Pexist(hid_t plist_id, const char *name);
+/**
+ * \ingroup GPLOA
+ *
+ * \brief Queries the value of a property
+ *
+ * \plist_id
+ * \param[in] name Name of property to query
+ * \param[out] value Pointer to a location to which to copy the value of
+ * the property
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget() retrieves a copy of the value for a property in a
+ * property list. If there is a \p get callback routine registered
+ * for this property, the copy of the value of the property will
+ * first be passed to that routine and any changes to the copy of
+ * the value will be used when returning the property value from
+ * this routine.
+ *
+ * This routine may be called for zero-sized properties with the
+ * \p value set to NULL. The \p get routine will be called with
+ * a NULL value if the callback exists.
+ *
+ * The property name must exist or this routine will fail.
+ *
+ * If the \p get callback routine returns an error, \ value will
+ * not be modified.
+ *
+ * \since 1.4.0
+ *
+ */
+H5_DLL herr_t H5Pget(hid_t plist_id, const char *name, void * value);
+/**
+ *\ingroup GPLO
+ *
+ * \brief Returns the property list class identifier for a property list
+ *
+ * \plist_id
+ *
+ * \return \hid_t{property list class}
+ *
+ * \details H5Pget_class() returns the property list class identifier for
+ * the property list identified by the \p plist_id parameter.
+ *
+ * Note that H5Pget_class() returns a value of #hid_t type, an
+ * internal HDF5 identifier, rather than directly returning a
+ * property list class. That identifier can then be used with
+ * either H5Pequal() or H5Pget_class_name() to determine which
+ * predefined HDF5 property list class H5Pget_class() has returned.
+ *
+ * A full list of valid predefined property list classes appears
+ * in the description of H5Pcreate().
+ *
+ * Determining the HDF5 property list class name with H5Pequal()
+ * requires a series of H5Pequal() calls in an if-else sequence.
+ * An iterative sequence of H5Pequal() calls can compare the
+ * identifier returned by H5Pget_class() to members of the list of
+ * valid property list class names. A pseudo-code snippet might
+ * read as follows:
+ *
+ * \code
+ * plist_class_id = H5Pget_class (dsetA_plist);
+ *
+ * if H5Pequal (plist_class_id, H5P_OBJECT_CREATE) = TRUE;
+ * [ H5P_OBJECT_CREATE is the property list class ]
+ * [ returned by H5Pget_class. ]
+ *
+ * else if H5Pequal (plist_class_id, H5P_DATASET_CREATE) = TRUE;
+ * [ H5P_DATASET_CREATE is the property list class. ]
+ *
+ * else if H5Pequal (plist_class_id, H5P_DATASET_XFER) = TRUE;
+ * [ H5P_DATASET_XFER is the property list class. ]
+ *
+ * .
+ * . [ Continuing the iteration until a match is found. ]
+ * .
+ * \endcode
+ *
+ * H5Pget_class_name() returns the property list class name directly
+ * as a string:
+ *
+ * \code
+ * plist_class_id = H5Pget_class (dsetA_plist);
+ * plist_class_name = H5Pget_class_name (plist_class_id)
+ * \endcode
+ *
+ * Note that frequent use of H5Pget_class_name() can become a
+ * performance problem in a high-performance environment. The
+ * H5Pequal() approach is generally much faster.
+ *
+ * \version 1.6.0 Return type changed in this release.
+ * \since 1.0.0
+ *
+ */
+H5_DLL hid_t H5Pget_class(hid_t plist_id);
+/**
+ * \ingroup GPLOA
+ *
+ * \brief Retrieves the name of a class
+ *
+ * \plistcls_id{pclass_id}
+ *
+ * \return Returns a pointer to an allocated string containing the class
+ * name if successful, and NULL if not successful.
+ *
+ * \details H5Pget_class_name() retrieves the name of a generic property
+ * list class. The pointer to the name must be freed by the user
+ * with a call to H5free_memory() after each successful call.
+ *
+ * <table>
+ * <tr>
+ * <th>Class Name (class identifier) Returned</th>
+ * <th>Property List Class</th>
+ * <th>Expanded Name of the Property List Class</th>
+ * <th>The Class Identifier Used with H5Pcreate</th>
+ * <th>Comments</th>
+ * </tr>
+ * <tr>
+ * <td>attribute create</td>
+ * <td>acpl</td>
+ * <td>Attribute Creation Property List</td>
+ * <td>H5P_ATTRIBUTE_CREATE</td>
+ * <td> </td>
+ * </tr>
+ * <tr>
+ * <td>dataset access</td>
+ * <td>dapl</td>
+ * <td>Dataset Access Property List</td>
+ * <td>H5P_DATASET_ACCESS</td>
+ * <td> </td>
+ * </tr>
+ * <tr>
+ * <td>dataset create</td>
+ * <td>dcpl</td>
+ * <td>Dataset Creation Property List</td>
+ * <td>H5P_DATASET_CREATE</td>
+ * <td> </td>
+ * </tr>
+ * <tr>
+ * <td>data transfer</td>
+ * <td>dxpl</td>
+ * <td>Data Transfer Property List</td>
+ * <td>H5P_DATASET_XFER</td>
+ * <td> </td>
+ * </tr>
+ * <tr>
+ * <td>datatype access</td>
+ * <td> </td>
+ * <td> </td>
+ * <td>H5P_DATATYPE_ACCESS</td>
+ * <td>This class can be created, but there are no properties
+ * in the class currently.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>datatype create</td>
+ * <td> </td>
+ * <td> </td>
+ * <td>H5P_DATATYPE_CREATE</td>
+ * <td>This class can be created, but there
+ * are no properties in the class currently.</td>
+ * </tr>
+ * <tr>
+ * <td>file access</td>
+ * <td>fapl</td>
+ * <td>File Access Property List</td>
+ * <td>H5P_FILE_ACCESS</td>
+ * <td> </td>
+ * </tr>
+ * <tr>
+ * <td>file create</td>
+ * <td>fcpl</td>
+ * <td>File Creation Property List</td>
+ * <td>H5P_FILE_CREATE</td>
+ * <td> </td>
+ * </tr>
+ * <tr>
+ * <td>file mount</td>
+ * <td>fmpl</td>
+ * <td>File Mount Property List</td>
+ * <td>H5P_FILE_MOUNT</td>
+ * <td> </td>
+ * </tr>
+ * <tr>
+ * <td>group access</td>
+ * <td> </td>
+ * <td> </td>
+ * <td>H5P_GROUP_ACCESS</td>
+ * <td>This class can be created, but there
+ * are no properties in the class currently.</td>
+ * </tr>
+ * <tr>
+ * <td>group create</td>
+ * <td>gcpl</td>
+ * <td>Group Creation Property List</td>
+ * <td>H5P_GROUP_CREATE</td>
+ * <td> </td>
+ * </tr>
+ * <tr>
+ * <td>link access</td>
+ * <td>lapl</td>
+ * <td>Link Access Property List</td>
+ * <td>H5P_LINK_ACCESS</td>
+ * <td> </td>
+ * </tr>
+ * <tr>
+ * <td>link create</td>
+ * <td>lcpl</td>
+ * <td>Link Creation Property List</td>
+ * <td>H5P_LINK_CREATE</td>
+ * <td> </td>
+ * </tr>
+ * <tr>
+ * <td>object copy</td>
+ * <td>ocpypl</td>
+ * <td>Object Copy Property List</td>
+ * <td>H5P_OBJECT_COPY</td>
+ * <td> </td>
+ * </tr>
+ * <tr>
+ * <td>object create</td>
+ * <td>ocpl</td>
+ * <td>Object Creation Property List</td>
+ * <td>H5P_OBJECT_CREATE</td>
+ * <td> </td>
+ * </tr>
+ * <tr>
+ * <td>string create</td>
+ * <td>strcpl</td>
+ * <td>String Creation Property List</td>
+ * <td>H5P_STRING_CREATE</td>
+ * <td> </td>
+ * </tr>
+ * </table>
+ *
+ * \since 1.4.0
+ *
+ */
+H5_DLL char *H5Pget_class_name(hid_t pclass_id);
+/**
+ * \ingroup GPLOA
+ *
+ * \brief Retrieves the parent class of a property class
+ *
+ * \plistcls_id{pclass_id}
+ *
+ * \return \hid_t{parent class object}
+ *
+ * \details H5Pget_class_parent() retrieves an identifier for the parent
+ * class of a property class.
+ *
+ * \since 1.4.0
+ *
+ */
+H5_DLL hid_t H5Pget_class_parent(hid_t pclass_id);
+/**
+ * \ingroup GPLOA
+ *
+ * \brief Queries the number of properties in a property list or class
+ *
+ * \param[in] id Identifier for property object to query
+ * \param[out] nprops Number of properties in object
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_nprops() retrieves the number of properties in a
+ * property list or property list class.
+ *
+ * If \p id is a property list identifier, the current number of
+ * properties in the list is returned in \p nprops.
+ *
+ * If \p id is a property list class identifier, the number of
+ * registered properties in the class is returned in \p nprops.
+ *
+ * \since 1.4.0
+ *
+ */
+H5_DLL herr_t H5Pget_nprops(hid_t id, size_t *nprops);
+/**
+ * \ingroup GPLOA
+ *
+ * \brief Queries the size of a property value in bytes
+ *
+ * \param[in] id Identifier of property object to query
+ * \param[in] name Name of property to query
+ * \param[out] size Size of property in bytes
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_size() retrieves the size of a property's value in
+ * bytes. This function operates on both property lists and
+ * property classes.
+ *
+ * Zero-sized properties are allowed and return 0.
+ *
+ * \since 1.4.0
+ *
+ */
+H5_DLL herr_t H5Pget_size(hid_t id, const char *name, size_t *size);
+/**
+ * \ingroup GPLOA
+ *
+ * \brief Registers a temporary property with a property list
+ *
+ * \plist_id
+ * \param[in] name Name of property to create
+ * \param[in] size Size of property in bytes
+ * \param[in] value Initial value for the property
+ * \param[in] set Callback routine called before a new value is copied
+ * into the property's value
+ * \param[in] get Callback routine called when a property value is
+ * retrieved from the property
+ * \param[in] prp_del Callback routine called when a property is deleted
+ * from a property list
+ * \param[in] copy Callback routine called when a property is copied
+ * from an existing property list
+ * \param[in] compare Callback routine called when a property is compared
+ * with another property list
+ * \param[in] close Callback routine called when a property list is
+ * being closed and the property value will be disposed
+ * of
+ *
+ * \return \herr_t
+ *
+ * \details H5Pinsert2() creates a new property in a property
+ * list. The property will exist only in this property list and
+ * copies made from it.
+ *
+ * The initial property value must be provided in \p value and
+ * the property value will be set accordingly.
+ *
+ * The name of the property must not already exist in this list,
+ * or this routine will fail.
+ *
+ * The \p set and \p get callback routines may be set to NULL
+ * if they are not needed.
+ *
+ * Zero-sized properties are allowed and do not store any data
+ * in the property list. The default value of a zero-size
+ * property may be set to NULL. They may be used to indicate the
+ * presence or absence of a particular piece of information.
+ *
+ * The \p set routine is called before a new value is copied
+ * into the property. The #H5P_prp_set_func_t callback function
+ * is defined as follows:
+ * \snippet this H5P_prp_cb2_t_snip
+ *
+ * The parameters to the callback function are defined as follows:
+ * <table>
+ * <tr>
+ * <td>\ref hid_t \c prop_id</td>
+ * <td>IN: The identifier of the property list being
+ * modified</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{const char * name}</td>
+ * <td>IN: The name of the property being modified</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{size_t size}</td>
+ * <td>IN: The size of the property in bytes</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{void * value}</td>
+ * <td>IN: Pointer to new value pointer for the property
+ * being modified</td>
+ * </tr>
+ * </table>
+ *
+ * The \p set routine may modify the value pointer to be set and
+ * those changes will be used when setting the property's value.
+ * If the \p set routine returns a negative value, the new property
+ * value is not copied into the property and the \p set routine
+ * returns an error value. The \p set routine will be called for
+ * the initial value.
+ *
+ * \b Note: The \p set callback function may be useful to range
+ * check the value being set for the property or may perform some
+ * transformation or translation of the value set. The \p get
+ * callback would then reverse the transformation or translation.
+ * A single \p get or \p set callback could handle multiple
+ * properties by performing different actions based on the
+ * property name or other properties in the property list.
+ *
+ * The \p get routine is called when a value is retrieved from
+ * a property value. The #H5P_prp_get_func_t callback function
+ * is defined as follows:
+ *
+ * \snippet this H5P_prp_cb2_t_snip
+ *
+ * The parameters to the above callback function are:
+ *
+ * <table>
+ * <tr>
+ * <td>\ref hid_t \c prop_id</td>
+ * <td>IN: The identifier of the property list being queried</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{const char * name}</td>
+ * <td>IN: The name of the property being queried</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{size_t size}</td>
+ * <td>IN: The size of the property in bytes</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{void * value}</td>
+ * <td>IN: The value of the property being returned</td>
+ * </tr>
+ * </table>
+ *
+ * The \p get routine may modify the value to be returned from
+ * the query and those changes will be preserved. If the \p get
+ * routine returns a negative value, the query routine returns
+ * an error value.
+ *
+ * The \p prp_del routine is called when a property is being
+ * deleted from a property list. The #H5P_prp_delete_func_t
+ * callback function is defined as follows:
+ *
+ * \snippet this H5P_prp_cb2_t_snip
+ *
+ * The parameters to the above callback function are:
+ *
+ * <table>
+ * <tr>
+ * <td>\ref hid_t \c prop_id</td>
+ * <td>IN: The identifier of the property list the property is
+ * being deleted from</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{const char * name}</td>
+ * <td>IN: The name of the property in the list</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{size_t size}</td>
+ * <td>IN: The size of the property in bytes</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{void * value}</td>
+ * <td>IN: The value for the property being deleted</td>
+ * </tr>
+ * </table>
+ *
+ * The \p prp_del routine may modify the value passed in, but the
+ * value is not used by the library when the \p prp_del routine
+ * returns. If the \p prp_del routine returns a negative value,
+ * the property list \p prp_del routine returns an error value but
+ * the property is still deleted.
+ *
+ * The \p copy routine is called when a new property list with
+ * this property is being created through a \p copy operation.
+ *
+ * The #H5P_prp_copy_func_t callback function is defined as follows:
+ *
+ * \snippet this H5P_prp_cb1_t_snip
+ *
+ * The parameters to the above callback function are:
+ * <table>
+ * <tr>
+ * <td>\Code{const char * name}</td>
+ * <td>IN: The name of the property being copied</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{size_t size}</td>
+ * <td>IN: The size of the property in bytes</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{void * value}</td>
+ * <td>IN/OUT: The value for the property being copied</td>
+ * </tr>
+ * </table>
+ *
+ * The \p copy routine may modify the value to be set and those
+ * changes will be stored as the new value of the property. If the
+ * \p copy routine returns a negative value, the new property value
+ * is not copied into the property and the copy routine returns an
+ * error value.
+ *
+ * The \p compare routine is called when a property list with this
+ * property is compared to another property list with the same
+ * property.
+ *
+ * The #H5P_prp_compare_func_t callback function is defined as
+ * follows:
+ *
+ * \snippet this H5P_prp_compare_func_t_snip
+ *
+ * The parameters to the callback function are defined as follows:
+ *
+ * <table>
+ * <tr>
+ * <td>\Code{const void * value1}</td>
+ * <td>IN: The value of the first property to compare</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{const void * value2}</td>
+ * <td>IN: The value of the second property to compare</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{size_t size}</td>
+ * <td>IN: The size of the property in bytes</td>
+ * </tr>
+ * </table>
+ *
+ * The \p compare routine may not modify the values. The \p compare
+ * routine should return a positive value if \p value1 is greater
+ * than \p value2, a negative value if \p value2 is greater than
+ * \p value1 and zero if \p value1 and \p value2 are equal.
+ *
+ * The \p close routine is called when a property list with this
+ * property is being closed.
+ *
+ * The #H5P_prp_close_func_t callback function is defined as follows:
+ * \snippet this H5P_prp_cb1_t_snip
+ *
+ * The parameters to the callback function are defined as follows:
+ *
+ * <table>
+ * <tr>
+ * <td>\Code{const char * name}</td>
+ * <td>IN: The name of the property in the list</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{size_t size}</td>
+ * <td>IN: The size of the property in bytes</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{void * value}</td>
+ * <td>IN: The value for the property being closed</td>
+ * </tr>
+ * </table>
+ *
+ * The \p close routine may modify the value passed in, the
+ * value is not used by the library when the close routine
+ * returns. If the \p close routine returns a negative value,
+ * the property list \p close routine returns an error value
+ * but the property list is still closed.
+ *
+ * \b Note: There is no \p create callback routine for temporary
+ * property list objects; the initial value is assumed to
+ * have any necessary setup already performed on it.
+ *
+ * \todo "cpp_note" goes here
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL herr_t H5Pinsert2(hid_t plist_id, const char *name, size_t size,
+ void *value, H5P_prp_set_func_t set, H5P_prp_get_func_t get,
+ H5P_prp_delete_func_t prp_del, H5P_prp_copy_func_t copy,
+ H5P_prp_compare_func_t compare, H5P_prp_close_func_t close);
+/**
+ * \ingroup GPLOA
+ *
+ * \brief Determines whether a property list is a member of a class
+ *
+ * \plist_id
+ * \plistcls_id{pclass_id}
+ *
+ * \return \htri_t
+ *
+ * \details H5Pisa_class() checks to determine whether the property list
+ * \p plist_id is a member of the property list class
+ * \p pclass_id.
+ *
+ * \see H5Pcreate()
+ *
+ * \since 1.6.0
+ *
+ */
H5_DLL htri_t H5Pisa_class(hid_t plist_id, hid_t pclass_id);
-H5_DLL int H5Piterate(hid_t id, int *idx, H5P_iterate_t iter_func, void *iter_data);
-H5_DLL herr_t H5Pcopy_prop(hid_t dst_id, hid_t src_id, const char *name);
+/**
+ * \ingroup GPLOA
+ *
+ * \brief Iterates over properties in a property class or list
+ *
+ * \param[in] id Identifier of property object to iterate over
+ * \param[in,out] idx Index of the property to begin with
+ * \param[in] iter_func Function pointer to function to be called
+ * with each property iterated over
+ * \param[in,out] iter_data Pointer to iteration data from user
+ *
+ * \return On success: the return value of the last call to \p iter_func if
+ * it was non-zero; zero if all properties have been processed.
+ * On Failure, a negative value
+ *
+ * \details H5Piterate() iterates over the properties in the property
+ * object specified in \p id, which may be either a property
+ * list or a property class, performing a specified operation
+ * on each property in turn.
+ *
+ * For each property in the object, \p iter_func and the
+ * additional information specified below are passed to the
+ * #H5P_iterate_t operator function.
+ *
+ * The iteration begins with the \p idx-th property in the
+ * object; the next element to be processed by the operator
+ * is returned in \p idx. If \p idx is NULL, the iterator
+ * starts at the first property; since no stopping point is
+ * returned in this case, the iterator cannot be restarted if
+ * one of the calls to its operator returns non-zero.
+ *
+ * The prototype for the #H5P_iterate_t operator is as follows:
+ * \snippet this H5P_iterate_t_snip
+ *
+ * The operation receives the property list or class
+ * identifier for the object being iterated over, \p id, the
+ * name of the current property within the object, \p name,
+ * and the pointer to the operator data passed in to H5Piterate(),
+ * \p iter_data. The valid return values from an operator are
+ * as follows:
+ *
+ * <table>
+ * <tr>
+ * <td>Zero</td>
+ * <td>Causes the iterator to continue, returning zero when all
+ * properties have been processed</td>
+ * </tr>
+ * <tr>
+ * <td>Positive</td>
+ * <td>Causes the iterator to immediately return that positive
+ * value, indicating short-circuit success. The iterator
+ * can be restarted at the index of the next property</td>
+ * </tr>
+ * <tr>
+ * <td>Negative</td>
+ * <td>Causes the iterator to immediately return that value,
+ * indicating failure. The iterator can be restarted at the
+ * index of the next property</td>
+ * </tr>
+ * </table>
+ * H5Piterate() assumes that the properties in the object
+ * identified by \p id remain unchanged through the iteration.
+ * If the membership changes during the iteration, the function's
+ * behavior is undefined.
+ *
+ *
+ * \todo "cpp_note" goes here
+ *
+ * \since 1.4.0
+ *
+ */
+H5_DLL int H5Piterate(hid_t id, int *idx, H5P_iterate_t iter_func,
+ void *iter_data);
+/**
+ * \ingroup GPLOA
+ *
+ * \brief Registers a permanent property with a property list class
+ *
+ * \plistcls_id{cls_id}
+ * \param[in] name Name of property to register
+ * \param[in] size Size of property in bytes
+ * \param[in] def_value Default value for property in newly created
+ * property lists
+ * \param[in] create Callback routine called when a property list is
+ * being created and the property value will be
+ * initialized
+ * \param[in] set Callback routine called before a new value is
+ * copied into the property's value
+ * \param[in] get Callback routine called when a property value is
+ * retrieved from the property
+ * \param[in] prp_del Callback routine called when a property is deleted
+ * from a property list
+ * \param[in] copy Callback routine called when a property is copied
+ * from a property list
+ * \param[in] compare Callback routine called when a property is compared
+ * with another property list
+ * \param[in] close Callback routine called when a property list is
+ * being closed and the property value will be
+ * disposed of
+ *
+ * \return \herr_t
+ *
+ * \details H5Pregister2() registers a new property with a property list
+ * class. The \p cls_id identifier can be obtained by calling
+ * H5Pcreate_class(). The property will exist in all property
+ * list objects of \p cl_id created after this routine finishes. The
+ * name of the property must not already exist, or this routine
+ * will fail. The default property value must be provided and all
+ * new property lists created with this property will have the
+ * property value set to the default value. Any of the callback
+ * routines may be set to NULL if they are not needed.
+ *
+ * Zero-sized properties are allowed and do not store any data in
+ * the property list. These may be used as flags to indicate the
+ * presence or absence of a particular piece of information. The
+ * default pointer for a zero-sized property may be set to NULL.
+ * The property \p create and \p close callbacks are called for
+ * zero-sized properties, but the \p set and \p get callbacks are
+ * never called.
+ *
+ * The \p create routine is called when a new property list with
+ * this property is being created. The #H5P_prp_create_func_t
+ * callback function is defined as follows:
+ *
+ * \snippet this H5P_prp_cb1_t_snip
+ *
+ * The parameters to this callback function are defined as follows:
+ *
+ * <table>
+ * <tr>
+ * <td>\Code{const char * name}</td>
+ * <td>IN: The name of the property being modified</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{size_t size}</td>
+ * <td>IN: The size of the property in bytes</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{void * value}</td>
+ * <td>IN/OUT: The default value for the property being created,
+ * which will be passed to H5Pregister2()</td>
+ * </tr>
+ * </table>
+ *
+ * The \p create routine may modify the value to be set and those
+ * changes will be stored as the initial value of the property.
+ * If the \p create routine returns a negative value, the new
+ * property value is not copied into the property and the
+ * \p create routine returns an error value.
+ *
+ * The \p set routine is called before a new value is copied into
+ * the property. The #H5P_prp_set_func_t callback function is defined
+ * as follows:
+ *
+ * \snippet this H5P_prp_cb2_t_snip
+ *
+ * The parameters to this callback function are defined as follows:
+ *
+ * <table>
+ * <tr>
+ * <td>\ref hid_t \c prop_id</td>
+ * <td>IN: The identifier of the property list being modified</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{const char * name}</td>
+ * <td>IN: The name of the property being modified</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{size_t size}</td>
+ * <td>IN: The size of the property in bytes</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{void *value}</td>
+ * <td>IN/OUT: Pointer to new value pointer for the property
+ * being modified</td>
+ * </tr>
+ * </table>
+ *
+ * The \p set routine may modify the value pointer to be set and
+ * those changes will be used when setting the property's value.
+ * If the \p set routine returns a negative value, the new property
+ * value is not copied into the property and the \p set routine
+ * returns an error value. The \p set routine will not be called
+ * for the initial value; only the \p create routine will be called.
+ *
+ * \b Note: The \p set callback function may be useful to range
+ * check the value being set for the property or may perform some
+ * transformation or translation of the value set. The \p get
+ * callback would then reverse the transformation or translation.
+ * A single \p get or \p set callback could handle multiple
+ * properties by performing different actions based on the property
+ * name or other properties in the property list.
+ *
+ * The \p get routine is called when a value is retrieved from a
+ * property value. The #H5P_prp_get_func_t callback function is
+ * defined as follows:
+ *
+ * \snippet this H5P_prp_cb2_t_snip
+ *
+ * The parameters to the callback function are defined as follows:
+ *
+ * <table>
+ * <tr>
+ * <td>\ref hid_t \c prop_id</td>
+ * <td>IN: The identifier of the property list being
+ * queried</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{const char * name}</td>
+ * <td>IN: The name of the property being queried</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{size_t size}</td>
+ * <td>IN: The size of the property in bytes</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{void * value}</td>
+ * <td>IN/OUT: The value of the property being returned</td>
+ * </tr>
+ * </table>
+ *
+ * The \p get routine may modify the value to be returned from the
+ * query and those changes will be returned to the calling routine.
+ * If the \p set routine returns a negative value, the query
+ * routine returns an error value.
+ *
+ * The \p prp_del routine is called when a property is being
+ * deleted from a property list. The #H5P_prp_delete_func_t
+ * callback function is defined as follows:
+ *
+ * \snippet this H5P_prp_cb2_t_snip
+ *
+ * The parameters to the callback function are defined as follows:
+ *
+ * <table>
+ * <tr>
+ * <td>\ref hid_t \c prop_id</td>
+ * <td>IN: The identifier of the property list the property is
+ * being deleted from</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{const char * name}</td>
+ * <td>IN: The name of the property in the list</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{size_t size}</td>
+ * <td>IN: The size of the property in bytes</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{void * value}</td>
+ * <td>IN: The value for the property being deleted</td>
+ * </tr>
+ * </table>
+ *
+ * The \p prp_del routine may modify the value passed in, but the
+ * value is not used by the library when the \p prp_del routine
+ * returns. If the \p prp_del routine returns a negative value,
+ * the property list delete routine returns an error value but
+ * the property is still deleted.
+ *
+ * The \p copy routine is called when a new property list with
+ * this property is being created through a \p copy operation.
+ * The #H5P_prp_copy_func_t callback function is defined as follows:
+ *
+ * \snippet this H5P_prp_cb1_t_snip
+ *
+ * The parameters to the callback function are defined as follows:
+ *
+ * <table>
+ * <tr>
+ * <td>\Code{const char * name}</td>
+ * <td>IN: The name of the property being copied</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{size_t size}</td>
+ * <td>IN: The size of the property in bytes</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{void * value}</td>
+ * <td>IN/OUT: The value for the property being copied</td>
+ * </tr>
+ * </table>
+ *
+ * The \p copy routine may modify the value to be set and those
+ * changes will be stored as the new value of the property. If
+ * the \p copy routine returns a negative value, the new
+ * property value is not copied into the property and the \p copy
+ * routine returns an error value.
+ *
+ * The \p compare routine is called when a property list with this
+ * property is compared to another property list with the same
+ * property. The #H5P_prp_compare_func_t callback function is
+ * defined as follows:
+ *
+ * \snippet this H5P_prp_compare_func_t_snip
+ *
+ * The parameters to the callback function are defined as follows:
+ *
+ * <table>
+ * <tr>
+ * <td>\Code{const void * value1}</td>
+ * <td>IN: The value of the first property to compare</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{const void * value2}</td>
+ * <td>IN: The value of the second property to compare</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{size_t size}</td>
+ * <td>IN: The size of the property in bytes</td>
+ * </tr>
+ * </table>
+ *
+ * The \p compare routine may not modify the values. The \p compare
+ * routine should return a positive value if \p value1 is greater
+ * than \p value2, a negative value if \p value2 is greater than
+ * \p value1 and zero if \p value1 and \p value2 are equal.
+ *
+ * The \p close routine is called when a property list with this
+ * property is being closed. The #H5P_prp_close_func_t callback
+ * function is defined as follows:
+ *
+ * \snippet this H5P_prp_cb2_t_snip
+ *
+ * The parameters to the callback function are defined as follows:
+ *
+ * <table>
+ * <tr>
+ * <td>\ref hid_t \c prop_id</td>
+ * <td>IN: The identifier of the property list being closed</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{const char * name}</td>
+ * <td>IN: The name of the property in the list</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{size_t size}</td>
+ * <td>IN: The size of the property in bytes</td>
+ * </tr>
+ * <tr>
+ * <td>\Code{void * value}</td>
+ * <td>IN: The value for the property being closed</td>
+ * </tr>
+ * </table>
+ *
+ * The \p close routine may modify the value passed in, but the
+ * value is not used by the library when the \p close routine returns.
+ * If the \p close routine returns a negative value, the property
+ * list close routine returns an error value but the property list is
+ * still closed.
+ *
+ * \todo "cpp_note" goes here
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL herr_t H5Pregister2(hid_t cls_id, const char *name, size_t size,
+ void *def_value, H5P_prp_create_func_t create,
+ H5P_prp_set_func_t set, H5P_prp_get_func_t get,
+ H5P_prp_delete_func_t prp_del, H5P_prp_copy_func_t copy,
+ H5P_prp_compare_func_t compare, H5P_prp_close_func_t close);
+/**
+ * \ingroup GPLOA
+ *
+ * \brief Removes a property from a property list
+ *
+ * \plist_id
+ * \param[in] name Name of property to remove
+ *
+ * \return \herr_t
+ *
+ * \details H5Premove() removes a property from a property list. Both
+ * properties which were in existence when the property list was
+ * created (i.e. properties registered with H5Pregister()) and
+ * properties added to the list after it was created (i.e. added
+ * with H5Pinsert1() may be removed from a property list.
+ * Properties do not need to be removed from a property list
+ * before the list itself is closed; they will be released
+ * automatically when H5Pclose() is called.
+ *
+ * If a \p close callback exists for the removed property, it
+ * will be called before the property is released.
+ *
+ * \since 1.4.0
+ *
+ */
H5_DLL herr_t H5Premove(hid_t plist_id, const char *name);
+/**
+ * \ingroup GPLOA
+ *
+ * \brief Sets a property list value
+ *
+ * \plist_id
+ * \param[in] name Name of property to modify
+ * \param[in] value Pointer to value to set the property to
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset() sets a new value for a property in a property list.
+ * If there is a \p set callback routine registered for this
+ * property, the \p value will be passed to that routine and any
+ * changes to the \p value will be used when setting the property
+ * value. The information pointed to by the \p value pointer
+ * (possibly modified by the \p set callback) is copied into the
+ * property list value and may be changed by the application
+ * making the H5Pset() call without affecting the property value.
+ *
+ * The property name must exist or this routine will fail.
+ *
+ * If the \p set callback routine returns an error, the property
+ * value will not be modified.
+ *
+ * This routine may not be called for zero-sized properties and
+ * will return an error in that case.
+ *
+ * \since 1.4.0
+ *
+ */
+H5_DLL herr_t H5Pset(hid_t plist_id, const char *name, const void *value);
+/**
+ * \ingroup GPLOA
+ *
+ * \brief Removes a property from a property list class
+ *
+ * \plistcls_id{pclass_id}
+ * \param[in] name Name of property to remove
+ *
+ * \return \herr_t
+ *
+ * \details H5Punregister() removes a property from a property list class.
+ * Future property lists created of that class will not contain
+ * this property; existing property lists containing this property
+ * are not affected.
+ *
+ * \since 1.4.0
+ *
+ */
H5_DLL herr_t H5Punregister(hid_t pclass_id, const char *name);
-H5_DLL herr_t H5Pclose_class(hid_t plist_id);
-H5_DLL hid_t H5Pcopy(hid_t plist_id);
/* Object creation property list (OCPL) routines */
/**
* \ingroup OCPL
*
+ * \brief Verifies that all required filters are available
+ *
+ * \plist_id
+ *
+ * \return \htri_t
+ *
+ * \details H5Pall_filters_avail() verifies that all of the filters set in
+ * the dataset or group creation property list \p plist_id are
+ * currently available.
+ *
+ * \version 1.8.5 Function extended to work with group creation property
+ * lists.
+ * \since 1.6.0
+ *
+ */
+H5_DLL htri_t H5Pall_filters_avail(hid_t plist_id);
+/**
+ * \ingroup OCPL
+ *
+ * \brief Retrieves tracking and indexing settings for attribute creation
+ * order
+ *
+ * \plist_id
+ * \param[out] crt_order_flags Flags specifying whether to track and
+ * index attribute creation order
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_attr_creation_order() retrieves the settings for
+ * tracking and indexing attribute creation order on an object.
+ *
+ * \p plist_id is an object creation property list (\p ocpl),
+ * as it can be a dataset or group creation property list
+ * identifier. The term \p ocpl is used when different types
+ * of objects may be involved.
+ *
+ * \p crt_order_flags returns flags with the following meanings:
+ *
+ * <table>
+ * <tr>
+ * <td>#H5P_CRT_ORDER_TRACKED</td>
+ * <td>Attribute creation order is tracked but not necessarily
+ * indexed.</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_CRT_ORDER_INDEXED </td>
+ * <td>Attribute creation order is indexed (requires
+ * #H5P_CRT_ORDER_TRACKED).</td>
+ * </tr>
+ * </table>
+ *
+ * If \p crt_order_flags is returned with a value of 0 (zero),
+ * attribute creation order is neither tracked nor indexed.
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL herr_t H5Pget_attr_creation_order(hid_t plist_id, unsigned *crt_order_flags);
+/**
+ * \ingroup OCPL
+ *
+ * \brief Retrieves attribute storage phase change thresholds
+ *
+ * \plist_id
+ * \param[out] max_compact Maximum number of attributes to be stored in
+ * compact storage (Default: 8)
+ * \param[out] min_dense Minimum number of attributes to be stored in
+ * dense storage (Default: 6)
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_attr_phase_change() retrieves threshold values for
+ * attribute storage on an object. These thresholds determine the
+ * point at which attribute storage changes from compact storage
+ * (i.e., storage in the object header) to dense storage (i.e.,
+ * storage in a heap and indexed with a B-tree).
+ *
+ * In the general case, attributes are initially kept in compact
+ * storage. When the number of attributes exceeds \p max_compact,
+ * attribute storage switches to dense storage. If the number of
+ * attributes subsequently falls below \p min_dense, the
+ * attributes are returned to compact storage.
+ *
+ * If \p max_compact is set to 0 (zero), dense storage always used.
+ *
+ * \p plist_id is an object creation property list (\p ocpl), as it
+ * can be a dataset or group creation property list identifier.
+ * The term \p ocpl is used when different types of objects may be
+ * involved.
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL herr_t H5Pget_attr_phase_change(hid_t plist_id, unsigned *max_compact, unsigned *min_dense);
+/**
+ * \ingroup OCPL
+ *
* \brief Returns information about a filter in a pipeline
*
* \todo Signature for H5Pget_filter2 is different in H5Pocpl.c than in
@@ -472,103 +1866,2098 @@ H5_DLL hid_t H5Pcopy(hid_t plist_id);
* \since 1.8.0
*
*/
-H5_DLL H5Z_filter_t H5Pget_filter2(hid_t plist_id, unsigned idx, unsigned int *flags /*out*/,
- size_t *cd_nelmts /*out*/, unsigned cd_values[] /*out*/, size_t namelen,
- char name[], unsigned *filter_config /*out*/);
-H5_DLL herr_t H5Pset_attr_phase_change(hid_t plist_id, unsigned max_compact, unsigned min_dense);
-H5_DLL herr_t H5Pget_attr_phase_change(hid_t plist_id, unsigned *max_compact, unsigned *min_dense);
-H5_DLL herr_t H5Pset_attr_creation_order(hid_t plist_id, unsigned crt_order_flags);
-H5_DLL herr_t H5Pget_attr_creation_order(hid_t plist_id, unsigned *crt_order_flags);
-H5_DLL herr_t H5Pset_obj_track_times(hid_t plist_id, hbool_t track_times);
-H5_DLL herr_t H5Pget_obj_track_times(hid_t plist_id, hbool_t *track_times);
-H5_DLL herr_t H5Pmodify_filter(hid_t plist_id, H5Z_filter_t filter, unsigned int flags, size_t cd_nelmts,
- const unsigned int cd_values[/*cd_nelmts*/]);
-H5_DLL herr_t H5Pset_filter(hid_t plist_id, H5Z_filter_t filter, unsigned int flags, size_t cd_nelmts,
- const unsigned int c_values[]);
-H5_DLL int H5Pget_nfilters(hid_t plist_id);
-H5_DLL herr_t H5Pget_filter_by_id2(hid_t plist_id, H5Z_filter_t id, unsigned int *flags /*out*/,
- size_t *cd_nelmts /*out*/, unsigned cd_values[] /*out*/, size_t namelen,
- char name[] /*out*/, unsigned *filter_config /*out*/);
-H5_DLL htri_t H5Pall_filters_avail(hid_t plist_id);
+H5_DLL H5Z_filter_t H5Pget_filter2(hid_t plist_id, unsigned idx,
+ unsigned int *flags/*out*/,
+ size_t *cd_nelmts/*out*/,
+ unsigned cd_values[]/*out*/,
+ size_t namelen, char name[],
+ unsigned *filter_config /*out*/);
+/**
+ * \ingroup OCPL
+ *
+ * \brief Returns information about the specified filter
+ *
+ * \plist_id
+ * \param[in] filter_id Filter identifier
+ * \param[out] flags Bit vector specifying certain general
+ * properties of the filter
+ * \param[in,out] cd_nelmts Number of elements in \p cd_values
+ * \param[out] cd_values[] Auxiliary data for the filter
+ * \param[in] namelen Length of filter name and number of
+ * elements in \p name
+ * \param[out] name[] Name of filter
+ * \param[out] filter_config Bit field, as described in
+ * H5Zget_filter_info()
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_filter_by_id2() returns information about the filter
+ * specified in \p filter_id, a filter identifier.
+ *
+ * \p plist_id must be a dataset or group creation property list
+ * and \p filter_id must be in the associated filter pipeline.
+ *
+ * The \p filter_id and \p flags parameters are used in the same
+ * manner as described in the discussion of H5Pset_filter().
+ *
+ * Aside from the fact that they are used for output, the
+ * parameters \p cd_nelmts and \p cd_values[] are used in the same
+ * manner as described in the discussion of H5Pset_filter(). On
+ * input, the \p cd_nelmts parameter indicates the number of
+ * entries in the \p cd_values[] array allocated by the calling
+ * program; on exit it contains the number of values defined by
+ * the filter.
+ *
+ * On input, the \p namelen parameter indicates the number of
+ * characters allocated for the filter name by the calling program
+ * in the array \p name[]. On exit \p name[] contains the name of the
+ * filter with one character of the name in each element of the
+ * array.
+ *
+ * \p filter_config is the bit field described in
+ * H5Zget_filter_info().
+ *
+ * If the filter specified in \p filter_id is not set for the
+ * property list, an error will be returned and
+ * H5Pget_filter_by_id2() will fail.
+ *
+ * \version 1.8.5 Function extended to work with group creation property
+ * lists.
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL herr_t H5Pget_filter_by_id2(hid_t plist_id, H5Z_filter_t filter_id,
+ unsigned int *flags/*out*/, size_t *cd_nelmts/*out*/,
+ unsigned cd_values[]/*out*/, size_t namelen, char name[]/*out*/,
+ unsigned *filter_config/*out*/);
+/**
+ * \ingroup OCPL
+ *
+ * \brief Returns the number of filters in the pipeline
+ *
+ * \todo Signature for H5Pget_nfilters() is different in H5Pocpl.c than in
+ * H5Ppublic.h.
+ *
+ * \plist_id
+ *
+ * \return Returns the number of filters in the pipeline if successful;
+ * otherwise returns a negative value.
+ *
+ * \details H5Pget_nfilters() returns the number of filters defined in the
+ * filter pipeline associated with the property list \p plist_id.
+ *
+ * In each pipeline, the filters are numbered from 0 through N-1,
+ * where N is the value returned by this function. During output to
+ * the file, the filters are applied in increasing order; during
+ * input from the file, they are applied in decreasing order.
+ *
+ * H5Pget_nfilters() returns the number of filters in the pipeline,
+ * including zero (0) if there are none.
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL int H5Pget_nfilters(hid_t plist_id);
+/**
+ * \ingroup OCPL
+ *
+ * \brief Determines whether times associated with an object
+ * are being recorded
+ *
+ * \plist_id
+ * \param[out] track_times Boolean value, 1 (TRUE) or 0 (FALSE),
+ * specifying whether object times are being recorded
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_obj_track_times() queries the object creation property
+ * list, \p plist_id, to determine whether object times are being
+ * recorded.
+ *
+ * If \p track_times is returned as 1, times are being recorded;
+ * if \p track_times is returned as 0, times are not being
+ * recorded.
+ *
+ * Time data can be retrieved with H5Oget_info(), which will return
+ * it in the #H5O_info_t struct.
+ *
+ * If times are not tracked, they will be reported as follows
+ * when queried: 12:00 AM UDT, Jan. 1, 1970
+ *
+ * See H5Pset_obj_track_times() for further discussion.
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL herr_t H5Pget_obj_track_times(hid_t plist_id, hbool_t *track_times);
+/**
+ * \ingroup OCPL
+ *
+ * \brief Modifies a filter in the filter pipeline
+ *
+ * \plist_id
+ * \param[in] filter Filter to be modified
+ * \param[in] flags Bit vector specifying certain general properties
+ * of the filter
+ * \param[in] cd_nelmts Number of elements in \p cd_values
+ * \param[in] cd_values[] Auxiliary data for the filter
+ *
+ * \return \herr_t
+ *
+ * \details H5Pmodify_filter() modifies the specified \p filter in the
+ * filter pipeline. \p plist_id must be a dataset or group
+ * creation property list.
+ *
+ * The \p filter, \p flags \p cd_nelmts[], and \p cd_values
+ * parameters are used in the same manner and accept the same
+ * values as described in the discussion of H5Pset_filter().
+ *
+ * \version 1.8.5 Function extended to work with group creation property
+ * lists.
+ * \since 1.6.0
+ *
+ */
+H5_DLL herr_t H5Pmodify_filter(hid_t plist_id, H5Z_filter_t filter,
+ unsigned int flags, size_t cd_nelmts,
+ const unsigned int cd_values[/*cd_nelmts*/]);
+/**
+ * \ingroup OCPL
+ *
+ * \brief Delete one or more filters in the filter pipeline
+ *
+ * \plist_id
+ * \param[in] filter Filter to be deleted
+ *
+ * \return \herr_t
+ *
+ * \details H5Premove_filter() removes the specified \p filter from the
+ * filter pipeline in the dataset or group creation property
+ * list \p plist_id.
+ *
+ * The \p filter parameter specifies the filter to be removed.
+ * Valid values for use in \p filter are as follows:
+ *
+ * <table>
+ * <tr>
+ * <td>#H5Z_FILTER_ALL</td>
+ * <td>Removes all filters from the filter pipeline</td>
+ * </tr>
+ * <tr>
+ * <td>#H5Z_FILTER_DEFLATE</td>
+ * <td>Data compression filter, employing the gzip
+ * algorithm</td>
+ * </tr>
+ * <tr>
+ * <td>#H5Z_FILTER_SHUFFLE</td>
+ * <td>Data shuffling filter</td>
+ * </tr>
+ * <tr>
+ * <td>#H5Z_FILTER_FLETCHER32</td>
+ * <td>Error detection filter, employing the Fletcher32
+ * checksum algorithm</td>
+ * </tr>
+ * <tr>
+ * <td>#H5Z_FILTER_SZIP</td>
+ * <td>Data compression filter, employing the SZIP
+ * algorithm</td>
+ * </tr>
+ * <tr>
+ * <td>#H5Z_FILTER_NBIT</td>
+ * <td>Data compression filter, employing the N-Bit
+ * algorithm</td>
+ * </tr>
+ * <tr>
+ * <td>#H5Z_FILTER_SCALEOFFSET</td>
+ * <td>Data compression filter, employing the scale-offset
+ * algorithm</td>
+ * </tr>
+ * </table>
+ *
+ * Additionally, user-defined filters can be removed with this
+ * routine by passing the filter identifier with which they were
+ * registered with the HDF5 library.
+ *
+ * Attempting to remove a filter that is not in the filter
+ * pipeline is an error.
+ *
+ * \version 1.8.5 Function extended to work with group creation property
+ * lists.
+ * \since 1.6.3
+ *
+ */
H5_DLL herr_t H5Premove_filter(hid_t plist_id, H5Z_filter_t filter);
-H5_DLL herr_t H5Pset_deflate(hid_t plist_id, unsigned aggression);
+/**
+ * \ingroup OCPL
+ *
+ * \brief Sets tracking and indexing of attribute creation order
+ *
+ * \plist_id
+ * \param[in] crt_order_flags Flags specifying whether to track and index
+ * attribute creation order. \em Default: No
+ * flag set; attribute creation order is neither
+ * tracked not indexed
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_attr_creation_order() sets flags for tracking and
+ * indexing attribute creation order on an object.
+ *
+ * \p plist_id is a dataset or group creation property list
+ * identifier.
+ *
+ * \p crt_order_flags contains flags with the following meanings:
+ *
+ * <table>
+ * <tr>
+ * <td>#H5P_CRT_ORDER_TRACKED</td>
+ * <td>Attribute creation order is tracked but not necessarily
+ * indexed.</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_CRT_ORDER_INDEXED </td>
+ * <td>Attribute creation order is indexed (requires
+ * #H5P_CRT_ORDER_TRACKED).</td>
+ * </tr>
+ * </table>
+ *
+ * Default behavior is that attribute creation order is neither
+ * tracked nor indexed.
+ *
+ * H5Pset_attr_creation_order() can be used to set attribute
+ * creation order tracking, or to set attribute creation order
+ * tracking and indexing.
+ *
+ * \note If a creation order index is to be built, it must be specified in
+ * the object creation property list. HDF5 currently provides no
+ * mechanism to turn on attribute creation order tracking at object
+ * creation time and to build the index later.
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL herr_t H5Pset_attr_creation_order(hid_t plist_id, unsigned crt_order_flags);
+/**
+ * \ingroup OCPL
+ *
+ * \brief Sets attribute storage phase change thresholds
+ *
+ * \plist_id
+ * \param[in] max_compact Maximum number of attributes to be stored in
+ * compact storage (\em Default: 8); must be greater
+ * than or equal to \p min_dense
+ *
+ * \param[in] min_dense Minimum number of attributes to be stored in
+ * dense storage (\em Default: 6)
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_attr_phase_change() sets threshold values for attribute
+ * storage on an object. These thresholds determine the point at
+ * which attribute storage changes from compact storage (i.e.,
+ * storage in the object header) to dense storage (i.e., storage
+ * in a heap and indexed with a B-tree).
+ *
+ * In the general case, attributes are initially kept in compact
+ * storage. When the number of attributes exceeds \p max_compact,
+ * attribute storage switches to dense storage. If the number of
+ * attributes subsequently falls below \p min_dense, the attributes
+ * are returned to compact storage.
+ *
+ * If \p max_compact is set to 0 (zero), dense storage is always
+ * used. \p min_dense must be set to 0 (zero) when \p max_compact
+ * is 0 (zero).
+ *
+ * \p plist_id is a dataset or group creation property list
+ * identifier.
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL herr_t H5Pset_attr_phase_change(hid_t plist_id, unsigned max_compact, unsigned min_dense);
+/**
+ * \ingroup OCPL
+ *
+ * \brief Sets deflate (GNU gzip) compression method and compression level
+ *
+ * \plist_id
+ * \param[in] level Compression level
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_deflate() sets the deflate compression method and the
+ * compression level, \p level, for a dataset or group creation
+ * property list, \p plist_id.
+ *
+ * The filter identifier set in the property list is
+ * #H5Z_FILTER_DEFLATE.
+ *
+ * The compression level, \p level, is a value from zero to nine,
+ * inclusive. A compression level of 0 (zero) indicates no
+ * compression; compression improves but speed slows progressively
+ * from levels 1 through 9:
+ *
+ * <table>
+ * <tr>
+ * <th>Compression Level</th>
+ * <th>Gzip Action</th>
+ * </tr>
+ * <tr>
+ * <td>0</td>
+ * <td>No compression</td>
+ * </tr>
+ * <tr>
+ * <td>1</td>
+ * <td>Best compression speed; least compression</td>
+ * </tr>
+ * <tr>
+ * <td>2 through 8</td>
+ * <td>Compression improves; speed degrades</td>
+ * </tr>
+ * <tr>
+ * <td>9</td>
+ * <td>Best compression ratio; slowest speed</td>
+ * </tr>
+ * </table>
+ *
+ * Note that setting the compression level to 0 (zero) does not turn
+ * off use of the gzip filter; it simply sets the filter to perform
+ * no compression as it processes the data.
+ *
+ * HDF5 relies on GNU gzip for this compression.
+ *
+ * \version 1.8.5 Function extended to work with group creation property lists.
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Pset_deflate(hid_t plist_id, unsigned level);
+/**
+ * \ingroup OCPL
+ *
+ * \brief Adds a filter to the filter pipeline
+ *
+ * \param[in] plist_id Dataset or group creation property list identifier
+ * \param[in] filter Filter identifier for the filter to be added to the
+ * pipeline
+ * \param[in] flags Bit vector specifying certain general properties of
+ * the filter
+ * \param[in] cd_nelmts Number of elements in \p c_values
+ * \param[in] c_values Auxiliary data for the filter
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_filter() adds the specified \p filter identifier and
+ * corresponding properties to the end of an output filter
+ * pipeline.
+ *
+ * \p plist_id must be either a dataset creation property list or
+ * group creation property list identifier. If \p plist_id is a
+ * dataset creation property list identifier, the filter is added
+ * to the raw data filter pipeline.
+ *
+ * If \p plist_id is a group creation property list identifier,
+ * the filter is added to the link filter pipeline, which filters
+ * the fractal heap used to store most of the link metadata in
+ * certain types of groups. The only predefined filters that can
+ * be set in a group creation property list are the gzip filter
+ * (#H5Z_FILTER_DEFLATE) and the Fletcher32 error detection filter
+ * (#H5Z_FILTER_FLETCHER32).
+ *
+ * The array \p c_values contains \p cd_nelmts integers which are
+ * auxiliary data for the filter. The integer values will be
+ * stored in the dataset object header as part of the filter
+ * information.
+ *
+ * The \p flags argument is a bit vector with the following
+ * fields specifying certain general properties of the filter:
+ *
+ * <table>
+ * <tr>
+ * <td>#H5Z_FLAG_OPTIONAL</td>
+ * <td>If this bit is set then the filter is optional. If the
+ * filter fails (see below) during an H5Dwrite() operation
+ * then the filter is just excluded from the pipeline for
+ * the chunk for which it failed; the filter will not
+ * participate in the pipeline during an H5Dread() of the
+ * chunk. This is commonly used for compression filters:
+ * if the filter result would be larger than the input,
+ * then the compression filter returns failure and the
+ * uncompressed data is stored in the file.<br /><br />
+ * This flag should not be set for the Fletcher32 checksum
+ * filter as it will bypass the checksum filter without
+ * reporting checksum errors to an application.</td>
+ * </tr>
+ * <tr>
+ * <td>#H5Z_FLAG_MANDATORY</td>
+ * <td>If the filter is required, that is, set to mandatory,
+ * and the filter fails, the library’s behavior depends
+ * on whether the chunk cache is in use:
+ * \li If the chunk cache is enabled, data chunks will
+ * be flushed to the file during H5Dclose() and the
+ * library will return the failure in H5Dclose().
+ * \li When the chunk cache is disabled or not big enough,
+ * or the chunk is being evicted from the cache, the
+ * failure will happen during H5Dwrite().
+ *
+ * In each case, the library will still write to the file
+ * all data chunks that were processed by the filter
+ * before the failure occurred.<br /><br />
+ * For example, assume that an application creates a
+ * dataset of four chunks, the chunk cache is enabled and
+ * is big enough to hold all four chunks, and the filter
+ * fails when it tries to write the fourth chunk. The
+ * actual flush of the chunks will happen during
+ * H5Dclose(), not H5Dwrite(). By the time H5Dclose()
+ * fails, the first three chunks will have been written
+ * to the file. Even though H5Dclose() fails, all the
+ * resources will be released and the file can be closed
+ * properly. <br /><br />
+ * If, however, the filter fails on the second chunk, only
+ * the first chunk will be written to the file as nothing
+ * further can be written once the filter fails.</td>
+ * </tr>
+ * </table>
+ * The \p filter parameter specifies the filter to be set. Valid
+ * pre-defined filter identifiers are as follows:
+ *
+ * <table>
+ * <tr>
+ * <td>#H5Z_FILTER_DEFLATE</td>
+ * <td>Data compression filter, employing the gzip
+ * algorithm</td>
+ * </tr>
+ * <tr>
+ * <td>#H5Z_FILTER_SHUFFLE</td>
+ * <td>Data shuffling filter</td>
+ * </tr>
+ * <tr>
+ * <td>#H5Z_FILTER_FLETCHER32</td>
+ * <td>Error detection filter, employing the Fletcher32
+ * checksum algorithm</td>
+ * </tr>
+ * <tr>
+ * <td>#H5Z_FILTER_SZIP</td>
+ * <td>Data compression filter, employing the SZIP
+ * algorithm</td>
+ * </tr>
+ * <tr>
+ * <td>#H5Z_FILTER_NBIT</td>
+ * <td>Data compression filter, employing the N-Bit
+ * algorithm</td>
+ * </tr>
+ * <tr>
+ * <td>#H5Z_FILTER_SCALEOFFSET</td>
+ * <td>Data compression filter, employing the scale-offset
+ * algorithm</td>
+ * </tr>
+ * </table>
+ * Also see H5Pset_edc_check() and H5Pset_filter_callback().
+ *
+ * \note When a non-empty filter pipeline is used with a group creation
+ * property list, the group will be created with the new group file
+ * format. The filters will come into play only when dense storage
+ * is used (see H5Pset_link_phase_change()) and will be applied to
+ * the group’s fractal heap. The fractal heap will contain most of
+ * the the group’s link metadata, including link names.
+ *
+ * \note When working with group creation property lists, if you are
+ * adding a filter that is not in HDF5’s set of predefined filters,
+ * i.e., a user-defined or third-party filter, you must first
+ * determine that the filter will work for a group. See the
+ * discussion of the set local and can apply callback functions
+ * in H5Zregister().
+ *
+ * \note If multiple filters are set for a property list, they will be
+ * applied to each chunk of raw data for datasets or each block
+ * of the fractal heap for groups in the order in which they were
+ * set.
+ *
+ * \note Filters can be applied only to chunked datasets; they cannot be
+ * used with other dataset storage methods, such as contiguous,
+ * compact, or external datasets.
+ *
+ * \note Dataset elements of variable-length and dataset region
+ * reference datatypes are stored in separate structures in the
+ * file called heaps. Filters cannot currently be applied to
+ * these heaps.
+ *
+ * \note <b>Filter Behavior in HDF5:</b><br />
+ * Filters can be inserted into the HDF5 pipeline to perform
+ * functions such as compression and conversion. As such, they are
+ * a very flexible aspect of HDF5; for example, a user-defined
+ * filter could provide encryption for an HDF5 dataset.
+ *
+ * \note A filter can be declared as either required or optional.
+ * Required is the default status; optional status must be
+ * explicitly declared.
+ *
+ * \note A required filter that fails or is not defined causes an
+ * entire output operation to fail; if it was applied when the
+ * data was written, such a filter will cause an input operation
+ * to fail.
+ *
+ * \note The following table summarizes required filter behavior.
+ * <table>
+ * <tr>
+ * <th></th>
+ * <th>Required FILTER_X not available</th>
+ * <th>FILTER_X available</th>
+ * </tr>
+ * <tr>
+ * <td>H5Pset_<FILTER_X></td>
+ * <td>Will fail.</td>
+ * <td>Will succeed.</td>
+ * </tr>
+ * <tr>
+ * <td>H5Dwrite with FILTER_X set</td>
+ * <td>Will fail.</td>
+ * <td>Will succeed; FILTER_X will be applied to
+ * the data.</td>
+ * </tr>
+ * <tr>
+ * <td>H5Dread with FILTER_X set</td>
+ * <td>Will fail.</td>
+ * <td>Will succeed.</td>
+ * </tr>
+ * </table>
+ * \note An optional filter can be set for an HDF5 dataset even when
+ * the filter is not available. Such a filter can then be
+ * applied to the dataset when it becomes available on the
+ * original system or when the file containing the dataset is
+ * processed on a system on which it is available.
+ *
+ * \note A filter can be declared as optional through the use of the
+ * #H5Z_FLAG_OPTIONAL flag with H5Pset_filter().
+ *
+ * \note Consider a situation where one is creating files that will
+ * normally be used only on systems where the optional (and
+ * fictional) filter FILTER_Z is routinely available. One can
+ * create those files on system A, which lacks FILTER_Z, create
+ * chunked datasets in the files with FILTER_Z defined in the
+ * dataset creation property list, and even write data to those
+ * datasets. The dataset object header will indicate that FILTER_Z
+ * has been associated with this dataset. But since system A does
+ * not have FILTER_Z, dataset chunks will be written without it
+ * being applied.
+ *
+ * \note HDF5 has a mechanism for determining whether chunks are
+ * actually written with the filters specified in the object
+ * header, so while the filter remains unavailable, system A will
+ * be able to read the data. Once the file is moved to system B,
+ * where FILTER_Z is available, HDF5 will apply FILTER_Z to any
+ * data rewritten or new data written in these datasets. Dataset
+ * chunks that have been written on system B will then be
+ * unreadable on system A; chunks that have not been re-written
+ * since being written on system A will remain readable on system
+ * A. All chunks will be readable on system B.
+ *
+ * \note The following table summarizes optional filter behavior.
+ * <table>
+ * <tr>
+ * <th></th>
+ * <th>FILTER_Z not available</th>
+ * <th>FILTER_Z available<br /> with encode and decode</th>
+ * <th>FILTER_Z available decode only</th>
+ * </tr>
+ * <tr>
+ * <td>H5Pset_<FILTER_Z></td>
+ * <td>Will succeed.</td>
+ * <td>Will succeed.</td>
+ * <td>Will succeed.</td>
+ * </tr>
+ * <tr>
+ * <td>H5Dread with FILTER_Z set</td>
+ * <td>Will succeed if FILTER_Z has not actually<br />
+ * been applied to data.</td>
+ * <td>Will succeed.</td>
+ * <td>Will succeed.</td>
+ * </tr>
+ * <tr>
+ * <td>H5Dwrite with FILTER_Z set</td>
+ * <td>Will succeed;<br />
+ * FILTER_Z will not be applied to the data.</td>
+ * <td>Will succeed;<br />
+ * FILTER_Z will be applied to the data.</td>
+ * <td>Will succeed;<br />
+ * FILTER_Z will not be applied to the data.</td>
+ * </tr>
+ * </table>
+ * \note The above principles apply generally in the use of HDF5
+ * optional filters insofar as HDF5 does as much as possible to
+ * complete an operation when an optional filter is unavailable.
+ * (The SZIP filter is an exception to this rule; see H5Pset_szip()
+ * for details.)
+ *
+ * \todo Removed several references to links to documentation
+ *
+ * \version 1.8.5 Function applied to group creation property lists.
+ * \since 1.6.0
+ *
+ */
+H5_DLL herr_t H5Pset_filter(hid_t plist_id, H5Z_filter_t filter,
+ unsigned int flags, size_t cd_nelmts,
+ const unsigned int c_values[]);
+/**
+ * \ingroup OCPL
+ *
+ * \brief Sets up use of the Fletcher32 checksum filter
+ *
+ * \param[in] plist_id Dataset or group creation property list identifier
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_fletcher32() sets the Fletcher32 checksum filter in the
+ * dataset or group creation property list \p plist_id.
+ *
+ * \attention The Fletcher32 EDC checksum filter was added in HDF5 Release
+ * 1.6.0. In the original implementation, however, the checksum
+ * value was calculated incorrectly on little-endian systems.
+ * The error was fixed in HDF5 Release 1.6.3.
+ *
+ * \attention As a result of this fix, an HDF5 library of Release 1.6.0
+ * through Release 1.6.2 cannot read a dataset created or written
+ * with Release 1.6.3 or later if the dataset was created with
+ * the checksum filter and the filter is enabled in the reading
+ * library. (Libraries of Release 1.6.3 and later understand the
+ * earlier error and compensate appropriately.)
+ *
+ * \attention \b Work-around: An HDF5 library of Release 1.6.2 or earlier
+ * will be able to read a dataset created or written with the
+ * checksum filter by an HDF5 library of Release 1.6.3 or later
+ * if the checksum filter is disabled for the read operation.
+ * This can be accomplished via a call to H5Pset_edc_check()
+ * with the value #H5Z_DISABLE_EDC in the second parameter.
+ * This has the obvious drawback that the application will be
+ * unable to verify the checksum, but the data does remain
+ * accessible.
+ *
+ * \version 1.8.5 Function extended to work with group creation property
+ * lists.
+ * \version 1.6.3 Error in checksum calculation on little-endian systems
+ * corrected in this release.
+ * \since 1.6.0
+ *
+ */
H5_DLL herr_t H5Pset_fletcher32(hid_t plist_id);
+/**
+ * \ingroup OCPL
+ *
+ * \brief Sets the recording of times associated with an object
+ *
+ * \param[in] plist_id Object creation property list identifier
+ * \param[in] track_times Boolean value, 1 or 0, specifying whether object
+ * times are to be tracked
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_obj_track_times() sets a property in the object creation
+ * property list, \p plist_id, that governs the recording of times
+ * associated with an object.
+ *
+ * If \p track_times is set to 1, time data will be recorded. If
+ * \p track_times is set to 0, time data will not be recorded.
+ *
+ * Time data can be retrieved with H5Oget_info(), which will
+ * return it in the #H5O_info_t struct.
+ *
+ * If times are not tracked, they will be reported as follows when queried:
+ * \Code{ 12:00 AM UDT, Jan. 1, 1970}
+ *
+ * That date and time are commonly used to represent the beginning of the UNIX epoch.
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL herr_t H5Pset_obj_track_times(hid_t plist_id, hbool_t track_times);
/* File creation property list (FCPL) routines */
-H5_DLL herr_t H5Pset_userblock(hid_t plist_id, hsize_t size);
+/**
+ * \ingroup FCPL
+ *
+ * \brief Retrieves the file space page size for a file creation property
+ * list
+ *
+ * \fcpl_id{plist_id}
+ * \param[out] fsp_size File space page size
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_file_space_page_size() retrieves the file space page
+ * size for paged aggregation in the parameter \p fsp_size.
+ *
+ * The library default is 4KB (4096) if \p fsp_size is not
+ * previously set via a call to H5Pset_file_space_page_size().
+ *
+ * \since 1.10.1
+ *
+ */
+H5_DLL herr_t H5Pget_file_space_page_size(hid_t plist_id, hsize_t *fsp_size);
+/**
+ * \ingroup FCPL
+ *
+ * \brief Retrieves the file space handling strategy, persisting free-space
+ * condition and threshold value for a file creation property list
+ *
+ * \fcpl_id{plist_id}
+ * \param[out] strategy The file space handling strategy
+ * \param[out] persist The boolean value indicating whether free space is
+ * persistent or not
+ * \param[out] threshold The free-space section size threshold value
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_file_space_strategy() retrieves the file space handling
+ * strategy, the persisting free-space condition and the threshold
+ * value in the parameters \p strategy, \p persist and
+ * \p threshold respectively.
+ *
+ * The library default values returned when
+ * H5Pset_file_space_strategy() has not been called are:
+ *
+ * \li \p strategy - #H5F_FSPACE_STRATEGY_FSM_AGGR
+ * \li \p persist - 0
+ * \li \p threshold - 1
+ *
+ * \since 1.10.1
+ *
+ */
+H5_DLL herr_t H5Pget_file_space_strategy(hid_t plist_id, H5F_fspace_strategy_t *strategy, hbool_t *persist, hsize_t *threshold);
+/**
+ * \ingroup FCPL
+ *
+ * \brief Queries the 1/2 rank of an indexed storage B-tree
+ *
+ * \fcpl_id{plist_id}
+ * \param[out] ik Pointer to location to return the chunked storage B-tree
+ * 1/2 rank (<em>Default value of B-tree 1/2 rank: 32</em>)
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_istore_k() queries the 1/2 rank of an indexed storage
+ * B-tree.
+ *
+ * The argument \p ik may be the null pointer (NULL).
+ * This function is valid only for file creation property lists.
+ *
+ * \see H5Pset_istore_k()
+ *
+ * \version 1.6.4 \p ik parameter type changed to \em unsigned.
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Pget_istore_k(hid_t plist_id, unsigned *ik/*out*/);
+/**
+ * \ingroup FCPL
+ *
+ * \brief Retrieves the configuration settings for a shared message index
+ *
+ * \fcpl_id{plist_id}
+ * \param[in] index_num Index being configured
+ * \param[out] mesg_type_flags Types of messages that may be stored in
+ * this index
+ * \param[out] min_mesg_size Minimum message size
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_shared_mesg_index() retrieves the message type and
+ * minimum message size settings from the file creation property
+ * list \p plist_id for the shared object header message index
+ * specified by \p index_num.
+ *
+ * \p index_num specifies the index. \p index_num is zero-indexed,
+ * so in a file with three indexes, they will be numbered 0, 1,
+ * and 2.
+ *
+ * \p mesg_type_flags and \p min_mesg_size will contain,
+ * respectively, the types of messages and the minimum size, in
+ * bytes, of messages that can be stored in this index.
+ *
+ * Valid message types are described in H5Pset_shared_mesg_index().
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL herr_t H5Pget_shared_mesg_index(hid_t plist_id, unsigned index_num, unsigned *mesg_type_flags, unsigned *min_mesg_size);
+/**
+ * \ingroup FCPL
+ *
+ * \brief Retrieves number of shared object header message indexes in file
+ * creation property list
+ *
+ * \fcpl_id{plist_id}
+ * \param[out] nindexes Number of shared object header message indexes
+ * available in files created with this property list
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_shared_mesg_nindexes() retrieves the number of shared
+ * object header message indexes in the specified file creation
+ * property list \p plist_id.
+ *
+ * If the value of \p nindexes is 0 (zero), shared object header
+ * messages are disabled in files created with this property list.
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL herr_t H5Pget_shared_mesg_nindexes(hid_t plist_id, unsigned *nindexes);
+/**
+ * \ingroup FCPL
+ *
+ * \brief Retrieves shared object header message phase change information
+ *
+ * \fcpl_id{plist_id}
+ * \param[out] max_list Threshold above which storage of a shared object
+ * header message index shifts from list to B-tree
+ * \param[out] min_btree Threshold below which storage of a shared object
+ * header message index reverts to list format
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_shared_mesg_phase_change() retrieves the threshold values
+ * for storage of shared object header message indexes in a file.
+ * These phase change thresholds determine the point at which the
+ * index storage mechanism changes from a more compact list format
+ * to a more performance-oriented B-tree format, and vice-versa.
+ *
+ * By default, a shared object header message index is initially
+ * stored as a compact list. When the number of messages in an
+ * index exceeds the specified \p max_list threshold, storage
+ * switches to a B-tree format for improved performance. If the
+ * number of messages subsequently falls below the \p min_btree
+ * threshold, the index will revert to the list format.
+ *
+ * If \p max_list is set to 0 (zero), shared object header message
+ * indexes in the file will always be stored as B-trees.
+ *
+ * \p plist_id specifies the file creation property list.
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL herr_t H5Pget_shared_mesg_phase_change(hid_t plist_id, unsigned *max_list, unsigned *min_btree);
+/**
+ * \ingroup FCPL
+ *
+ * \brief Retrieves the size of the offsets and lengths used in an HDF5
+ * file
+ *
+ * \fcpl_id{plist_id}
+ * \param[out] sizeof_addr Pointer to location to return offset size in
+ * bytes
+ * \param[out] sizeof_size Pointer to location to return length size in
+ * bytes
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_sizes() retrieves the size of the offsets and lengths
+ * used in an HDF5 file. This function is only valid for file
+ * creation property lists.
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Pget_sizes(hid_t plist_id, size_t *sizeof_addr/*out*/,
+ size_t *sizeof_size/*out*/);
+/**
+ * \ingroup FCPL
+ *
+ * \brief Retrieves the size of the symbol table B-tree 1/2 rank and the
+ * symbol table leaf node 1/2 size
+ *
+ * \fcpl_id{plist_id}
+ * \param[out] ik Pointer to location to return the symbol table's B-tree
+ * 1/2 rank (<em>Default value of B-tree 1/2 rank: 16</em>)
+ * \param[out] lk Pointer to location to return the symbol table's leaf
+ * node 1/2 size (<em>Default value of leaf node 1/2
+ * size: 4</em>)
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_sym_k() retrieves the size of the symbol table B-tree
+ * 1/2 rank and the symbol table leaf node 1/2 size.
+ *
+ * This function is valid only for file creation property lists.
+ *
+ * If a parameter value is set to NULL, that parameter is not
+ * retrieved.
+ *
+ * \see H5Pset_sym_k()
+ *
+ * \version 1.6.4 \p ik parameter type changed to \em unsigned
+ * \version 1.6.0 The \p ik parameter has changed from type int to
+ * \em unsigned
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Pget_sym_k(hid_t plist_id, unsigned *ik/*out*/, unsigned *lk/*out*/);
+/**
+ * \ingroup FCPL
+ *
+ * \brief Retrieves the size of a user block
+ *
+ * \fcpl_id{plist_id}
+ * \param[out] size Pointer to location to return user-block size
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_userblock() retrieves the size of a user block in a
+ * file creation property list.
+ *
+ * \since 1.0.0
+ *
+ */
H5_DLL herr_t H5Pget_userblock(hid_t plist_id, hsize_t *size);
-H5_DLL herr_t H5Pset_sizes(hid_t plist_id, size_t sizeof_addr, size_t sizeof_size);
-H5_DLL herr_t H5Pget_sizes(hid_t plist_id, size_t *sizeof_addr /*out*/, size_t *sizeof_size /*out*/);
-H5_DLL herr_t H5Pset_sym_k(hid_t plist_id, unsigned ik, unsigned lk);
-H5_DLL herr_t H5Pget_sym_k(hid_t plist_id, unsigned *ik /*out*/, unsigned *lk /*out*/);
+/**
+ * \ingroup FCPL
+ *
+ * \brief Sets the file space page size for a file creation property list
+ *
+ * \fcpl_id{plist_id}
+ * \param[in] fsp_size File space page size
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_file_space_page_size() sets the file space page size
+ * \p fsp_size used in paged aggregation and paged buffering.
+ *
+ * \p fsp_size has a minimum size of 512. Setting a value less
+ * than 512 will return an error. The library default size for
+ * the file space page size when not set is 4096.
+ *
+ * The size set via this routine may not be changed for the life
+ * of the file.
+ *
+ * \since 1.10.1
+ *
+ */
+H5_DLL herr_t H5Pset_file_space_page_size(hid_t plist_id, hsize_t fsp_size);
+/**
+ * \ingroup FCPL
+ *
+ * \brief Sets the file space handling strategy and persisting free-space
+ * values for a file creation property list
+ *
+ * \fcpl_id{plist_id}
+ * \param[in] strategy The file space handling strategy to be used. See:
+ * #H5F_fspace_strategy_t
+ * \param[in] persist A boolean value to indicate whether free space
+ * should be persistent or not
+ * \param[in] threshold The smallest free-space section size that the free
+ * space manager will track
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_file_space_strategy() sets the file space handling
+ * \p strategy, specifies persisting free-space or not (\p persist),
+ * and sets the free-space section size \p threshold in the file
+ * creation property list \p plist_id.
+ *
+ * #H5F_fspace_strategy_t is a struct defined in H5Fpublic.h as
+ * follows:
+ *
+ * \snippet H5Fpublic.h H5F_fspace_strategy_t_snip
+ *
+ * This setting cannot be changed for the life of the file.
+ *
+ * As the #H5F_FSPACE_STRATEGY_AGGR and #H5F_FSPACE_STRATEGY_NONE
+ * strategies do not use the free-space managers, the \p persist
+ * and \p threshold settings will be ignored for those strategies.
+ *
+ * \since 1.10.1
+ *
+ */
+H5_DLL herr_t H5Pset_file_space_strategy(hid_t plist_id, H5F_fspace_strategy_t strategy, hbool_t persist, hsize_t threshold);
+/**
+ * \ingroup FCPL
+ *
+ * \brief Sets the size of the parameter used to control the B-trees for
+ * indexing chunked datasets
+ *
+ * \fcpl_id{plist_id}
+ * \param[in] ik 1/2 rank of chunked storage B-tree
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_istore_k() sets the size of the parameter used to
+ * control the B-trees for indexing chunked datasets. This
+ * function is valid only for file creation property lists.
+ *
+ * \p ik is one half the rank of a tree that stores chunked
+ * raw data. On average, such a tree will be 75% full, or have
+ * an average rank of 1.5 times the value of \p ik.
+ *
+ * The HDF5 library uses (\p ik*2) as the maximum # of entries
+ * before splitting a B-tree node. Since only 2 bytes are used
+ * in storing # of entries for a B-tree node in an HDF5 file,
+ * (\p ik*2) cannot exceed 65536. The default value for
+ * \p ik is 32.
+ *
+ * \version 1.6.4 \p ik parameter type changed to \p unsigned.
+ * \since 1.0.0
+ *
+ */
H5_DLL herr_t H5Pset_istore_k(hid_t plist_id, unsigned ik);
-H5_DLL herr_t H5Pget_istore_k(hid_t plist_id, unsigned *ik /*out*/);
+/**
+ * \ingroup FCPL
+ *
+ * \brief Configures the specified shared object header message index
+ *
+ * \fcpl_id{plist_id}
+ * \param[in] index_num Index being configured
+ * \param[in] mesg_type_flags Types of messages that should be stored in
+ * this index
+ * \param[in] min_mesg_size Minimum message size
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_shared_mesg_index() is used to configure the specified
+ * shared object header message index, setting the types of
+ * messages that may be stored in the index and the minimum size
+ * of each message.
+ *
+ * \p plist_id specifies the file creation property list.
+ *
+ * \p index_num specifies the index to be configured.
+ * \p index_num is zero-indexed, so in a file with three indexes,
+ * they will be numbered 0, 1, and 2.
+ *
+ * \p mesg_type_flags and \p min_mesg_size specify, respectively,
+ * the types and minimum size of messages that can be stored in
+ * this index.
+ *
+ * Valid message types are as follows:
+ *
+ * <table>
+ * <tr>
+ * <td>#H5O_SHMESG_NONE_FLAG</td>
+ * <td>No shared messages</td>
+ * </tr>
+ * <tr>
+ * <td>#H5O_SHMESG_SDSPACE_FLAG</td>
+ * <td>Simple dataspace message</td>
+ * </tr>
+ * <tr>
+ * <td>#H5O_SHMESG_DTYPE_FLAG</td>
+ * <td>Datatype message</td>
+ * </tr>
+ * <tr>
+ * <td>#H5O_SHMESG_FILL_FLAG</td>
+ * <td>Fill value message</td>
+ * </tr>
+ * <tr>
+ * <td>#H5O_SHMESG_PLINE_FLAG</td>
+ * <td>Filter pipeline message</td>
+ * </tr>
+ * <tr>
+ * <td>#H5O_SHMESG_ATTR_FLAG</td>
+ * <td>Attribute message</td>
+ * </tr>
+ * <tr>
+ * <td>#H5O_SHMESG_ALL_FLAG</td>
+ * <td>All message types; i.e., equivalent to the following:
+ * (#H5O_SHMESG_SDSPACE_FLAG | #H5O_SHMESG_DTYPE_FLAG |
+ * #H5O_SHMESG_FILL_FLAG | #H5O_SHMESG_PLINE_FLAG |
+ * #H5O_SHMESG_ATTR_FLAG)</td>
+ * </tr>
+ * </table>
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL herr_t H5Pset_shared_mesg_index(hid_t plist_id, unsigned index_num, unsigned mesg_type_flags, unsigned min_mesg_size);
+/**
+ * \ingroup FCPL
+ *
+ * \brief Sets number of shared object header message indexes
+ *
+ * \fcpl_id{plist_id}
+ * \param[in] nindexes Number of shared object header message indexes to be
+ * available in files created with this property list
+ * (\p nindexes must be <= #H5O_SHMESG_MAX_NINDEXES (8))
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_shared_mesg_nindexes() sets the number of shared object
+ * header message indexes in the specified file creation property
+ * list.
+ *
+ * This setting determines the number of shared object header
+ * message indexes, \p nindexes, that will be available in files
+ * created with this property list. These indexes can then be
+ * configured with H5Pset_shared_mesg_index().
+ *
+ * If \p nindexes is set to 0 (zero), shared object header messages
+ * are disabled in files created with this property list.
+ *
+ * There is a limit of #H5O_SHMESG_MAX_NINDEXES (8) that can be set
+ * with H5Pset_shared_mesg_nindexes(). An error will occur if
+ * specifying a value of \p nindexes that is greater than this value.
+ *
+ * \since 1.8.0
+ *
+ */
H5_DLL herr_t H5Pset_shared_mesg_nindexes(hid_t plist_id, unsigned nindexes);
-H5_DLL herr_t H5Pget_shared_mesg_nindexes(hid_t plist_id, unsigned *nindexes);
-H5_DLL herr_t H5Pset_shared_mesg_index(hid_t plist_id, unsigned index_num, unsigned mesg_type_flags,
- unsigned min_mesg_size);
-H5_DLL herr_t H5Pget_shared_mesg_index(hid_t plist_id, unsigned index_num, unsigned *mesg_type_flags,
- unsigned *min_mesg_size);
+/**
+ * \ingroup FCPL
+ *
+ * \brief Sets shared object header message storage phase change thresholds
+ *
+ * \fcpl_id{plist_id}
+ * \param[in] max_list Threshold above which storage of a shared object
+ * header message index shifts from list to B-tree
+ * \param[in] min_btree Threshold below which storage of a shared object
+ * header message index reverts to list format
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_shared_mesg_phase_change() sets threshold values for
+ * storage of shared object header message indexes in a file.
+ * These phase change thresholds determine the point at which the
+ * index storage mechanism changes from a more compact list format
+ * to a more performance-oriented B-tree format, and vice-versa.
+ *
+ * By default, a shared object header message index is initially
+ * stored as a compact list. When the number of messages in an
+ * index exceeds the threshold value of \p max_list, storage
+ * switches to a B-tree for improved performance. If the number
+ * of messages subsequently falls below the \p min_btree threshold,
+ * the index will revert to the list format.
+ *
+ * If \p max_list is set to 0 (zero), shared object header message
+ * indexes in the file will be created as B-trees and will never
+ * revert to lists.
+ *
+ * \p plist_id specifies the file creation property list.
+ *
+ * \since 1.8.0
+ *
+ */
H5_DLL herr_t H5Pset_shared_mesg_phase_change(hid_t plist_id, unsigned max_list, unsigned min_btree);
-H5_DLL herr_t H5Pget_shared_mesg_phase_change(hid_t plist_id, unsigned *max_list, unsigned *min_btree);
-H5_DLL herr_t H5Pset_file_space_strategy(hid_t plist_id, H5F_fspace_strategy_t strategy, hbool_t persist,
- hsize_t threshold);
-H5_DLL herr_t H5Pget_file_space_strategy(hid_t plist_id, H5F_fspace_strategy_t *strategy, hbool_t *persist,
- hsize_t *threshold);
-H5_DLL herr_t H5Pset_file_space_page_size(hid_t plist_id, hsize_t fsp_size);
-H5_DLL herr_t H5Pget_file_space_page_size(hid_t plist_id, hsize_t *fsp_size);
+/**
+ * \ingroup FCPL
+ *
+ * \brief Sets the byte size of the offsets and lengths used to address
+ * objects in an HDF5 file
+ *
+ * \fcpl_id{plist_id}
+ * \param[in] sizeof_addr Size of an object offset in bytes
+ * \param[in] sizeof_size Size of an object length in bytes
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_sizes() sets the byte size of the offsets and lengths
+ * used to address objects in an HDF5 file. This function is only
+ * valid for file creation property lists. Passing in a value
+ * of 0 for one of the parameters retains the current value. The
+ * default value for both values is the same as sizeof(hsize_t)
+ * in the library (normally 8 bytes). Valid values currently
+ * are 2, 4, 8 and 16.
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Pset_sizes(hid_t plist_id, size_t sizeof_addr,
+ size_t sizeof_size);
+/**
+ * \ingroup FCPL
+ *
+ * \brief
+ *
+ * \fcpl_id{plist_id}
+ * \param[in] ik Symbol table tree rank
+ * \param[in] lk Symbol table node size
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_sym_k() sets the size of parameters used to control the
+ * symbol table nodes.
+ *
+ * This function is valid only for file creation property lists.
+ * Passing in a value of zero (0) for one of the parameters retains
+ * the current value.
+ *
+ * \p ik is one half the rank of a B-tree that stores a symbol
+ * table for a group. Internal nodes of the symbol table are on
+ * average 75% full. That is, the average rank of the tree is
+ * 1.5 times the value of \p ik. The HDF5 library uses (\p ik*2) as
+ * the maximum # of entries before splitting a B-tree node. Since
+ * only 2 bytes are used in storing # of entries for a B-tree node
+ * in an HDF5 file, (\p ik*2) cannot exceed 65536. The default value
+ * for \p ik is 16.
+ *
+ * \p lk is one half of the number of symbols that can be stored in
+ * a symbol table node. A symbol table node is the leaf of a symbol
+ * table tree which is used to store a group. When symbols are
+ * inserted randomly into a group, the group's symbol table nodes are
+ * 75% full on average. That is, they contain 1.5 times the number of
+ * symbols specified by \p lk. The default value for \p lk is 4.
+ *
+ * \version 1.6.4 \p ik parameter type changed to \em unsigned.
+ * \version 1.6.0 The \p ik parameter has changed from type int to
+ * \em unsigned.
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Pset_sym_k(hid_t plist_id, unsigned ik, unsigned lk);
+/**
+ * \ingroup FCPL
+ *
+ * \brief Sets user block size
+ *
+ * \fcpl_id{plist_id}
+ * \param[in] size Size of the user-block in bytes
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_userblock() sets the user block size of a file creation
+ * property list. The default user block size is 0; it may be set
+ * to any power of 2 equal to 512 or greater (512, 1024, 2048, etc.).
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Pset_userblock(hid_t plist_id, hsize_t size);
/* File access property list (FAPL) routines */
-H5_DLL herr_t H5Pset_alignment(hid_t fapl_id, hsize_t threshold, hsize_t alignment);
-H5_DLL herr_t H5Pget_alignment(hid_t fapl_id, hsize_t *threshold /*out*/, hsize_t *alignment /*out*/);
-H5_DLL herr_t H5Pset_driver(hid_t plist_id, hid_t driver_id, const void *driver_info);
-H5_DLL hid_t H5Pget_driver(hid_t plist_id);
+/**
+ * \ingroup FAPL
+ *
+ * \brief Retrieves the current settings for alignment properties from a
+ * file access property list
+ *
+ * \fapl_id
+ * \param[out] threshold Pointer to location of return threshold value
+ * \param[out] alignment Pointer to location of return alignment value
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_alignment() retrieves the current settings for
+ * alignment properties from a file access property list. The
+ * \p threshold and/or \p alignment pointers may be null
+ * pointers (NULL).
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Pget_alignment(hid_t fapl_id, hsize_t *threshold/*out*/,
+ hsize_t *alignment/*out*/);
+/**
+ * \ingroup FAPL
+ *
+ * \brief Queries the raw data chunk cache parameters
+ *
+ * \fapl_id{plist_id}
+ * \param[in,out] mdc_nelmts <i>No longer used</i>
+ * \param[in,out] rdcc_nslots Number of elements (objects) in the raw data
+ * chunk cache
+ * \param[in,out] rdcc_nbytes Total size of the raw data chunk cache, in
+ * bytes
+ * \param[in,out] rdcc_w0 Preemption policy
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_cache() retrieves the maximum possible number of
+ * elements in the raw data chunk cache, the maximum possible
+ * number of bytes in the raw data chunk cache, and the
+ * preemption policy value.
+ *
+ * Any (or all) arguments may be null pointers, in which case
+ * the corresponding datum is not returned.
+ *
+ * Note that the \p mdc_nelmts parameter is no longer used.
+ *
+ * \version 1.8.0 Use of the \p mdc_nelmts parameter discontinued.
+ * Metadata cache configuration is managed with
+ * H5Pset_mdc_config() and H5Pget_mdc_config()
+ * \version 1.6.0 The \p rdcc_nbytes and \p rdcc_nslots parameters changed
+ * from type int to size_t.
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Pget_cache(hid_t plist_id,
+ int *mdc_nelmts, /* out */
+ size_t *rdcc_nslots/*out*/,
+ size_t *rdcc_nbytes/*out*/, double *rdcc_w0);
+/**
+ * \ingroup FAPL
+ *
+ * \brief Gets information about the write tracking feature used by
+ * the core VFD
+ *
+ * \fapl_id
+ * \param[out] is_enabled Whether the feature is enabled
+ * \param[out] page_size Size, in bytes, of write aggregation pages
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_core_write_tracking() retrieves information about the
+ * write tracking feature used by the core VFD.
+ *
+ * When a file is created or opened for writing using the core
+ * virtual file driver (VFD) with the backing store option turned
+ * on, the VFD can be configured to track changes to the file
+ * and only write out the modified bytes. To avoid a large number
+ * of small writes, the changes can be aggregated into pages of
+ * a user-specified size. The core VFD is also known as the
+ * memory VFD. The driver identifier is #H5FD_CORE.
+ *
+ * \note This function is only for use with the core VFD and must be used
+ * after the call to H5Pset_fapl_core(). It is an error to use this
+ * function with any other VFD.
+ *
+ * \note This function only applies to the backing store write operation
+ * which typically occurs when the file is flushed or closed. This
+ * function has no relationship to the increment parameter passed
+ * to H5Pset_fapl_core().
+ *
+ * \note For optimum performance, the \p page_size parameter should be
+ * a power of two.
+ *
+ * \since 1.8.13
+ *
+ */
+H5_DLL herr_t H5Pget_core_write_tracking(hid_t fapl_id, hbool_t *is_enabled, size_t *page_size);
+/**
+ * \ingroup FAPL
+ *
+ * \brief Returns low-lever driver identifier
+ *
+ * \plist_id
+ *
+ * \return \hid_t{low level driver}
+ *
+ * \details H5Pget_driver() returns the identifier of the low-level file
+ * driver associated with the file access property list or
+ * data transfer property list \p plist_id.
+ *
+ * Valid driver identifiers distributed with HDF5 are listed and
+ * described in the following table.
+ *
+ * <table>
+ * <tr>
+ * <th>Driver Name</th>
+ * <th>Driver Identifier</th>
+ * <th>Description</th>
+ * <th>Related Function</th>
+ * </tr>
+ * <tr>
+ * <td>POSIX</td>
+ * <td>#H5FD_SEC2</td>
+ * <td>This driver uses POSIX file-system functions like read and
+ * write to perform I/O to a single, permanent file on local disk
+ * with no system buffering. This driver is POSIX-compliant and is
+ * the default file driver for all systems.</td>
+ * <td>H5Pset_fapl_sec2()</td>
+ * </tr>
+ * <tr>
+ * <td>Direct</td>
+ * <td>#H5FD_DIRECT</td>
+ * <td>This is the #H5FD_SEC2 driver except data is written to or
+ * read from the file synchronously without being cached by the
+ * system.</td>
+ * <td>H5Pset_fapl_direct()</td>
+ * </tr>
+ * <tr>
+ * <td>Log</td>
+ * <td>#H5FD_LOG</td>
+ * <td>This is the #H5FD_SEC2 driver with logging capabilities.</td>
+ * <td>H5Pset_fapl_log()</td>
+ * </tr>
+ * <tr>
+ * <td>Windows</td>
+ * <td>#H5FD_WINDOWS</td>
+ * <td>This driver was modified in HDF5-1.8.8 to be a wrapper of the
+ * POSIX driver, #H5FD_SEC2. This change should not affect user
+ * applications.</td>
+ * <td>H5Pset_fapl_windows()</td>
+ * </tr>
+ * <tr>
+ * <td>STDIO</td>
+ * <td>#H5FD_STDIO</td>
+ * <td>This driver uses functions from the standard C stdio.h to
+ * perform I/O to a single, permanent file on local disk with
+ * additional system buffering.</td>
+ * <td>H5Pset_fapl_stdio()</td>
+ * </tr>
+ * <tr>
+ * <td>Memory</td>
+ * <td>#H5FD_CORE</td>
+ * <td>With this driver, an application can work with a file in
+ * memory for faster reads and writes. File contents are kept in
+ * memory until the file is closed. At closing, the memory version
+ * of the file can be written back to disk or abandoned.</td>
+ * <td>H5Pset_fapl_core()</td>
+ * </tr>
+ * <tr>
+ * <td>Family</td>
+ * <td>#H5FD_FAMILY</td>
+ * <td>With this driver, the HDF5 file’s address space is partitioned
+ * into pieces and sent to separate storage files using an
+ * underlying driver of the user’s choice. This driver is for
+ * systems that do not support files larger than 2 gigabytes.</td>
+ * <td>H5Pset_fapl_family()</td>
+ * </tr>
+ * <tr>
+ * <td>Multi</td>
+ * <td>#H5FD_MULTI</td>
+ * <td>With this driver, data can be stored in multiple files
+ * according to the type of the data. I/O might work better if
+ * data is stored in separate files based on the type of data.
+ * The Split driver is a special case of this driver.</td>
+ * <td>H5Pset_fapl_multi()</td>
+ * </tr>
+ * <tr>
+ * <td>Parallel</td>
+ * <td>#H5FD_MPIO</td>
+ * <td>This is the standard HDF5 file driver for parallel file
+ * systems. This driver uses the MPI standard for both
+ * communication and file I/O.</td>
+ * <td>H5Pset_fapl_mpio()</td>
+ * </tr>
+ * <tr>
+ * <td>Parallel POSIX</td>
+ * <td>H5FD_MPIPOSIX</td>
+ * <td>This driver is no longer available.</td>
+ * <td></td>
+ * </tr>
+ * <tr>
+ * <td>Stream</td>
+ * <td>H5FD_STREAM</td>
+ * <td>This driver is no longer available.</td>
+ * <td></td>
+ * </tr>
+ * </table>
+ *
+ * This list does not include custom drivers that might be
+ * defined and registered by a user.
+ *
+ * The returned driver identifier is only valid as long as the
+ * file driver remains registered.
+ *
+ *
+ * \since 1.4.0
+ *
+ */
+H5_DLL hid_t H5Pget_driver(hid_t plist_id);
+/**
+ * \ingroup FAPL
+ *
+ * \brief Returns a pointer to file driver information
+ *
+ * \param[in] plist_id File access or data transfer property list
+ * identifier
+ *
+ * \return Returns a pointer to a struct containing low-level driver
+ * information. Otherwise returns NULL. NULL is also returned if
+ * no driver-specific properties have been registered. No error
+ * is pushed on the stack in this case.
+ *
+ * \details H5Pget_driver_info() returns a pointer to file driver-specific
+ * information for the low-level driver associated with the file
+ * access or data transfer property list \p plist_id.
+ *
+ * The pointer returned by this function points to an “uncopied”
+ * struct. Driver-specific versions of that struct are defined
+ * for each low-level driver in the relevant source code file
+ * H5FD*.c. For example, the struct used for the MULTI driver is
+ * #H5FD_multi_fapl_t defined in H5FDmulti.c.
+ *
+ * If no driver-specific properties have been registered,
+ * H5Pget_driver_info() returns NULL.
+ *
+ * \note H5Pget_driver_info() and H5Pset_driver() are used only when
+ * creating a virtual file driver (VFD) in the virtual file
+ * layer (VFL).
+ *
+ * \version 1.10.1 Return value was changed from \em void * to
+ * \em const \em void *.
+ * \version 1.8.2 Function publicized in this release; previous releases
+ * described this function only in the virtual file driver
+ * documentation.
+ *
+ */
H5_DLL const void *H5Pget_driver_info(hid_t plist_id);
-H5_DLL herr_t H5Pset_vol(hid_t plist_id, hid_t new_vol_id, const void *new_vol_info);
-H5_DLL herr_t H5Pget_vol_id(hid_t plist_id, hid_t *vol_id);
-H5_DLL herr_t H5Pget_vol_info(hid_t plist_id, void **vol_info);
-H5_DLL herr_t H5Pset_family_offset(hid_t fapl_id, hsize_t offset);
-H5_DLL herr_t H5Pget_family_offset(hid_t fapl_id, hsize_t *offset);
-H5_DLL herr_t H5Pset_multi_type(hid_t fapl_id, H5FD_mem_t type);
-H5_DLL herr_t H5Pget_multi_type(hid_t fapl_id, H5FD_mem_t *type);
-H5_DLL herr_t H5Pset_cache(hid_t plist_id, int mdc_nelmts, size_t rdcc_nslots, size_t rdcc_nbytes,
- double rdcc_w0);
-H5_DLL herr_t H5Pget_cache(hid_t plist_id, int *mdc_nelmts, /* out */
- size_t *rdcc_nslots /*out*/, size_t *rdcc_nbytes /*out*/, double *rdcc_w0);
-H5_DLL herr_t H5Pset_mdc_config(hid_t plist_id, H5AC_cache_config_t *config_ptr);
-H5_DLL herr_t H5Pget_mdc_config(hid_t plist_id, H5AC_cache_config_t *config_ptr); /* out */
-H5_DLL herr_t H5Pset_gc_references(hid_t fapl_id, unsigned gc_ref);
-H5_DLL herr_t H5Pget_gc_references(hid_t fapl_id, unsigned *gc_ref /*out*/);
-H5_DLL herr_t H5Pset_fclose_degree(hid_t fapl_id, H5F_close_degree_t degree);
-H5_DLL herr_t H5Pget_fclose_degree(hid_t fapl_id, H5F_close_degree_t *degree);
-H5_DLL herr_t H5Pset_meta_block_size(hid_t fapl_id, hsize_t size);
-H5_DLL herr_t H5Pget_meta_block_size(hid_t fapl_id, hsize_t *size /*out*/);
-H5_DLL herr_t H5Pset_sieve_buf_size(hid_t fapl_id, size_t size);
-H5_DLL herr_t H5Pget_sieve_buf_size(hid_t fapl_id, size_t *size /*out*/);
-H5_DLL herr_t H5Pset_small_data_block_size(hid_t fapl_id, hsize_t size);
-H5_DLL herr_t H5Pget_small_data_block_size(hid_t fapl_id, hsize_t *size /*out*/);
-H5_DLL herr_t H5Pset_libver_bounds(hid_t plist_id, H5F_libver_t low, H5F_libver_t high);
-H5_DLL herr_t H5Pget_libver_bounds(hid_t plist_id, H5F_libver_t *low, H5F_libver_t *high);
+H5_DLL herr_t H5Pget_elink_file_cache_size(hid_t plist_id, unsigned *efc_size);
+H5_DLL herr_t H5Pget_evict_on_close(hid_t fapl_id, hbool_t *evict_on_close);
+/**
+ * \ingroup FAPL
+ *
+ * \brief Retrieves a data offset from the file access property list
+ *
+ * \fapl_id
+ * \param[out] offset Offset in bytes within the HDF5 file
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_family_offset() retrieves the value of offset from the
+ * file access property list \p fapl_id so that the user
+ * application can retrieve a file handle for low-level access to
+ * a particular member of a family of files. The file handle is
+ * retrieved with a separate call to H5Fget_vfd_handle() (or,
+ * in special circumstances, to H5FDget_vfd_handle()).
+ *
+ * \todo References the VFL documentation.
+ *
+ * \since 1.6.0
+ *
+ */
+H5_DLL herr_t H5Pget_family_offset(hid_t fapl_id, hsize_t *offset);
+/**
+ * \ingroup FAPL
+ *
+ * \brief Returns the file close degree
+ *
+ * \fapl_id
+ * \param[out] degree Pointer to a location to which to return the file
+ * close degree property, the value of \p degree
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_fclose_degree() returns the current setting of the file
+ * close degree property \p degree in the file access property
+ * list \p fapl_id. The value of \p degree determines how
+ * aggressively H5Fclose() deals with objects within a file that
+ * remain open when H5Fclose() is called to close that file.
+ *
+ * \since 1.6.0
+ *
+ */
+H5_DLL herr_t H5Pget_fclose_degree(hid_t fapl_id, H5F_close_degree_t *degree);
+H5_DLL herr_t H5Pget_file_image(hid_t fapl_id, void **buf_ptr_ptr, size_t *buf_len_ptr);
+H5_DLL herr_t H5Pget_file_image_callbacks(hid_t fapl_id,
+ H5FD_file_image_callbacks_t *callbacks_ptr);
+H5_DLL herr_t H5Pget_file_locking(hid_t fapl_id, hbool_t *use_file_locking, hbool_t *ignore_when_disabled);
+/**
+ * \ingroup FAPL
+ *
+ * \brief Returns garbage collecting references setting
+ *
+ * \fapl_id
+ * \param[out] gc_ref Flag returning the state of reference garbage
+ * collection. A returned value of 1 indicates that
+ * garbage collection is on while 0 indicates that
+ * garbage collection is off.
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_gc_references() returns the current setting for the
+ * garbage collection references property from the specified
+ * file access property list. The garbage collection references
+ * property is set by H5Pset_gc_references().
+ *
+ * \since 1.2.0
+ *
+ */
+H5_DLL herr_t H5Pget_gc_references(hid_t fapl_id, unsigned *gc_ref/*out*/);
+/**
+ * \ingroup FAPL
+ *
+ * \brief Retrieves library version bounds settings that indirectly control
+ * the format versions used when creating objects
+ *
+ * \fapl_id{plist_id}
+ * \param[out] low The earliest version of the library that will be used
+ * for writing objects
+ * \param[out] high The latest version of the library that will be used for
+ * writing objects
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_libver_bounds() retrieves the lower and upper bounds on
+ * the HDF5 library release versions that indirectly determine the
+ * object format versions used when creating objects in the file.
+ *
+ * This property is retrieved from the file access property list
+ * specified by the parameter \p fapl_id.
+ *
+ * The value returned in the parameters \p low and \p high is one
+ * of the enumerated values in the #H5F_libver_t struct, which is
+ * defined in H5Fpublic.h.
+ *
+ * \version 1.10.2 Add #H5F_LIBVER_V18 to the enumerated defines in
+ * #H5F_libver_t
+ * \since 1.8.0
+ *
+ */
+H5_DLL herr_t H5Pget_libver_bounds(hid_t plist_id, H5F_libver_t *low,
+ H5F_libver_t *high);
+H5_DLL herr_t H5Pget_mdc_config(hid_t plist_id,
+ H5AC_cache_config_t * config_ptr); /* out */
+H5_DLL herr_t H5Pget_mdc_image_config(hid_t plist_id, H5AC_cache_image_config_t *config_ptr /*out*/);
+H5_DLL herr_t H5Pget_mdc_log_options(hid_t plist_id, hbool_t *is_enabled, char *location, size_t *location_size, hbool_t *start_on_access);
+H5_DLL herr_t H5Pget_meta_block_size(hid_t fapl_id, hsize_t *size/*out*/);
+H5_DLL herr_t H5Pget_metadata_read_attempts(hid_t plist_id, unsigned *attempts);
+/**
+ * \ingroup FAPL
+ *
+ * \brief Retrieves type of data property for MULTI driver
+ *
+ * \param[in] fapl_id File access property list or data transfer property
+ * list identifier
+ * \param[out] type Type of data
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_multi_type() retrieves the type of data setting from
+ * the file access or data transfer property list \p fapl_id.
+ * This enables a user application to specify the type of data
+ * the application wishes to access so that the application can
+ * retrieve a file handle for low-level access to the particular
+ * member of a set of MULTI files in which that type of data is
+ * stored. The file handle is retrieved with a separate call to
+ * H5Fget_vfd_handle() (or, in special circumstances, to
+ * H5FDget_vfd_handle(); see the Virtual File Layer documentation
+ * for more information.
+ *
+ * The type of data returned in \p type will be one of those
+ * listed in the discussion of the \p type parameter in the the
+ * description of the function H5Pset_multi_type().
+ *
+ * Use of this function is only appropriate for an HDF5 file
+ * written as a set of files with the MULTI file driver.
+ *
+ * \since 1.6.0
+ *
+ */
+H5_DLL herr_t H5Pget_multi_type(hid_t fapl_id, H5FD_mem_t *type);
+H5_DLL herr_t H5Pget_object_flush_cb(hid_t plist_id, H5F_flush_cb_t *func, void **udata);
+H5_DLL herr_t H5Pget_page_buffer_size(hid_t plist_id, size_t *buf_size, unsigned *min_meta_per, unsigned *min_raw_per);
+H5_DLL herr_t H5Pget_sieve_buf_size(hid_t fapl_id, size_t *size/*out*/);
+H5_DLL herr_t H5Pget_small_data_block_size(hid_t fapl_id, hsize_t *size/*out*/);
+/**
+ * \ingroup FAPL
+ *
+ * \brief Returns the identifier of the current VOL connector
+ *
+ * \fapl_id{plist_id}
+ * \param[out] vol_id Current VOL connector identifier
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_vol_id() returns the VOL connector identifier \p vol_id for
+ * the file access property list \p plist_id. This identifier should
+ * be closed with H5VLclose().
+ *
+ * \since 1.12.0
+ *
+ */
+H5_DLL herr_t H5Pget_vol_id(hid_t plist_id, hid_t *vol_id);
+/**
+ * \ingroup FAPL
+ *
+ * \brief Returns a copy of the VOL information for a connector
+ *
+ * \fapl_id{plist_id}
+ * \param[out] vol_info The VOL information for a connector
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_vol_info() returns a copy of the VOL information \p vol_info
+ * for a connector specified by the file access property list
+ * \p plist_id.
+ *
+ * \since 1.12.0
+ *
+ */
+H5_DLL herr_t H5Pget_vol_info(hid_t plist_id, void **vol_info);
+/**
+ * \ingroup FAPL
+ *
+ * \brief Sets alignment properties of a file access property list
+ *
+ * \fapl_id
+ * \param[in] threshold Threshold value. Note that setting the threshold
+ * value to 0 (zero) has the effect of a special case,
+ * forcing everything to be aligned
+ * \param[in] alignment Alignment value
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_alignment() sets the alignment properties of a
+ * file access property list so that any file object greater
+ * than or equal in size to \p threshold bytes will be aligned
+ * on an address which is a multiple of \p alignment. The
+ * addresses are relative to the end of the user block; the
+ * alignment is calculated by subtracting the user block size
+ * from the absolute file address and then adjusting the address
+ * to be a multiple of \p alignment.
+ *
+ * Default values for \p threshold and \p alignment are one,
+ * implying no alignment. Generally the default values will
+ * result in the best performance for single-process access to
+ * the file. For MPI IO and other parallel systems, choose an
+ * alignment which is a multiple of the disk block size.
+ *
+ * If the file space handling strategy is set to
+ * #H5F_FSPACE_STRATEGY_PAGE, then the alignment set via this
+ * routine is ignored. The file space handling strategy is set
+ * by H5Pset_file_space_strategy().
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Pset_alignment(hid_t fapl_id, hsize_t threshold,
+ hsize_t alignment);
+/**
+ * \ingroup FAPL
+ *
+ * \brief Sets the raw data chunk cache parameters
+ *
+ * \fapl_id{plist_id}
+ * \param[in] mdc_nelmts No longer used; any value passed is ignored
+ * \param[in] rdcc_nslots The number of chunk slots in the raw data chunk
+ * cache for this dataset. Increasing this value
+ * reduces the number of cache collisions, but
+ * slightly increases the memory used. Due to the
+ * hashing strategy, this value should ideally be a
+ * prime number. As a rule of thumb, this value
+ * should be at least 10 times the number of chunks
+ * that can fit in \p rdcc_nbytes bytes. For
+ * maximum performance, this value should be set
+ * approximately 100 times that number of chunks.
+ * The default value is 521.
+ * \param[in] rdcc_nbytes Total size of the raw data chunk cache in bytes.
+ * The default size is 1 MB per dataset.
+ * \param[in] rdcc_w0 The chunk preemption policy for all datasets.
+ * This must be between 0 and 1 inclusive and
+ * indicates the weighting according to which chunks
+ * which have been fully read or written are
+ * penalized when determining which chunks to flush
+ * from cache. A value of 0 means fully read or
+ * written chunks are treated no differently than
+ * other chunks (the preemption is strictly LRU)
+ * while a value of 1 means fully read or written
+ * chunks are always preempted before other chunks.
+ * If your application only reads or writes data once,
+ * this can be safely set to 1. Otherwise, this should
+ * be set lower depending on how often you re-read or
+ * re-write the same data. The default value is 0.75.
+ * If the value passed is #H5D_CHUNK_CACHE_W0_DEFAULT,
+ * then the property will not be set on the dataset
+ * access property list, and the parameter will come
+ * from the file access property list.
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_cache() sets the number of elements, the total number of
+ * bytes, and the preemption policy value for all datasets in a file
+ * on the file’s file access property list.
+ *
+ * The raw data chunk cache inserts chunks into the cache by first
+ * computing a hash value using the address of a chunk and then by
+ * using that hash value as the chunk’s index into the table of
+ * cached chunks. In other words, the size of this hash table and the
+ * number of possible hash values is determined by the \p rdcc_nslots
+ * parameter. If a different chunk in the cache has the same hash value,
+ * a collision will occur, which will reduce efficiency. If inserting
+ * the chunk into the cache would cause the cache to be too big, then
+ * the cache will be pruned according to the \p rdcc_w0 parameter.
+ *
+ * The \p mdc_nelmts parameter is no longer used; any value passed
+ * in that parameter will be ignored.
+ *
+ * \note \b Motivation: Setting raw data chunk cache parameters
+ * can be done with H5Pset_cache(), H5Pset_chunk_cache(),
+ * or a combination of both. H5Pset_cache() is used to
+ * adjust the chunk cache parameters for all datasets via
+ * a global setting for the file, and H5Pset_chunk_cache()
+ * is used to adjust the chunk cache parameters for
+ * individual datasets. When both are used, parameters
+ * set with H5Pset_chunk_cache() will override any parameters
+ * set with H5Pset_cache().
+ *
+ * \note Optimum chunk cache parameters may vary widely depending
+ * on different data layout and access patterns. For datasets
+ * with low performance requirements for example, changing
+ * the cache settings can save memory.
+ *
+ * \note Note: Raw dataset chunk caching is not currently
+ * supported when using the MPI I/O and MPI POSIX file drivers
+ * in read/write mode; see H5Pset_fapl_mpio() and
+ * H5Pset_fapl_mpiposix(), respectively. When using one of these
+ * file drivers, all calls to H5Dread() and H5Dwrite() will access
+ * the disk directly, and H5Pset_cache() will have no effect on
+ * performance.
+ *
+ * \note Raw dataset chunk caching is supported when these drivers are
+ * used in read-only mode.
+ *
+ * \todo Check on H5Pset_fapl_mpio() and H5Pset_fapl_mpiposix().
+ *
+ * \version 1.8.0 The use of the \p mdc_nelmts parameter was discontinued.
+ * Metadata cache configuration is managed with
+ * H5Pset_mdc_config() and H5Pget_mdc_config().
+ * \version 1.6.0 The \p rdcc_nbytes and \p rdcc_nelmts parameters
+ * changed from type int to size_t.
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Pset_cache(hid_t plist_id, int mdc_nelmts,
+ size_t rdcc_nslots, size_t rdcc_nbytes,
+ double rdcc_w0);
+H5_DLL herr_t H5Pset_core_write_tracking(hid_t fapl_id, hbool_t is_enabled, size_t page_size);
+/**
+ * \ingroup FAPL
+ *
+ * \brief Sets a file driver
+ *
+ * \plist_id
+ * \param[in] driver_id The new driver identifier
+ * \param[in] driver_info Optional struct containing driver properties
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_driver() sets the file driver, driver_id, for a file
+ * access or data transfer property list, \p plist_id, and
+ * supplies an optional struct containing the driver-specific
+ * properties, \p driver_info.
+ *
+ * The driver properties will be copied into the property list
+ * and the reference count on the driver will be incremented,
+ * allowing the caller to close the driver identifier but still
+ * use the property list.
+ *
+ * \version 1.8.2 Function publicized in this release; previous releases
+ * described this function only in the virtual file driver
+ * documentation.
+ *
+ */
+H5_DLL herr_t H5Pset_driver(hid_t plist_id, hid_t driver_id,
+ const void *driver_info);
H5_DLL herr_t H5Pset_elink_file_cache_size(hid_t plist_id, unsigned efc_size);
-H5_DLL herr_t H5Pget_elink_file_cache_size(hid_t plist_id, unsigned *efc_size);
+H5_DLL herr_t H5Pset_evict_on_close(hid_t fapl_id, hbool_t evict_on_close);
+H5_DLL herr_t H5Pset_family_offset(hid_t fapl_id, hsize_t offset);
+/**
+ * \ingroup FAPL
+ *
+ * \brief Sets the file close degree
+ *
+ * \fapl_id
+ * \param[in] degree Pointer to a location containing the file close
+ * degree property, the value of \p degree
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_fclose_degree() sets the file close degree property
+ * \p degree in the file access property list \p fapl_id.
+ *
+ * The value of \p degree determines how aggressively
+ * H5Fclose() deals with objects within a file that remain open
+ * when H5Fclose() is called to close that file. \p degree can
+ * have any one of four valid values:
+ *
+ * <table>
+ * <tr>
+ * <th>Degree name</th>
+ * <th>H5Fclose behavior with no open object in file</th>
+ * <th>H5Fclose behavior with open object(s) in file</th>
+ * </tr>
+ * <tr>
+ * <td>#H5F_CLOSE_WEAK</td>
+ * <td>Actual file is closed.</td>
+ * <td>Access to file identifier is terminated; actual file
+ * close is delayed until all objects in file are closed
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>#H5F_CLOSE_SEMI</td>
+ * <td>Actual file is closed.</td>
+ * <td>Function returns FAILURE</td>
+ * </tr>
+ * <tr>
+ * <td>#H5F_CLOSE_STRONG</td>
+ * <td>Actual file is closed.</td>
+ * <td>All open objects remaining in the file are closed then
+ * file is closed</td>
+ * </tr>
+ * <tr>
+ * <td>#H5F_CLOSE_DEFAULT</td>
+ * <td>The VFL driver chooses the behavior. Currently, all VFL
+ * drivers set this value to #H5F_CLOSE_WEAK, except for the
+ * MPI-I/O driver, which sets it to #H5F_CLOSE_SEMI.</td>
+ * <td></td>
+ * </tr>
+ *
+ * </table>
+ * \warning If a file is opened multiple times without being closed, each
+ * open operation must use the same file close degree setting.
+ * For example, if a file is already open with #H5F_CLOSE_WEAK,
+ * an H5Fopen() call with #H5F_CLOSE_STRONG will fail.
+ *
+ * \since 1.6.0
+ *
+ */
+H5_DLL herr_t H5Pset_fclose_degree(hid_t fapl_id, H5F_close_degree_t degree);
H5_DLL herr_t H5Pset_file_image(hid_t fapl_id, void *buf_ptr, size_t buf_len);
-H5_DLL herr_t H5Pget_file_image(hid_t fapl_id, void **buf_ptr_ptr, size_t *buf_len_ptr);
H5_DLL herr_t H5Pset_file_image_callbacks(hid_t fapl_id, H5FD_file_image_callbacks_t *callbacks_ptr);
-H5_DLL herr_t H5Pget_file_image_callbacks(hid_t fapl_id, H5FD_file_image_callbacks_t *callbacks_ptr);
-H5_DLL herr_t H5Pset_core_write_tracking(hid_t fapl_id, hbool_t is_enabled, size_t page_size);
-H5_DLL herr_t H5Pget_core_write_tracking(hid_t fapl_id, hbool_t *is_enabled, size_t *page_size);
-H5_DLL herr_t H5Pset_metadata_read_attempts(hid_t plist_id, unsigned attempts);
-H5_DLL herr_t H5Pget_metadata_read_attempts(hid_t plist_id, unsigned *attempts);
-H5_DLL herr_t H5Pset_object_flush_cb(hid_t plist_id, H5F_flush_cb_t func, void *udata);
-H5_DLL herr_t H5Pget_object_flush_cb(hid_t plist_id, H5F_flush_cb_t *func, void **udata);
+H5_DLL herr_t H5Pset_file_locking(hid_t fapl_id, hbool_t use_file_locking, hbool_t ignore_when_disabled);
+H5_DLL herr_t H5Pset_gc_references(hid_t fapl_id, unsigned gc_ref);
+/**
+ * \ingroup FAPL
+ *
+ * \brief Controls the range of library release versions used when creating
+ * objects in a file
+ *
+ * \fapl_id{plist_id}
+ * \param[in] low The earliest version of the library that will be used
+ * for writing objects
+ * \param[in] high The latest version of the library that will be used for
+ * writing objects
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_libver_bounds() controls the range of library release
+ * versions that will be used when creating objects in a file.
+ * The object format versions are determined indirectly from the
+ * library release versions specified in the call.
+ *
+ * This property is set in the file access property list
+ * specified by the parameter \p fapl_id.
+ *
+ * The parameter \p low sets the earliest possible format
+ * versions that the library will use when creating objects in
+ * the file. Note that earliest possible is different from
+ * earliest, as some features introduced in library versions
+ * later than 1.0.0 resulted in updates to object formats.
+ * The parameter \p high sets the latest format versions that
+ * the library will be allowed to use when creating objects in
+ * the file.
+ *
+ * The parameters \p low and \p high must be one of the
+ * enumerated values in the #H5F_libver_t struct, which is
+ * defined in H5Fpublic.h.
+ *
+ * The macro #H5F_LIBVER_LATEST is aliased to the highest
+ * enumerated value in #H5F_libver_t, indicating that this is
+ * currently the latest format available.
+ *
+ * The library supports the following five pairs of
+ * (\p low, \p high) combinations as derived from the values
+ * in #H5F_libver_t:
+ *
+ * <table>
+ * <tr>
+ * <th>Value of \p low and \p high</th>
+ * <th>Result</th>
+ * </tr>
+ * <tr>
+ * <td>\p low=#H5F_LIBVER_EARLIEST<br />
+ * \p high=#H5F_LIBVER_V18</td>
+ * <td>
+ * \li The library will create objects with the earliest
+ * possible format versions.
+ * \li The library will allow objects to be created with the
+ * latest format versions available to library release 1.8.x.
+ * \li API calls that create objects or features that are
+ * available to versions of the library greater than 1.8.x
+ * release will fail.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>\p low=#H5F_LIBVER_EARLIEST<br />
+ * \p high=#H5F_LIBVER_V110</td>
+ * <td>
+ * \li The library will create objects with the earliest possible
+ * format versions.
+ * \li The library will allow objects to be created with the latest
+ * format versions available to library release 1.10.x.
+ * Since 1.10.x is also #H5F_LIBVER_LATEST, there is no upper
+ * limit on the format versions to use. For example, if a newer
+ * format version is required to support a feature e.g. virtual
+ * dataset, this setting will allow the object to be created.
+ * \li This is the library default setting and provides the greatest
+ * format compatibility.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>\p low=#H5F_LIBVER_V18<br />
+ * \p high=#H5F_LIBVER_V18</td>
+ * <td>
+ * \li The library will create objects with the latest format versions
+ * available to library release 1.8.x.
+ * \li API calls that create objects or features that are available
+ * to versions of the library greater than 1.8.x release will fail.
+ * \li Earlier versions of the library may not be able to access
+ * objects created with this setting.</td>
+ * </tr>
+ * <tr>
+ * <td>\p low=#H5F_LIBVER_V18<br />
+ * \p high=#H5F_LIBVER_V110</td>
+ * <td>
+ * \li The library will create objects with the latest format versions
+ * available to library release 1.8.x.
+ * \li The library will allow objects to be created with the latest
+ * format versions available to library release 1.10.x.
+ * Since 1.10.x is also #H5F_LIBVER_LATEST, there is no upper limit
+ * on the format versions to use. For example, if a newer format
+ * version is required to support a feature e.g. virtual dataset,
+ * this setting will allow the object to be created.
+ * \li Earlier versions of the library may not be able to access
+ * objects created with this setting.</td>
+ * </tr>
+ * <tr>
+ * <td>\p low=#H5F_LIBVER_V110<br />
+ * \p high=#H5F_LIBVER_V110
+ * </td>
+ * <td>
+ * \li The library will create objects with the latest format versions
+ * available to library release 1.10.x.
+ * \li The library will allow objects to be created with the latest
+ * format versions available to library release 1.10.x.
+ * Since 1.10.x is also #H5F_LIBVER_LATEST, there is no upper limit
+ * on the format versions to use. For example, if a newer format
+ * version is required to support a feature e.g. virtual dataset,
+ * this setting will allow the object to be created.
+ * \li This setting allows users to take advantage of the latest
+ * features and performance enhancements in the library. However,
+ * objects written with this setting may be accessible to a smaller
+ * range of library versions than would be the case if low is set
+ * to #H5F_LIBVER_EARLIEST.
+ * \li Earlier versions of the library may not be able to access objects created with this setting.
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * \version 1.10.2 #H5F_LIBVER_V18 added to the enumerated defines in #H5F_libver_t.
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL herr_t H5Pset_libver_bounds(hid_t plist_id, H5F_libver_t low,
+ H5F_libver_t high);
+H5_DLL herr_t H5Pset_mdc_config(hid_t plist_id, H5AC_cache_config_t *config_ptr);
H5_DLL herr_t H5Pset_mdc_log_options(hid_t plist_id, hbool_t is_enabled, const char *location,
hbool_t start_on_access);
-H5_DLL herr_t H5Pget_mdc_log_options(hid_t plist_id, hbool_t *is_enabled, char *location,
- size_t *location_size, hbool_t *start_on_access);
-H5_DLL herr_t H5Pset_evict_on_close(hid_t fapl_id, hbool_t evict_on_close);
-H5_DLL herr_t H5Pget_evict_on_close(hid_t fapl_id, hbool_t *evict_on_close);
-H5_DLL herr_t H5Pset_file_locking(hid_t fapl_id, hbool_t use_file_locking, hbool_t ignore_when_disabled);
-H5_DLL herr_t H5Pget_file_locking(hid_t fapl_id, hbool_t *use_file_locking, hbool_t *ignore_when_disabled);
+H5_DLL herr_t H5Pset_meta_block_size(hid_t fapl_id, hsize_t size);
+H5_DLL herr_t H5Pset_metadata_read_attempts(hid_t plist_id, unsigned attempts);
+H5_DLL herr_t H5Pset_multi_type(hid_t fapl_id, H5FD_mem_t type);
+H5_DLL herr_t H5Pset_object_flush_cb(hid_t plist_id, H5F_flush_cb_t func, void *udata);
+H5_DLL herr_t H5Pset_sieve_buf_size(hid_t fapl_id, size_t size);
+H5_DLL herr_t H5Pset_small_data_block_size(hid_t fapl_id, hsize_t size);
+/**
+ * \ingroup FAPL
+ *
+ * \brief Set the file VOL connector for a file access property list
+ *
+ * \fapl_id{plist_id}
+ * \param[in] new_vol_id VOL connector identifier
+ * \param[in] new_vol_info Optional VOL information
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_vol() sets the VOL connector \p new_vol_id for a file access
+ * property list \p plist_id using the (optional) VOL information in
+ * \p new_vol_info.
+ *
+ * \since 1.12.0
+ *
+ */
+H5_DLL herr_t H5Pset_vol(hid_t plist_id, hid_t new_vol_id, const void *new_vol_info);
+
#ifdef H5_HAVE_PARALLEL
H5_DLL herr_t H5Pset_all_coll_metadata_ops(hid_t plist_id, hbool_t is_collective);
H5_DLL herr_t H5Pget_all_coll_metadata_ops(hid_t plist_id, hbool_t *is_collective);
@@ -578,14 +3967,92 @@ H5_DLL herr_t H5Pget_mpi_params(hid_t fapl_id, MPI_Comm *comm, MPI_Info *info);
H5_DLL herr_t H5Pset_mpi_params(hid_t fapl_id, MPI_Comm comm, MPI_Info info);
#endif /* H5_HAVE_PARALLEL */
H5_DLL herr_t H5Pset_mdc_image_config(hid_t plist_id, H5AC_cache_image_config_t *config_ptr);
-H5_DLL herr_t H5Pget_mdc_image_config(hid_t plist_id, H5AC_cache_image_config_t *config_ptr /*out*/);
H5_DLL herr_t H5Pset_page_buffer_size(hid_t plist_id, size_t buf_size, unsigned min_meta_per,
unsigned min_raw_per);
-H5_DLL herr_t H5Pget_page_buffer_size(hid_t plist_id, size_t *buf_size, unsigned *min_meta_per,
- unsigned *min_raw_per);
/* Dataset creation property list (DCPL) routines */
-
+/**
+ * \ingroup DCPL
+ *
+ * \brief Determines whether fill value is defined
+ *
+ * \dcpl_id{plist}
+ * \param[out] status Status of fill value in property list
+ *
+ * \return \herr_t
+ *
+ * \details H5Pfill_value_defined() determines whether a fill value is
+ * defined in the dataset creation property list \p plist. Valid
+ * values returned in status are as follows:
+ *
+ * <table>
+ * <tr>
+ * <td>#H5D_FILL_VALUE_UNDEFINED</td>
+ * <td>Fill value is undefined.</td>
+ * </tr>
+ * <tr>
+ * <td>#H5D_FILL_VALUE_DEFAULT</td>
+ * <td>Fill value is the library default.</td>
+ * </tr>
+ * <tr>
+ * <td>#H5D_FILL_VALUE_USER_DEFINED</td>
+ * <td>Fill value is defined by the application.</td>
+ * </tr>
+ * </table>
+ *
+ * \since 1.6.0
+ *
+ */
+H5_DLL herr_t H5Pfill_value_defined(hid_t plist, H5D_fill_value_t *status);
+/**
+ * \ingroup DCPL
+ *
+ * \brief Retrieves the timing for storage space allocation
+ *
+ * \dcpl_id{plist_id}
+ * \param[out] alloc_time The timing setting for allocating dataset
+ * storage space
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_alloc_time() retrieves the timing for allocating storage
+ * space for a dataset's raw data. This property is set in the
+ * dataset creation property list \p plist_id. The timing setting
+ * is returned in \p alloc_time as one of the following values:
+ *
+ * <table>
+ * <tr>
+ * <td>#H5D_ALLOC_TIME_DEFAULT<br />&nbsp;</td>
+ * <td>Uses the default allocation time, based on the dataset
+ * storage method. <br />See the \p alloc_time description in
+ * H5Pset_alloc_time() for default allocation times for
+ * various storage methods.</td>
+ * </tr>
+ * <tr>
+ * <td>#H5D_ALLOC_TIME_EARLY</td>
+ * <td>All space is allocated when the dataset is created.</td>
+ * </tr>
+ * <tr>
+ * <td>#H5D_ALLOC_TIME_INCR</td>
+ * <td>Space is allocated incrementally as data is written
+ * to the dataset.</td>
+ * </tr>
+ * <tr>
+ * <td>#H5D_ALLOC_TIME_LATE</td>
+ * <td>All space is allocated when data is first written to
+ * the dataset.</td>
+ * </tr>
+ * </table>
+ *
+ * \note H5Pget_alloc_time() is designed to work in concert with the
+ * dataset fill value and fill value write time properties, set
+ * with the functions H5Pget_fill_value() and H5Pget_fill_time().
+ *
+ * \since 1.6.0
+ *
+ */
+H5_DLL herr_t H5Pget_alloc_time(hid_t plist_id, H5D_alloc_time_t
+ *alloc_time/*out*/);
/**
* \ingroup DCPL
*
@@ -607,9 +4074,8 @@ H5_DLL herr_t H5Pget_page_buffer_size(hid_t plist_id, size_t *buf_size, unsigned
* \since 1.0.0
*
*/
-H5_DLL int H5Pget_chunk(hid_t plist_id, int max_ndims, hsize_t dim[] /*out*/);
+H5_DLL int H5Pget_chunk(hid_t plist_id, int max_ndims, hsize_t dim[]/*out*/);
/**
- *-------------------------------------------------------------------------
*
* \ingroup DCPL
*
@@ -636,8 +4102,81 @@ H5_DLL int H5Pget_chunk(hid_t plist_id, int max_ndims, hsize_t dim[] /*out*/);
*/
H5_DLL herr_t H5Pget_chunk_opts(hid_t plist_id, unsigned *opts);
/**
- *-------------------------------------------------------------------------
+ * \ingroup DCPL
+ *
+ * \brief Retrieves the setting for whether or not to create minimized
+ * dataset object headers
+ *
+ * \dcpl_id
+ * \param[out] minimize Flag indicating whether the library will or will
+ * not create minimized dataset object headers
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_dset_no_attrs_hint() retrieves the
+ * <i>no dataset attributes</i> hint setting for the dataset
+ * creation property list \p dcpl_id. This setting is used to
+ * inform the library to create minimized dataset object headers
+ * when TRUE. The setting value is returned in the boolean pointer
+ * \p minimize.
+ *
+ * \since 1.10.5
+ *
+ */
+H5_DLL herr_t H5Pget_dset_no_attrs_hint(hid_t dcpl_id, hbool_t *minimize);
+/**
+ * \ingroup DCPL
+ *
+ * \brief Returns information about an external file
+ *
+ * \dcpl_id{plist_id}
+ * \param[in] idx External file index
+ * \param[in] name_size Maximum length of \p name array
+ * \param[out] name Name of the external file
+ * \param[out] offset Pointer to a location to return an offset value
+ * \param[out] size Pointer to a location to return the size of the
+ * external file data
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_external() returns information about an external file.
+ * The external file is specified by its index, \p idx, which
+ * is a number from zero to N-1, where N is the value returned
+ * by H5Pget_external_count(). At most \p name_size characters
+ * are copied into the \p name array. If the external file name
+ * is longer than \p name_size with the null terminator, the
+ * return value is not null terminated (similar to strncpy()).
+ *
+ * If \p name_size is zero or \p name is the null pointer, the
+ * external file name is not returned. If \p offset or \p size
+ * are null pointers then the corresponding information is not
+ * returned.
+ *
+ * \version 1.6.4 \p idx parameter type changed to unsigned.
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Pget_external(hid_t plist_id, unsigned idx, size_t name_size,
+ char *name/*out*/, off_t *offset/*out*/,
+ hsize_t *size/*out*/);
+/**
+ * \ingroup DCPL
+ *
+ * \brief Returns the number of external files for a dataset
+ *
+ * \dcpl_id{plist_id}
+ *
+ * \return Returns the number of external files if successful; otherwise
+ * returns a negative value.
*
+ * \details H5Pget_external_count() returns the number of external files
+ * for the specified dataset.
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL int H5Pget_external_count(hid_t plist_id);
+/**
* \ingroup DCPL
*
* \brief Retrieves the time when fill values are written to a dataset
@@ -680,10 +4219,9 @@ H5_DLL herr_t H5Pget_chunk_opts(hid_t plist_id, unsigned *opts);
* \since 1.6.0
*
*/
-H5_DLL herr_t H5Pget_fill_time(hid_t plist_id, H5D_fill_time_t *fill_time /*out*/);
+H5_DLL herr_t H5Pget_fill_time(hid_t plist_id, H5D_fill_time_t
+ *fill_time/*out*/);
/**
- *-------------------------------------------------------------------------
- *
* \ingroup DCPL
*
* \brief Retrieves a dataset fill value
@@ -719,9 +4257,9 @@ H5_DLL herr_t H5Pget_fill_time(hid_t plist_id, H5D_fill_time_t *fill_time /*out*
* \since 1.0.0
*
*/
-H5_DLL herr_t H5Pget_fill_value(hid_t plist_id, hid_t type_id, void *value /*out*/);
+H5_DLL herr_t H5Pget_fill_value(hid_t plist_id, hid_t type_id,
+ void *value/*out*/);
/**
- *-------------------------------------------------------------------------
* \ingroup DCPL
*
* \brief Returns the layout of the raw data for a dataset
@@ -757,7 +4295,224 @@ H5_DLL herr_t H5Pget_fill_value(hid_t plist_id, hid_t type_id, void *value /*out
*/
H5_DLL H5D_layout_t H5Pget_layout(hid_t plist_id);
/**
- *-------------------------------------------------------------------------
+ * \ingroup DCPL
+ *
+ * \brief Gets the number of mappings for the virtual dataset
+ *
+ * \dcpl_id
+ * \param[out] count The number of mappings
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_virtual_count() gets the number of mappings for a
+ * virtual dataset that has the creation property list specified
+ * by \p dcpl_id.
+ *
+ * \virtual
+ *
+ * \since 1.10.0
+ *
+ */
+H5_DLL herr_t H5Pget_virtual_count(hid_t dcpl_id, size_t *count/*out*/);
+/**
+ * \ingroup DCPL
+ *
+ * \brief Gets the name of a source dataset used in the mapping
+ *
+ * \dcpl_id
+ * \param[in] index Mapping index. The value of \p index is 0 (zero) or
+ * greater and less than \p count
+ * (0 ≤ \p index < \p count), where \p count is the
+ * number of mappings returned by H5Pget_virtual_count().
+ * \param[out] name A buffer containing the name of the source dataset
+ * \param[in] size The size, in bytes, of the name buffer. Must be the
+ * size of the dataset name in bytes plus 1 for a NULL
+ * terminator
+ *
+ * \return Returns the length of the dataset name if successful;
+ * otherwise returns a negative value.
+ *
+ * \details H5Pget_virtual_dsetname() takes the dataset creation property
+ * list for the virtual dataset, \p dcpl_id, the mapping index,
+ * \p index, the size of the dataset name for a source dataset,
+ * \p size, and retrieves the name of the source dataset used in
+ * the mapping.
+ *
+ * Up to \p size characters of the dataset name are returned in
+ * \p name; additional characters, if any, are not returned to
+ * the user application.
+ *
+ * If the length of the dataset name, which determines the
+ * required value of \p size, is unknown, a preliminary call
+ * to H5Pget_virtual_dsetname() with the last two parameters
+ * set to NULL and zero respectively can be made. The return
+ * value of this call will be the size in bytes of the dataset
+ * name. That value, plus 1 for a NULL terminator, must then be
+ * assigned to \p size for a second H5Pget_virtual_dsetname()
+ * call, which will retrieve the actual dataset name.
+ *
+ * \virtual
+ *
+ * \since 1.10.0
+ *
+ */
+H5_DLL ssize_t H5Pget_virtual_dsetname(hid_t dcpl_id, size_t index,
+ char *name/*out*/, size_t size);
+/**
+ * \ingroup DCPL
+ *
+ * \brief Gets the filename of a source dataset used in the mapping
+ *
+ * \dcpl_id
+ * \param[in] index Mapping index. The value of \p index is 0 (zero) or
+ * greater and less than \p count
+ * (0 ≤ \p index < \p count), where \p count is the
+ * number of mappings returned by H5Pget_virtual_count().
+ * \param[out] name A buffer containing the name of the file containing
+ * the source dataset
+ * \param[in] size The size, in bytes, of the name buffer. Must be the
+ * size of the filename in bytes plus 1 for a NULL
+ * terminator
+ *
+ * \return Returns the length of the filename if successful; otherwise
+ * returns a negative value.
+ *
+ * \details H5Pget_virtual_filename() takes the dataset creation property
+ * list for the virtual dataset, \p dcpl_id, the mapping index,
+ * \p index, the size of the filename for a source dataset,
+ * \p size, and retrieves the name of the file for a source dataset
+ * used in the mapping.
+ *
+ * Up to \p size characters of the filename are returned in
+ * \p name; additional characters, if any, are not returned to
+ * the user application.
+ *
+ * If the length of the filename, which determines the required
+ * value of \p size, is unknown, a preliminary call to
+ * H5Pget_virtual_filename() with the last two parameters set
+ * to NULL and zero respectively can be made. The return value
+ * of this call will be the size in bytes of the filename. That
+ * value, plus 1 for a NULL terminator, must then be assigned to
+ * \p size for a second H5Pget_virtual_filename() call, which
+ * will retrieve the actual filename.
+ *
+ * \virtual
+ *
+ * \since 1.10.0
+ *
+ */
+H5_DLL ssize_t H5Pget_virtual_filename(hid_t dcpl_id, size_t index,
+ char *name/*out*/, size_t size);
+/**
+ * \ingroup DCPL
+ *
+ * \brief Gets a dataspace identifier for the selection within the source
+ * dataset used in the mapping
+ *
+ * \dcpl_id
+ * \param[in] index Mapping index. The value of \p index is 0 (zero) or
+ * greater and less than \p count
+ * (0 ≤ \p index < \p count), where \p count is the number
+ * of mappings returned by H5Pget_virtual_count().
+ *
+ * \return \hid_t{valid dataspace identifier}
+ *
+ * \details H5Pget_virtual_srcspace() takes the dataset creation property
+ * list for the virtual dataset, \p dcpl_id, and the mapping
+ * index, \p index, and returns a dataspace identifier for the
+ * selection within the source dataset used in the mapping.
+ *
+ * \virtual
+ *
+ * \since 1.10.0
+ *
+ */
+H5_DLL hid_t H5Pget_virtual_srcspace(hid_t dcpl_id, size_t index);
+/**
+ * \ingroup DCPL
+ *
+ * \brief Gets a dataspace identifier for the selection within the virtual
+ * dataset used in the mapping
+ *
+ * \dcpl_id
+ * \param[in] index Mapping index. The value of \p index is 0 (zero) or
+ * greater and less than \p count
+ * (0 ≤ \p index < \p count), where \p count is the number
+ * of mappings returned by H5Pget_virtual_count()
+ *
+ * \return \hid_t{valid dataspace identifier}
+ *
+ * \details H5Pget_virtual_vspace() takes the dataset creation property
+ * list for the virtual dataset, \p dcpl_id, and the mapping
+ * index, \p index, and returns a dataspace identifier for the
+ * selection within the virtual dataset used in the mapping.
+ *
+ * \virtual
+ *
+ * \since 1.10.0
+ *
+ */
+H5_DLL hid_t H5Pget_virtual_vspace(hid_t dcpl_id, size_t index);
+/**
+ * \ingroup DCPL
+ *
+ * \brief Sets the timing for storage space allocation
+ *
+ * \dcpl_id{plist_id}
+ * \param[in] alloc_time When to allocate dataset storage space
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_alloc_time() sets up the timing for the allocation of
+ * storage space for a dataset's raw data. This property is set
+ * in the dataset creation property list \p plist_id. Timing is
+ * specified in \p alloc_time with one of the following values:
+ *
+ * <table>
+ * <tr>
+ * <td>#H5D_ALLOC_TIME_DEFAULT</td>
+ * <td>Allocate dataset storage space at the default time<br />
+ * (Defaults differ by storage method.)</td>
+ * </tr>
+ * <tr>
+ * <td>#H5D_ALLOC_TIME_EARLY</td>
+ * <td>Allocate all space when the dataset is created<br />
+ * (Default for compact datasets.)</td>
+ * </tr>
+ * <tr>
+ * <td>#H5D_ALLOC_TIME_INCR</td>
+ * <td>Allocate space incrementally, as data is written to
+ * the dataset<br />(Default for chunked storage datasets.)
+ *
+ * \li Chunked datasets: Storage space allocation for each
+ * chunk is deferred until data is written to the chunk.
+ * \li Contiguous datasets: Incremental storage space
+ * allocation for contiguous data is treated as late
+ * allocation.
+ * \li Compact datasets: Incremental allocation is not
+ * allowed with compact datasets; H5Pset_alloc_time()
+ * will return an error.</td>
+ * </tr>
+ * <tr>
+ * <td>#H5D_ALLOC_TIME_LATE</td>
+ * <td>Allocate all space when data is first written to the
+ * dataset<br />
+ * (Default for contiguous datasets.)</td>
+ * </tr>
+ * </table>
+ *
+ * \note H5Pset_alloc_time() is designed to work in concert with the
+ * dataset fill value and fill value write time properties, set
+ * with the functions H5Pset_fill_value() and H5Pset_fill_time().
+ *
+ * \note See H5Dcreate() for further cross-references.
+ *
+ * \since 1.6.0
+ *
+ */
+H5_DLL herr_t H5Pset_alloc_time(hid_t plist_id, H5D_alloc_time_t
+ alloc_time);
+/**
* \ingroup DCPL
*
* \brief Sets the size of the chunks used to store a chunked layout
@@ -801,8 +4556,6 @@ H5_DLL H5D_layout_t H5Pget_layout(hid_t plist_id);
*/
H5_DLL herr_t H5Pset_chunk(hid_t plist_id, int ndims, const hsize_t dim[/*ndims*/]);
/**
- *-------------------------------------------------------------------------
- *
* \ingroup DCPL
*
* \brief Sets the edge chunk option in a dataset creation property list
@@ -842,8 +4595,80 @@ H5_DLL herr_t H5Pset_chunk(hid_t plist_id, int ndims, const hsize_t dim[/*ndims*
*/
H5_DLL herr_t H5Pset_chunk_opts(hid_t plist_id, unsigned opts);
/**
- *-------------------------------------------------------------------------
+ * \ingroup DCPL
+ *
+ * \brief Sets the flag to create minimized dataset object headers
+ *
+ * \dcpl_id
+ * \param[in] minimize Flag for indicating whether or not a dataset's
+ * object header will be minimized
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_dset_no_attrs_hint() sets the no dataset attributes
+ * hint setting for the dataset creation property list \p dcpl_id.
+ * Datasets created with the dataset creation property list
+ * \p dcpl_id will have their object headers minimized if the
+ * boolean flag \p minimize is set to TRUE. By setting \p minimize
+ * to TRUE, the library expects that no attributes will be added
+ * to the dataset. Attributes can be added, but they are appended
+ * with a continuation message, which can reduce performance.
*
+ * This setting interacts with H5Fset_dset_no_attrs_hint(): if
+ * either is set to TRUE, then the created dataset's object header
+ * will be minimized.
+ *
+ * \since 1.10.5
+ *
+ */
+H5_DLL herr_t H5Pset_dset_no_attrs_hint(hid_t dcpl_id, hbool_t minimize);
+/**
+ * \ingroup DCPL
+ *
+ * \brief Adds an external file to the list of external files
+ *
+ * \dcpl_id{plist_id}
+ * \param[in] name Name of an external file
+ * \param[in] offset Offset, in bytes, from the beginning of the file to
+ * the location in the file where the data starts
+ * \param[in] size Number of bytes reserved in the file for the data
+ *
+ * \return \herr_t
+ *
+ * \details The first call to H5Pset_external() sets the external
+ * storage property in the property list, thus designating that
+ * the dataset will be stored in one or more non-HDF5 file(s)
+ * external to the HDF5 file. This call also adds the file
+ * \p name as the first file in the list of external files.
+ * Subsequent calls to the function add the named file as the
+ * next file in the list.
+ *
+ * If a dataset is split across multiple files, then the files
+ * should be defined in order. The total size of the dataset is
+ * the sum of the \p size arguments for all the external files.
+ * If the total size is larger than the size of a dataset then
+ * the dataset can be extended (provided the data space also
+ * allows the extending).
+ *
+ * The \p size argument specifies the number of bytes reserved
+ * for data in the external file. If \p size is set to
+ * #H5F_UNLIMITED, the external file can be of unlimited size
+ * and no more files can be added to the external files list.
+ * If \p size is set to 0 (zero), no external file will actually
+ * be created.
+ *
+ * All of the external files for a given dataset must be specified
+ * with H5Pset_external() before H5Dcreate() is called to create
+ * the dataset. If one these files does not exist on the system
+ * when H5Dwrite() is called to write data to it, the library
+ * will create the file.
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Pset_external(hid_t plist_id, const char *name, off_t offset,
+ hsize_t size);
+/**
* \ingroup DCPL
*
* \brief Sets the time when fill values are written to a dataset
@@ -886,8 +4711,6 @@ H5_DLL herr_t H5Pset_chunk_opts(hid_t plist_id, unsigned opts);
*/
H5_DLL herr_t H5Pset_fill_time(hid_t plist_id, H5D_fill_time_t fill_time);
/**
- *-------------------------------------------------------------------------
- *
* \ingroup DCPL
*
* \brief Sets the fill value for a dataset
@@ -936,10 +4759,9 @@ H5_DLL herr_t H5Pset_fill_time(hid_t plist_id, H5D_fill_time_t fill_time);
* \since 1.0.0
*
*/
-H5_DLL herr_t H5Pset_fill_value(hid_t plist_id, hid_t type_id, const void *value);
+H5_DLL herr_t H5Pset_fill_value(hid_t plist_id, hid_t type_id,
+ const void *value);
/**
- *-------------------------------------------------------------------------
- *
* \ingroup DCPL
*
* \brief Sets up use of the shuffle filter
@@ -974,7 +4796,6 @@ H5_DLL herr_t H5Pset_fill_value(hid_t plist_id, hid_t type_id, const void *value
*/
H5_DLL herr_t H5Pset_shuffle(hid_t plist_id);
/**
- *-------------------------------------------------------------------------
* \ingroup DCPL
*
* \brief Sets the type of storage used to store the raw data for a dataset
@@ -1011,8 +4832,208 @@ H5_DLL herr_t H5Pset_shuffle(hid_t plist_id);
*
*/
H5_DLL herr_t H5Pset_layout(hid_t plist_id, H5D_layout_t layout);
+//! [nbit_code_snip]
+/*
+hid_t nbit_datatype = H5Tcopy(H5T_STD_I32LE);
+H5Tset_precision(nbit_datatype, 16);
+H5Tset_offset(nbit_datatype, 4);
+*/
+//! [nbit_code_snip]
+/**
+ * \ingroup DCPL
+ *
+ * \brief Sets up the use of the N-Bit filter
+ *
+ * \dcpl_id{plist_id}
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_nbit() sets the N-Bit filter, #H5Z_FILTER_NBIT, in the
+ * dataset creation property list \p plist_id.
+ *
+ * The HDF5 user can create an N-Bit datatype with the following
+ * code:
+ * \snippet this nbit_code_snip
+ *
+ * In memory, one value of the N-Bit datatype in the above example
+ * will be stored on a little-endian machine as follows:
+ *
+ * <table>
+ * <tr>
+ * <td>byte 3</td>
+ * <td>byte 2</td>
+ * <td>byte 1</td>
+ * <td>byte 0</td>
+ * </tr>
+ * <tr>
+ * <td>????????</td>
+ * <td>????SPPP</td>
+ * <td>PPPPPPPP</td>
+ * <td>PPPP????</td>
+ * </tr>
+ * </table>
+ * Note: S - sign bit, P - significant bit, ? - padding bit; For
+ * signed integer, the sign bit is included in the precision.
+ *
+ * When data of the above datatype is stored on disk using the
+ * N-bit filter, all padding bits are chopped off and only
+ * significant bits are stored. The values on disk will be
+ * something like:
+ *
+ * <table>
+ * <tr>
+ * <td>1st value</td>
+ * <td>2nd value</td>
+ * <td>...</td>
+ * </tr>
+ * <tr>
+ * <td>SPPPPPPPPPPPPPPP</td>
+ * <td>SPPPPPPPPPPPPPPP</td>
+ * <td>...</td>
+ * </tr>
+ * </table>
+ * The N-Bit filter is used effectively for compressing data of
+ * an N-Bit datatype as well as a compound and an array
+ * datatype with N-Bit fields. However, the datatype classes of
+ * the N-Bit datatype or the N-Bit field of the compound
+ * datatype or the array datatype are limited to integer or
+ * floating-point.
+ *
+ * The N-Bit filter supports complex situations where a compound
+ * datatype contains member(s) of a compound datatype or an array
+ * datatype that has a compound datatype as the base type.
+ * However, it does not support the situation where an array
+ * datatype has a variable-length or variable-length string as
+ * its base datatype. The filter does support the situation where
+ * a variable-length or variable-length string is a member of a
+ * compound datatype.
+ *
+ * The N-Bit filter allows all other HDF5 datatypes (such as
+ * time, string, bitfield, opaque, reference, enum, and variable
+ * length) to pass through as a no-op.
+ *
+ * Like other I/O filters supported by the HDF5 library,
+ * application using the N-Bit filter must store data with
+ * chunked storage.
+ *
+ * By nature, the N-Bit filter should not be used together with
+ * other I/O filters.
+ *
+ * \version 1.8.8 Fortran subroutine introduced in this release.
+ * \todo fix "nbit_code_snip"
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL herr_t H5Pset_nbit(hid_t plist_id);
+/**
+ * \ingroup DCPL
+ *
+ * \brief Sets up the use of the scale-offset filter
+ *
+ * \dcpl_id{plist_id}
+ * \param[in] scale_type Flag indicating compression method
+ * \param[in] scale_factor Parameter related to scale. Must be
+ * non-negative
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_scaleoffset() sets the scale-offset filter,
+ * #H5Z_FILTER_SCALEOFFSET, for a dataset.
+ *
+ * Generally speaking, scale-offset compression performs a scale and/or
+ * offset operation on each data value and truncates the resulting
+ * value to a minimum number of bits (MinBits) before storing it. The
+ * current scale-offset filter supports integer and floating-point
+ * datatypes.
+ *
+ * For an integer datatype, the parameter \p scale_type should be set
+ * to #H5Z_SO_INT (2). The parameter \p scale_factor denotes MinBits.
+ * If the user sets it to H5Z_SO_INT_MINBITS_DEFAULT (0), the filter
+ * will calculate MinBits. If \p scale_factor is set to a positive
+ * integer, the filter does not do any calculation and just uses the
+ * number as MinBits. However, if the user gives a MinBits that is less
+ * than what would be generated by the filter, the compression will be
+ * lossy. Also, the MinBits supplied by the user cannot exceed the
+ * number of bits to store one value of the dataset datatype.
+ *
+ * For a floating-point datatype, the filter adopts the GRiB data
+ * packing mechanism, which offers two alternate methods: E-scaling and
+ * D-scaling. Both methods are lossy compression. If the parameter
+ * \p scale_type is set to #H5Z_SO_FLOAT_DSCALE (0), the filter will
+ * use the D-scaling method; if it is set to #H5Z_SO_FLOAT_ESCALE (1),
+ * the filter will use the E-scaling method. Since only the D-scaling
+ * method is implemented, \p scale_type should be set to
+ * #H5Z_SO_FLOAT_DSCALE or 0.
+ *
+ * When the D-scaling method is used, the original data is "D" scaled
+ * — multiplied by 10 to the power of \p scale_factor, and the
+ * "significant" part of the value is moved to the left of the decimal
+ * point. Care should be taken in setting the decimal \p scale_factor
+ * so that the integer part will have enough precision to contain the
+ * appropriate information of the data value. For example, if
+ * \p scale_factor is set to 2, the number 104.561 will be 10456.1
+ * after "D" scaling. The last digit 1 is not "significant" and is
+ * thrown off in the process of rounding. The user should make sure that
+ * after "D" scaling and rounding, the data values are within the range
+ * that can be represented by the integer (same size as the
+ * floating-point type).
+ *
+ * Valid values for scale_type are as follows:
+ *
+ * <table>
+ * <tr>
+ * <td>#H5Z_SO_FLOAT_DSCALE (0)</td>
+ * <td>Floating-point type, using variable MinBits method</td>
+ * </tr>
+ * <tr>
+ * <td>#H5Z_SO_FLOAT_ESCALE (1)</td>
+ * <td>Floating-point type, using fixed MinBits method</td>
+ * </tr>
+ * <tr>
+ * <td>#H5Z_SO_INT (2)</td>
+ * <td>Integer type</td>
+ * </tr>
+ * </table>
+ *
+ * The meaning of \p scale_factor varies according to the value
+ * assigned to \p scale_type:
+ *
+ * <table>
+ * <tr>
+ * <th>\p scale_type value</th>
+ * <th>\p scale_factor description</th>
+ * </tr>
+ * <tr>
+ * <td>#H5Z_SO_FLOAT_DSCALE</td>
+ * <td>Denotes the decimal scale factor for D-scaling and can be
+ * positive, negative or zero. This is the current
+ * implementation of the library.</td>
+ * </tr>
+ * <tr>
+ * <td>#H5Z_SO_FLOAT_ESCALE</td>
+ * <td>Denotes MinBits for E-scaling and must be a positive integer.
+ * This is not currently implemented by the library.</td>
+ * </tr>
+ * <tr>
+ * <td>#H5Z_SO_INT</td>
+ * <td>Denotes MinBits and it should be a positive integer or
+ * #H5Z_SO_INT_MINBITS_DEFAULT (0). If it is less than 0, the
+ * library will reset it to 0 since it is not implemented.
+ * </td>
+ * </tr>
+ * </table>
+ * Like other I/O filters supported by the HDF5 library, an
+ * application using the scale-offset filter must store data with
+ * chunked storage.
+ *
+ * \version 1.8.8 Fortran90 subroutine introduced in this release.
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL herr_t H5Pset_scaleoffset(hid_t plist_id, H5Z_SO_scale_type_t scale_type, int scale_factor);
/**
- *-------------------------------------------------------------------------
* \ingroup DCPL
*
* \brief Sets up use of the SZIP compression filter
@@ -1165,66 +5186,682 @@ H5_DLL herr_t H5Pset_layout(hid_t plist_id, H5D_layout_t layout);
*
* \since 1.6.0
*
- *--------------------------------------------------------------------------
- */
-H5_DLL herr_t H5Pset_szip(hid_t plist_id, unsigned options_mask, unsigned pixels_per_block);
-H5_DLL herr_t H5Pset_virtual(hid_t dcpl_id, hid_t vspace_id, const char *src_file_name,
- const char *src_dset_name, hid_t src_space_id);
-H5_DLL herr_t H5Pget_virtual_count(hid_t dcpl_id, size_t *count /*out*/);
-H5_DLL hid_t H5Pget_virtual_vspace(hid_t dcpl_id, size_t index);
-H5_DLL hid_t H5Pget_virtual_srcspace(hid_t dcpl_id, size_t index);
-H5_DLL ssize_t H5Pget_virtual_filename(hid_t dcpl_id, size_t index, char *name /*out*/, size_t size);
-H5_DLL ssize_t H5Pget_virtual_dsetname(hid_t dcpl_id, size_t index, char *name /*out*/, size_t size);
-H5_DLL herr_t H5Pset_external(hid_t plist_id, const char *name, off_t offset, hsize_t size);
-H5_DLL int H5Pget_external_count(hid_t plist_id);
-H5_DLL herr_t H5Pget_external(hid_t plist_id, unsigned idx, size_t name_size, char *name /*out*/,
- off_t *offset /*out*/, hsize_t *size /*out*/);
-H5_DLL herr_t H5Pset_nbit(hid_t plist_id);
-H5_DLL herr_t H5Pset_scaleoffset(hid_t plist_id, H5Z_SO_scale_type_t scale_type, int scale_factor);
-H5_DLL herr_t H5Pfill_value_defined(hid_t plist, H5D_fill_value_t *status);
-H5_DLL herr_t H5Pset_alloc_time(hid_t plist_id, H5D_alloc_time_t alloc_time);
-H5_DLL herr_t H5Pget_alloc_time(hid_t plist_id, H5D_alloc_time_t *alloc_time /*out*/);
-H5_DLL herr_t H5Pget_dset_no_attrs_hint(hid_t dcpl_id, hbool_t *minimize);
-H5_DLL herr_t H5Pset_dset_no_attrs_hint(hid_t dcpl_id, hbool_t minimize);
+ */
+H5_DLL herr_t H5Pset_szip(hid_t plist_id, unsigned options_mask, unsigned pixels_per_block);
+H5_DLL herr_t H5Pset_virtual(hid_t dcpl_id, hid_t vspace_id, const char *src_file_name,
+ const char *src_dset_name, hid_t src_space_id);
/* Dataset access property list (DAPL) routines */
-H5_DLL herr_t H5Pset_chunk_cache(hid_t dapl_id, size_t rdcc_nslots, size_t rdcc_nbytes, double rdcc_w0);
-H5_DLL herr_t H5Pget_chunk_cache(hid_t dapl_id, size_t *rdcc_nslots /*out*/, size_t *rdcc_nbytes /*out*/,
- double *rdcc_w0 /*out*/);
-H5_DLL herr_t H5Pset_virtual_view(hid_t plist_id, H5D_vds_view_t view);
-H5_DLL herr_t H5Pget_virtual_view(hid_t plist_id, H5D_vds_view_t *view);
-H5_DLL herr_t H5Pset_virtual_printf_gap(hid_t plist_id, hsize_t gap_size);
-H5_DLL herr_t H5Pget_virtual_printf_gap(hid_t plist_id, hsize_t *gap_size);
-H5_DLL herr_t H5Pset_virtual_prefix(hid_t dapl_id, const char *prefix);
-H5_DLL ssize_t H5Pget_virtual_prefix(hid_t dapl_id, char *prefix /*out*/, size_t size);
-H5_DLL herr_t H5Pset_append_flush(hid_t plist_id, unsigned ndims, const hsize_t boundary[],
- H5D_append_cb_t func, void *udata);
-H5_DLL herr_t H5Pget_append_flush(hid_t plist_id, unsigned dims, hsize_t boundary[], H5D_append_cb_t *func,
- void **udata);
-H5_DLL herr_t H5Pset_efile_prefix(hid_t dapl_id, const char *prefix);
-H5_DLL ssize_t H5Pget_efile_prefix(hid_t dapl_id, char *prefix /*out*/, size_t size);
+/**
+ * \ingroup DAPL
+ *
+ * \brief Retrieves the values of the append property that is set up in
+ * the dataset access property list
+ *
+ * \dapl_id
+ * \param[in] dims The number of elements for \p boundary
+ * \param[in] boundary The dimension sizes used to determine the boundary
+ * \param[in] func The user-defined callback function
+ * \param[in] udata The user-defined input data
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_append_flush() obtains the following information
+ * from the dataset access property list, \p dapl_id.
+ *
+ * \p boundary consists of the sizes set up in the access
+ * property list that are used to determine when a dataset
+ * dimension size hits the boundary. Only at most \p dims
+ * boundary sizes are retrieved, and \p dims will not exceed
+ * the corresponding value that is set in the property list.
+ *
+ * \p func is the user-defined callback function to invoke when
+ * a dataset’s appended dimension size reaches a boundary and
+ * \p udata is the user-defined input data for the callback
+ * function.
+ *
+ * \todo Example Usage was removed and needs to be re-added
+ *
+ * \since 1.10.0
+ *
+ */
+H5_DLL herr_t H5Pget_append_flush(hid_t dapl_id, unsigned dims,
+ hsize_t boundary[], H5D_append_cb_t *func, void **udata);
+/**
+ * \ingroup DAPL
+ *
+ * \brief Retrieves the raw data chunk cache parameters
+ *
+ * \dapl_id
+ * \param[out] rdcc_nslots Number of chunk slots in the raw data chunk
+ * cache hash table
+ * \param[out] rdcc_nbytes Total size of the raw data chunk cache, in
+ * bytes
+ * \param[out] rdcc_w0 Preemption policy
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_chunk_cache() retrieves the number of chunk slots in
+ * the raw data chunk cache hash table, the maximum possible
+ * number of bytes in the raw data chunk cache, and the
+ * preemption policy value.
+ *
+ * These values are retrieved from a dataset access property
+ * list. If the values have not been set on the property list,
+ * then values returned will be the corresponding values from
+ * a default file access property list.
+ *
+ * Any (or all) pointer arguments may be null pointers, in which
+ * case the corresponding data is not returned.
+ *
+ * \since 1.8.3
+ *
+ */
+H5_DLL herr_t H5Pget_chunk_cache(hid_t dapl_id,
+ size_t *rdcc_nslots/*out*/,
+ size_t *rdcc_nbytes/*out*/,
+ double *rdcc_w0/*out*/);
+/**
+ * \ingroup DAPL
+ *
+ * \brief Retrieves the prefix for external raw data storage files as set
+ * in the dataset access property list
+ *
+ * \dapl_id
+ * \param[in,out] prefix Dataset external storage prefix in UTF-8 or
+ * ASCII (\em Path and \em filename must be ASCII
+ * on Windows systems.)
+ * \param[in] size Size of prefix buffer in bytes
+ *
+ * \return Returns the size of \p prefix and the prefix string will be
+ * stored in \p prefix if successful.
+ * Otherwise returns a negative value and the contents of \p prefix
+ * will be undefined.
+ *
+ * \details H5Pget_efile_prefix() retrieves the file system path prefix
+ * for locating external files associated with a dataset that
+ * uses external storage. This will be the value set with
+ * H5Pset_efile_prefix() or the HDF5 library’s default.
+ *
+ * The value of \p size is the size in bytes of the prefix,
+ * including the NULL terminator. If the size is unknown, a
+ * preliminary H5Pget_elink_prefix() call with the pointer
+ * \p prefix set to NULL will return the size of the prefix
+ * without the NULL terminator.
+ *
+ * The \p prefix buffer must be allocated by the caller. In a
+ * call that retrieves the actual prefix, that buffer must be
+ * of the size specified in \p size.
+ *
+ * \note See H5Pset_efile_prefix() for a more complete description of
+ * file location behavior and for notes on the use of the
+ * HDF5_EXTFILE_PREFIX environment variable.
+ *
+ * \since 1.10.0, 1.8.17
+ *
+ */
+H5_DLL ssize_t H5Pget_efile_prefix(hid_t dapl_id, char* prefix /*out*/, size_t size);
+/**
+ * \ingroup DAPL
+ *
+ * \brief Retrieves prefix applied to VDS source file paths
+ *
+ * \dapl_id
+ * \param[out] prefix Prefix applied to VDS source file paths
+ * \param[in] size Size of prefix, including null terminator
+ *
+ * \return If successful, returns a non-negative value specifying the size
+ * in bytes of the prefix without the NULL terminator; otherwise
+ * returns a negative value.
+ *
+ * \details H5Pget_virtual_prefix() retrieves the prefix applied to the
+ * path of any VDS source files traversed.
+ *
+ * When an VDS source file is traversed, the prefix is retrieved
+ * from the dataset access property list \p dapl_id, returned
+ * in the user-allocated buffer pointed to by \p prefix, and
+ * prepended to the filename stored in the VDS virtual file, set
+ * with H5Pset_virtual().
+ *
+ * The size in bytes of the prefix, including the NULL terminator,
+ * is specified in \p size. If \p size is unknown, a preliminary
+ * H5Pget_virtual_prefix() call with the pointer \p prefix set to
+ * NULL will return the size of the prefix without the NULL
+ * terminator.
+ *
+ * \virtual
+ *
+ * \since 1.10.2
+ *
+ */
+H5_DLL ssize_t H5Pget_virtual_prefix(hid_t dapl_id, char* prefix /*out*/, size_t size);
+/**
+ * \ingroup DAPL
+ *
+ * \brief Returns the maximum number of missing source files and/or datasets
+ * with the printf-style names when getting the extent for an unlimited
+ * virtual dataset
+ *
+ * \dapl_id
+ * \param[out] gap_size Maximum number of the files and/or datasets
+ * allowed to be missing for determining the extent
+ * of an unlimited virtual dataset with printf-style
+ * mappings. (\em Default: 0)
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_virtual_printf_gap() returns the maximum number of
+ * missing printf-style files and/or datasets for determining the
+ * extent of an unlimited virtual dataaset, \p gap_size, using
+ * the access property list for the virtual dataset, \p dapl_id.
+ *
+ * The default library value for \p gap_size is 0 (zero).
+ *
+ * \since 1.10.0
+ *
+ */
+H5_DLL herr_t H5Pget_virtual_printf_gap(hid_t dapl_id, hsize_t *gap_size);
+/**
+ * \ingroup DAPL
+ *
+ * \brief Retrieves the view of a virtual dataset accessed with
+ * \p dapl_id
+ *
+ * \dapl_id
+ * \param[out] view The flag specifying the view of the virtual dataset.
+ * Valid values are:
+ * \li #H5D_VDS_FIRST_MISSING
+ * \li #H5D_VDS_LAST_AVAILABLE
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_virtual_view() takes the virtual dataset access property
+ * list, \p dapl_id, and retrieves the flag, \p view, set by the
+ * H5Pset_virtual_view() call.
+ *
+ * \virtual
+ *
+ * \since 1.10.0
+ *
+ */
+H5_DLL herr_t H5Pget_virtual_view(hid_t dapl_id, H5D_vds_view_t *view);
+/**
+ * \ingroup DAPL
+ *
+ * \brief Sets two actions to perform when the size of a dataset’s
+ * dimension being appended reaches a specified boundary
+ *
+ * \dapl_id
+ * \param[in] ndims The number of elements for boundary
+ * \param[in] boundary The dimension sizes used to determine the boundary
+ * \param[in] func The user-defined callback function
+ * \param[in] udata The user-defined input data
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_append_flush() sets the following two actions to
+ * perform for a dataset associated with the dataset access
+ * property list \p dapl_id:
+ *
+ * \li Call the callback function \p func set in the property
+ * list
+ * \li Flush the dataset associated with the dataset access
+ * property list
+ *
+ * When a user is appending data to a dataset via H5DOappend()
+ * and the dataset’s newly extended dimension size hits a
+ * specified boundary, the library will perform the first action
+ * listed above. Upon return from the callback function, the
+ * library will then perform the second action listed above and
+ * return to the user. If no boundary is hit or set, the two
+ * actions above are not invoked.
+ *
+ * The specified boundary is indicated by the parameter
+ * \p boundary. It is a 1-dimensional array with \p ndims
+ * elements, which should be the same as the rank of the
+ * dataset’s dataspace. While appending to a dataset along a
+ * particular dimension index via H5DOappend(), the library
+ * determines a boundary is reached when the resulting dimension
+ * size is divisible by \p boundary[index]. A zero value for
+ * \p boundary[index] indicates no boundary is set for that
+ * dimension index.
+ *
+ * The setting of this property will apply only for a chunked
+ * dataset with an extendible dataspace. A dataspace is extendible
+ * when it is defined with either one of the following:
+ *
+ * \li A dataspace with fixed current and maximum dimension sizes
+ * \li A dataspace with at least one unlimited dimension for its
+ * maximum dimension size
+ *
+ * When creating or opening a chunked dataset, the library will
+ * check whether the boundary as specified in the access property
+ * list is set up properly. The library will fail the dataset
+ * create or open if the following conditions are true:
+ *
+ * \li \p ndims, the number of elements for boundary, is not the
+ * same as the rank of the dataset’s dataspace.
+ * \li A non-zero boundary value is specified for a non-extendible
+ * dimension.
+ *
+ * The callback function \p func must conform to the following
+ * prototype:
+ * \Code{typedef herr_t (#H5D_append_cb_t)(hid_t dataset_id,
+ * hsize_t *cur_dims, void *user_data)}
+ *
+ * The parameters of the callback function, per the above
+ * prototype, are defined as follows:
+ *
+ * \li \p dataset_id is the dataset identifier.
+ * \li \p cur_dims is the dataset’s current dimension sizes when
+ * a boundary is hit.
+ * \li \p user_data is the user-defined input data.
+ *
+ * \todo Example Usage was removed and should be added back.
+ * \todo Adding snippet for H5D_append_cb_t_snip did not work.
+ * \todo H5DOappend() not found
+ *
+ * \since 1.10.0
+ *
+ */
+H5_DLL herr_t H5Pset_append_flush(hid_t dapl_id, unsigned ndims,
+ const hsize_t boundary[], H5D_append_cb_t func, void *udata);
+/**
+ * \ingroup DAPL
+ *
+ * \brief Sets the raw data chunk cache parameters
+ *
+ * \dapl_id
+ * \param[in] rdcc_nslots The number of chunk slots in the raw data chunk
+ * cache for this dataset. Increasing this value
+ * reduces the number of cache collisions, but
+ * slightly increases the memory used. Due to the
+ * hashing strategy, this value should ideally be a
+ * prime number. As a rule of thumb, this value
+ * should be at least 10 times the number of chunks
+ * that can fit in \p rdcc_nbytes bytes. For maximum
+ * performance, this value should be set
+ * approximately 100 times that number of chunks.
+ * The default value is 521. If the value passed is
+ * #H5D_CHUNK_CACHE_NSLOTS_DEFAULT, then the
+ * property will not be set on \p dapl_id and the
+ * parameter will come from the file access
+ * property list used to open the file.
+ * \param[in] rdcc_nbytes The total size of the raw data chunk cache for
+ * this dataset. In most cases increasing this
+ * number will improve performance, as long as
+ * you have enough free memory.
+ * The default size is 1 MB. If the value passed is
+ * #H5D_CHUNK_CACHE_NBYTES_DEFAULT, then the
+ * property will not be set on \p dapl_id and the
+ * parameter will come from the file access
+ * property list.
+ * \param[in] rdcc_w0 The chunk preemption policy for this dataset.
+ * This must be between 0 and 1 inclusive and
+ * indicates the weighting according to which chunks
+ * which have been fully read or written are
+ * penalized when determining which chunks to flush
+ * from cache. A value of 0 means fully read or
+ * written chunks are treated no differently than
+ * other chunks (the preemption is strictly LRU)
+ * while a value of 1 means fully read or written
+ * chunks are always preempted before other chunks.
+ * If your application only reads or writes data
+ * once, this can be safely set to 1. Otherwise,
+ * this should be set lower, depending on how often
+ * you re-read or re-write the same data.
+ * The default value is 0.75. If the value passed is
+ * #H5D_CHUNK_CACHE_W0_DEFAULT, then the property
+ * will not be set on \p dapl_id and the parameter
+ * will come from the file access property list.
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_chunk_cache() sets the number of elements, the total
+ * number of bytes, and the preemption policy value in the raw
+ * data chunk cache on a dataset access property list. After
+ * calling this function, the values set in the property list
+ * will override the values in the file's file access property
+ * list.
+ *
+ * The raw data chunk cache inserts chunks into the cache
+ * by first computing a hash value using the address of a chunk,
+ * then using that hash value as the chunk's index into the table
+ * of cached chunks. The size of this hash table, i.e., and the
+ * number of possible hash values, is determined by the
+ * \p rdcc_nslots parameter. If a different chunk in the cache
+ * has the same hash value, this causes a collision, which
+ * reduces efficiency. If inserting the chunk into cache would
+ * cause the cache to be too big, then the cache is pruned
+ * according to the \p rdcc_w0 parameter.
+ *
+ * \note \b Motivation: H5Pset_chunk_cache() is used to adjust the chunk
+ * cache parameters on a per-dataset basis, as opposed to a global
+ * setting for the file using H5Pset_cache(). The optimum chunk
+ * cache parameters may vary widely with different data layout and
+ * access patterns, so for optimal performance they must be set
+ * individually for each dataset. It may also be beneficial to
+ * reduce the size of the chunk cache for datasets whose
+ * performance is not important in order to save memory space.
+ *
+ * \note \b Example \b Usage: The following code sets the chunk cache to
+ * use a hash table with 12421 elements and a maximum size of
+ * 16 MB, while using the preemption policy specified for the
+ * entire file:
+ * \Code{
+ * H5Pset_chunk_cache(dapl_id, 12421, 16*1024*1024,
+ * H5D_CHUNK_CACHE_W0_DEFAULT);}
+ *
+ * \note \b Usage \b Notes: The chunk cache size is a property for
+ * accessing a dataset and is not stored with a dataset or a
+ * file. To guarantee the same chunk cache settings each time
+ * the dataset is opened, call H5Dopen() with a dataset access
+ * property list where the chunk cache size is set by calling
+ * H5Pset_chunk_cache() for that property list. The property
+ * list can be used for multiple accesses in the same
+ * application.
+ *
+ * \note For files where the same chunk cache size will be
+ * appropriate for all or most datasets, H5Pset_cache() can
+ * be called with a file access property list to set the
+ * chunk cache size for accessing all datasets in the file.
+ *
+ * \note Both methods can be used in combination, in which case
+ * the chunk cache size set by H5Pset_cache() will apply
+ * except for specific datasets where H5Dopen() is called
+ * with dataset property list with the chunk cache size
+ * set by H5Pset_chunk_cache().
+ *
+ * \note In the absence of any cache settings, H5Dopen() will
+ * by default create a 1 MB chunk cache for the opened
+ * dataset. If this size happens to be appropriate, no
+ * call will be needed to either function to set the
+ * chunk cache size.
+ *
+ * \note It is also possible that a change in access pattern
+ * for later access to a dataset will change the
+ * appropriate chunk cache size.
+ *
+ * \since 1.8.3
+ *
+ */
+H5_DLL herr_t H5Pset_chunk_cache(hid_t dapl_id, size_t rdcc_nslots,
+ size_t rdcc_nbytes, double rdcc_w0);
+/**
+ * \ingroup DAPL
+ *
+ * \brief Sets the external dataset storage file prefix in the dataset
+ * access property list
+ *
+ * \dapl_id
+ * \param[in] prefix Dataset external storage prefix in UTF-8 or ASCII
+ * (<em>Path and filename must be ASCII on Windows systems.</em>)
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_efile_prefix() sets the prefix used to locate raw data
+ * files for a dataset that uses external storage. This prefix
+ * can provide either an absolute path or a relative path to the
+ * external files.
+ *
+ * H5Pset_efile_prefix() is used in conjunction with
+ * H5Pset_external() to control the behavior of the HDF5 library
+ * when searching for the raw data files associated with a dataset
+ * that uses external storage:
+ *
+ * \li The default behavior of the library is to search for the
+ * dataset’s external storage raw data files in the same
+ * directory as the HDF5 file which contains the dataset.
+ * \li If the prefix is set to an absolute path, the target
+ * directory will be searched for the dataset’s external
+ * storage raw data files.
+ * \li If the prefix is set to a relative path, the target
+ * directory, relative to the current working directory, will
+ * be searched for the dataset’s external storage raw data
+ * files.
+ * \li If the prefix is set to a relative path that begins with
+ * the special token ${ORIGIN}, that directory, relative to
+ * the HDF5 file containing the dataset, will be searched for
+ * the dataset’s external storage raw data files.
+ *
+ * The HDF5_EXTFILE_PREFIX environment variable can be used to
+ * override the above behavior (the environment variable
+ * supersedes the API call). Setting the variable to a path
+ * string and calling H5Dcreate() or H5Dopen() is the equivalent
+ * of calling H5Pset_efile_prefix() and calling the same create
+ * or open function. The environment variable is checked at the
+ * time of the create or open action and copied so it can be
+ * safely changed after the H5Dcreate() or H5Dopen() call.
+ *
+ * Calling H5Pset_efile_prefix() with \p prefix set to NULL or
+ * the empty string returns the search path to the default. The
+ * result would be the same as if H5Pset_efile_prefix() had never
+ * been called.
+ *
+ * \note If the external file prefix is not an absolute path and the HDF5
+ * file is moved, the external storage files will also need to be
+ * moved so they can be accessed at the new location.
+ *
+ * \note As stated above, the use of the HDF5_EXTFILE_PREFIX environment
+ * variable overrides any property list setting.
+ * H5Pset_efile_prefix() and H5Pget_efile_prefix(), being property
+ * functions, set and retrieve only the property list setting; they
+ * are unaware of the environment variable.
+ *
+ * \note On Windows, the prefix must be an ASCII string since the Windows
+ * standard C library’s I/O functions cannot handle UTF-8 file names.
+ *
+ * \since 1.10.0, 1.8.17
+ *
+ */
+H5_DLL herr_t H5Pset_efile_prefix(hid_t dapl_id, const char* prefix);
+/**
+ * \ingroup DAPL
+ *
+ * \brief Sets prefix to be applied to VDS source file paths
+ *
+ * \dapl_id
+ * \param[in] prefix Prefix to be applied to VDS source file paths
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_virtual_prefix() sets the prefix to be applied to the
+ * path of any VDS source files traversed. The prefix is prepended
+ * to the filename stored in the VDS virtual file, set with
+ * H5Pset_virtual().
+ *
+ * The prefix is specified in the user-allocated buffer \p prefix
+ * and set in the dataset access property list \p dapl_id. The
+ * buffer should not be freed until the property list has been
+ * closed.
+ *
+ * \virtual
+ *
+ * \since 1.10.2
+ *
+ */
+H5_DLL herr_t H5Pset_virtual_prefix(hid_t dapl_id, const char* prefix);
+/**
+ * \ingroup DAPL
+ *
+ * \brief Sets the maximum number of missing source files and/or datasets
+ * with the printf-style names when getting the extent of an
+ * unlimited virtual dataset
+ *
+ * \dapl_id
+ * \param[in] gap_size Maximum number of files and/or datasets allowed to
+ * be missing for determining the extent of an
+ * unlimited virtual dataset with printf-style
+ * mappings (<em>Default value</em>: 0)
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_virtual_printf_gap() sets the access property list for
+ * the virtual dataset, \p dapl_id, to instruct the library to
+ * stop looking for the mapped data stored in the files and/or
+ * datasets with the printf-style names after not finding
+ * \p gap_size files and/or datasets. The found source files and
+ * datasets will determine the extent of the unlimited virtual
+ * dataset with the printf-style mappings.
+ *
+ * Consider the following examples where the regularly spaced
+ * blocks of a virtual dataset are mapped to datasets with the
+ * names d-1, d-2, d-3, ..., d-N, ... :
+ *
+ * \li If the dataset d-2 is missing and \p gap_size is set to 0,
+ * then the virtual dataset will contain only data found
+ * in d-1.
+ * \li If d-2 and d-3 are missing and \p gap_size is set to 2,
+ * then the virtual dataset will contain the data from
+ * d-1, d-3, ..., d-N, ... . The blocks that are mapped to
+ * d-2 and d-3 will be filled according to the virtual
+ * dataset’s fill value setting.
+ *
+ * \virtual
+ *
+ * \since 1.10.0
+ *
+ */
+H5_DLL herr_t H5Pset_virtual_printf_gap(hid_t dapl_id, hsize_t gap_size);
+/**
+ * \ingroup DAPL
+ *
+ * \brief Sets the view of the virtual dataset (VDS) to include or exclude
+ * missing mapped elements
+ *
+ * \dapl_id
+ * \param[in] view Flag specifying the extent of the data to be included
+ * in the view. Valid values are:
+ * \li #H5D_VDS_FIRST_MISSING: View includes all data
+ * before the first missing mapped data
+ * \li #H5D_VDS_LAST_AVAILABLE View includes all
+ * available mapped data
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_virtual_view() takes the access property list for the
+ * virtual dataset, \p dapl_id, and the flag, \p view, and sets
+ * the VDS view according to the flag value.
+ *
+ * If \p view is set to #H5D_VDS_FIRST_MISSING, the view includes
+ * all data before the first missing mapped data. This setting
+ * provides a view containing only the continuous data starting
+ * with the dataset’s first data element. Any break in
+ * continuity terminates the view.
+ *
+ * If \p view is set to #H5D_VDS_LAST_AVAILABLE, the view
+ * includes all available mapped data.
+ *
+ * Missing mapped data is filled with the fill value set in the
+ * VDS creation property list.
+ *
+ * \virtual
+ *
+ * \since 1.10.0
+ *
+ */
+H5_DLL herr_t H5Pset_virtual_view(hid_t dapl_id, H5D_vds_view_t view);
/* Dataset xfer property list (DXPL) routines */
-H5_DLL herr_t H5Pset_data_transform(hid_t plist_id, const char *expression);
-H5_DLL ssize_t H5Pget_data_transform(hid_t plist_id, char *expression /*out*/, size_t size);
-H5_DLL herr_t H5Pset_buffer(hid_t plist_id, size_t size, void *tconv, void *bkg);
-H5_DLL size_t H5Pget_buffer(hid_t plist_id, void **tconv /*out*/, void **bkg /*out*/);
-H5_DLL herr_t H5Pset_preserve(hid_t plist_id, hbool_t status);
-H5_DLL int H5Pget_preserve(hid_t plist_id);
-H5_DLL herr_t H5Pset_edc_check(hid_t plist_id, H5Z_EDC_t check);
+H5_DLL herr_t H5Pget_btree_ratios(hid_t plist_id, double *left/*out*/,
+ double *middle/*out*/,
+ double *right/*out*/);
+H5_DLL size_t H5Pget_buffer(hid_t plist_id, void **tconv/*out*/,
+ void **bkg/*out*/);
+/**
+ *
+ * \ingroup DXPL
+ *
+ * \brief Retrieves a data transform expression
+ *
+ * \param[in] plist_id Identifier of the property list or class
+ * \param[out] expression Pointer to memory where the transform expression
+ * will be copied
+ * \param[in] size Number of bytes of the transform expression to copy to
+ *
+ * \return Returns the size of the transform expression if successful;
+ * otherwise returns a negative value.
+ *
+ * \details H5Pget_data_transform() retrieves the data transform
+ * expression previously set in the dataset transfer property
+ * list \p plist_id by H5Pset_data_transform().
+ *
+ * H5Pget_data_transform() can be used to both retrieve the
+ * transform expression and to query its size.
+ *
+ * If \p expression is non-NULL, up to \p size bytes of the data
+ * transform expression are written to the buffer. If
+ * \p expression is NULL, \p size is ignored and the function
+ * does not write anything to the buffer. The function always
+ * returns the size of the data transform expression.
+ *
+ * If 0 is returned for the size of the expression, no data
+ * transform expression exists for the property list.
+ *
+ * If an error occurs, the buffer pointed to by \p expression is
+ * unchanged and the function returns a negative value.
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL ssize_t H5Pget_data_transform(hid_t plist_id, char* expression /*out*/, size_t size);
H5_DLL H5Z_EDC_t H5Pget_edc_check(hid_t plist_id);
-H5_DLL herr_t H5Pset_filter_callback(hid_t plist_id, H5Z_filter_func_t func, void *op_data);
-H5_DLL herr_t H5Pset_btree_ratios(hid_t plist_id, double left, double middle, double right);
-H5_DLL herr_t H5Pget_btree_ratios(hid_t plist_id, double *left /*out*/, double *middle /*out*/,
- double *right /*out*/);
-H5_DLL herr_t H5Pset_vlen_mem_manager(hid_t plist_id, H5MM_allocate_t alloc_func, void *alloc_info,
- H5MM_free_t free_func, void *free_info);
-H5_DLL herr_t H5Pget_vlen_mem_manager(hid_t plist_id, H5MM_allocate_t *alloc_func, void **alloc_info,
- H5MM_free_t *free_func, void **free_info);
-H5_DLL herr_t H5Pset_hyper_vector_size(hid_t fapl_id, size_t size);
-H5_DLL herr_t H5Pget_hyper_vector_size(hid_t fapl_id, size_t *size /*out*/);
-H5_DLL herr_t H5Pset_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t op, void *operate_data);
-H5_DLL herr_t H5Pget_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t *op, void **operate_data);
+H5_DLL herr_t H5Pget_hyper_vector_size(hid_t fapl_id, size_t *size/*out*/);
+H5_DLL int H5Pget_preserve(hid_t plist_id);
+H5_DLL herr_t H5Pget_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t *op, void** operate_data);
+H5_DLL herr_t H5Pget_vlen_mem_manager(hid_t plist_id,
+ H5MM_allocate_t *alloc_func,
+ void **alloc_info,
+ H5MM_free_t *free_func,
+ void **free_info);
+H5_DLL herr_t H5Pset_btree_ratios(hid_t plist_id, double left, double middle,
+ double right);
+H5_DLL herr_t H5Pset_buffer(hid_t plist_id, size_t size, void *tconv,
+ void *bkg);
+/**
+ * \ingroup DXPL
+ *
+ * \brief Sets a data transform expression
+ *
+ * \param[in] plist_id Identifier of the property list or class
+ * \param[in] expression Pointer to the null-terminated data transform
+ * expression
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_data_transform() sets the data transform to be used for
+ * reading and writing data. This function operates on the dataset
+ * transfer property list \p plist_id.
+ *
+ * The \p expression parameter is a string containing an algebraic
+ * expression, such as (5/9.0)*(x-32) or x*(x-5). When a dataset
+ * is read or written with this property list, the transform
+ * expression is applied with the x being replaced by the values
+ * in the dataset. When reading data, the values in the file are
+ * not changed and the transformed data is returned to the user.
+ *
+ * Data transforms can only be applied to integer or
+ * floating-point datasets. Order of operations is obeyed and
+ * the only supported operations are +, -, *, and /. Parentheses
+ * can be nested arbitrarily and can be used to change precedence.
+ * When writing data back to the dataset, the transformed data is
+ * written to the file and there is no way to recover the original
+ * values to which the transform was applied.
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL herr_t H5Pset_data_transform(hid_t plist_id, const char* expression);
+H5_DLL herr_t H5Pset_edc_check(hid_t plist_id, H5Z_EDC_t check);
+H5_DLL herr_t H5Pset_filter_callback(hid_t plist_id, H5Z_filter_func_t func,
+ void* op_data);
+H5_DLL herr_t H5Pset_hyper_vector_size(hid_t fapl_id, size_t size);
+H5_DLL herr_t H5Pset_preserve(hid_t plist_id, hbool_t status);
+H5_DLL herr_t H5Pset_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t op, void* operate_data);
+H5_DLL herr_t H5Pset_vlen_mem_manager(hid_t plist_id,
+ H5MM_allocate_t alloc_func,
+ void *alloc_info, H5MM_free_t free_func,
+ void *free_info);
#ifdef H5_HAVE_PARALLEL
H5_DLL herr_t H5Pget_mpio_actual_chunk_opt_mode(hid_t plist_id,
H5D_mpio_actual_chunk_opt_mode_t *actual_chunk_opt_mode);
@@ -1294,17 +5931,16 @@ H5_DLL herr_t H5Pget_mcdt_search_cb(hid_t plist_id, H5O_mcdt_search_cb_t *func,
/* Typedefs */
/* Function prototypes */
-H5_DLL herr_t H5Pregister1(hid_t cls_id, const char *name, size_t size, void *def_value,
- H5P_prp_create_func_t prp_create, H5P_prp_set_func_t prp_set,
- H5P_prp_get_func_t prp_get, H5P_prp_delete_func_t prp_del,
- H5P_prp_copy_func_t prp_copy, H5P_prp_close_func_t prp_close);
-H5_DLL herr_t H5Pinsert1(hid_t plist_id, const char *name, size_t size, void *value,
- H5P_prp_set_func_t prp_set, H5P_prp_get_func_t prp_get,
- H5P_prp_delete_func_t prp_delete, H5P_prp_copy_func_t prp_copy,
- H5P_prp_close_func_t prp_close);
-H5_DLL herr_t H5Pencode1(hid_t plist_id, void *buf, size_t *nalloc);
-/**
- *-------------------------------------------------------------------------
+H5_DLL herr_t H5Pregister1(hid_t cls_id, const char *name, size_t size, void *def_value,
+ H5P_prp_create_func_t prp_create, H5P_prp_set_func_t prp_set,
+ H5P_prp_get_func_t prp_get, H5P_prp_delete_func_t prp_del,
+ H5P_prp_copy_func_t prp_copy, H5P_prp_close_func_t prp_close);
+H5_DLL herr_t H5Pinsert1(hid_t plist_id, const char *name, size_t size, void *value,
+ H5P_prp_set_func_t prp_set, H5P_prp_get_func_t prp_get,
+ H5P_prp_delete_func_t prp_delete, H5P_prp_copy_func_t prp_copy,
+ H5P_prp_close_func_t prp_close);
+H5_DLL herr_t H5Pencode1(hid_t plist_id, void *buf, size_t *nalloc);
+/**
* \ingroup OCPL
*
* \brief Returns information about a filter in a pipeline (DEPRECATED)
diff --git a/src/H5Spublic.h b/src/H5Spublic.h
index 62e2128..e4163df 100644
--- a/src/H5Spublic.h
+++ b/src/H5Spublic.h
@@ -120,7 +120,7 @@ typedef enum {
extern "C" {
#endif
-/* Operations on dataspaces and dataspace selections */
+/* Operations on dataspaces, dataspace selections and selection iterators */
/**
* \ingroup H5S
@@ -143,6 +143,77 @@ H5_DLL herr_t H5Sclose(hid_t space_id);
/**
* \ingroup H5S
*
+ * \brief Performs an operation on a hyperslab and an existing selection and
+ * returns the resulting selection
+ *
+ * \space_id
+ * \param[in] op Operation to perform on the current selection
+ * \param[in] start Offset of the start of of the hyperslab
+ * \param[in] stride Hyperslab stride
+ * \param[in] count Number of blocks included in the hyperslab
+ * \param[in] block Size of a block in the hyperslab
+ *
+ * \return \hid_tv{dataspace}
+ *
+ * \details H5Scombine_hyperslab() combines a hyperslab selection specified
+ * by \p start, \p stride, \p count and \p block with the current
+ * selection for the dataspace \p space_id, creating a new dataspace
+ * to return the generated selection. If the current selection is
+ * not a hyperslab, it is freed and the hyperslab parameters passed
+ * in are combined with the #H5S_SEL_ALL hyperslab (ie. a selection
+ * composing the entire current extent). If either \p stride or
+ * \p block is NULL, then it will be set to \p 1.
+ *
+ * \since 1.12.0
+ *
+ */
+H5_DLL hid_t H5Scombine_hyperslab(hid_t space_id, H5S_seloper_t op,
+ const hsize_t start[], const hsize_t stride[], const hsize_t count[],
+ const hsize_t block[]);
+/**
+ * \ingroup H5S
+ *
+ * \brief Combine two hyperslab selections with an operation, returning a
+ * dataspace with the resulting selection
+ *
+ * \space_id{space1_id}
+ * \param[in] op Selection operator
+ * \space_id{space2_id}
+ *
+ * \return \hid_t{dataspace}
+ *
+ * \details H5Scombine_select() combines two hyperslab selections
+ * \p space1_id and \p space2_id with an operation, returning a
+ * new dataspace with the resulting selection. The dataspace extent
+ * from \p space1_id is copied for the dataspace extent of the
+ * newly created dataspace.
+ *
+ * \since 1.12.0
+ *
+*/
+H5_DLL hid_t H5Scombine_select(hid_t space1_id, H5S_seloper_t op, hid_t space2_id);
+/**
+ * \ingroup H5S
+ *
+ * \brief Creates an exact copy of a dataspace
+ *
+ * \space_id
+ *
+ * \return \hid_tv{dataspace}
+ *
+ * \details H5Scopy() creates a new dataspace which is an exact copy of the
+ * dataspace identified by \p space_id. The dataspace identifier
+ * returned from this function should be released with H5Sclose()
+ * or resource leaks will occur.
+ *
+ * \version 1.4.0 Fortran subroutine introduced.
+ * \since 1.0.0
+ *
+ */
+H5_DLL hid_t H5Scopy(hid_t space_id);
+/**
+ * \ingroup H5S
+ *
* \brief Creates a new dataspace of a specified type
*
* \param[in] type Type of dataspace to be created
@@ -171,7 +242,7 @@ H5_DLL herr_t H5Sclose(hid_t space_id);
* \since 1.0.0
*
*/
-H5_DLL hid_t H5Screate(H5S_class_t type);
+H5_DLL hid_t H5Screate(H5S_class_t type);
/**
* \ingroup H5S
* \brief Creates a new simple dataspace and opens it for access
@@ -182,32 +253,34 @@ H5_DLL hid_t H5Screate(H5S_class_t type);
*
* \return \hid_t{dataspace}
*
- * \details H5Screate_simple() creates a new simple dataspace and opens it
- * for access, returning a dataspace identifier.
+ * \details H5Screate_simple() creates a new simple dataspace and opens it
+ * for access, returning a dataspace identifier.
*
- * \p rank is the number of dimensions used in the dataspace.
+ * \p rank is the number of dimensions used in the dataspace.
*
- * \p dims is a one-dimensional array of size rank specifying the
- * size of each dimension of the dataset. \p maxdims is an array of the
- * same size specifying the upper limit on the size of each dimension.
+ * \p dims is a one-dimensional array of size rank specifying the
+ * size of each dimension of the dataset. \p maxdims is an array of
+ * the same size specifying the upper limit on the size of each
+ * dimension.
*
- * Any element of \p dims can be \p 0 (zero). Note that no data can
- * be written to a dataset if the size of any dimension of its current
- * dataspace is \p 0. This is sometimes a useful initial state for a dataset.
+ * Any element of \p dims can be \p 0 (zero). Note that no data can
+ * be written to a dataset if the size of any dimension of its current
+ * dataspace is \p 0. This is sometimes a useful initial state for
+ * a dataset.
*
- * \p maxdims may be the null pointer, in which case the upper limit is
- * the same as \p dims. Otherwise, no element of \p maxdims
- * should be smaller than the corresponding element of \p dims.
+ * \p maxdims may be the null pointer, in which case the upper limit
+ * is the same as \p dims. Otherwise, no element of \p maxdims
+ * should be smaller than the corresponding element of \p dims.
*
- * If an element of \p maxdims is #H5S_UNLIMITED, the maximum size of the
- * corresponding dimension is unlimited.
+ * If an element of \p maxdims is #H5S_UNLIMITED, the maximum size of
+ * the corresponding dimension is unlimited.
*
- * Any dataset with an unlimited dimension must also be chunked; see
- * H5Pset_chunk(). Similarly, a dataset must be chunked if \p dims does
- * not equal \p maxdims.
+ * Any dataset with an unlimited dimension must also be chunked; see
+ * H5Pset_chunk(). Similarly, a dataset must be chunked if \p dims
+ * does not equal \p maxdims.
*
- * The dataspace identifier returned from this function must be released with
- * H5Sclose() or resource leaks will occur.
+ * The dataspace identifier returned from this function must be
+ * released with H5Sclose() or resource leaks will occur.
*
* \note Once a dataspace has been created, specific regions or elements in
* the dataspace can be selected and selections can be removed, as well.
@@ -223,8 +296,304 @@ H5_DLL hid_t H5Screate(H5S_class_t type);
*
*/
H5_DLL hid_t H5Screate_simple(int rank, const hsize_t dims[], const hsize_t maxdims[]);
-/*--------------------------------------------------------------------------*/
-/**\ingroup H5S
+/**
+ * \ingroup H5S
+ *
+ * \brief Decodes a binary object description of data space and returns a
+ * new object handle
+ *
+ * \param[in] buf Buffer for the data space object to be decoded
+ *
+ * \return \hid_t{dataspace}
+ *
+ * \details Given an object description of a dataspace in binary in a
+ * buffer, H5Sdecode() reconstructs the HDF5 data type object and
+ * returns a new object handle for it. The binary description of the
+ * object is encoded by H5Sencode(). The user is responsible for
+ * passing in the right buffer. The types of dataspace addressed
+ * in this function are null, scalar, and simple space. For a
+ * simple dataspace, the selection information (for example,
+ * hyperslab selection) is also encoded and decoded. A complex
+ * dataspace has not been implemented in the library.
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL hid_t H5Sdecode(const void *buf);
+/**
+ * \ingroup H5S
+ *
+ * \brief Encodes a data space object description into a binary buffer
+ *
+ * \space_id{obj_id}
+ * \param[in,out] buf Buffer for the object to be encoded into;
+ * If the provided buffer is NULL, only the size
+ * of buffer needed is returned through \p nalloc.
+ * \param[in,out] nalloc The size of the allocated buffer
+ * \fapl_id{fapl}
+ *
+ * \return \herr_t
+ *
+ * \details Given the data space identifier \p obj_id, H5Sencode2() converts
+ * a data space description into binary form in a buffer. Using this
+ * binary form in the buffer, a data space object can be
+ * reconstructed with H5Sdecode() to return a new object handle
+ * (#hid_t) for this data space.
+ *
+ * A preliminary H5Sencode2() call can be made to determine the
+ * size of the buffer needed. This value is returned in \p nalloc.
+ * That value can then be assigned to \p nalloc for a second
+ * H5Sencode2() call, which will retrieve the actual encoded object.
+ *
+ * If the library determines that \p nalloc is not big enough for the
+ * object, it simply returns the size of the buffer needed through
+ * \p nalloc without encoding the provided buffer.
+ *
+ * The file access property list \p fapl_id is used to control the
+ * encoding via the \a libver_bounds property (see
+ * H5Pset_libver_bounds()). If the \a libver_bounds property is missing,
+ * H5Sencode2() proceeds as if the \a libver_bounds property were set to
+ * (#H5F_LIBVER_EARLIEST, #H5F_LIBVER_LATEST). (Functionally,
+ * H5Sencode1() is identical to H5Sencode2() with \a libver_bounds set to
+ * (#H5F_LIBVER_EARLIEST, #H5F_LIBVER_LATEST).)
+ *
+ * The types of data space that are addressed in this function are
+ * null, scalar, and simple space. For a simple data space, the
+ * information on the selection, for example, hyperslab selection,
+ * is also encoded and decoded. A complex data space has not been
+ * implemented in the library.
+ *
+ * \note Motivation: This function was introduced in HDF5-1.12 as part of the
+ * H5Sencode() format change to enable 64-bit selection encodings and
+ * a dataspace selection that is tied to a file. See the New Features
+ * in HDF5 Release 1.12 as well as the H5Sencode() / H5Sdecode() Format Change RFC.
+ *
+ * \todo Fix the references.
+ *
+ * \since 1.12.0
+ *
+ */
+H5_DLL herr_t H5Sencode2(hid_t obj_id, void *buf, size_t *nalloc, hid_t fapl);
+/**
+ * \ingroup H5S
+ *
+ * \brief Copies the extent of a dataspace
+ *
+ * \space_id{dst_id}
+ * \space_id{src_id}
+ *
+ * \return \herr_t
+ *
+ * \details H5Sextent_copy() copies the extent from \p src_id to \p dst_id.
+ * This action may change the type of the dataspace.
+ *
+ * \version 1.4.0 Fortran subroutine was introduced.
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Sextent_copy(hid_t dst_id,hid_t src_id);
+/**
+ * \ingroup H5S
+ *
+ * \brief Determines whether two dataspace extents are equal
+ *
+ * \space_id{space1_id}
+ * \space_id{space2_id}
+ *
+ * \return \htri_t
+ *
+ * \details H5Sextent_equal() determines whether the dataspace extents of
+ * two dataspaces, \p space1_id and \p space2_id, are equal.
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL htri_t H5Sextent_equal(hid_t space1_id, hid_t space2_id);
+/**
+ * \ingroup H5S
+ *
+ * \brief Retrieves a regular hyperslab selection
+ *
+ * \space_id{spaceid}
+ * \param[out] start Offset of the start of the regular hyperslab
+ * \param[out] stride Stride of the regular hyperslab
+ * \param[out] count Number of blocks in the regular hyperslab
+ * \param[out] block Size of a block in the regular hyperslab
+ *
+ * \return \herr_t
+ *
+ * \details H5Sget_regular_hyperslab() takes the dataspace identifier,
+ * \p spaceid, and retrieves the values of \p start, \p stride,
+ * \p count, and \p block for the regular hyperslab selection.
+ *
+ * A regular hyperslab selection is a hyperslab selection
+ * described by setting the \p offset, \p stride, \p count, and
+ * \p block parameters to the H5Sselect_hyperslab() call. If
+ * several calls to H5Sselect_hyperslab() are needed, the
+ * hyperslab selection is irregular.
+ *
+ * See H5Sselect_hyperslab() for descriptions of \p offset,
+ * \p stride, \p count, and \p block.
+ *
+ * \note If a hyperslab selection is originally regular, then becomes
+ * irregular through selection operations, and then becomes regular
+ * again, the final regular selection may be equivalent but not
+ * identical to the original regular selection.
+ *
+ * \since 1.10.0
+ *
+ */
+H5_DLL htri_t H5Sget_regular_hyperslab(hid_t spaceid, hsize_t start[],
+ hsize_t stride[], hsize_t count[], hsize_t block[]);
+/**
+ * \ingroup H5S
+ *
+ * \brief Gets the bounding box containing the current selection
+ *
+ * \space_id{spaceid}
+ * \param[out] start Starting coordinates of the bounding box
+ * \param[out] end Ending coordinates of the bounding box, i.e., the
+ * coordinates of the diagonally opposite corner
+ *
+ * \return \herr_t
+ *
+ * \details H5Sget_select_bounds() retrieves the coordinates of the bounding
+ * box containing the current selection and places them into
+ * user-supplied buffers.
+ *
+ * The \p start and \p end buffers must be large enough to hold
+ * the dataspace rank number of coordinates.
+ *
+ * The bounding box exactly contains the selection. I.e., if a
+ * 2-dimensional element selection is currently defined as containing
+ * the points (4,5), (6,8), and (10,7), then the bounding box
+ * will be (4, 5), (10, 8).
+ *
+ * The bounding box calculation includes the current offset of the
+ * selection within the dataspace extent.
+ *
+ * Calling this function on a \a none selection will fail.
+ *
+ * \version 1.6.0 The \p start and \p end parameters have changed from type
+ * \p hsize_t * to \p hssize_t *.
+ * \version 1.4.0 Fortran subroutine was introduced.
+ * \since 1.2.0
+ *
+ */
+H5_DLL herr_t H5Sget_select_bounds(hid_t spaceid, hsize_t start[],
+ hsize_t end[]);
+/**
+ * \ingroup H5S
+ *
+ * \brief Gets the number of element points in the current selection
+ *
+ * \space_id{spaceid}
+ *
+ * \return Returns the number of element points in the current dataspace
+ * selection if successful. Otherwise returns a negative value.
+ *
+ * \details H5Sget_select_elem_npoints() returns the number of element
+ * points in the current dataspace selection, so that the element
+ * points can be retrieved with H5Sget_select_elem_pointlist().
+ * (This is similar to the way that H5Sget_select_hyper_nblocks()
+ * and H5Sget_select_hyper_blocklist() work with hyperslab
+ * selections.)
+ *
+ * Coincidentally, H5Sget_select_npoints() and
+ * H5Sget_select_elem_npoints() will always return the same value
+ * when an element selection is queried, but
+ * H5Sget_select_elem_npoints() does not work with other selection
+ * types.
+ *
+ * \since 1.2.0
+ *
+ */
+H5_DLL hssize_t H5Sget_select_elem_npoints(hid_t spaceid);
+/**
+ * \ingroup H5S
+ *
+ * \brief Gets the list of element points currently selected
+ *
+ * \space_id{spaceid}
+ * \param[in] startpoint Element point to start with
+ * \param[in] numpoints Number of element points to get
+ * \param[out] buf List of element points selected
+ *
+ * \details H5Sget_select_elem_pointlist() returns the list of element
+ * points in the current dataspace selection \p space_id. Starting
+ * with the \p startpoint in the list of points, \p numpoints
+ * points are put into the user's buffer. If the user's buffer
+ * fills up before \p numpoints points are inserted, the buffer
+ * will contain only as many points as fit.
+ *
+ * The element point coordinates have the same dimensionality
+ * (rank) as the dataspace they are located within. The list of
+ * element points is formatted as follows:\n
+ * \<coordinate\>, followed by\n
+ * the next coordinate,\n
+ * etc.\n
+ * until all of the selected element points have been listed.
+ *
+ * The points are returned in the order they will be iterated
+ * through when the selection is read/written from/to disk.
+ *
+ * \since 1.2.0
+ *
+ */
+H5_DLL herr_t H5Sget_select_elem_pointlist(hid_t spaceid, hsize_t startpoint,
+ hsize_t numpoints, hsize_t buf[/*numpoints*/]);
+/**
+ * \ingroup H5S
+ *
+ * \brief Gets the list of hyperslab blocks currently selected
+ *
+ * \space_id{spaceid}
+ * \param[in] startblock Hyperslab block to start with
+ * \param[in] numblocks Number of hyperslab blocks to get
+ * \param[out] buf List of hyperslab blocks selected
+ *
+ * \return \herr_t
+ *
+ * \details H5Sget_select_hyper_blocklist() returns a list of the hyperslab
+ * blocks currently selected. Starting with the \p startblock-th block
+ * in the list of blocks, \p numblocks blocks are put into the
+ * user's buffer. If the user's buffer fills up before \p numblocks
+ * blocks are inserted, the buffer will contain only as many blocks
+ * as fit.
+ *
+ * The block coordinates have the same dimensionality (rank) as the
+ * dataspace they are located within. The list of blocks is
+ * formatted as follows:\n
+ * \<"start" coordinate\>, immediately followed by\n
+ * \<"opposite" corner coordinate\>, followed by\n
+ * the next "start" and "opposite" coordinates,\n
+ * etc. until all of the selected blocks have been listed.\n
+ * No guarantee of any order of the blocks is implied.
+ *
+ * \since 1.2.0
+ *
+ */
+H5_DLL herr_t H5Sget_select_hyper_blocklist(hid_t spaceid, hsize_t startblock,
+ hsize_t numblocks, hsize_t buf[/*numblocks*/]);
+/**
+ * \ingroup H5S
+ *
+ * \brief Get number of hyperslab blocks
+ *
+ * \space_id{spaceid}
+ *
+ * \return Returns the number of hyperslab blocks in the current dataspace
+ * selection if successful. Otherwise returns a negative value.
+ *
+ * \details H5Sget_select_hyper_nblocks() returns the number of hyperslab
+ * blocks in the current dataspace selection.
+ *
+ * \since 1.2.0
+ *
+ */
+H5_DLL hssize_t H5Sget_select_hyper_nblocks(hid_t spaceid);
+/**
+ * \ingroup H5S
*
* \brief Determines the number of elements in a dataspace selection
*
@@ -243,8 +612,47 @@ H5_DLL hid_t H5Screate_simple(int rank, const hsize_t dims[], const hsize_t maxd
*
*/
H5_DLL hssize_t H5Sget_select_npoints(hid_t spaceid);
-/*-------------------------------------------------------------------------*/
-/**\ingroup H5S
+/**
+ * \ingroup H5S
+ *
+ * \brief Determines the type of the dataspace selection
+ *
+ * \space_id{spaceid}
+ *
+ * \return Returns the dataspace selection type, a value of the enumerated
+ * datatype #H5S_sel_type, if successful.
+ *
+ * \details H5Sget_select_type() retrieves the type of dataspace selection
+ * currently defined for the dataspace \p space_id. Valid values
+ * for the dataspace selection type are:
+ *
+ * <table>
+ * <tr>
+ * <td>#H5S_SEL_NONE</td>
+ * <td>No selection is defined</td>
+ * </tr>
+ * <tr>
+ * <td>#H5S_SEL_POINTS</td>
+ * <td>A sequence of points is selected</td>
+ * </tr>
+ * <tr>
+ * <td>#H5S_SEL_HYPERSLABS</td>
+ * <td>A hyperslab or compound hyperslab is selected</td>
+ * </tr>
+ * <tr>
+ * <td>#H5S_SEL_ALL</td>
+ * <td>The entire dataset is selected</td>
+ * </tr>
+ * </table>
+ *
+ * Otherwise returns a negative value.
+ *
+ * \since 1.6.0
+ *
+ */
+H5_DLL H5S_sel_type H5Sget_select_type(hid_t spaceid);
+/**
+ * \ingroup H5S
*
* \brief Retrieves dataspace dimension size and maximum size
*
@@ -269,9 +677,10 @@ H5_DLL hssize_t H5Sget_select_npoints(hid_t spaceid);
* \since 1.0.0
*
*/
-H5_DLL int H5Sget_simple_extent_dims(hid_t space_id, hsize_t dims[], hsize_t maxdims[]);
-/*-------------------------------------------------------------------------*/
-/**\ingroup H5S
+H5_DLL int H5Sget_simple_extent_dims(hid_t space_id, hsize_t dims[],
+ hsize_t maxdims[]);
+/**
+ * \ingroup H5S
*
* \brief Determines the dimensionality of a dataspace
*
@@ -288,9 +697,391 @@ H5_DLL int H5Sget_simple_extent_dims(hid_t space_id, hsize_t dims[], hsize_t max
*
*/
H5_DLL int H5Sget_simple_extent_ndims(hid_t space_id);
-/*--------------------------------------------------------------------------*/
+/**
+ * \ingroup H5S
+ *
+ * \brief Determines the number of elements in a dataspace
+ *
+ * \space_id
+ *
+ * \return Returns the number of elements in the dataspace if successful;
+ * otherwise returns a negative value.
+ *
+ * \details H5Sget_simple_extent_npoints() determines the number of elements
+ * in a dataspace \p space_id. For example, a simple 3-dimensional
+ * dataspace with dimensions 2, 3, and 4 would have 24 elements.
+ *
+ * \version 1.4.0 Fortran subroutine introduced.
+ * \since 1.0.0
+ *
+ */
+H5_DLL hssize_t H5Sget_simple_extent_npoints(hid_t space_id);
+/**
+ * \ingroup H5S
+ *
+ * \brief Determines the current class of a dataspace
+ *
+ * \space_id
+ *
+ * \return Returns a dataspace class name if successful;
+ * otherwise #H5S_NO_CLASS (-1).
+ *
+ * \details H5Sget_simple_extent_type() determines the current class of a
+ * dataspace \p space_id.
+ *
+ * \version 1.4.0 Fortran subroutine was introduced.
+ * \since 1.0.0
+ *
+ */
+H5_DLL H5S_class_t H5Sget_simple_extent_type(hid_t space_id);
+/**
+ * \ingroup H5S
+ *
+ * \brief Determines if a hyperslab selection is regular
+ *
+ * \space_id{spaceid}
+ *
+ * \return \htri_t
+ *
+ * \details H5Sis_regular_hyperslab() takes the dataspace identifier,
+ * \p spaceid, and queries the type of the hyperslab selection.
+ *
+ * A regular hyperslab selection is a hyperslab selection described
+ * by setting the offset, stride, count, and block parameters for
+ * a single H5Sselect_hyperslab() call. If several calls to
+ * H5Sselect_hyperslab() are needed, then the hyperslab selection
+ * is irregular.
+ *
+ * \since 1.10.0
+ *
+ */
+H5_DLL htri_t H5Sis_regular_hyperslab(hid_t spaceid);
+/**
+ * \ingroup H5S
+ *
+ * \brief Determines whether a dataspace is a simple dataspace
+ *
+ * \space_id
+ *
+ * \return \htri_t
+ *
+ * \details H5Sis_simple() determines whether or not a dataspace is a simple
+ * dataspace.
+ *
+ * \note Currently, all dataspace objects are simple dataspaces; complex
+ * dataspace support will be added in the future.
+ *
+ * \version 1.4.0 Fortran subroutine was introduced.
+ * \since 1.0.0
+ *
+ */
+H5_DLL htri_t H5Sis_simple(hid_t space_id);
+/**
+ * \ingroup H5S
+ *
+ * \brief Refines a hyperslab selection with an operation, using a second
+ * hyperslab to modify it
+ *
+ * \space_id{space1_id}
+ * \param[in] op Selection operator
+ * \space_id{space2_id}
+ *
+ * \return \herr_t
+ *
+ * \details H5Smodify_select() refines an existing hyperslab selection
+ * \p space1_id with an operation \p op, using a second hyperslab
+ * \p space2_id. The first selection is modified to contain the
+ * result of \p space1_id operated on by \p space2_id.
+ *
+ * \since 1.12.0
+ *
+*/
+H5_DLL herr_t H5Smodify_select(hid_t space1_id, H5S_seloper_t op, hid_t space2_id);
+/**
+ * \ingroup H5S
+ *
+ * \brief Sets the offset of a simple dataspace
+ *
+ * \space_id
+ * \param[in] offset The offset at which to position the selection
+ *
+ * \return \herr_t
+ *
+ * \details H5Soffset_simple() sets the offset of a simple dataspace
+ * \p space_id. The offset array must be the same number of
+ * elements as the number of dimensions for the dataspace. If the
+ * \p offset array is set to NULL, the offset for the dataspace is
+ * reset to 0.
+ *
+ * This function allows the same shaped selection to be moved to
+ * different locations within a dataspace without requiring it to
+ * be redefined.
+ *
+ * \version 1.4.0 Fortran subroutine was introduced.
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Soffset_simple(hid_t space_id, const hssize_t *offset);
+/**
+ * \ingroup H5S
+ *
+ * \brief Closes a dataspace selection iterator
+ *
+ * \space_id{sel_iter_id}
+ *
+ * \return \herr_t
+ *
+ * \details H5Ssel_iter_close() closes a dataspace selection iterator
+ * specified by \p sel_iter_id, releasing its state.
+ *
+ * \since 1.12.0
+ *
+ */
+H5_DLL herr_t H5Ssel_iter_close(hid_t sel_iter_id);
/**\ingroup H5S
*
+ * \brief Creates a dataspace selection iterator for a dataspace's selection
+ *
+ * \space_id{spaceid}
+ * \param[in] elmt_size Size of element in the selection
+ * \param[in] flags Selection iterator flag
+ *
+ * \return \hid_t{valid dataspace selection iterator}
+ *
+ * \details H5Ssel_iter_create() creates a selection iterator and initializes
+ * it to start at the first element selected in the dataspace.
+ *
+ * \since 1.12.0
+ *
+ */
+H5_DLL hid_t H5Ssel_iter_create(hid_t spaceid, size_t elmt_size, unsigned flags);
+/**
+ * \ingroup H5S
+ *
+ * \brief Retrieves a list of offset / length sequences for the elements in
+ * an iterator
+ *
+ * \space_id{sel_iter_id}
+ * \param[in] maxseq Maximum number of sequences to retrieve
+ * \param[in] maxbytes Maximum number of bytes to retrieve in sequences
+ * \param[out] nseq Number of sequences retrieved
+ * \param[out] nbytes Number of bytes retrieved, in all sequences
+ * \param[out] off Array of sequence offsets
+ * \param[out] len Array of sequence lengths
+ *
+ * \return \herr_t
+ *
+ * \details H5Ssel_iter_get_seq_list() retrieves a list of offset / length
+ * pairs (a list of "sequences") matching the selected elements for
+ * an iterator \p sel_iter_id, according to the iteration order for
+ * the iterator. The lengths returned are in bytes, not elements.
+ *
+ * Note that the iteration order for "all" and "hyperslab"
+ * selections is row-major (i.e. "C-ordered"), but the iteration
+ * order for "point" selections is "in order selected", unless the
+ * #H5S_SEL_ITER_GET_SEQ_LIST_SORTED flag is passed to
+ * H5Ssel_iter_create() for a point selection.
+ *
+ * \p maxseq and \p maxbytes specify the most sequences or bytes
+ * possible to place into the \p off and \p len arrays. \p nseq and
+ * \p nbytes return the actual number of sequences and bytes put
+ * into the arrays.
+ *
+ * Each call to H5Ssel_iter_get_seq_list() will retrieve the next
+ * set of sequences for the selection being iterated over.
+ *
+ * The total number of bytes possible to retrieve from a selection
+ * iterator is the \p elmt_size passed to H5Ssel_iter_create()
+ * multiplied by the number of elements selected in the dataspace
+ * the iterator was created from (which can be retrieved with
+ * H5Sget_select_npoints(). When there are no further sequences of
+ * elements to retrieve, calls to this routine will set \p nseq
+ * and \p nbytes to zero.
+ *
+ * \since 1.12.0
+ *
+ */
+H5_DLL herr_t H5Ssel_iter_get_seq_list(hid_t sel_iter_id, size_t maxseq,
+ size_t maxbytes, size_t *nseq, size_t *nbytes, hsize_t *off, size_t *len);
+/**
+ * \ingroup H5S
+ *
+ * \brief Resets a dataspace selection iterator back to an initial state
+ *
+ * \param[in] sel_iter_id Identifier of the dataspace selection iterator
+ * to reset
+ * \param[in] space_id Identifier of the dataspace with selection to
+ * iterate over
+ *
+ * \return \herr_t
+ *
+ * \details H5Ssel_iter_reset() resets a dataspace selection iterator back to
+ * an initial state so that the iterator may be used for iteration
+ * once again.
+ *
+ * \since 1.12.1
+ *
+ */
+H5_DLL herr_t H5Ssel_iter_reset(hid_t sel_iter_id, hid_t space_id);
+/**
+ * \ingroup H5S
+ *
+ * \brief Adjusts a selection by subtracting an offset
+ *
+ * \space_id{spaceid}
+ * \param[in] offset Offset to subtract
+ *
+ * \return \herr_t
+ *
+ * \details H5Sselect_adjust() shifts a dataspace selection by a specified
+ * logical offset within the dataspace extent.
+ *
+ * \note This can be useful for VOL developers to implement chunked datasets.
+ *
+ * \since 1.12.0
+ */
+H5_DLL herr_t H5Sselect_adjust(hid_t spaceid, const hssize_t *offset);
+/**
+ * \ingroup H5S
+ *
+ * \brief Selects an entire dataspace
+ *
+ * \space_id{spaceid}
+ *
+ * \return \herr_t
+ *
+ * \details H5Sselect_all() selects the entire extent of the dataspace
+ * \p dspace_id.
+ *
+ * More specifically, H5Sselect_all() sets the selection type to
+ * #H5S_SEL_ALL, which specifies the entire dataspace anywhere it
+ * is applied.
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Sselect_all(hid_t spaceid);
+/**
+ * \ingroup H5S
+ *
+ * \brief Copies a selection from one dataspace to another
+ *
+ * \space_id{dst_id}
+ * \space_id{src_id}
+ *
+ * \return \herr_t
+ *
+ * \details H5Sselect_copy() copies all selection information (including
+ * offset) from the source dataspace \p src_id to the destination
+ * dataspace \p dst_id.
+ *
+ * \since 1.12.0
+ *
+ */
+H5_DLL herr_t H5Sselect_copy(hid_t dst_id, hid_t src_id);
+/**
+ * \ingroup H5S
+ *
+ * \brief Selects array elements to be included in the selection for a
+ * dataspace
+ *
+ * \space_id
+ * \param[in] op Operator specifying how the new selection is to be
+ * combined with the existing selection for the dataspace
+ * \param[in] num_elem Number of elements to be selected
+ * \param[in] coord A pointer to a buffer containing a serialized copy of
+ * a 2-dimensional array of zero-based values specifying
+ * the coordinates of the elements in the point selection
+ *
+ * \return \herr_t
+ *
+ * \details H5Sselect_elements() selects array elements to be included in
+ * the selection for the \p space_id dataspace. This is referred
+ * to as a point selection.
+ *
+ * The number of elements selected is set in the \p num_elements
+ * parameter.
+ *
+ * The \p coord parameter is a pointer to a buffer containing a
+ * serialized 2-dimensional array of size \p num_elements by the
+ * rank of the dataspace. The array lists dataset elements in the
+ * point selection; that is, it’s a list of of zero-based values
+ * specifying the coordinates in the dataset of the selected
+ * elements. The order of the element coordinates in the \p coord
+ * array specifies the order in which the array elements are
+ * iterated through when I/O is performed. Duplicate coordinate
+ * locations are not checked for. See below for examples of the
+ * mapping between the serialized contents of the buffer and the
+ * point selection array that it represents.
+ *
+ * The selection operator \p op determines how the new selection
+ * is to be combined with the previously existing selection for
+ * the dataspace. The following operators are supported:
+ *
+ * <table>
+ * <tr>
+ * <td>#H5S_SELECT_SET</td>
+ * <td>Replaces the existing selection with the parameters from
+ * this call. Overlapping blocks are not supported with this
+ * operator. Adds the new selection to the existing selection.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>#H5S_SELECT_APPEND</td>
+ * <td>Adds the new selection following the last element of the
+ * existing selection.</td>
+ * </tr>
+ * <tr>
+ * <td>#H5S_SELECT_PREPEND</td>
+ * <td>Adds the new selection preceding the first element of the
+ * existing selection.</td>
+ * </tr>
+ * </table>
+ *
+ * <b>Mapping the serialized \p coord buffer to a 2-dimensional
+ * point selection array:</b>
+ * To illustrate the construction of the contents of the \p coord
+ * buffer, consider two simple examples: a selection of 5 points in
+ * a 1-dimensional array and a selection of 3 points in a
+ * 4-dimensional array.
+ *
+ * In the 1D case, we will be selecting five points and a 1D
+ * dataspace has rank 1, so the selection will be described in a
+ * 5-by-1 array. To select the 1st, 14th, 17th, 23rd, 8th elements
+ * of the dataset, the selection array would be as follows
+ * (remembering that point coordinates are zero-based):
+ * \n 0
+ * \n 13
+ * \n 16
+ * \n 22
+ * \n 7
+ *
+ * This point selection array will be serialized in the \p coord
+ * buffer as:
+ * \n 0 13 16 22 7
+ *
+ * In the 4D case, we will be selecting three points and a 4D
+ * dataspace has rank 4, so the selection will be described in a
+ * 3-by-4 array. To select the points (1,1,1,1), (14,6,12,18), and
+ * (8,22,30,22), the point selection array would be as follows:
+ * \n 0 0 0 0
+ * \n 13 5 11 17
+ * \n 7 21 29 21
+ *
+ * This point selection array will be serialized in the \p coord
+ * buffer as:
+ * \n 0 0 0 0 13 5 11 17 7 21 29 21
+ *
+ * \version 1.6.4 C coord parameter type changed to \p const #hsize_t.
+ * \version 1.6.4 Fortran \p coord parameter type changed to \p INTEGER(HSIZE_T).
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Sselect_elements(hid_t space_id, H5S_seloper_t op,
+ size_t num_elem, const hsize_t *coord);
+/**
+ * \ingroup H5S
+ *
* \brief Selects a hyperslab region to add to the current selected region
*
* \space_id
@@ -393,53 +1184,165 @@ H5_DLL int H5Sget_simple_extent_ndims(hid_t space_id);
* \since 1.0.0
*
*/
-H5_DLL herr_t H5Sselect_hyperslab(hid_t space_id, H5S_seloper_t op, const hsize_t start[],
- const hsize_t stride[], const hsize_t count[], const hsize_t block[]);
-H5_DLL herr_t H5Sset_extent_simple(hid_t space_id, int rank, const hsize_t dims[], const hsize_t max[]);
-H5_DLL hid_t H5Scopy(hid_t space_id);
-H5_DLL herr_t H5Sencode2(hid_t obj_id, void *buf, size_t *nalloc, hid_t fapl);
-H5_DLL hid_t H5Sdecode(const void *buf);
-H5_DLL hssize_t H5Sget_simple_extent_npoints(hid_t space_id);
-H5_DLL htri_t H5Sis_simple(hid_t space_id);
-H5_DLL H5S_class_t H5Sget_simple_extent_type(hid_t space_id);
-H5_DLL herr_t H5Sset_extent_none(hid_t space_id);
-H5_DLL herr_t H5Sextent_copy(hid_t dst_id, hid_t src_id);
-H5_DLL htri_t H5Sextent_equal(hid_t sid1, hid_t sid2);
-
-/* Operations on dataspace selections */
-H5_DLL H5S_sel_type H5Sget_select_type(hid_t spaceid);
-H5_DLL herr_t H5Sselect_copy(hid_t dst_id, hid_t src_id);
-H5_DLL htri_t H5Sselect_valid(hid_t spaceid);
-H5_DLL herr_t H5Sselect_adjust(hid_t spaceid, const hssize_t *offset);
-H5_DLL herr_t H5Sget_select_bounds(hid_t spaceid, hsize_t start[], hsize_t end[]);
-H5_DLL htri_t H5Sselect_shape_same(hid_t space1_id, hid_t space2_id);
-H5_DLL htri_t H5Sselect_intersect_block(hid_t space_id, const hsize_t *start, const hsize_t *end);
-H5_DLL herr_t H5Soffset_simple(hid_t space_id, const hssize_t *offset);
-H5_DLL herr_t H5Sselect_all(hid_t spaceid);
-H5_DLL herr_t H5Sselect_none(hid_t spaceid);
-H5_DLL herr_t H5Sselect_elements(hid_t space_id, H5S_seloper_t op, size_t num_elem, const hsize_t *coord);
-H5_DLL hssize_t H5Sget_select_elem_npoints(hid_t spaceid);
-H5_DLL herr_t H5Sget_select_elem_pointlist(hid_t spaceid, hsize_t startpoint, hsize_t numpoints,
- hsize_t buf[/*numpoints*/]);
-H5_DLL hid_t H5Scombine_hyperslab(hid_t space_id, H5S_seloper_t op, const hsize_t start[],
- const hsize_t _stride[], const hsize_t count[], const hsize_t _block[]);
-H5_DLL herr_t H5Smodify_select(hid_t space1_id, H5S_seloper_t op, hid_t space2_id);
-H5_DLL hid_t H5Scombine_select(hid_t space1_id, H5S_seloper_t op, hid_t space2_id);
-H5_DLL htri_t H5Sis_regular_hyperslab(hid_t spaceid);
-H5_DLL htri_t H5Sget_regular_hyperslab(hid_t spaceid, hsize_t start[], hsize_t stride[], hsize_t count[],
- hsize_t block[]);
-H5_DLL hssize_t H5Sget_select_hyper_nblocks(hid_t spaceid);
-H5_DLL herr_t H5Sget_select_hyper_blocklist(hid_t spaceid, hsize_t startblock, hsize_t numblocks,
- hsize_t buf[/*numblocks*/]);
-H5_DLL hid_t H5Sselect_project_intersection(hid_t src_space_id, hid_t dst_space_id,
- hid_t src_intersect_space_id);
-
-/* Operations on dataspace selection iterators */
-H5_DLL hid_t H5Ssel_iter_create(hid_t spaceid, size_t elmt_size, unsigned flags);
-H5_DLL herr_t H5Ssel_iter_get_seq_list(hid_t sel_iter_id, size_t maxseq, size_t maxbytes, size_t *nseq,
- size_t *nbytes, hsize_t *off, size_t *len);
-H5_DLL herr_t H5Ssel_iter_reset(hid_t sel_iter_id, hid_t space_id);
-H5_DLL herr_t H5Ssel_iter_close(hid_t sel_iter_id);
+H5_DLL herr_t H5Sselect_hyperslab(hid_t space_id, H5S_seloper_t op,
+ const hsize_t start[], const hsize_t stride[], const hsize_t count[],
+ const hsize_t block[]);
+/*--------------------------------------------------------------------------*/
+/**\ingroup H5S
+ *
+ * \brief Checks if current selection intersects with a block
+ *
+ * \space_id
+ * \param[in] start Starting coordinate of block
+ * \param[in] end Opposite ("ending") coordinate of block
+ *
+ * \return \htri_t
+ *
+ * \details H5Sselect_intersect_block() checks to see if the current
+ * selection \p space_id in the dataspace intersects with the block
+ * specified by \p start and \p end.
+ *
+ * \note Assumes that \p start & \p end block bounds are inclusive, so
+ * \p start == \p end value is OK.
+ *
+ * \since 1.12.0
+ *
+ */
+H5_DLL htri_t H5Sselect_intersect_block(hid_t space_id, const hsize_t *start,
+ const hsize_t *end);
+/*--------------------------------------------------------------------------*/
+/**\ingroup H5S
+ *
+ * \brief Resets the selection region to include no elements
+ *
+ * \space_id{spaceid}
+ *
+ * \return \herr_t
+ *
+ * \details H5Sselect_none() resets the selection region for the dataspace
+ * \p space_id to include no elements.
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Sselect_none(hid_t spaceid);
+/*--------------------------------------------------------------------------*/
+/**\ingroup H5S
+ *
+ * \brief Projects the intersection of two source selections to a
+ * destination selection
+ *
+ * \space_id{src_space_id}
+ * \space_id{dst_space_id}
+ * \space_id{src_intersect_space_id}
+ *
+ * \return Returns a dataspace with a selection equal to the intersection of
+ * \p src_intersect_space_id and \p src_space_id projected from
+ * \p src_space to \p dst_space on success, negative on failure.
+ *
+ * \details H5Sselect_project_intersection() computes the intersection
+ * between two dataspace selections and projects that intersection
+ * into a third selection.This can be useful for VOL developers to
+ * implement chunked or virtual datasets.
+ *
+ * \since 1.12.0
+ *
+ */
+H5_DLL hid_t H5Sselect_project_intersection(hid_t src_space_id,
+ hid_t dst_space_id, hid_t src_intersect_space_id);
+/*--------------------------------------------------------------------------*/
+/**\ingroup H5S
+ *
+ * \brief Checks if two selections are the same shape
+ *
+ * \space_id{space1_id}
+ * \space_id{space2_id}
+ *
+ * \return \htri_t
+ *
+ * \details H5Sselect_shape_same() checks to see if the current selection
+ * in the dataspaces are the same dimensionality and shape.
+ *
+ * This is primarily used for reading the entire selection in
+ * one swoop.
+ *
+ * \since 1.12.0
+ *
+ */
+H5_DLL htri_t H5Sselect_shape_same(hid_t space1_id, hid_t space2_id);
+/*--------------------------------------------------------------------------*/
+/**\ingroup H5S
+ *
+ * \brief Verifies that the selection is within the extent of the dataspace
+ *
+ * \space_id{spaceid}
+ *
+ * \return \htri_t
+ *
+ * \details H5Sselect_valid() verifies that the selection for the dataspace
+ * \p space_id is within the extent of the dataspace if the current
+ * offset for the dataspace is used.
+ *
+ * \version 1.4.0 Fortran subroutine introduced in this release.
+ * \since 1.0.0
+ *
+ */
+H5_DLL htri_t H5Sselect_valid(hid_t spaceid);
+/*--------------------------------------------------------------------------*/
+/**\ingroup H5S
+ *
+ * \brief Resets the extent of a dataspace back to "none"
+ *
+ * \space_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Sset_extent_none() resets the type of a dataspace to
+ * #H5S_NULL with no extent information stored for the dataspace.
+ *
+ * \version 1.10.7, 1.12.1 The function behavior changed. The previous
+ * behavior was to set the class to #H5S_NO_CLASS.
+ * \version 1.4.0 Fortran subroutine was introduced.
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Sset_extent_none(hid_t space_id);
+/*--------------------------------------------------------------------------*/
+/**\ingroup H5S
+ *
+ * \brief Sets or resets the size of an existing dataspace
+ *
+ * \space_id
+ * \param[in] rank Rank, or dimensionality, of the dataspace
+ * \param[in] dims Array containing current size of dataspace
+ * \param[in] max Array containing maximum size of dataspace
+ *
+ * \return \herr_t
+ *
+ * \details H5Sset_extent_simple() sets or resets the size of an existing
+ * dataspace.
+ *
+ * \p rank is the dimensionality, or number of dimensions, of the
+ * dataspace.
+ *
+ * \p dims is an array of size \p rank which contains the new size
+ * of each dimension in the dataspace. \p max is an array of size
+ * \p rank which contains the maximum size of each dimension in
+ * the dataspace.
+ *
+ * Any previous extent is removed from the dataspace, the dataspace
+ * type is set to #H5S_SIMPLE, and the extent is set as specified.
+ *
+ * Note that a dataset must be chunked if \p dims does not equal
+ * \p max.
+ *
+ *
+ * \version 1.4.0 Fortran subroutine was introduced.
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Sset_extent_simple(hid_t space_id, int rank,
+ const hsize_t dims[], const hsize_t max[]);
/* Symbols defined for compatibility with previous versions of the HDF5 API.
*
@@ -447,6 +1350,47 @@ H5_DLL herr_t H5Ssel_iter_close(hid_t sel_iter_id);
*/
#ifndef H5_NO_DEPRECATED_SYMBOLS
/* Function prototypes */
+/* --------------------------------------------------------------------------*/
+/**\ingroup H5S
+ *
+ * \brief Encodes a data space object description into a binary buffer
+ *
+ * \space_id{obj_id}
+ * \param[in,out] buf Buffer for the object to be encoded into;
+ * If the provided buffer is NULL, only the size of
+ * buffer needed is returned through \p nalloc.
+ * \param[in,out] nalloc The size of the allocated buffer
+ *
+ * \return \herr_t
+ *
+ * \deprecated Deprecated in favor of H5Sencode2()
+ *
+ * \details Given the data space identifier \p obj_id, H5Sencode1() converts
+ * a data space description into binary form in a buffer. Using
+ * this binary form in the buffer, a data space object can be
+ * reconstructed using H5Sdecode() to return a new object handle
+ * (\p hid_t) for this data space.
+ *
+ * A preliminary H5Sencode1() call can be made to find out the size
+ * of the buffer needed. This value is returned as \p nalloc. That
+ * value can then be assigned to \p nalloc for a second H5Sencode1()
+ * call, which will retrieve the actual encoded object.
+ *
+ * If the library finds out \p nalloc is not big enough for the
+ * object, it simply returns the size of the buffer needed through
+ * \p nalloc without encoding the provided buffer.
+ *
+ * The types of data space addressed in this function are null,
+ * scalar, and simple space. For a simple data space, the information
+ * on the selection, for example, hyperslab selection, is also
+ * encoded and decoded. A complex data space has not been
+ * implemented in the library.
+ *
+ * \version 1.12.0 The function H5Sencode() was renamed H5Sencode1() and
+ * deprecated.
+ * \since 1.8.0
+ *
+ */
H5_DLL herr_t H5Sencode1(hid_t obj_id, void *buf, size_t *nalloc);
#endif /* H5_NO_DEPRECATED_SYMBOLS */