summaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
authorbljhdf <58825073+bljhdf@users.noreply.github.com>2020-11-23 22:17:44 (GMT)
committerGitHub <noreply@github.com>2020-11-23 22:17:44 (GMT)
commitc56464fc36a78167c22b84e4cfef0e0c2aafce80 (patch)
treee10abc0a4c439f6723295a3aa7227e3d54b4552c /src
parentecbcb4356c2bbdad7ad801f9c61fe695082a6b25 (diff)
downloadhdf5-c56464fc36a78167c22b84e4cfef0e0c2aafce80.zip
hdf5-c56464fc36a78167c22b84e4cfef0e0c2aafce80.tar.gz
hdf5-c56464fc36a78167c22b84e4cfef0e0c2aafce80.tar.bz2
Doxygen - added (mostly) beginner functions (#112)
* Doxygen - added (mostly) beginner functions * Removed duplicate H5Pset_szip function
Diffstat (limited to 'src')
-rw-r--r--src/H5Amodule.h17
-rw-r--r--src/H5Apublic.h341
-rw-r--r--src/H5Pmodule.h43
-rw-r--r--src/H5Ppublic.h868
-rw-r--r--src/H5Smodule.h27
-rw-r--r--src/H5Spublic.h282
6 files changed, 1551 insertions, 27 deletions
diff --git a/src/H5Amodule.h b/src/H5Amodule.h
index 707fc54..09e6c4a 100644
--- a/src/H5Amodule.h
+++ b/src/H5Amodule.h
@@ -29,4 +29,21 @@
#define H5_MY_PKG_ERR H5E_ATTR
#define H5_MY_PKG_INIT YES
+/**\defgroup H5A H5A
+ * \brief Attribute Interface
+ *
+ * \details The Attribute Interface, H5A, provides a mechanism for attaching
+ * additional information to a dataset, group, or named datatype.
+ *
+ * Attributes are accessed by opening the object that they are
+ * attached to and are not independent objects. Typically an
+ * attribute is small in size and contains user metadata about the
+ * object that it is attached to.
+ *
+ * Attributes look similar to HDF5 datasets in that they have a
+ * datatype and dataspace. However, they do not support partial
+ * I/O operations and cannot be compressed or extended.
+ *
+ */
+
#endif /* _H5Amodule_H */
diff --git a/src/H5Apublic.h b/src/H5Apublic.h
index 89a3b04..3b836e7 100644
--- a/src/H5Apublic.h
+++ b/src/H5Apublic.h
@@ -45,18 +45,306 @@ typedef herr_t (*H5A_operator2_t)(hid_t location_id /*in*/, const char *attr_nam
extern "C" {
#endif
+/*-------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Closes the specified attribute
+ *
+ * \attr_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Aclose() terminates access to the attribute specified by
+ * \p attr_id by releasing the identifier.
+ *
+ * \attention Further use of a released attribute identifier is illegal; a
+ * function using such an identifier will generate an error.
+ *
+ * \since 1.0.0
+ *
+ * \see H5Acreate(), H5Aopen()
+ */
+H5_DLL herr_t H5Aclose(hid_t attr_id);
+/* --------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Creates an attribute attached to a specified object
+ *
+ * \fgdt_loc_id
+ * \param[in] attr_name Name of attribute
+ * \param[in] type_id Attribute datatype identifier
+ * \space_id
+ * \acpl_id
+ * \aapl_id
+ *
+ * \return \hid_tv{attribute}
+ *
+ * \details H5Acreate2() creates an attribute, \p attr_name, which is attached
+ * to the object specified by the identifier \p loc_id.
+ *
+ * The attribute name, \p attr_name, must be unique for the object.
+ *
+ * The attribute is created with the specified datatype and dataspace,
+ * \p type_id and \p space_id, which are created with the H5T and
+ * H5S interfaces, respectively.
+ *
+ * If \p type_id is either a fixed-length or variable-length string,
+ * it is important to set the string length when defining the
+ * datatype. String datatypes are derived from #H5T_C_S1 (or
+ * #H5T_FORTRAN_S1 for Fortran), which defaults to 1 character in
+ * size. See H5Tset_size() and Creating variable-length string
+ * datatypes.
+ *
+ * The access property list is currently unused, but will be used in
+ * the future. This property list should currently be #H5P_DEFAULT.
+ *
+ * The attribute identifier returned by this function must be released
+ * with H5Aclose() resource leaks will develop.
+ *
+ * \note The \p acpl and \p aapl parameters are currently not used; specify
+ * #H5P_DEFAULT.
+ * \note If \p loc_id is a file identifier, the attribute will be attached
+ * that file’s root group.
+ *
+ * \since 1.8.0
+ *
+ * \see H5Aclose()
+ *
+ */
H5_DLL hid_t H5Acreate2(hid_t loc_id, const char *attr_name, hid_t type_id, hid_t space_id, hid_t acpl_id,
hid_t aapl_id);
+/*--------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Creates an attribute attached to a specified object
+ *
+ * \fgdt_loc_id
+ * \param[in] obj_name Name, relative to \p loc_id, of object that
+ * attribute is to be attached to
+ * \param[in] attr_name Attribute name
+ * \param[in] type_id Attribute datatype identifier
+ * \space_id
+ * \acpl_id
+ * \aapl_id
+ * \lapl_id
+ *
+ * \return \hid_tv{attribute}
+ *
+ * \details H5Acreate_by_name() creates an attribute, \p attr_name, which is
+ * attached to the object specified by \p loc_id and \p obj_name.
+ *
+ * \p loc_id is a location identifier; \p obj_name is the object
+ * name relative to \p loc_id. If \p loc_id fully specifies the
+ * object to which the attribute is to be attached, \p obj_name
+ * should be '.' (a dot).
+ *
+ * The attribute name, \p attr_name, must be unique for the object.
+ *
+ * The attribute is created with the specified datatype and
+ * dataspace, \p type_id and \p space_id, which are created with
+ * the H5T and H5S interfaces respectively.
+ *
+ * The attribute creation and access property lists are currently
+ * unused, but will be used in the future for optional attribute
+ * creation and access properties. These property lists should
+ * currently be #H5P_DEFAULT.
+ *
+ * The link access property list, \p lapl_id, may provide
+ * information regarding the properties of links required to access
+ * the object, \p obj_name.
+ *
+ * The attribute identifier returned by this function must be
+ * released with H5close() or resource leaks will develop.
+ *
+ * \since 1.8.0
+ *
+ */
H5_DLL hid_t H5Acreate_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t type_id,
hid_t space_id, hid_t acpl_id, hid_t aapl_id, hid_t lapl_id);
+/*--------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Opens an attribute for an object specified by object identifier and
+ * attribute name
+ *
+ * \fgdt_loc_id{obj_id}
+ * \param[in] attr_name Name of attribute to open
+ * \aapl_id
+ *
+ * \return \hid_tv{attribute}
+ *
+ * \details H5Aopen() opens an existing attribute, \p attr_name, that is
+ * attached to object specified by an object identifier, \p obj_id.
+ *
+ * The attribute access property list, \p aapl_id, is currently unused
+ * and should be #H5P_DEFAULT.
+ *
+ * This function, H5Aopen_by_idx() or H5Aopen_by_name() must be called
+ * before the attribute can be accessed for any further purpose,
+ * including reading, writing, or any modification.
+ *
+ * The attribute identifier returned by this function must be released
+ * with H5Aclose() or resource leaks will develop.
+ *
+ * \since 1.8.0
+ *
+ * \see H5Aclose(), H5Acreate()
+ */
H5_DLL hid_t H5Aopen(hid_t obj_id, const char *attr_name, hid_t aapl_id);
-H5_DLL hid_t H5Aopen_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t aapl_id,
- hid_t lapl_id);
+/*--------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Opens the nth attribute attached to an object
+ *
+ * \loc_id
+ * \param[in] obj_name Name of object to which attribute is attached,
+ * relative to location
+ * \param[in] idx_type Type of index
+ * \param[in] order Index traversal order
+ * \param[in] n Attribute’s position in index
+ * \aapl_id
+ * \lapl_id
+ *
+ * \return \hid_tv{attribute}
+ *
+ * \details H5Aopen_by_idx() opens an existing attribute that is attached
+ * to an object specified by location and name, \p loc_id and
+ * \p obj_name, respectively. If \p loc_id fully specifies the
+ * object to which the attribute is attached, \p obj_name, should
+ * be '.' (a dot).
+ *
+ * The attribute is identified by an index type, an index traversal
+ * order, and a position in the index, \p idx_type, \p order and
+ * \p n, respectively. These parameters and their valid values are
+ * discussed in the description of H5Aiterate2().
+ *
+ * The attribute access property list, \p aapl_id, is currently
+ * unused and should currently be #H5P_DEFAULT.
+ *
+ * The link access property list, \p lapl_id, may provide
+ * information regarding the properties of links required to access
+ * the object, \p obj_name.
+ *
+ * This function, H5Aopen(), or H5Aopen_by_name() must be called
+ * before an attribute can be accessed for any further purpose,
+ * including reading, writing, or any modification.
+ *
+ * The attribute identifier returned by this function must be
+ * released with H5Aclose() or resource leaks will develop.
+ *
+ * \since 1.8.0
+ *
+ */
H5_DLL hid_t H5Aopen_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order,
hsize_t n, hid_t aapl_id, hid_t lapl_id);
-H5_DLL herr_t H5Awrite(hid_t attr_id, hid_t type_id, const void *buf);
+/*--------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Opens an attribute for an object by object name and attribute name
+ *
+ * \fgdt_loc_id
+ * \param[in] obj_name Name of object to which attribute is attached,
+ * relative to \p loc_id
+ * \param[in] attr_name Name of attribute to open
+ * \aapl_id
+ * \lapl_id
+ *
+ * \return \hid_tv{attribute}
+ *
+ * \details H5Aopen_by_name() opens an existing attribute, \p attr_name,
+ * that is attached to an object specified by location and name,
+ * \p loc_id and \p obj_name, respectively.
+ *
+ * \p loc_id specifies a location from which the target object can
+ * be located and \p obj_name is an object name relative to
+ * \p loc_id. If \p loc_id fully specifies the object to which the
+ * attribute is attached, \p obj_name should be '.' (a dot).
+ *
+ * The attribute access property list, \p aapl_id, is currently
+ * unused and should currently be #H5P_DEFAULT.
+ *
+ * The link access property list, \p lapl_id, may provide
+ * information regarding the properties of links required to access
+ * the object, \p obj_name.
+ *
+ * This function, H5Aopen(), or H5Aopen_by_idx() must be called
+ * before an attribute can be accessed for any further purpose,
+ * including reading, writing, or any modification.
+ *
+ * The attribute identifier returned by this function must be
+ * released with H5Aclose() or resource leaks will develop.
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL hid_t H5Aopen_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t aapl_id,
+ hid_t lapl_id);
+/*-------------------------------------------------------------------------- */
+/**
+ * \ingroup H5A
+ *
+ * \brief Reads the value of an attribute
+ *
+ * \attr_id
+ * \mem_type_id{type_id}
+ * \param[out] buf Buffer for data to be read
+ *
+ * \return \herr_t
+ *
+ * \details H5Aread() reads an attribute, specified with \p attr_id. The
+ * attribute's in-memory datatype is specified with \p type_id. The
+ * entire attribute is read into \p buf from the file.
+ *
+ * Datatype conversion takes place at the time of a read or write and
+ * is automatic.
+ *
+ * \version 1.8.8 Fortran updated to Fortran2003.
+ * \version 1.4.2 The \p dims parameter was added to the Fortran API in this
+ * release.
+ * \since 1.0.0
+ *
+ * \see H5Awrite()
+ *
+*/
H5_DLL herr_t H5Aread(hid_t attr_id, hid_t type_id, void *buf);
-H5_DLL herr_t H5Aclose(hid_t attr_id);
+/*--------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Writes data to an attribute
+ *
+ * \attr_id
+ * \mem_type_id{type_id}
+ * \param[out] buf Data to be written
+ *
+ * \return \herr_t
+ *
+ * \details H5Awrite() writes an attribute, specified with \p attr_id. The
+ * attribute's in-memory datatype is specified with \p type_id.
+ * The entire attribute is written from \p buf to the file.
+ *
+ * If \p type_id is either a fixed-length or variable-length string,
+ * it is important to set the string length when defining the datatype.
+ * String datatypes are derived from #H5T_C_S1 (or #H5T_FORTRAN_S1 for
+ * Fortran codes), which defaults to 1 character in size.
+ * See H5Tset_size() and Creating variable-length string datatypes.
+ *
+ * Datatype conversion takes place at the time of a read or write and
+ * is automatic.
+ *
+ * \version 1.8.8 Fortran updated to Fortran2003.
+ * \version 1.4.2 Fortran \p dims parameter added in this release
+ * \since 1.0.0
+ * \see H5Aread()
+ *
+ */
+H5_DLL herr_t H5Awrite(hid_t attr_id, hid_t type_id, const void *buf);
H5_DLL hid_t H5Aget_space(hid_t attr_id);
H5_DLL hid_t H5Aget_type(hid_t attr_id);
H5_DLL hid_t H5Aget_create_plist(hid_t attr_id);
@@ -100,6 +388,51 @@ typedef herr_t (*H5A_operator1_t)(hid_t location_id /*in*/, const char *attr_nam
void *operator_data /*in,out*/);
/* Function prototypes */
+/* --------------------------------------------------------------------------*/
+/**
+ * \ingroup H5A
+ *
+ * \brief Creates an attribute attached to a specified object
+ *
+ * \fgdt_loc_id
+ * \param[in] name Name of attribute to locate and open
+ * \param[in] type_id Identifier of attribute datatype
+ * \space_id
+ * \acpl_id
+ *
+ * \return \hid_tv{attribute}
+ *
+ * \note The \p acpl parameters is currently not used; specify #H5P_DEFAULT.
+ *
+ * \deprecated Deprecated in favor of H5Acreate2()
+ *
+ * \details H5Acreate1() creates an attribute, \p name, which is attached
+ * to the object specified by the identifier \p loc_id.
+ *
+ * The attribute name, \p name, must be unique for the object.
+ *
+ * The attribute is created with the specified datatype and dataspace,
+ * \p type_id and \p space_id, which are created with the H5T and
+ * H5S interfaces, respectively.
+ *
+ * If \p type_id is either a fixed-length or variable-length string,
+ * it is important to set the string length when defining the
+ * datatype. String datatypes are derived from #H5T_C_S1 (or
+ * #H5T_FORTRAN_S1 for Fortran), which defaults to 1 character in
+ * size. See H5Tset_size() and Creating variable-length string
+ * datatypes.
+ *
+ * The attribute identifier returned by this function must be released
+ * with H5Aclose() resource leaks will develop.
+ *
+ * \since 1.8.0
+ *
+ * \version 1.8.0 The function H5Acreate() was renamed to H5Acreate1() and
+ * deprecated in this release.
+ *
+ * \see H5Aclose()
+ *
+ */
H5_DLL hid_t H5Acreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t acpl_id);
H5_DLL hid_t H5Aopen_name(hid_t loc_id, const char *name);
H5_DLL hid_t H5Aopen_idx(hid_t loc_id, unsigned idx);
diff --git a/src/H5Pmodule.h b/src/H5Pmodule.h
index d8cc430..b9e1180 100644
--- a/src/H5Pmodule.h
+++ b/src/H5Pmodule.h
@@ -29,4 +29,47 @@
#define H5_MY_PKG_ERR H5E_PLIST
#define H5_MY_PKG_INIT YES
+/**\defgroup H5P H5P
+ * \brief Property List Interface
+ *
+ * \details The HDF5 Property List Interface provides a mechanism to take
+ * advantage of more powerful or unusual features in HDF5.
+ *
+ * HDF5 objects have properties or characteristics associated with
+ * them, and there are default properties that handle the most
+ * common needs. These default properties can be modified using the
+ * HDF5 Property List Interface. For example, the data storage
+ * layout property of a dataset is contiguous by default. For better
+ * performance, the layout can be modified to be chunked or chunked
+ * and compressed.
+ *
+ * \todo Describe concisely what the functions in this module are about.
+ * \todo Clicking on "more" after "Property List Interface" at the top does not work
+ *
+ * \defgroup GPLO General Property List Operations
+ * \ingroup H5P
+ * \defgroup GPLOA General Property List Operations (Advanced)
+ * \ingroup H5P
+ * \defgroup FCPL File Creation Properties
+ * \ingroup H5P
+ * \defgroup FAPL File Access Properties
+ * \ingroup H5P
+ * \defgroup GCPL Group Creation Properties
+ * \ingroup H5P
+ * \defgroup ALCAPL Attribute and Link Creation Properties
+ * \ingroup H5P
+ * \defgroup LAPL Link Access Properties
+ * \ingroup H5P
+ * \defgroup DCPL Dataset Creation Properties
+ * \ingroup H5P
+ * \defgroup DAPL Dataset Access Properties
+ * \ingroup H5P
+ * \defgroup DXPL Dataset Transfer Properties
+ * \ingroup H5P
+ * \defgroup OCPL Object Creation Properties
+ * \ingroup H5P
+ * \defgroup OCPPL Object Copy Properties
+ * \ingroup H5P
+ */
+
#endif /* _H5Pmodule_H */
diff --git a/src/H5Ppublic.h b/src/H5Ppublic.h
index ffcdd99..a978895 100644
--- a/src/H5Ppublic.h
+++ b/src/H5Ppublic.h
@@ -232,11 +232,153 @@ H5_DLLVAR hid_t H5P_LST_REFERENCE_ACCESS_ID_g;
/*********************/
/* Generic property list routines */
+
+/**
+ * \ingroup GPLO
+ *
+ * \brief Terminates access to a property list
+ *
+ * \plist_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Pclose() terminates access to a property list. All property
+ * lists should be closed when the application is finished
+ * accessing them. This frees resources used by the property
+ * list.
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Pclose(hid_t plist_id);
+/**
+ * \ingroup GPLO
+ *
+ * \brief Creates a new property list as an instance of a property list class
+ *
+ * \plistcls_id{cls_id}
+ *
+ * \return \hid_t{property list}
+ *
+ * \details H5Pcreate() creates a new property list as an instance of
+ * some property list class. The new property list is initialized
+ * with default values for the specified class. The classes are as
+ * follows:
+ *
+ * <table>
+ * <tr>
+ * <th>Class Identifier</th>
+ * <th>Class Name</th>
+ * <th>Comments</th>
+ * </tr>
+ * <tr>
+ * <td>#H5P_ATTRIBUTE_CREATE</td>
+ * <td>attribute create</td>
+ * <td>Properties for attribute creation</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_DATASET_ACCESS</td>
+ * <td>dataset access</td>
+ * <td>Properties for dataset access</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_DATASET_CREATE</td>
+ * <td>dataset create</td>
+ * <td>Properties for dataset creation</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_DATASET_XFER</td>
+ * <td>data transfer</td>
+ * <td>Properties for raw data transfer</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_DATATYPE_ACCESS</td>
+ * <td>datatype access</td>
+ * <td>Properties for datatype access</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_DATATYPE_CREATE</td>
+ * <td>datatype create</td>
+ * <td>Properties for datatype creation</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_FILE_ACCESS</td>
+ * <td>file access</td>
+ * <td>Properties for file access</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_FILE_CREATE</td>
+ * <td>file create</td>
+ * <td>Properties for file creation</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_FILE_MOUNT</td>
+ * <td>file mount</td>
+ * <td>Properties for file mounting</td>
+ * </tr>
+ * <tr valign="top">
+ * <td>#H5P_GROUP_ACCESS</td>
+ * <td>group access</td>
+ * <td>Properties for group access</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_GROUP_CREATE</td>
+ * <td>group create</td>
+ * <td>Properties for group creation</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_LINK_ACCESS</td>
+ * <td>link access</td>
+ * <td>Properties governing link traversal when accessing objects</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_LINK_CREATE</td>
+ * <td>link create</td>
+ * <td>Properties governing link creation</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_OBJECT_COPY</td>
+ * <td>object copy</td>
+ * <td>Properties governing the object copying process</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_OBJECT_CREATE</td>
+ * <td>object create</td>
+ * <td>Properties for object creation</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_STRING_CREATE</td>
+ * <td>string create</td>
+ * <td>Properties for character encoding when encoding strings or
+ * object names</td>
+ * </tr>
+ * <tr>
+ * <td>#H5P_VOL_INITIALIZE</td>
+ * <td>vol initialize</td>
+ * <td>Properties for VOL initialization</td>
+ * </tr>
+ * </table>
+ *
+ * This property list must eventually be closed with H5Pclose();
+ * otherwise, errors are likely to occur.
+ *
+ * \version 1.12.0 The #H5P_VOL_INITIALIZE property list class was added
+ * \version 1.8.15 For each class, the class name returned by
+ * H5Pget_class_name() was added.
+ * The list of possible Fortran values was updated.
+ * \version 1.8.0 The following property list classes were added at this
+ * release: #H5P_DATASET_ACCESS, #H5P_GROUP_CREATE,
+ * #H5P_GROUP_ACCESS, #H5P_DATATYPE_CREATE,
+ * #H5P_DATATYPE_ACCESS, #H5P_ATTRIBUTE_CREATE
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL hid_t H5Pcreate(hid_t cls_id);
H5_DLL hid_t H5Pcreate_class(hid_t parent, const char *name, H5P_cls_create_func_t cls_create,
void *create_data, H5P_cls_copy_func_t cls_copy, void *copy_data,
H5P_cls_close_func_t cls_close, void *close_data);
H5_DLL char * H5Pget_class_name(hid_t pclass_id);
-H5_DLL hid_t H5Pcreate(hid_t cls_id);
H5_DLL herr_t H5Pregister2(hid_t cls_id, const char *name, size_t size, void *def_value,
H5P_prp_create_func_t prp_create, H5P_prp_set_func_t prp_set,
H5P_prp_get_func_t prp_get, H5P_prp_delete_func_t prp_del,
@@ -262,10 +404,80 @@ H5_DLL herr_t H5Pcopy_prop(hid_t dst_id, hid_t src_id, const char *name);
H5_DLL herr_t H5Premove(hid_t plist_id, const char *name);
H5_DLL herr_t H5Punregister(hid_t pclass_id, const char *name);
H5_DLL herr_t H5Pclose_class(hid_t plist_id);
-H5_DLL herr_t H5Pclose(hid_t plist_id);
H5_DLL hid_t H5Pcopy(hid_t plist_id);
/* Object creation property list (OCPL) routines */
+
+/**
+ * \ingroup OCPL
+ *
+ * \brief Returns information about a filter in a pipeline
+ *
+ * \todo Signature for H5Pget_filter2 is different in H5Pocpl.c than in
+ * H5Ppublic.h
+ *
+ * \plist_id{plist_id}
+ * \param[in] idx Sequence number within the filter pipeline of the filter
+ * for which information is sought
+ * \param[out] flags Bit vector specifying certain general properties of the
+ * filter
+ * \param[in,out] cd_nelmts Number of elements in \p cd_values
+ * \param[out] cd_values Auxiliary data for the filter
+ * \param[in] namelen Anticipated number of characters in \p name
+ * \param[out] name Name of the filter
+ * \param[out] filter_config Bit field, as described in H5Zget_filter_info()
+ *
+ * \return Returns a negative value on failure, and the filter identifier
+ * if successful (see #H5Z_filter_t):
+ * - #H5Z_FILTER_DEFLATE Data compression filter,
+ * employing the gzip algorithm
+ * - #H5Z_FILTER_SHUFFLE Data shuffling filter
+ * - #H5Z_FILTER_FLETCHER32 Error detection filter, employing the
+ * Fletcher32 checksum algorithm
+ * - #H5Z_FILTER_SZIP Data compression filter, employing the
+ * SZIP algorithm
+ * - #H5Z_FILTER_NBIT Data compression filter, employing the
+ * N-bit algorithm
+ * - #H5Z_FILTER_SCALEOFFSET Data compression filter, employing the
+ * scale-offset algorithm
+ *
+ * \details H5Pget_filter2() returns information about a filter specified by
+ * its filter number, in a filter pipeline specified by the property
+ * list with which it is associated.
+ *
+ * \p plist_id must be a dataset or group creation property list.
+ *
+ * \p idx is a value between zero and N-1, as described in
+ * H5Pget_nfilters(). The function will return a negative value if
+ * the filter number is out of range.
+ *
+ * The structure of the \p flags argument is discussed in
+ * H5Pset_filter().
+ *
+ * On input, \p cd_nelmts indicates the number of entries in the
+ * \p cd_values array, as allocated by the caller; on return,
+ * \p cd_nelmts contains the number of values defined by the filter.
+ *
+ * If \p name is a pointer to an array of at least \p namelen bytes,
+ * the filter name will be copied into that array. The name will be
+ * null terminated if \p namelen is large enough. The filter name
+ * returned will be the name appearing in the file, the name
+ * registered for the filter, or an empty string.
+ *
+ * \p filter_config is the bit field described in
+ * H5Zget_filter_info().
+ *
+ * \version 1.8.5 Function extended to work with group creation property
+ * lists.
+ * \since 1.8.0
+ *
+ */
+H5_DLL H5Z_filter_t H5Pget_filter2(hid_t plist_id, unsigned idx,
+ unsigned int *flags/*out*/,
+ size_t *cd_nelmts/*out*/,
+ unsigned cd_values[]/*out*/,
+ size_t namelen, char name[],
+ unsigned *filter_config /*out*/);
H5_DLL herr_t H5Pset_attr_phase_change(hid_t plist_id, unsigned max_compact, unsigned min_dense);
H5_DLL herr_t H5Pget_attr_phase_change(hid_t plist_id, unsigned *max_compact, unsigned *min_dense);
H5_DLL herr_t H5Pset_attr_creation_order(hid_t plist_id, unsigned crt_order_flags);
@@ -277,9 +489,6 @@ H5_DLL herr_t H5Pmodify_filter(hid_t plist_id, H5Z_filter_t filter, unsigned int
H5_DLL herr_t H5Pset_filter(hid_t plist_id, H5Z_filter_t filter, unsigned int flags, size_t cd_nelmts,
const unsigned int c_values[]);
H5_DLL int H5Pget_nfilters(hid_t plist_id);
-H5_DLL H5Z_filter_t H5Pget_filter2(hid_t plist_id, unsigned filter, unsigned int *flags /*out*/,
- size_t *cd_nelmts /*out*/, unsigned cd_values[] /*out*/, size_t namelen,
- char name[], unsigned *filter_config /*out*/);
H5_DLL herr_t H5Pget_filter_by_id2(hid_t plist_id, H5Z_filter_t id, unsigned int *flags /*out*/,
size_t *cd_nelmts /*out*/, unsigned cd_values[] /*out*/, size_t namelen,
char name[] /*out*/, unsigned *filter_config /*out*/);
@@ -379,10 +588,592 @@ H5_DLL herr_t H5Pget_page_buffer_size(hid_t plist_id, size_t *buf_size, unsigned
unsigned *min_raw_per);
/* Dataset creation property list (DCPL) routines */
-H5_DLL herr_t H5Pset_layout(hid_t plist_id, H5D_layout_t layout);
+
+/**
+ * \ingroup DCPL
+ *
+ * \brief Retrieves the size of chunks for the raw data of a chunked
+ * layout dataset
+ *
+ * \dcpl_id{plist_id}
+ * \param[in] max_ndims Size of the \p dims array
+ * \param[out] dim Array to store the chunk dimensions
+ *
+ * \return Returns chunk dimensionality if successful;
+ * otherwise returns a negative value.
+ *
+ * \details H5Pget_chunk() retrieves the size of chunks for the raw data
+ * of a chunked layout dataset. This function is only valid for
+ * dataset creation property lists. At most, \p max_ndims elements
+ * of \p dim will be initialized.
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL int H5Pget_chunk(hid_t plist_id, int max_ndims, hsize_t dim[]/*out*/);
+/**
+ *-------------------------------------------------------------------------
+ *
+ * \ingroup DCPL
+ *
+ * \brief Retrieves the edge chunk option setting from a dataset creation
+ * property list
+ *
+ * \dcpl_id{plist_id}
+ * \param[out] opts Edge chunk option flag. Valid values are described in
+ * H5Pset_chunk_opts(). The option status can be
+ * retrieved using the bitwise AND operator ( & ). For
+ * example, the expression
+ * (opts&#H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS) will
+ * evaluate to #H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS if
+ * that option has been enabled. Otherwise, it will
+ * evaluate to 0 (zero).
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_chunk_opts() retrieves the edge chunk option setting
+ * stored in the dataset creation property list \p plist_id.
+ *
+ * \since 1.10.0
+ *
+ */
+H5_DLL herr_t H5Pget_chunk_opts(hid_t plist_id, unsigned *opts);
+/**
+ *-------------------------------------------------------------------------
+ *
+ * \ingroup DCPL
+ *
+ * \brief Retrieves the time when fill values are written to a dataset
+ *
+ * \dcpl_id{plist_id}
+ * \param[out] fill_time Setting for the timing of writing fill values to
+ * the dataset
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_fill_time() examines the dataset creation property list
+ * \p plist_id to determine when fill values are to be written to
+ * a dataset. Valid values returned in \p fill_time are as
+ * follows:
+ *
+ * <table>
+ * <tr>
+ * <td>#H5D_FILL_TIME_IFSET</td>
+ * <td>Fill values are written to the dataset when storage
+ * space is allocated only if there is a user-defined fill
+ * value, i.e., one set with H5Pset_fill_value(). (Default)
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>#H5D_FILL_TIME_ALLOC</td>
+ * <td>Fill values are written to the dataset when storage
+ * space is allocated.</td>
+ * </tr>
+ * <tr>
+ * <td>#H5D_FILL_TIME_NEVER</td>
+ * <td>Fill values are never written to the dataset.</td>
+ * </tr>
+ * </table>
+ *
+ * \note H5Pget_fill_time() is designed to work in coordination with the
+ * dataset fill value and dataset storage allocation time properties,
+ * retrieved with the functions H5Pget_fill_value() and
+ * H5Pget_alloc_time().
+ *
+ * \since 1.6.0
+ *
+ */
+H5_DLL herr_t H5Pget_fill_time(hid_t plist_id, H5D_fill_time_t
+ *fill_time/*out*/);
+/**
+ *-------------------------------------------------------------------------
+ *
+ * \ingroup DCPL
+ *
+ * \brief Retrieves a dataset fill value
+ *
+ * \dcpl_id{plist_id}
+ * \param[in] type_id Datatype identifier for the value passed via
+ * \p value
+ * \param[out] value Pointer to buffer to contain the returned
+ * fill value
+ *
+ * \return \herr_t
+ *
+ * \details H5Pget_fill_value() returns the dataset fill value defined in
+ * the dataset creation property list \p plist_id. The fill value
+ * is returned through the \p value pointer and will be converted
+ * to the datatype specified by \p type_id. This datatype may
+ * differ from the fill value datatype in the property list, but
+ * the HDF5 library must be able to convert between the two
+ * datatypes.
+ *
+ * If the fill value is undefined, i.e., set to NULL in the
+ * property list, H5Pget_fill_value() will return an error.
+ * H5Pfill_value_defined() should be used to check for this
+ * condition before H5Pget_fill_value() is called.
+ *
+ * Memory must be allocated by the calling application.
+ *
+ * \note H5Pget_fill_value() is designed to coordinate with the dataset
+ * storage allocation time and fill value write time properties,
+ * which can be retrieved with the functions H5Pget_alloc_time()
+ * and H5Pget_fill_time(), respectively.
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Pget_fill_value(hid_t plist_id, hid_t type_id,
+ void *value/*out*/);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup DCPL
+ *
+ * \brief Returns the layout of the raw data for a dataset
+ *
+ * \dcpl_id{plist_id}
+ *
+ * \return Returns the layout type (a non-negative value) of a dataset
+ * creation property list if successful. Valid return values are:
+ * - #H5D_COMPACT: Raw data is stored in the object header in the
+ * file.
+ * - #H5D_CONTIGUOUS: Raw data is stored separately from the object
+ * header in one contiguous chunk in the file.
+ * - #H5D_CHUNKED: Raw data is stored separately from the object
+ * header in chunks in separate locations in the
+ * file.
+ * - #H5D_VIRTUAL: Raw data is drawn from multiple datasets in
+ * different files.
+ * \return
+ * Otherwise, returns a negative value indicating failure.
+ *
+ * \details H5Pget_layout() returns the layout of the raw data for a
+ * dataset. This function is only valid for dataset creation
+ * property lists.
+ *
+ * Note that a compact storage layout may affect writing data to
+ * the dataset with parallel applications. See the H5Dwrite()
+ * documentation for details.
+ *
+ * \version 1.10.0 #H5D_VIRTUAL added in this release.
+ *
+ * \since 1.0.0
+ *
+ */
H5_DLL H5D_layout_t H5Pget_layout(hid_t plist_id);
-H5_DLL herr_t H5Pset_chunk(hid_t plist_id, int ndims, const hsize_t dim[/*ndims*/]);
-H5_DLL int H5Pget_chunk(hid_t plist_id, int max_ndims, hsize_t dim[] /*out*/);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup DCPL
+ *
+ * \brief Sets the size of the chunks used to store a chunked layout
+ * dataset
+ *
+ * \dcpl_id{plist_id}
+ * \param[in] ndims The number of dimensions of each chunk
+ * \param[in] dim An array defining the size, in dataset elements, of
+ * each chunk
+ *
+ * \return \herr_t
+ * \details H5Pset_chunk() sets the size of the chunks used to store a
+ * chunked layout dataset. This function is only valid for dataset
+ * creation property lists.
+ *
+ * The \p ndims parameter currently must be the same size as the
+ * rank of the dataset.
+ *
+ * The values of the \p dim array define the size of the chunks
+ * to store the dataset's raw data. The unit of measure for \p dim
+ * values is dataset elements.
+ *
+ * As a side-effect of this function, the layout of the dataset is
+ * changed to #H5D_CHUNKED, if it is not already so set.
+ *
+ * \note Chunk size cannot exceed the size of a fixed-size dataset. For
+ * example, a dataset consisting of a 5x4 fixed-size array cannot be
+ * defined with 10x10 chunks. Chunk maximums:
+ * - The maximum number of elements in a chunk is 2<sup>32</sup>-1 which
+ * is equal to 4,294,967,295. If the number of elements in a chunk is
+ * set via H5Pset_chunk() to a value greater than 2<sup>32</sup>-1,
+ * then H5Pset_chunk() will fail.
+ * - The maximum size for any chunk is 4GB. If a chunk that is larger
+ * than 4GB attempts to be written with H5Dwrite(), then H5Dwrite()
+ * will fail.
+ *
+ * \see H5Pset_layout(), H5Dwrite()
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Pset_chunk(hid_t plist_id, int ndims, const hsize_t dim[/*ndims*/]);
+/**
+ *-------------------------------------------------------------------------
+ *
+ * \ingroup DCPL
+ *
+ * \brief Sets the edge chunk option in a dataset creation property list
+ *
+ * \dcpl_id{plist_id}
+ * \param[in] opts Edge chunk option flag. Valid values are:
+ * \li #H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS
+ * When enabled, filters are not applied to partial
+ * edge chunks. When disabled, partial edge chunks are
+ * filtered. Enabling this option will improve
+ * performance when appending to the dataset and, when
+ * compression filters are used, prevent reallocation
+ * of these chunks. Datasets created with this option
+ * enabled will be inaccessible with HDF5 library
+ * versions before Release 1.10. Default: \e Disabled
+ * \li 0 (zero) Disables option; partial edge chunks
+ * will be compressed.
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_chunk_opts() sets the edge chunk option in the
+ * dataset creation property list \p dcpl_id.
+ *
+ * The available option is detailed in the parameters section.
+ * Only chunks that are not completely filled by the dataset’s
+ * dataspace are affected by this option. Such chunks are
+ * referred to as partial edge chunks.
+ *
+ * \note \b Motivation: H5Pset_chunk_opts() is used to specify storage
+ * options for chunks on the edge of a dataset’s dataspace. This
+ * capability allows the user to tune performance in cases where
+ * the dataset size may not be a multiple of the chunk size and
+ * the handling of partial edge chunks can impact performance.
+ *
+ * \since 1.10.0
+ *
+ */
+H5_DLL herr_t H5Pset_chunk_opts(hid_t plist_id, unsigned opts);
+/**
+ *-------------------------------------------------------------------------
+ *
+ * \ingroup DCPL
+ *
+ * \brief Sets the time when fill values are written to a dataset
+ *
+ * \dcpl_id{plist_id}
+ * \param[in] fill_time When to write fill values to a dataset
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_fill_time() sets up the timing for writing fill values
+ * to a dataset. This property is set in the dataset creation
+ * property list \p plist_id. Timing is specified in \p fill_time
+ * with one of the following values:
+ *
+ * <table>
+ * <tr>
+ * <td>#H5D_FILL_TIME_IFSET</td>
+ * <td>Write fill values to the dataset when storage space is
+ * allocated only if there is a user-defined fill value,
+ * i.e.,one set with H5Pset_fill_value(). (Default)</td>
+ * </tr>
+ * <tr>
+ * <td>#H5D_FILL_TIME_ALLOC</td>
+ * <td>Write fill values to the dataset when storage space is
+ * allocated.</td>
+ * </tr>
+ * <tr>
+ * <td>#H5D_FILL_TIME_NEVER</td>
+ * <td>Never write fill values to the dataset.</td>
+ * </tr>
+ * </table>
+ *
+ * \note H5Pset_fill_time() is designed for coordination with the dataset
+ * fill value and dataset storage allocation time properties, set
+ * with the functions H5Pset_fill_value() and H5Pset_alloc_time().
+ * See H5Dcreate() for further cross-references.
+ *
+ * \since 1.6.0
+ *
+ */
+H5_DLL herr_t H5Pset_fill_time(hid_t plist_id, H5D_fill_time_t fill_time);
+/**
+ *-------------------------------------------------------------------------
+ *
+ * \ingroup DCPL
+ *
+ * \brief Sets the fill value for a dataset
+ *
+ * \dcpl_id{plist_id}
+ * \param[in] type_id Datatype of \p value
+ * \param[in] value Pointer to buffer containing value to use as
+ * fill value
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_fill_value() sets the fill value for a dataset in the
+ * dataset creation property list. \p value is interpreted as
+ * being of datatype \p type_id. This datatype may differ from
+ * that of the dataset, but the HDF5 library must be able to
+ * convert \p value to the dataset datatype when the dataset is
+ * created.
+ *
+ * The default fill value is 0 (zero), which is interpreted
+ * according to the actual dataset datatype.
+ *
+ * Setting \p value to NULL indicates that the fill value is to
+ * be undefined.
+ *
+ * \note Applications sometimes write data only to portions of an allocated
+ * dataset. It is often useful in such cases to fill the unused space
+ * with a known fill value. This function allows the user application
+ * to set that fill value; the functions H5Dfill() and
+ * H5Pset_fill_time(), respectively, provide the ability to apply the
+ * fill value on demand or to set up its automatic application.
+ *
+ * \note A fill value should be defined so that it is appropriate for the
+ * application. While the HDF5 default fill value is 0 (zero), it is
+ * often appropriate to use another value. It might be useful, for
+ * example, to use a value that is known to be impossible for the
+ * application to legitimately generate.
+ *
+ * \note H5Pset_fill_value() is designed to work in concert with
+ * H5Pset_alloc_time() and H5Pset_fill_time(). H5Pset_alloc_time()
+ * and H5Pset_fill_time() govern the timing of dataset storage
+ * allocation and fill value write operations and can be important in
+ * tuning application performance.
+ *
+ * \note See H5Dcreate() for further cross-references.
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Pset_fill_value(hid_t plist_id, hid_t type_id,
+ const void *value);
+/**
+ *-------------------------------------------------------------------------
+ *
+ * \ingroup DCPL
+ *
+ * \brief Sets up use of the shuffle filter
+ *
+ * \dcpl_id{plist_id}
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_shuffle() sets the shuffle filter, #H5Z_FILTER_SHUFFLE,
+ * in the dataset creation property list \p plist_id. The shuffle
+ * filter de-interlaces a block of data by reordering the bytes.
+ * All the bytes from one consistent byte position of each data
+ * element are placed together in one block; all bytes from a
+ * second consistent byte position of each data element are placed
+ * together a second block; etc. For example, given three data
+ * elements of a 4-byte datatype stored as 012301230123, shuffling
+ * will re-order data as 000111222333. This can be a valuable step
+ * in an effective compression algorithm because the bytes in each
+ * byte position are often closely related to each other and
+ * putting them together can increase the compression ratio.
+ *
+ * As implied above, the primary value of the shuffle filter lies
+ * in its coordinated use with a compression filter; it does not
+ * provide data compression when used alone. When the shuffle
+ * filter is applied to a dataset immediately prior to the use of
+ * a compression filter, the compression ratio achieved is often
+ * superior to that achieved by the use of a compression filter
+ * without the shuffle filter.
+ *
+ * \since 1.6.0
+ *
+ */
+H5_DLL herr_t H5Pset_shuffle(hid_t plist_id);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup DCPL
+ *
+ * \brief Sets the type of storage used to store the raw data for a dataset
+ *
+ * \dcpl_id{plist_id}
+ * \param[in] layout Type of storage layout for raw data
+ *
+ * \return \herr_t
+ * \details H5Pset_layout() sets the type of storage used to store the raw
+ * data for a dataset. This function is only valid for dataset
+ * creation property lists.
+ *
+ * Valid values for \p layout are:
+ * - #H5D_COMPACT: Store raw data in the dataset object header
+ * in file. This should only be used for datasets
+ * with small amounts of raw data. The raw data
+ * size limit is 64K (65520 bytes). Attempting
+ * to create a dataset with raw data larger than
+ * this limit will cause the H5Dcreate() call to
+ * fail.
+ * - #H5D_CONTIGUOUS: Store raw data separately from the object
+ * header in one large chunk in the file.
+ * - #H5D_CHUNKED: Store raw data separately from the object header
+ * as chunks of data in separate locations in
+ * the file.
+ * - #H5D_VIRTUAL: Draw raw data from multiple datasets in
+ * different files.
+ *
+ * Note that a compact storage layout may affect writing data to
+ * the dataset with parallel applications. See the note in
+ * H5Dwrite() documentation for details.
+ * \version 1.10.0 #H5D_VIRTUAL added in this release.
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Pset_layout(hid_t plist_id, H5D_layout_t layout);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup DCPL
+ *
+ * \brief Sets up use of the SZIP compression filter
+ *
+ * \dcpl_id{plist_id}
+ * \param[in] options_mask A bit-mask conveying the desired SZIP options;
+ * Valid values are #H5_SZIP_EC_OPTION_MASK and
+ * #H5_SZIP_NN_OPTION_MASK.
+ * \param[in] pixels_per_block The number of pixels or data elements in each
+ * data block
+ *
+ * \return \herr_t
+ *
+ * \details H5Pset_szip() sets an SZIP compression filter, #H5Z_FILTER_SZIP,
+ * for a dataset. SZIP is a compression method designed for use with
+ * scientific data.
+ *
+ * Before proceeding, all users should review the “Limitations”
+ * section below.
+ *
+ * Users familiar with SZIP outside the HDF5 context may benefit
+ * from reviewing the Note “For Users Familiar with SZIP in Other
+ * Contexts” below.
+ *
+ * In the text below, the term pixel refers to an HDF5 data element.
+ * This terminology derives from SZIP compression's use with image
+ * data, where pixel referred to an image pixel.
+ *
+ * The SZIP \p bits_per_pixel value (see Note, below) is automatically
+ * set, based on the HDF5 datatype. SZIP can be used with atomic
+ * datatypes that may have size of 8, 16, 32, or 64 bits.
+ * Specifically, a dataset with a datatype that is 8-, 16-, 32-, or
+ * 64-bit signed or unsigned integer; char; or 32- or 64-bit float
+ * can be compressed with SZIP. See Note, below, for further
+ * discussion of the the SZIP \p bits_per_pixel setting.
+ *
+ * SZIP options are passed in an options mask, \p options_mask,
+ * as follows.
+ *
+ * <table>
+ * <tr>
+ * <th>Option</th>
+ * <th>Description (Mutually exclusive; select one.)</th>
+ * </tr>
+ * <tr>
+ * <td>#H5_SZIP_EC_OPTION_MASK</td>
+ * <td>Selects entropy coding method</td>
+ * </tr>
+ * <tr>
+ * <td>#H5_SZIP_NN_OPTION_MASK</td>
+ * <td>Selects nearest neighbor coding method</td>
+ * </tr>
+ * </table>
+ *
+ * The following guidelines can be used in determining which
+ * option to select:
+ *
+ * - The entropy coding method, the EC option specified by
+ * #H5_SZIP_EC_OPTION_MASK, is best suited for data that has been
+ * processed. The EC method works best for small numbers.
+ * - The nearest neighbor coding method, the NN option specified
+ * by #H5_SZIP_NN_OPTION_MASK, preprocesses the data then the
+ * applies EC method as above.
+ *
+ * Other factors may affect results, but the above criteria
+ * provides a good starting point for optimizing data compression.
+ *
+ * SZIP compresses data block by block, with a user-tunable block
+ * size. This block size is passed in the parameter
+ * \p pixels_per_block and must be even and not greater than 32,
+ * with typical values being 8, 10, 16, or 32. This parameter
+ * affects compression ratio; the more pixel values vary, the
+ * smaller this number should be to achieve better performance.
+ *
+ * In HDF5, compression can be applied only to chunked datasets.
+ * If \p pixels_per_block is bigger than the total number of
+ * elements in a dataset chunk, H5Pset_szip() will succeed but
+ * the subsequent call to H5Dcreate() will fail; the conflict
+ * can be detected only when the property list is used.
+ *
+ * To achieve optimal performance for SZIP compression, it is
+ * recommended that a chunk's fastest-changing dimension be equal
+ * to N times \p pixels_per_block where N is the maximum number of
+ * blocks per scan line allowed by the SZIP library. In the
+ * current version of SZIP, N is set to 128.
+ *
+ * SZIP compression is an optional HDF5 filter.
+ *
+ * \b Limitations:
+ *
+ * - SZIP compression cannot be applied to compound, array,
+ * variable-length, enumeration, or any other user-defined
+ * datatypes. If an SZIP filter is set in a dataset creation
+ * property list used to create a dataset containing a
+ * non-allowed datatype, the call to H5Dcreate() will fail; the
+ * conflict can be detected only when the property list is used.
+ * - Users should be aware that there are factors that affect one’s
+ * rights and ability to use SZIP compression by reviewing the
+ * SZIP copyright notice.
+ *
+ * \note \b For \b Users \b Familiar \b with \b SZIP \b in \b Other \b Contexts:
+ *
+ * \note The following notes are of interest primarily to those who have
+ * used SZIP compression outside of the HDF5 context.
+ * In non-HDF5 applications, SZIP typically requires that the user
+ * application supply additional parameters:
+ * - \p pixels_in_object, the number of pixels in the object to
+ * be compressed
+ * - \p bits_per_pixel, the number of bits per pixel
+ * - \p pixels_per_scanline, the number of pixels per scan line
+ *
+ * \note These values need not be independently supplied in the HDF5
+ * environment as they are derived from the datatype and dataspace,
+ * which are already known. In particular, HDF5 sets
+ * \p pixels_in_object to the number of elements in a chunk and
+ * \p bits_per_pixel to the size of the element or pixel datatype.
+ *
+ * \note The following algorithm is used to set \p pixels_per_scanline:
+ * - If the size of a chunk's fastest-changing dimension, size,
+ * is greater than 4K, set \p pixels_per_scanline to 128 times
+ * \p pixels_per_block.
+ * - If size is less than 4K but greater than \p pixels_per_block,
+ * set \p pixels_per_scanline to the minimum of size and 128
+ * times \p pixels_per_block.
+ * - If size is less than \p pixels_per_block but greater than the
+ * number elements in the chunk, set \p pixels_per_scanline to
+ * the minimum of the number elements in the chunk and 128 times
+ * \p pixels_per_block.
+ *
+ * \note The HDF5 datatype may have precision that is less than the full
+ * size of the data element, e.g., an 11-bit integer can be defined
+ * using H5Tset_precision(). To a certain extent, SZIP can take
+ * advantage of the precision of the datatype to improve compression:
+ * - If the HDF5 datatype size is 24-bit or less and the offset of
+ * the bits in the HDF5 datatype is zero (see H5Tset_offset() or
+ * H5Tget_offset()), the data is the in lowest N bits of the data
+ * element. In this case, the SZIP \p bits_per_pixel is set to the
+ * precision of the HDF5 datatype.
+ * - If the offset is not zero, the SZIP \p bits_per_pixel will be
+ * set to the number of bits in the full size of the data element.
+ * - If the HDF5 datatype precision is 25-bit to 32-bit, the SZIP
+ * \p bits_per_pixel will be set to 32.
+ * - If the HDF5 datatype precision is 33-bit to 64-bit, the SZIP
+ * \p bits_per_pixel will be set to 64.
+ *
+ * \note HDF5 always modifies the options mask provided by the user to set up
+ * usage of RAW_OPTION_MASK, ALLOW_K13_OPTION_MASK, and one of
+ * LSB_OPTION_MASK or MSB_OPTION_MASK, depending on endianness of the
+ * datatype.
+ *
+ * \since 1.6.0
+ *
+ *--------------------------------------------------------------------------
+ */
+H5_DLL herr_t H5Pset_szip(hid_t plist_id, unsigned options_mask, unsigned pixels_per_block);
H5_DLL herr_t H5Pset_virtual(hid_t dcpl_id, hid_t vspace_id, const char *src_file_name,
const char *src_dset_name, hid_t src_space_id);
H5_DLL herr_t H5Pget_virtual_count(hid_t dcpl_id, size_t *count /*out*/);
@@ -391,22 +1182,14 @@ H5_DLL hid_t H5Pget_virtual_srcspace(hid_t dcpl_id, size_t index);
H5_DLL ssize_t H5Pget_virtual_filename(hid_t dcpl_id, size_t index, char *name /*out*/, size_t size);
H5_DLL ssize_t H5Pget_virtual_dsetname(hid_t dcpl_id, size_t index, char *name /*out*/, size_t size);
H5_DLL herr_t H5Pset_external(hid_t plist_id, const char *name, off_t offset, hsize_t size);
-H5_DLL herr_t H5Pset_chunk_opts(hid_t plist_id, unsigned opts);
-H5_DLL herr_t H5Pget_chunk_opts(hid_t plist_id, unsigned *opts);
H5_DLL int H5Pget_external_count(hid_t plist_id);
H5_DLL herr_t H5Pget_external(hid_t plist_id, unsigned idx, size_t name_size, char *name /*out*/,
off_t *offset /*out*/, hsize_t *size /*out*/);
-H5_DLL herr_t H5Pset_szip(hid_t plist_id, unsigned options_mask, unsigned pixels_per_block);
-H5_DLL herr_t H5Pset_shuffle(hid_t plist_id);
H5_DLL herr_t H5Pset_nbit(hid_t plist_id);
H5_DLL herr_t H5Pset_scaleoffset(hid_t plist_id, H5Z_SO_scale_type_t scale_type, int scale_factor);
-H5_DLL herr_t H5Pset_fill_value(hid_t plist_id, hid_t type_id, const void *value);
-H5_DLL herr_t H5Pget_fill_value(hid_t plist_id, hid_t type_id, void *value /*out*/);
H5_DLL herr_t H5Pfill_value_defined(hid_t plist, H5D_fill_value_t *status);
H5_DLL herr_t H5Pset_alloc_time(hid_t plist_id, H5D_alloc_time_t alloc_time);
H5_DLL herr_t H5Pget_alloc_time(hid_t plist_id, H5D_alloc_time_t *alloc_time /*out*/);
-H5_DLL herr_t H5Pset_fill_time(hid_t plist_id, H5D_fill_time_t fill_time);
-H5_DLL herr_t H5Pget_fill_time(hid_t plist_id, H5D_fill_time_t *fill_time /*out*/);
H5_DLL herr_t H5Pget_dset_no_attrs_hint(hid_t dcpl_id, hbool_t *minimize);
H5_DLL herr_t H5Pset_dset_no_attrs_hint(hid_t dcpl_id, hbool_t minimize);
@@ -526,6 +1309,59 @@ H5_DLL herr_t H5Pinsert1(hid_t plist_id, const char *name, size_t size, vo
H5P_prp_delete_func_t prp_delete, H5P_prp_copy_func_t prp_copy,
H5P_prp_close_func_t prp_close);
H5_DLL herr_t H5Pencode1(hid_t plist_id, void *buf, size_t *nalloc);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup OCPL
+ *
+ * \brief Returns information about a filter in a pipeline (DEPRECATED)
+ *
+ * \todo H5Pget_filter1() prototype does not match source in H5Pocpl.c.
+ * Also, it is not in a deprecated file. Is that okay?
+ *
+ * \plist_id{plist_id}
+ * \param[in] filter Sequence number within the filter pipeline of the filter
+ * for which information is sought
+ * \param[out] flags Bit vector specifying certain general properties of
+ * the filter
+ * \param[in,out] cd_nelmts Number of elements in \p cd_values
+ * \param[out] cd_values Auxiliary data for the filter
+ * \param[in] namelen Anticipated number of characters in \p name
+ * \param[out] name Name of the filter
+ *
+ * \return Returns the filter identifier if successful; Otherwise returns
+ * a negative value. See: #H5Z_filter_t
+ *
+ * \details H5Pget_filter1() returns information about a filter, specified
+ * by its filter number, in a filter pipeline, specified by the
+ * property list with which it is associated.
+ *
+ * \p plist_id must be a dataset or group creation property list.
+ *
+ * \p filter is a value between zero and N-1, as described in
+ * H5Pget_nfilters(). The function will return a negative value
+ * if the filter number is out of range.
+ *
+ * The structure of the \p flags argument is discussed in
+ * H5Pset_filter().
+ *
+ * On input, \p cd_nelmts indicates the number of entries in the
+ * \p cd_values array, as allocated by the caller; on return,
+ * \p cd_nelmts contains the number of values defined by the filter.
+ *
+ * If \p name is a pointer to an array of at least \p namelen
+ * bytes, the filter name will be copied into that array. The name
+ * will be null terminated if \p namelen is large enough. The
+ * filter name returned will be the name appearing in the file, the
+ * name registered for the filter, or an empty string.
+ *
+ * \version 1.8.5 Function extended to work with group creation property
+ * lists.
+ * \version 1.8.0 N-bit and scale-offset filters added.
+ * \version 1.8.0 Function H5Pget_filter() renamed to H5Pget_filter1() and
+ * deprecated in this release.
+ * \version 1.6.4 \p filter parameter type changed to unsigned.
+ *
+ */
H5_DLL H5Z_filter_t H5Pget_filter1(hid_t plist_id, unsigned filter, unsigned int *flags /*out*/,
size_t *cd_nelmts /*out*/, unsigned cd_values[] /*out*/, size_t namelen,
char name[]);
diff --git a/src/H5Smodule.h b/src/H5Smodule.h
index 11494ee..6e8208b 100644
--- a/src/H5Smodule.h
+++ b/src/H5Smodule.h
@@ -29,4 +29,31 @@
#define H5_MY_PKG_ERR H5E_DATASPACE
#define H5_MY_PKG_INIT YES
+/**\defgroup H5S H5S
+ * \brief Dataspace Interface
+ *
+ * \details The Dataspace Interface provides functions for creating and
+ * working with dataspaces.
+ *
+ * A dataspace has two roles:
+ *
+ * \li It contains the spatial information (logical layout) of a
+ * dataset stored in a file.
+ * \li It describes an application’s data buffers and data elements
+ * participating in I/O. In other words, it can be used to
+ * select a portion or subset of a dataset.
+ *
+ * The spatial information of a dataset in a file includes the
+ * rank and dimensions of the dataset, which are a permanent part
+ * of the dataset definition. It can have dimensions that are fixed
+ * (unchanging) or unlimited, which means they can grow in size
+ * (or are extendible).
+ *
+ * A dataspace can consist of:
+ * \li no elements (NULL)
+ * \li a single element (scalar), or
+ * \li a simple array.
+ *
+ */
+
#endif /* _H5Smodule_H */
diff --git a/src/H5Spublic.h b/src/H5Spublic.h
index f0aa6dc..c16af93 100644
--- a/src/H5Spublic.h
+++ b/src/H5Spublic.h
@@ -120,17 +120,288 @@ typedef enum {
extern "C" {
#endif
-/* Operations on dataspaces */
+/* Operations on dataspaces and dataspace selections */
+
+/**
+ * \ingroup H5S
+ *
+ * \brief Releases and terminates access to a dataspace
+ *
+ * \space_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Sclose() releases a dataspace. Further access through the
+ * dataspace identifier is illegal. Failure to release a dataspace with this
+ * call will result in resource leaks.
+ *
+ * \version 1.4.0 Fortran subroutine introduced in this release.
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Sclose(hid_t space_id);
+/**
+ * \ingroup H5S
+ *
+ * \brief Creates a new dataspace of a specified type
+ *
+ * \param[in] type Type of dataspace to be created
+ *
+ * \return \hid_t{dataspace}
+ *
+ * \details H5Screate() creates a new dataspace of a particular type. Currently
+ * supported types are #H5S_SCALAR, #H5S_SIMPLE, and #H5S_NULL.
+ *
+ * Further dataspace types may be added later.
+ *
+ * A scalar dataspace, #H5S_SCALAR, has a single element, though that
+ * element may be of a complex datatype, such as a compound or array
+ * datatype. By convention, the rank of a scalar dataspace is always \p 0
+ * (zero); think of it geometrically as a single, dimensionless point,
+ * though that point can be complex.
+ *
+ * A simple dataspace, #H5S_SIMPLE, consists of a regular array of elements.
+ *
+ * A null dataspace, #H5S_NULL, has no data elements.
+ *
+ * The dataspace identifier returned by this function can be released with
+ * H5Sclose() so that resource leaks will not occur.
+ *
+ * \version 1.4.0 Fortran subroutine introduced.
+ * \since 1.0.0
+ *
+ */
H5_DLL hid_t H5Screate(H5S_class_t type);
+/**
+ * \ingroup H5S
+ * \brief Creates a new simple dataspace and opens it for access
+ *
+ * \param[in] rank Number of dimensions of dataspace
+ * \param[in] dims Array specifying the size of each dimension
+ * \param[in] maxdims Array specifying the maximum size of each dimension
+ *
+ * \return \hid_t{dataspace}
+ *
+ * \details H5Screate_simple() creates a new simple dataspace and opens it
+ * for access, returning a dataspace identifier.
+ *
+ * \p rank is the number of dimensions used in the dataspace.
+ *
+ * \p dims is a one-dimensional array of size rank specifying the
+ * size of each dimension of the dataset. \p maxdims is an array of the
+ * same size specifying the upper limit on the size of each dimension.
+ *
+ * Any element of \p dims can be \p 0 (zero). Note that no data can
+ * be written to a dataset if the size of any dimension of its current
+ * dataspace is \p 0. This is sometimes a useful initial state for a dataset.
+ *
+ * \p maxdims may be the null pointer, in which case the upper limit is
+ * the same as \p dims. Otherwise, no element of \p maxdims
+ * should be smaller than the corresponding element of \p dims.
+ *
+ * If an element of \p maxdims is #H5S_UNLIMITED, the maximum size of the
+ * corresponding dimension is unlimited.
+ *
+ * Any dataset with an unlimited dimension must also be chunked; see
+ * H5Pset_chunk(). Similarly, a dataset must be chunked if \p dims does
+ * not equal \p maxdims.
+ *
+ * The dataspace identifier returned from this function must be released with
+ * H5Sclose() or resource leaks will occur.
+ *
+ * \note Once a dataspace has been created, specific regions or elements in
+ * the dataspace can be selected and selections can be removed, as well.
+ * For example, H5Sselect_hyperslab() selects a region in a dataspace and
+ * H5Sselect_elements() selects array elements in a dataspace. These
+ * functions are used for subsetting. H5Sselect_none() removes all
+ * selections from a dataspace and is used in Parallel HDF5 when a process
+ * does not have or need to write data.
+ *
+ * \version 1.4.0 Fortran subroutine introduced.
+ *
+ * \since 1.0.0
+ *
+ */
H5_DLL hid_t H5Screate_simple(int rank, const hsize_t dims[], const hsize_t maxdims[]);
+/*--------------------------------------------------------------------------*/
+/**\ingroup H5S
+ *
+ * \brief Determines the number of elements in a dataspace selection
+ *
+ * \space_id{spaceid}
+ *
+ * \return Returns the number of elements in the selection if successful;
+ * otherwise returns a negative value.
+ *
+ * \details H5Sget_select_npoints() determines the number of elements in
+ * the current selection of a dataspace. It works with any
+ * selection type, and is the correct way to retrieve the number
+ * of elements in a selection.
+ *
+ * \version 1.4.0 Fortran subroutine introduced in this release.
+ * \since 1.0.0
+ *
+ */
+H5_DLL hssize_t H5Sget_select_npoints(hid_t spaceid);
+/*-------------------------------------------------------------------------*/
+/**\ingroup H5S
+ *
+ * \brief Retrieves dataspace dimension size and maximum size
+ *
+ * \space_id
+ * \param[out] dims Pointer to array to store the size of each dimension
+ * \param[out] maxdims Pointer to array to store the maximum size of each
+ * dimension
+ *
+ * \return Returns the number of dimensions in the dataspace if successful;
+ * otherwise returns a negative value.
+ *
+ * \details H5Sget_simple_extent_dims() returns the size and maximum sizes
+ * of each dimension of a dataspace \p space_id through the \p dims
+ * and \p maxdims parameters.
+ *
+ * Either or both of \p dims and \p maxdims may be NULL.
+ *
+ * If a value in the returned array \p maxdims is #H5S_UNLIMITED (-1),
+ * the maximum size of that dimension is unlimited.
+ *
+ * \version 1.4.0 Fortran subroutine introduced.
+ * \since 1.0.0
+ *
+ */
+H5_DLL int H5Sget_simple_extent_dims(hid_t space_id, hsize_t dims[],
+ hsize_t maxdims[]);
+/*-------------------------------------------------------------------------*/
+/**\ingroup H5S
+ *
+ * \brief Determines the dimensionality of a dataspace
+ *
+ * \space_id
+ *
+ * \return Returns the number of dimensions in the dataspace if successful;
+ * otherwise returns a negative value.
+ *
+ * \details H5Sget_simple_extent_ndims() determines the dimensionality (or
+ * rank) of a dataspace.
+ *
+ * \version 1.4.0 Fortran subroutine introduced.
+ * \since 1.0.0
+ *
+ */
+H5_DLL int H5Sget_simple_extent_ndims(hid_t space_id);
+/*--------------------------------------------------------------------------*/
+/**\ingroup H5S
+ *
+ * \brief Selects a hyperslab region to add to the current selected region
+ *
+ * \space_id
+ * \param[in] op Operation to perform on current selection
+ * \param[in] start Offset of start of hyperslab
+ * \param[in] stride Hyperslab stride
+ * \param[in] count Number of blocks included in hyperslab
+ * \param[in] block Size of block in hyperslab
+ *
+ * \return \herr_t
+ *
+ * \details H5Sselect_hyperslab() selects a hyperslab region to add to the
+ * current selected region for the dataspace specified by
+ * \p space_id.
+ *
+ * The \p start, \p stride, \p count, and \p block arrays must be the
+ * same size as the rank of the dataspace. For example, if the
+ * dataspace is 4-dimensional, each of these parameters must be a
+ * 1-dimensional array of size 4.
+ *
+ * The selection operator \p op determines how the new selection
+ * is to be combined with the already existing selection for the
+ * dataspace. The following operators are supported:
+ *
+ * <table>
+ * <tr>
+ * <td>#H5S_SELECT_SET</td>
+ * <td>Replaces the existing selection with the
+ * parameters from this call. Overlapping blocks
+ * are not supported with this operator.</td>
+ * </tr>
+ * <tr>
+ * <td>#H5S_SELECT_OR</td>
+ * <td>Adds the new selection to the existing selection.
+ * (Binary OR)</td>
+ * </tr>
+ * <tr>
+ * <td>#H5S_SELECT_AND</td>
+ * <td>Retains only the overlapping portions of the
+ * new selection and the existing selection.
+ * (Binary AND)</td>
+ * </tr>
+ * <tr>
+ * <td>#H5S_SELECT_XOR</td>
+ * <td>Retains only the elements that are members of
+ * the new selection or the existing selection,
+ * excluding elements that are members of both
+ * selections. (Binary exclusive-OR, XOR)
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>#H5S_SELECT_NOTB</td>
+ * <td>Retains only elements of the existing selection
+ * that are not in the new selection.</td>
+ * </tr>
+ * <tr>
+ * <td>#H5S_SELECT_NOTA</td>
+ * <td>Retains only elements of the new selection that
+ * are not in the existing selection.</td>
+ * </tr>
+ * </table>
+ *
+ * The \p start array specifies the offset of the starting element
+ * of the specified hyperslab.
+ *
+ * The \p stride array chooses array locations from the dataspace with
+ * each value in the \p stride array determining how many elements to
+ * move in each dimension. Setting a value in the \p stride array to
+ * \p 1 moves to each element in that dimension of the dataspace;
+ * setting a value of \p 2 in allocation in the \p stride array moves
+ * to every other element in that dimension of the dataspace. In
+ * other words, the \p stride determines the number of elements to
+ * move from the \p start location in each dimension. Stride values
+ * of \p 0 are not allowed. If the \p stride parameter is NULL, a
+ * contiguous hyperslab is selected (as if each value in the \p stride
+ * array were set to \p 1).
+ *
+ * The \p count array determines how many blocks to select from the
+ * dataspace, in each dimension.
+ *
+ * The \p block array determines the size of the element block
+ * selected from the dataspace. If the \p block parameter is set to
+ * NULL, the block size defaults to a single element in each dimension
+ * (as if each value in the \p block array were set to \p 1).
+ *
+ * For example, consider a 2-dimensional dataspace with hyperslab
+ * selection settings as follows: the \p start offset is specified as
+ * [1,1], \p stride is [4,4], \p count is [3,7], and \p block is [2,2].
+ * In C, these settings will specify a hyperslab consisting of 21
+ * 2x2 blocks of array elements starting with location (1,1) with the
+ * selected blocks at locations (1,1), (5,1), (9,1), (1,5), (5,5), etc.;
+ * in Fortran, they will specify a hyperslab consisting of 21 2x2
+ * blocks of array elements starting with location (2,2) with the
+ * selected blocks at locations (2,2), (6,2), (10,2), (2,6), (6,6), etc.
+ *
+ * Regions selected with this function call default to C order
+ * iteration when I/O is performed.
+ *
+ * \version 1.4.0 Fortran subroutine introduced in this release.
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Sselect_hyperslab(hid_t space_id, H5S_seloper_t op,
+ const hsize_t start[], const hsize_t stride[], const hsize_t count[],
+ const hsize_t block[]);
H5_DLL herr_t H5Sset_extent_simple(hid_t space_id, int rank, const hsize_t dims[], const hsize_t max[]);
H5_DLL hid_t H5Scopy(hid_t space_id);
-H5_DLL herr_t H5Sclose(hid_t space_id);
H5_DLL herr_t H5Sencode2(hid_t obj_id, void *buf, size_t *nalloc, hid_t fapl);
H5_DLL hid_t H5Sdecode(const void *buf);
H5_DLL hssize_t H5Sget_simple_extent_npoints(hid_t space_id);
-H5_DLL int H5Sget_simple_extent_ndims(hid_t space_id);
-H5_DLL int H5Sget_simple_extent_dims(hid_t space_id, hsize_t dims[], hsize_t maxdims[]);
H5_DLL htri_t H5Sis_simple(hid_t space_id);
H5_DLL H5S_class_t H5Sget_simple_extent_type(hid_t space_id);
H5_DLL herr_t H5Sset_extent_none(hid_t space_id);
@@ -139,7 +410,6 @@ H5_DLL htri_t H5Sextent_equal(hid_t sid1, hid_t sid2);
/* Operations on dataspace selections */
H5_DLL H5S_sel_type H5Sget_select_type(hid_t spaceid);
-H5_DLL hssize_t H5Sget_select_npoints(hid_t spaceid);
H5_DLL herr_t H5Sselect_copy(hid_t dst_id, hid_t src_id);
H5_DLL htri_t H5Sselect_valid(hid_t spaceid);
H5_DLL herr_t H5Sselect_adjust(hid_t spaceid, const hssize_t *offset);
@@ -153,8 +423,6 @@ H5_DLL herr_t H5Sselect_elements(hid_t space_id, H5S_seloper_t op, size_t num_
H5_DLL hssize_t H5Sget_select_elem_npoints(hid_t spaceid);
H5_DLL herr_t H5Sget_select_elem_pointlist(hid_t spaceid, hsize_t startpoint, hsize_t numpoints,
hsize_t buf[/*numpoints*/]);
-H5_DLL herr_t H5Sselect_hyperslab(hid_t space_id, H5S_seloper_t op, const hsize_t start[],
- const hsize_t _stride[], const hsize_t count[], const hsize_t _block[]);
H5_DLL hid_t H5Scombine_hyperslab(hid_t space_id, H5S_seloper_t op, const hsize_t start[],
const hsize_t _stride[], const hsize_t count[], const hsize_t _block[]);
H5_DLL herr_t H5Smodify_select(hid_t space1_id, H5S_seloper_t op, hid_t space2_id);