diff options
| author | Gerd Heber <gheber@hdfgroup.org> | 2021-09-01 21:09:27 (GMT) |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2021-09-01 21:09:27 (GMT) |
| commit | cf25524474a4012a70cc2bdb6eaddc402b5ea136 (patch) | |
| tree | cf7e30d16a602e5146500158696d429a146cb2c2 /src | |
| parent | 01fe2549a36d7635b2cbe6f6a57cbcce29c1335b (diff) | |
| download | hdf5-cf25524474a4012a70cc2bdb6eaddc402b5ea136.zip hdf5-cf25524474a4012a70cc2bdb6eaddc402b5ea136.tar.gz hdf5-cf25524474a4012a70cc2bdb6eaddc402b5ea136.tar.bz2 | |
A batch of life-cycle examples for different modules (#654)
* Create a tag file for permalinks.
* Added DOXYGEN_TAG_FILE.
* Added Doxygen life-cycle examples for different modules.
Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
Diffstat (limited to 'src')
| -rw-r--r-- | src/CMakeLists.txt | 1 | ||||
| -rw-r--r-- | src/H5Amodule.h | 24 | ||||
| -rw-r--r-- | src/H5Apublic.h | 267 | ||||
| -rw-r--r-- | src/H5Dmodule.h | 8 | ||||
| -rw-r--r-- | src/H5Dpublic.h | 562 | ||||
| -rw-r--r-- | src/H5ESmodule.h | 6 | ||||
| -rw-r--r-- | src/H5Emodule.h | 75 | ||||
| -rw-r--r-- | src/H5Epublic.h | 36 | ||||
| -rw-r--r-- | src/H5Fmodule.h | 19 | ||||
| -rw-r--r-- | src/H5Fpublic.h | 2 | ||||
| -rw-r--r-- | src/H5Gmodule.h | 25 | ||||
| -rw-r--r-- | src/H5Gpublic.h | 2 | ||||
| -rw-r--r-- | src/H5Imodule.h | 81 | ||||
| -rw-r--r-- | src/H5Ipublic.h | 33 | ||||
| -rw-r--r-- | src/H5Lmodule.h | 25 | ||||
| -rw-r--r-- | src/H5Lpublic.h | 2 | ||||
| -rw-r--r-- | src/H5Mmodule.h | 6 | ||||
| -rw-r--r-- | src/H5Mpublic.h | 2 | ||||
| -rw-r--r-- | src/H5Omodule.h | 41 | ||||
| -rw-r--r-- | src/H5Opublic.h | 681 | ||||
| -rw-r--r-- | src/H5PLmodule.h | 30 | ||||
| -rw-r--r-- | src/H5Pmodule.h | 164 | ||||
| -rw-r--r-- | src/H5Ppublic.h | 51 | ||||
| -rw-r--r-- | src/H5Rmodule.h | 29 | ||||
| -rw-r--r-- | src/H5Rpublic.h | 10 | ||||
| -rw-r--r-- | src/H5Smodule.h | 45 | ||||
| -rw-r--r-- | src/H5Spublic.h | 112 | ||||
| -rw-r--r-- | src/H5Tmodule.h | 36 | ||||
| -rw-r--r-- | src/H5VLmodule.h | 8 | ||||
| -rw-r--r-- | src/H5Zmodule.h | 109 | ||||
| -rw-r--r-- | src/H5module.h | 27 | ||||
| -rw-r--r-- | src/H5public.h | 30 |
32 files changed, 1166 insertions, 1383 deletions
diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index ff47c8e..7989899 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -1416,6 +1416,7 @@ if (DOXYGEN_FOUND) set (DOXYGEN_HTML_FOOTER ${HDF5_DOXYGEN_DIR}/hdf5_footer.html) set (DOXYGEN_HTML_EXTRA_STYLESHEET ${HDF5_DOXYGEN_DIR}/hdf5doxy.css) set (DOXYGEN_HTML_EXTRA_FILES "${HDF5_DOXYGEN_DIR}/hdf5_navtree_hacks.js ${HDF5_DOXYGEN_DIR}/img/ftv2node.png ${HDF5_DOXYGEN_DIR}/img/ftv2pnode.png") + set (DOXYGEN_TAG_FILE ${HDF5_DOXYGEN_DIR}/hdf5.tag) set (DOXYGEN_SERVER_BASED_SEARCH NO) set (DOXYGEN_EXTERNAL_SEARCH NO) set (DOXYGEN_SEARCHENGINE_URL) diff --git a/src/H5Amodule.h b/src/H5Amodule.h index c89c93f..9f86ddd 100644 --- a/src/H5Amodule.h +++ b/src/H5Amodule.h @@ -33,33 +33,29 @@ * * Use the functions in this module to manage HDF5 attributes. * - * 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. + * Like HDF5 datasets, HDF5 attributes are array variables which have an element + * datatype and a shape (dataspace). However, they perform a different function: + * Attributes decorate other HDF5 objects, and are typically used to + * represent application metadata. Unlike datasets, the HDF5 library does not + * support partial I/O operations for attributes and they cannot be compressed + * or extended. * * <table> * <tr><th>Create</th><th>Read</th></tr> * <tr valign="top"> * <td> - * \snippet H5A_examples.c create + * \snippet{lineno} H5A_examples.c create * </td> * <td> - * \snippet H5A_examples.c read + * \snippet{lineno} H5A_examples.c read * </td> * <tr><th>Update</th><th>Delete</th></tr> * <tr valign="top"> * <td> - * \snippet H5A_examples.c update + * \snippet{lineno} H5A_examples.c update * </td> * <td> - * \snippet H5A_examples.c delete + * \snippet{lineno} H5A_examples.c delete * </td> * </tr> * </table> diff --git a/src/H5Apublic.h b/src/H5Apublic.h index b3da77f..b78ae05 100644 --- a/src/H5Apublic.h +++ b/src/H5Apublic.h @@ -78,11 +78,11 @@ extern "C" { * * \return \herr_t * - * \details H5Aclose() terminates access to the attribute specified by - * \p attr_id by releasing the identifier. + * \details H5Aclose() terminates access to the attribute through + * \p attr_id and releases the identifier. * - * \attention Further use of a released attribute identifier is illegal; a - * function using such an identifier will generate an error. + * \par Example + * \snippet H5A_examples.c create * * \since 1.0.0 * @@ -117,27 +117,19 @@ H5_DLL herr_t H5Aclose_async(const char *app_file, const char *app_func, unsigne * 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. + * \p type_id and \p space_id. * - * 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. + * \plist_unused{acpl} * * The attribute identifier returned by this function must be released * with H5Aclose() resource leaks will develop. * - * \note The \p aapl parameter is currently not used; specify #H5P_DEFAULT. - * * \note If \p loc_id is a file identifier, the attribute will be attached * that file’s root group. * + * \par Example + * \snippet H5A_examples.c create + * * \since 1.8.0 * * \see H5Aclose() @@ -175,28 +167,19 @@ H5_DLL hid_t H5Acreate_async(const char *app_file, const char *app_func, unsigne * 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). + * name relative to \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. + * dataspace, \p type_id and \p space_id. * - * 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. + * \plist_unused{aapl} * * 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 * */ @@ -224,10 +207,14 @@ H5_DLL hid_t H5Acreate_by_name_async(const char *app_file, const char *app_func, * * \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. + * + * \attention This function should not be used when other attribute identifiers + * are open on \p loc_id. This may cause the internal indexes of + * the attributes to change and future writes to the open + * attributes to produce incorrect results. + * + * \par Example + * \snippet H5A_examples.c delete * * \since 1.0.0 * @@ -254,27 +241,16 @@ H5_DLL herr_t H5Adelete(hid_t loc_id, const char *attr_name); * * 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). + * \p obj_name, respectively. * * 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, + * index, \p n. The type of index is specified by \p idx_type. + * The order in which the index is to be traversed is specified by + * \p 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 + * respectively, the fifth attribute in lexicographic 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. @@ -302,9 +278,6 @@ H5_DLL herr_t H5Adelete_by_idx(hid_t loc_id, const char *obj_name, H5_index_t id * 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. @@ -360,9 +333,7 @@ H5_DLL herr_t H5Aexists_async(const char *app_file, const char *app_func, unsign * \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). + * or an absolute name, based in the root group of the file. * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to access @@ -394,9 +365,6 @@ H5_DLL herr_t H5Aexists_by_name_async(const char *app_file, const char *app_func * 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 * */ @@ -413,32 +381,9 @@ H5_DLL hid_t H5Aget_create_plist(hid_t attr_id); * \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 with an attribute identifier, \p attr_id. 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 * */ @@ -466,16 +411,9 @@ H5_DLL herr_t H5Aget_info(hid_t attr_id, H5A_info_t *ainfo /*out*/); * 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(). + * \p order and \p n, respectively. * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to access @@ -493,8 +431,7 @@ H5_DLL herr_t H5Aget_info_by_idx(hid_t loc_id, const char *obj_name, H5_index_t * \brief Retrieves attribute information, by attribute name * * \fgdt_loc_id - * - * \param[in] obj_name Name of object to which attribute is attached, + * \param[in] obj_name Name of the object to which an attribute is attached, * relative to location * \param[in] attr_name Attribute name * \param[out] ainfo Struct containing returned attribute information @@ -507,11 +444,6 @@ H5_DLL herr_t H5Aget_info_by_idx(hid_t loc_id, const char *obj_name, H5_index_t * 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. @@ -542,8 +474,8 @@ H5_DLL herr_t H5Aget_info_by_name(hid_t loc_id, const char *obj_name, const char * 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 + * If the user only wants to retrieve the name length, the + * values 0 and NULL should be passed for the parameters * \p bufsize and \p buf. * * \since 1.0.0 @@ -554,7 +486,7 @@ 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 + * \brief Gets an attribute name by attribute index position * * \fgdt_loc_id * \param[in] obj_name Name of object to which attribute is attached, @@ -575,13 +507,9 @@ H5_DLL ssize_t H5Aget_name(hid_t attr_id, size_t buf_size, char *buf); * 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(). + * \p order and \p n, respectively. * * 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 @@ -621,7 +549,7 @@ H5_DLL hid_t H5Aget_space(hid_t attr_id); /** * \ingroup H5A * - * \brief Returns the amount of storage required for an attribute + * \brief Returns the amount of storage used to store an attribute * * \attr_id * @@ -639,17 +567,16 @@ H5_DLL hsize_t H5Aget_storage_size(hid_t attr_id); /** * \ingroup H5A * - * \brief Gets an attribute datatype + * \brief Gets an attribute's datatype * * \attr_id * * \return \hid_t{datatype} * - * \details H5Aget_type() retrieves a copy of the datatype for an attribute. + * \details H5Aget_type() retrieves a copy of the attribute's datatype. * 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. + * are always read-only. * * The datatype identifier returned from this function must be * released with H5Tclose() or resource leaks will develop. @@ -662,7 +589,7 @@ H5_DLL hid_t H5Aget_type(hid_t attr_id); /** * \ingroup H5A * - * \brief Calls user-defined function for each attribute on an object + * \brief Calls a user-defined function for each attribute on an object * * \fgdt_loc_id * \param[in] idx_type Type of index @@ -689,17 +616,6 @@ H5_DLL hid_t H5Aget_type(hid_t attr_id); * 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. * @@ -716,11 +632,6 @@ H5_DLL hid_t H5Aget_type(hid_t attr_id); * the value returned identifies the parameter to be operated on * in the next step of the iteration. * - * \p op is a user-defined function whose prototype is defined - * as follows: - * \snippet this H5A_operator2_t_snip - * \click4more - * * \note This function is also available through the H5Aiterate() macro. * * \since 1.8.0 @@ -756,24 +667,10 @@ H5_DLL herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t ord * 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. * @@ -790,25 +687,6 @@ H5_DLL herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t ord * the value returned identifies the parameter to be operated on in * the next step of the iteration. * - * \p op is a user-defined function whose prototype is defined - * as follows: - * \snippet this H5A_operator2_t_snip - * \click4more - * - * Valid return values from an operator and the resulting - * H5Aiterate_by_name() and \p op behavior are as follows: - * - * \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. @@ -835,8 +713,7 @@ H5_DLL herr_t H5Aiterate_by_name(hid_t loc_id, const char *obj_name, H5_index_t * \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. + * \plist_unused{aapl_id} * * This function, H5Aopen_by_idx() or H5Aopen_by_name() must be called * before the attribute can be accessed for any further purpose, @@ -845,6 +722,9 @@ H5_DLL herr_t H5Aiterate_by_name(hid_t loc_id, const char *obj_name, H5_index_t * The attribute identifier returned by this function must be released * with H5Aclose() or resource leaks will develop. * + * \par Example + * \snippet H5A_examples.c read + * * \since 1.8.0 * * \see H5Aclose(), H5Acreate() @@ -876,17 +756,13 @@ H5_DLL hid_t H5Aopen_async(const char *app_file, const char *app_func, unsigned * * \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). + * \p obj_name, respectively. * * 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(). + * \p n, respectively. * - * The attribute access property list, \p aapl_id, is currently - * unused and should currently be #H5P_DEFAULT. + * \plist_unused{aapl_id} * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to access @@ -933,11 +809,9 @@ H5_DLL hid_t H5Aopen_by_idx_async(const char *app_file, const char *app_func, un * * \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). + * \p loc_id. * - * The attribute access property list, \p aapl_id, is currently - * unused and should currently be #H5P_DEFAULT. + * \plist_unused{aapl_id} * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to access @@ -982,6 +856,9 @@ H5_DLL hid_t H5Aopen_by_name_async(const char *app_file, const char *app_func, u * Datatype conversion takes place at the time of a read or write and * is automatic. * + * \par Example + * \snippet H5A_examples.c read + * * \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. @@ -1051,15 +928,12 @@ H5_DLL herr_t H5Arename_by_name_async(const char *app_file, const char *app_func * 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. * + * \par Example + * \snippet H5A_examples.c update + * * \version 1.8.8 Fortran updated to Fortran2003. * \version 1.4.2 Fortran \p dims parameter added in this release * \since 1.0.0 @@ -1100,6 +974,7 @@ H5_DLL herr_t H5Awrite_async(const char *app_file, const char *app_func, unsigne 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); +/// \cond DEV /* API Wrappers for async routines */ /* (Must be defined _after_ the function prototype) */ /* (And must only defined when included in application code, not the library) */ @@ -1133,6 +1008,7 @@ H5_DLL herr_t H5Arename_by_name(hid_t loc_id, const char *obj_name, const char * #define H5Aexists_by_name_async_wrap H5_NO_EXPAND(H5Aexists_by_name_async) #define H5Aclose_async_wrap H5_NO_EXPAND(H5Aclose_async) #endif /* H5A_MODULE */ +/// \endcond /* Symbols defined for compatibility with previous versions of the HDF5 API. * @@ -1182,9 +1058,9 @@ typedef herr_t (*H5A_operator1_t)(hid_t location_id /*in*/, const char *attr_nam * * \return \hid_tv{attribute} * - * \note The \p acpl parameters is currently not used; specify #H5P_DEFAULT. + * \deprecation_note{H5Acreate2()} * - * \deprecated Deprecated in favor of H5Acreate2() + * \plist_unused{acpl} * * \details H5Acreate1() creates an attribute, \p name, which is attached * to the object specified by the identifier \p loc_id. @@ -1192,18 +1068,7 @@ typedef herr_t (*H5A_operator1_t)(hid_t location_id /*in*/, const char *attr_nam * 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. + * \p type_id and \p space_id. * * \since 1.8.0 * @@ -1225,8 +1090,7 @@ H5_DLL hid_t H5Acreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t spa * \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(). + * \deprecation_note{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. @@ -1249,8 +1113,7 @@ H5_DLL int H5Aget_num_attrs(hid_t loc_id); * * \return \herr_t * - * \deprecated This function is deprecated in favor of the function - * H5Aiterate2(). + * \deprecation_note{H5Aiterate2()} * * \details H5Aiterate1() iterates over the attributes of the object * specified by its identifier, \p loc_id. The object can be a @@ -1262,10 +1125,6 @@ H5_DLL int H5Aget_num_attrs(hid_t loc_id); * \p op, is returned in \p idx. If \p idx is the null pointer, * then all attributes are processed. * - * \p op is a user-defined function whose prototype is defined as follows: - * \snippet this H5A_operator1_t_snip - * \click4more - * * \version 1.8.0 The function \p H5Aiterate was renamed to H5Aiterate1() * and deprecated in this release. * \since 1.0.0 @@ -1283,8 +1142,7 @@ H5_DLL herr_t H5Aiterate1(hid_t loc_id, unsigned *idx, H5A_operator1_t op, void * * \return \hid_tv{attribute} * - * \deprecated This function is deprecated in favor of the function - * H5Aopen_by_idx(). + * \deprecation_note{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 @@ -1310,8 +1168,7 @@ H5_DLL hid_t H5Aopen_idx(hid_t loc_id, unsigned idx); * * \return \hid_tv{attribute} * - * \deprecated This function is deprecated in favor of the function - * H5Aopen_by_name(). + * \deprecation_note{H5Aopen_by_name()} * * \details H5Aopen_name() opens an attribute specified by its name, * \p name, which is attached to the object specified with diff --git a/src/H5Dmodule.h b/src/H5Dmodule.h index 595c714..596fd48 100644 --- a/src/H5Dmodule.h +++ b/src/H5Dmodule.h @@ -44,18 +44,18 @@ * <tr><th>Create</th><th>Read</th></tr> * <tr valign="top"> * <td> - * \snippet H5D_examples.c create + * \snippet{lineno} H5D_examples.c create * </td> * <td> - * \snippet H5D_examples.c read + * \snippet{lineno} H5D_examples.c read * </td> * <tr><th>Update</th><th>Delete</th></tr> * <tr valign="top"> * <td> - * \snippet H5D_examples.c update + * \snippet{lineno} H5D_examples.c update * </td> * <td> - * \snippet H5D_examples.c delete + * \snippet{lineno} H5D_examples.c delete * </td> * </tr> * </table> diff --git a/src/H5Dpublic.h b/src/H5Dpublic.h index 63cc61c..8fe8020 100644 --- a/src/H5Dpublic.h +++ b/src/H5Dpublic.h @@ -32,7 +32,9 @@ #define H5D_CHUNK_CACHE_NBYTES_DEFAULT SIZE_MAX #define H5D_CHUNK_CACHE_W0_DEFAULT (-1.0) -/* Bit flags for the H5Pset_chunk_opts() and H5Pget_chunk_opts() */ +/** + * Bit flags for the H5Pset_chunk_opts() and H5Pget_chunk_opts() + */ #define H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS (0x0002u) /*******************/ @@ -44,13 +46,12 @@ * Values for the H5D_LAYOUT property */ typedef enum H5D_layout_t { - H5D_LAYOUT_ERROR = -1, - - H5D_COMPACT = 0, /**< raw data is very small */ - H5D_CONTIGUOUS = 1, /**< the default */ - H5D_CHUNKED = 2, /**< slow and fancy */ - H5D_VIRTUAL = 3, /**< actual data is stored in other datasets */ - H5D_NLAYOUTS = 4 /**< this one must be last! */ + H5D_LAYOUT_ERROR = -1, /**< error */ + H5D_COMPACT = 0, /**< raw data is small (< 64KB) */ + H5D_CONTIGUOUS = 1, /**< contiguous layout */ + H5D_CHUNKED = 2, /**< chunked or tiled layout */ + H5D_VIRTUAL = 3, /**< actual data is stored in other datasets */ + H5D_NLAYOUTS = 4 /**< this one must be last! */ } H5D_layout_t; //! <!-- [H5D_layout_t_snip] --> @@ -75,11 +76,11 @@ typedef enum H5D_chunk_index_t { * Values for the space allocation time property */ typedef enum H5D_alloc_time_t { - H5D_ALLOC_TIME_ERROR = -1, - H5D_ALLOC_TIME_DEFAULT = 0, - H5D_ALLOC_TIME_EARLY = 1, - H5D_ALLOC_TIME_LATE = 2, - H5D_ALLOC_TIME_INCR = 3 + H5D_ALLOC_TIME_ERROR = -1, /**< Error */ + H5D_ALLOC_TIME_DEFAULT = 0, /**< \todo Define this! */ + H5D_ALLOC_TIME_EARLY = 1, /**< Allocate on creation */ + H5D_ALLOC_TIME_LATE = 2, /**< Allocate on first write */ + H5D_ALLOC_TIME_INCR = 3 /**< Allocate incrementally (by chunk) */ } H5D_alloc_time_t; //! <!-- [H5D_alloc_time_t_snip] --> @@ -88,10 +89,11 @@ typedef enum H5D_alloc_time_t { * Values for the status of space allocation */ typedef enum H5D_space_status_t { - H5D_SPACE_STATUS_ERROR = -1, - H5D_SPACE_STATUS_NOT_ALLOCATED = 0, - H5D_SPACE_STATUS_PART_ALLOCATED = 1, - H5D_SPACE_STATUS_ALLOCATED = 2 + H5D_SPACE_STATUS_ERROR = -1, /**< Error */ + H5D_SPACE_STATUS_NOT_ALLOCATED = 0, /**< Space has not been allocated for this dataset. */ + H5D_SPACE_STATUS_PART_ALLOCATED = 1, /**< Space has been allocated for this dataset. */ + H5D_SPACE_STATUS_ALLOCATED = 2 /**< Space has been partially allocated for this dataset. (Used only for + datasets with chunked storage.) */ } H5D_space_status_t; //! <!-- [H5D_space_status_t_snip] --> @@ -100,10 +102,10 @@ typedef enum H5D_space_status_t { * Values for time of writing fill value property */ typedef enum H5D_fill_time_t { - H5D_FILL_TIME_ERROR = -1, - H5D_FILL_TIME_ALLOC = 0, - H5D_FILL_TIME_NEVER = 1, - H5D_FILL_TIME_IFSET = 2 + H5D_FILL_TIME_ERROR = -1, /**< Error */ + H5D_FILL_TIME_ALLOC = 0, /**< Fill on allocation */ + H5D_FILL_TIME_NEVER = 1, /**< Never write fill values */ + H5D_FILL_TIME_IFSET = 2 /**< Fill if fill-value was set */ } H5D_fill_time_t; //! <!-- [H5D_fill_time_t_snip] --> @@ -112,10 +114,10 @@ typedef enum H5D_fill_time_t { * Values for fill value status */ typedef enum H5D_fill_value_t { - H5D_FILL_VALUE_ERROR = -1, - H5D_FILL_VALUE_UNDEFINED = 0, - H5D_FILL_VALUE_DEFAULT = 1, - H5D_FILL_VALUE_USER_DEFINED = 2 + H5D_FILL_VALUE_ERROR = -1, /**< Error */ + H5D_FILL_VALUE_UNDEFINED = 0, /**< No fill value defined */ + H5D_FILL_VALUE_DEFAULT = 1, /**< Default fill-value */ + H5D_FILL_VALUE_USER_DEFINED = 2 /**< User-defined fill-value */ } H5D_fill_value_t; //! <!-- [H5D_fill_value_t_snip] --> @@ -124,22 +126,40 @@ typedef enum H5D_fill_value_t { * Values for VDS bounds option */ typedef enum H5D_vds_view_t { - H5D_VDS_ERROR = -1, - H5D_VDS_FIRST_MISSING = 0, - H5D_VDS_LAST_AVAILABLE = 1 + H5D_VDS_ERROR = -1, /**< Error */ + H5D_VDS_FIRST_MISSING = 0, /**< \todo Define this! */ + H5D_VDS_LAST_AVAILABLE = 1 /**< \todo Define this! */ } H5D_vds_view_t; //! <!-- [H5D_vds_view_t_snip] --> //! <!-- [H5D_append_cb_t_snip] --> /** - * Callback for H5Pset_append_flush() in a dataset access property list + * \brief Callback for H5Pset_append_flush() + * + * \dset_id{dataset_id} + * \param[in] cur_dims The current extent of the dataset's dimensions + * \param[in,out] op_data User context + * + * \return \herr_t + * */ typedef herr_t (*H5D_append_cb_t)(hid_t dataset_id, hsize_t *cur_dims, void *op_data); //! <!-- [H5D_append_cb_t_snip] --> //! <!-- [H5D_operator_t_snip] --> /** - * Define the operator function pointer for H5Diterate() + * \brief Callback for H5Diterate() + * + * \param[in,out] elem Pointer to the memory buffer containing the current dataset + * element + * \param[in] type_id Datatype identifier of the elements stored in \pelem + * \param[in] ndim Number of dimensions for the \p point array + * \param[in] point Array containing the location of the element within + * the original dataspace + * \param[in,out] operator_data Pointer to any user-defined data associated with + * the operation + * \return \herr_t_iter + * */ typedef herr_t (*H5D_operator_t)(void *elem, hid_t type_id, unsigned ndim, const hsize_t *point, void *operator_data); @@ -147,7 +167,29 @@ typedef herr_t (*H5D_operator_t)(void *elem, hid_t type_id, unsigned ndim, const //! <!-- [H5D_scatter_func_t_snip] --> /** - * Define the operator function pointer for H5Dscatter() + * \brief Callback for H5Dscatter() + * + * \param[out] src_buf Pointer to the buffer holding the next set of elements to + * scatter. On entry, the value of where \p src_buf points to + * is undefined. The callback function should set \p src_buf + * to point to the next set of elements. + * \param[out] src_buf_bytes_used Pointer to the number of valid bytes in \p src_buf. + * On entry, the value where \p src_buf_bytes_used points + * to is undefined. The callback function should set + * \p src_buf_bytes_used to the of valid bytes in \p src_buf. + * This number must be a multiple of the datatype size. + * \param[in,out] op_data User-defined pointer to data required by the callback + * function. A pass-through of the \p op_data pointer provided + * with the H5Dscatter() function call. + * \return herr_t + * + * \details The callback function should always return at least one + * element in \p src_buf, and must not return more elements + * than are remaining to be scattered. This function will be + * repeatedly called until all elements to be scattered have + * been returned. The callback function should return zero (0) + * to indicate success, and a negative value to indicate failure. + * */ typedef herr_t (*H5D_scatter_func_t)(const void **src_buf /*out*/, size_t *src_buf_bytes_used /*out*/, void *op_data); @@ -155,18 +197,51 @@ typedef herr_t (*H5D_scatter_func_t)(const void **src_buf /*out*/, size_t *src_b //! <!-- [H5D_gather_func_t_snip] --> /** - * Define the operator function pointer for H5Dgather() + * \brief Callback for H5Dgather() + * + * \param[in] dst_buf Pointer to the destination buffer which has been filled + * with the next set of elements gathered. This will always + * be identical to the \p dst_buf passed to H5Dgather() + * \param[in] dst_buf_bytes_used Pointer to the number of valid bytes in + * \p dst_buf. This number must be a multiple of + * the datatype size. + * \param[in,out] op_data User-defined pointer to data required by the callback + * function; a pass-through of the \p op_data pointer + * provided with the H5Dgather() function call. + * \returns \herr_t + * + * \details The callback function should process, store, or otherwise make use + * of the data returned in dst_buf before it returns, because the + * buffer will be overwritten unless it is the last call to the + * callback. This function will be repeatedly called until all gathered + * elements have been passed to the callback in dst_buf. The callback + * function should return zero (0) to indicate success, and a negative + * value to indicate failure. + * */ typedef herr_t (*H5D_gather_func_t)(const void *dst_buf, size_t dst_buf_bytes_used, void *op_data); //! <!-- [H5D_gather_func_t_snip] --> //! <!-- [H5D_chunk_iter_op_t_snip] --> /** - * Define the operator function pointer for H5Dchunk_iter() + * \brief Callback for H5Dchunk_iter() + * + * \param[in] offset Array of starting logical coordinates of chunk. + * \param[in] filter_mask Filter mask of chunk. + * \param[in] addr Offset in file of chunk data. + * \param[in] nbytes Size in bytes of chunk data in file. + * \param[in,out] op_data Pointer to any user-defined data associated with + * the operation. + * \returns \li Zero (#H5_ITER_CONT) causes the iterator to continue, returning + * zero when all elements have been processed. + * \li A positive value (#H5_ITER_STOP) causes the iterator to + * immediately return that value, indicating short-circuit success. + * \li A negative (#H5_ITER_ERROR) causes the iterator to immediately + * return that value, indicating failure. */ -//! <!-- [H5D_chunk_iter_op_t_snip] --> typedef int (*H5D_chunk_iter_op_t)(const hsize_t *offset, uint32_t filter_mask, haddr_t addr, uint32_t nbytes, void *op_data); +//! <!-- [H5D_chunk_iter_op_t_snip] --> /********************/ /* Public Variables */ @@ -186,7 +261,7 @@ extern "C" { * \brief Creates a new dataset and links it into the file * * \fgdta_loc_id - * \param[in] name Name of the dataset to create + * \param[in] name Name of the dataset to create * \type_id * \space_id * \lcpl_id @@ -211,13 +286,6 @@ extern "C" { * \p name may be either an absolute path in the file or a relative * path from \p loc_id naming the dataset. * - * \p dtype_id specifies the datatype of each data element as stored - * in the file. If \p dtype_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. - * * If \p dtype_id is a committed datatype, and if the file location * associated with the committed datatype is different from the * file location where the dataset will be created, the datatype @@ -225,7 +293,7 @@ extern "C" { * * The link creation property list, \p lcpl_id, governs creation * of the link(s) by which the new dataset is accessed and the - * creation of any * intermediate groups that may be missing. + * creation of any intermediate groups that may be missing. * * The datatype and dataspace properties and the dataset creation * and access property lists are attached to the dataset, so the @@ -236,8 +304,8 @@ extern "C" { * not previously written, the HDF5 library will return default * or user-defined fill values. * - * To conserve and release resources, the dataset should be closed - * when access is no longer required. + * \par Example + * \snippet H5D_examples.c create * * \since 1.8.0 * @@ -285,34 +353,14 @@ H5_DLL hid_t H5Dcreate_async(const char *app_file, const char *app_func, unsigne * the file, which may differ from the datatype and dataspace * in application memory. * - * Dataset creation property list and dataset access creation - * property list are specified by \p dcpl_id and \p dapl_id. - * * H5Dcreate_anon() returns a new dataset identifier. Using * this identifier, the new dataset must be linked into the * HDF5 file structure with H5Olink() or it will be deleted - * from the file when the file is closed. - * - * See H5Dcreate2() for further details and considerations on - * the use of H5Dcreate2() and H5Dcreate_anon(). - * - * The differences between this function and H5Dcreate2() are - * as follows: - * \li H5Dcreate_anon() explicitly includes a dataset access property - * list. H5Dcreate() always uses default dataset access properties. - * - * \li H5Dcreate_anon() neither provides the new dataset’s name nor - * links it into the HDF5 file structure; those actions must be - * performed separately through a call to H5Olink(), which offers - * greater control over linking. - * - * A dataset created with this function should be closed with - * H5Dclose() when the dataset is no longer needed so that resource - * leaks will not develop. + * when the file is closed. * * \since 1.8.0 * - * \see H5Olink(), H5Dcreate(), Using Identifiers + * \see H5Olink(), H5Dcreate() * */ H5_DLL hid_t H5Dcreate_anon(hid_t loc_id, hid_t type_id, hid_t space_id, hid_t dcpl_id, hid_t dapl_id); @@ -338,12 +386,6 @@ H5_DLL hid_t H5Dcreate_anon(hid_t loc_id, hid_t type_id, hid_t space_id, hid_t d * specified then the dataset will be opened at the location * where the attribute, dataset, or named datatype is attached. * - * The dataset access property list, \p dapl_id, provides - * information regarding access to the dataset. - * - * To conserve and release resources, the dataset should be closed - * when access is no longer required. - * * \since 1.8.0 * * \see H5Dcreate2(), H5Dclose() @@ -377,6 +419,9 @@ H5_DLL hid_t H5Dopen_async(const char *app_file, const char *app_func, unsigned * be released with H5Sclose() when the identifier is no longer * needed so that resource leaks will not occur. * + * \par Example + * \snippet H5D_examples.c update + * * \see H5Sclose() * */ @@ -393,7 +438,19 @@ H5_DLL hid_t H5Dget_space_async(const char *app_file, const char *app_func, unsi /** * -------------------------------------------------------------------------- * \ingroup H5D - * \todo Document this function! + * + * \brief Determines whether space has been allocated for a dataset + * + * \dset_id + * \param[out] allocation Space allocation status + * + * \return \herr_t + * + * \details H5Dget_space_status() determines whether space has been allocated + * for the dataset \p dset_id. + * + * \since 1.6.0 + * */ H5_DLL herr_t H5Dget_space_status(hid_t dset_id, H5D_space_status_t *allocation); @@ -412,27 +469,7 @@ H5_DLL herr_t H5Dget_space_status(hid_t dset_id, H5D_space_status_t *allocation) * * If a dataset has a named datatype, then an identifier to the * opened datatype is returned. Otherwise, the returned datatype - * is read-only. If atomization of the datatype fails, then the - * datatype is closed. - * - * A datatype identifier returned from this function should be - * released with H5Tclose() when the identifier is no longer - * needed to prevent resource leaks. - * - * \note Datatype Identifiers - * - * Please note that the datatype identifier is actually an object - * identifier or a handle returned from opening the datatype. It - * is not persistent and its value can be different from one HDF5 - * session to the next. - * - * H5Tequal() can be used to compare datatypes. - * - * HDF5 High Level APIs that may also be of interest are: - * - * H5LTdtype_to_text() creates a text description of a - * datatype. H5LTtext_to_dtype() creates an HDF5 datatype - * given a text description. + * is read-only. * */ H5_DLL hid_t H5Dget_type(hid_t dset_id); @@ -452,9 +489,6 @@ H5_DLL hid_t H5Dget_type(hid_t dset_id); * a copy of the dataset creation property list associated with * the dataset specified by \p dset_id. * - * The creation property list identifier should be released - * with H5Pclose() to prevent resource leaks. - * */ H5_DLL hid_t H5Dget_create_plist(hid_t dset_id); @@ -488,10 +522,6 @@ H5_DLL hid_t H5Dget_create_plist(hid_t dset_id); * All link access properties in the returned list will be set * to the default values. * - * The access property list identifier should be released with - * H5Pclose() when the identifier is no longer needed so that - * resource leaks will not develop. - * * \since 1.8.3 * */ @@ -510,11 +540,8 @@ H5_DLL hid_t H5Dget_access_plist(hid_t dset_id); * \details H5Dget_storage_size() returns the amount of storage, * in bytes, that is allocated in the file for the raw data of * the dataset specified by \p dset_id. - * - * \note The amount of storage in this case is the storage - * allocated in the written file, which will typically differ - * from the space required to hold a dataset in working memory. - * + * H5Dget_storage_size() reports only the space required to store + * the dataset elements, excluding any metadata. * \li For contiguous datasets, the returned size equals the current * allocated size of the raw data. * \li For unfiltered chunked datasets, the returned size is the @@ -524,21 +551,19 @@ H5_DLL hid_t H5Dget_access_plist(hid_t dset_id); * compression filter is in use, H5Dget_storage_size() will return * the total space required to store the compressed chunks. * - * H5Dget_storage_size() reports only the space required to store - * the data, not including that of any metadata. + * \note Note that H5Dget_storage_size() is not generally an + * appropriate function to use when determining the amount + * of memory required to work with a dataset. In such + * circumstances, you must determine the number of data + * points in a dataset and the size of an individual dataset + * element. H5Sget_simple_extent_npoints() and H5Tget_size() + * can be used to calculate that amount. * - * \attention H5Dget_storage_size() does not differentiate between 0 (zero), + * \warning H5Dget_storage_size() does not differentiate between 0 (zero), * the value returned for the storage size of a dataset * with no stored values, and 0 (zero), the value returned to * indicate an error. * - * \note Note that H5Dget_storage_size() is not generally an - * appropriate function to use when determining the amount - * of memory required to work with a dataset. In such - * circumstances, you must determine the number of data - * points in a dataset and the size of an individual data - * element. H5Sget_simple_extent_npoints() and H5Tget_size() - * can be used to get that information. * */ H5_DLL hsize_t H5Dget_storage_size(hid_t dset_id); @@ -595,7 +620,7 @@ H5_DLL herr_t H5Dget_chunk_storage_size(hid_t dset_id, const hsize_t *offset, hs * effect. Also, the implementation does not handle the #H5S_ALL * macro correctly. As a workaround, application can get * the dataspace for the dataset using H5Dget_space() and pass that - * in for \p fspace_id. This will be fixed in coming releases. + * in for \p fspace_id. This will be fixed in a future release. * * \since 1.10.5 * @@ -638,7 +663,7 @@ H5_DLL herr_t H5Dget_chunk_info_by_coord(hid_t dset_id, const hsize_t *offset, u * -------------------------------------------------------------------------- * \ingroup H5D * - * \brief Iterate over all chunks + * \brief Iterate over all chunks of a chunked dataset * * \dset_id * \param[in] dxpl_id Identifier of a transfer property list @@ -649,33 +674,16 @@ H5_DLL herr_t H5Dget_chunk_info_by_coord(hid_t dset_id, const hsize_t *offset, u * * \details H5Dget_chunk_iter iterates over all chunks in the dataset, calling the * user supplied callback with the details of the chunk and the supplied - * \p op_data. - * - * Callback information: - * H5D_chunk_iter_op_t is defined as: - * - * typedef int (*H5D_chunk_iter_op_t)( - * const hsize_t *offset, - * uint32_t filter_mask, - * haddr_t addr, - * uint32_t nbytes, - * void *op_data); - * - * H5D_chunk_iter_op_t parameters: - * hsize_t *offset; IN/OUT: Array of starting logical coordinates of chunk. - * uint32_t filter_mask; IN: Filter mask of chunk. - * haddr_t addr; IN: Offset in file of chunk data. - * uint32_t nbytes; IN: Size in number of bytes of chunk data in file. - * void *op_data; IN/OUT: Pointer to any user-defined data - * associated with the operation. - * - * The return values from an operator are: - * Zero (H5_ITER_CONT) causes the iterator to continue, returning zero when all - * elements have been processed. - * Positive (H5_ITER_STOP) causes the iterator to immediately return that positive - * value, indicating short-circuit success. - * Negative (H5_ITER_ERROR) causes the iterator to immediately return that value, - * indicating failure. + * context \p op_data. + * + * \par Example + * For each chunk, print the allocated chunk size (0 for un-allocated chunks). + * \snippet H5D_examples.c H5Dchunk_iter_cb + * Iterate over all chunked datasets and chunks in a file. + * \snippet H5D_examples.c H5Ovisit_cb + * + * \version 1.?.? + * \todo When was this function introduced? * */ H5_DLL herr_t H5Dchunk_iter(hid_t dset_id, hid_t dxpl_id, H5D_chunk_iter_op_t cb, void *op_data); @@ -696,16 +704,16 @@ H5_DLL herr_t H5Dchunk_iter(hid_t dset_id, hid_t dxpl_id, H5D_chunk_iter_op_t cb * * \return \herr_t * - * \details H5Dget_chunk_info() retrieves the offset coordinates - * offset, filter mask filter_mask, size size and address addr for - * the dataset specified by the identifier dset_id and the chunk - * specified by the index index. The chunk belongs to a set of - * chunks in the selection specified by fspace_id. If the queried + * \details H5Dget_chunk_info() retrieves the offset coordinates, + * \p offset, filter mask, \p filter_mask, size, \p size, and address + * \p addr for the dataset specified by the identifier \p dset_id and the chunk + * specified by the index \p index. The chunk belongs to a set of + * chunks in the selection specified by \p fspace_id. If the queried * chunk does not exist in the file, the size will be set to 0 and - * address to \c HADDR_UNDEF. The value pointed to by filter_mask will - * not be modified. NULL can be passed in for any \p out parameters. + * address to #HADDR_UNDEF. The value pointed to by filter_mask will + * not be modified. \c NULL can be passed in for any \p out parameters. * - * \p chk_idx is the chunk index in the selection. Index value + * \p chk_idx is the chunk index in the selection. The index value * may have a value of 0 up to the number of chunks stored in * the file that have a nonempty intersection with the file * dataspace selection @@ -719,9 +727,9 @@ H5_DLL herr_t H5Dchunk_iter(hid_t dset_id, hid_t dxpl_id, H5D_chunk_iter_op_t cb * \note Please be aware that this function currently does not * support non-trivial selections, thus \p fspace_id has no * effect. Also, the implementation does not handle the #H5S_ALL - * macro correctly. As a workaround, application can get + * macro correctly. As a workaround, an application can get * the dataspace for the dataset using H5Dget_space() and pass that - * in for \p fspace_id. This will be fixed in coming releases. + * in for \p fspace_id. This will be fixed in a future release. * * \since 1.10.5 * @@ -737,7 +745,7 @@ H5_DLL herr_t H5Dget_chunk_info(hid_t dset_id, hid_t fspace_id, hsize_t chk_idx, * * \dset_id * - * \return Returns the offset in bytes; otherwise, returns \c HADDR_UNDEF, + * \return Returns the offset in bytes; otherwise, returns #HADDR_UNDEF, * a negative value. * * \details H5Dget_offset() returns the address in the file of @@ -786,9 +794,8 @@ H5_DLL haddr_t H5Dget_offset(hid_t dset_id); * used for the memory dataspace and the selection defined with \p * file_space_id is used for the selection within that dataspace. * - * If raw data storage space has not been allocated for the dataset - * and a fill value has been defined, the returned buffer \p buf - * is filled with the fill value. + * The number of elements selected in the memory dataspace \Emph{must} + * be equal to the number of elements selected in the file dataspace. * * The behavior of the library for the various combinations of * valid dataspace identifiers and #H5S_ALL for the \p mem_space_id @@ -833,14 +840,12 @@ H5_DLL haddr_t H5Dget_offset(hid_t dset_id); * </tr> * </table> * - * \details Setting an #H5S_ALL selection indicates that the entire - * dataspace, as defined by the current dimensions of a dataspace, - * will be selected. The number of elements selected in the memory - * dataspace must match the number of elements selected in the - * file dataspace. + * \note If no storage space was allocated for the dataset + * and a fill value is defined, the returned buffer \p buf + * is filled with the fill value. * - * \p dxpl_id can be the constant #H5P_DEFAULT, in which case the - * default data transfer properties are used. + * \par Example + * \snippet H5D_examples.c read * */ H5_DLL herr_t H5Dread(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, @@ -953,6 +958,8 @@ H5_DLL herr_t H5Dread_async(const char *app_file, const char *app_func, unsigned * time if the dataset's fill time is set to #H5D_FILL_TIME_IFSET * or #H5D_FILL_TIME_ALLOC. * + * \par_compr_note + * * \attention If a dataset's storage layout is 'compact', care must be * taken when writing data to the dataset in parallel. A compact * dataset's raw data is cached in memory and may be flushed @@ -960,6 +967,9 @@ H5_DLL herr_t H5Dread_async(const char *app_file, const char *app_func, unsigned * applications should always attempt to write identical data to * the dataset from all processes. * + * \par Example + * \snippet H5D_examples.c update + * * \see H5Pset_fill_time(), H5Pset_alloc_time() * */ @@ -1000,11 +1010,6 @@ H5_DLL herr_t H5Dwrite_async(const char *app_file, const char *app_func, unsigne * pipeline, including filters, and will be written directly to * the file. Only one chunk can be written with this function. * - * H5Dwrite_chunk() replaces the now deprecated H5DOwrite_chunk() - * function, which was located in the high level optimization - * library. The parameters and behavior are identical to the - * original. - * * \p filters is a mask providing a record of which filters are * used with the the chunk. The default value of the mask is * zero (0), indicating that all enabled filters are applied. A @@ -1032,11 +1037,10 @@ H5_DLL herr_t H5Dwrite_async(const char *app_file, const char *app_func, unsigne * in a file. H5Dwrite_chunk() bypasses hyperslab selection, the * conversion of data from one datatype to another, and the filter * pipeline to write the chunk. Developers should have experience - * with these processes before using this function. Please see - * Using the Direct Chunk Write Function for more information. + * with these processes before using this function. * - * \note H5Dread_chunk() and H5Dwrite_chunk() are not supported under - * parallel and do not support variable length types. + * \note H5Dread_chunk() and H5Dwrite_chunk() are currently not supported + * with parallel HDF5 and do not support variable-length types. * * \since 1.10.2 * @@ -1074,10 +1078,10 @@ H5_DLL herr_t H5Dwrite_chunk(hid_t dset_id, hid_t dxpl_id, uint32_t filters, con * the dimension limits and must specify a point that falls on * a dataset chunk boundary. * - * The mask \p filters indicates which filters are used with the - * chunk when written. A zero value indicates that all enabled - * filters are applied on the chunk. A filter is skipped if the - * bit corresponding to the filter’s position in the pipeline + * The mask \p filters indicates which filters were used when the + * chunk was written. A zero value (all bits 0) indicates that all + * enabled filters are applied on the chunk. A filter is skipped if + * the bit corresponding to the filter’s position in the pipeline * (0 ≤ position < 32) is turned on. * * \p buf is the memory buffer containing the chunk read from @@ -1091,8 +1095,8 @@ H5_DLL herr_t H5Dwrite_chunk(hid_t dset_id, hid_t dxpl_id, uint32_t filters, con * with these processes before using this function. Please see * Using the Direct Chunk Write Function for more information. * - * \note H5Dread_chunk() and H5Dwrite_chunk() are not supported under - * parallel and do not support variable length types. + * \note H5Dread_chunk() and H5Dwrite_chunk() are currently not supported + * with parallel HDF5 and do not support variable-length datatypes. * * \since 1.10.2 * @@ -1122,52 +1126,9 @@ H5_DLL herr_t H5Dread_chunk(hid_t dset_id, hid_t dxpl_id, const hsize_t *offset, * in the memory buffer \p buf, executing the callback function * \p op once for each such data element. * - * The prototype of the callback function \p op is as follows - * (as defined in the source code file H5Lpublic.h): - * \snippet this H5D_operator_t_snip - * The parameters of this callback function are: - * - * <table> - * <tr><td>\c elem</td> - * <td><tt>[in,out]</tt></td> - * <td>Pointer to the memory buffer containing the current - * data element</td></tr> - * <tr><td>\c type_id</td> - * <td><tt>[in]</tt></td> - * <td>Datatype identifier of the elements stored in elem</td></tr> - * <tr><td>\c ndim</td> - * <td><tt>[in]</tt></td> - * <td>Number of dimensions for the point array</td></tr> - * <tr><td>\c point</td> - * <td><tt>[in]</tt></td> - * <td>Array containing the location of the element within - * the original dataspace</td></tr> - * <tr><td>\c operator_data</td> - * <td><tt>[in,out]</tt></td> - * <td>Pointer to any user-defined data associated with the - * operation</td></tr> - * </table> - * - * The possible return values from the callback function, and - * the effect ofeach,are as follows: - * - * \li Zero causes the iterator to continue, returning zero - * when all data elements have been processed. - * \li A positive value causes the iterator to immediately - * return that positive value, indicating short-circuit success. - * \li A negative value causes the iterator to immediately return - * that value, indicating failure. - * - * The \p operator_data parameter is a user-defined pointer to - * the data required to process dataset elements in the course - * of the iteration. If operator needs to pass data back to the - * application, such data can be returned in this same buffer. This - * pointer is passed back to each step of the iteration in the - * operator callback function’s operator_data parameter. - * - * Unlike other HDF5 iterators, this iteration operation cannot - * be restarted at the point of exit; a second H5Diterate() - * call will always restart at the beginning. + * \attention Unlike other HDF5 iterators, this iteration operation cannot + * be restarted at the point of exit; a second H5Diterate() + * call will always restart at the beginning. * * * \since 1.10.2 @@ -1217,30 +1178,25 @@ H5_DLL herr_t H5Dvlen_get_buf_size(hid_t dset_id, hid_t type_id, hid_t space_id, * * \return \herr_t * - * \details H5Dfill() fills the dataspace selection in memory, \p space_id, + * \details H5Dfill() fills the dataspace selection, \p space_id, in memory * with the fill value specified in \p fill. If \p fill is NULL, * a fill value of 0 (zero) is used. * * \p fill_type_id specifies the datatype of the fill value. - * \p buf specifies the buffer in which the dataspace elements - * will be written. - * \p buf_type_id specifies the datatype of those data elements. + * \p buf specifies the buffer in which the fill elements + * will be written. \p buf_type_id specifies the datatype of + * those data elements. * * \note Note that if the fill value datatype differs from the memory - * buffer datatype, the fill value will be converted to the memory - * buffer datatype before filling the selection. + * buffer datatype, the fill value will be converted to the memory + * buffer datatype before filling the selection. * * \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. See the following - * function for more information: - * - H5Pset_fill_value() - * - H5Pget_fill_value() - * - H5Pfill_value_defined() - * - H5Pset_fill_time() - * - H5Pget_fill_time() - * - H5Pcreate() - * - H5Pcreate_anon() + * allocated dataset. It is often useful in such cases to fill + * the unused space with a known fill value. + * + * \see H5Pset_fill_value(), H5Pget_fill_value(), H5Pfill_value_defined(), + * H5Pset_fill_time(), H5Pget_fill_time(), H5Pcreate(), H5Dcreate_anon() * */ H5_DLL herr_t H5Dfill(const void *fill, hid_t fill_type_id, void *buf, hid_t buf_type_id, hid_t space_id); @@ -1287,22 +1243,21 @@ H5_DLL herr_t H5Dfill(const void *fill, hid_t fill_type_id, void *buf, hid_t buf * - If the dataset’s fill time is set to #H5D_FILL_TIME_ALLOC * (see H5Pset_alloc_time()) * - * \note - * \li If the sizes specified in \p size array are smaller than - * the dataset’s current dimension sizes, H5Dset_extent() will reduce - * the dataset’s dimension sizes to the specified values. It is the - * user application’s responsibility to ensure that valuable data is - * not lost as H5Dset_extent() does not check. + * \note If the sizes specified in \p size array are smaller than the dataset’s + * current dimension sizes, H5Dset_extent() will reduce the dataset’s + * dimension sizes to the specified values. It is the user application’s + * responsibility to ensure that valuable data is not lost as + * H5Dset_extent() does not check. * - * \li Except for external datasets, H5Dset_extent() is for use with - * chunked datasets only, not contiguous datasets. + * \note Except for external datasets, H5Dset_extent() is for use with + * chunked datasets only, not contiguous datasets. * - * \li A call to H5Dset_extent() affects the dataspace of a dataset. - * If a dataspace handle was opened for a dataset prior to a call to - * H5Dset_extent() then that dataspace handle will no longer reflect - * the correct dataspace extent of the dataset. H5Dget_space() must - * be called (after closing the previous handle) to obtain the current - * dataspace extent. + * \note A call to H5Dset_extent() affects the dataspace of a dataset. If a + * dataspace handle was opened for a dataset prior to a call to + * H5Dset_extent() then that dataspace handle will no longer reflect the + * correct dataspace extent of the dataset. H5Dget_space() must be called + * (after closing the previous handle) to obtain the current dataspace + * extent. * * \since 1.8.0 * @@ -1337,6 +1292,8 @@ H5_DLL herr_t H5Dset_extent_async(const char *app_file, const char *app_func, un * open files. After that, the OS is responsible for ensuring * that the data is actually flushed to disk. * + * \since 1.10.0 + * */ H5_DLL herr_t H5Dflush(hid_t dset_id); @@ -1395,40 +1352,7 @@ H5_DLL herr_t H5Drefresh(hid_t dset_id); * * To retrieve the data to be scattered, H5Dscatter() repeatedly * calls \p op, which should return a valid source buffer, until - * enough data to fill the selection has been retrieved. The - * prototype of the callback function \p op is as follows (as - * defined in the source code file H5Dpublic.h): - * \snippet this H5D_scatter_func_t_snip - * The parameters of this callback function are described below: - * - * <table> - * <tr><td>\c src_buf</td> - * <td><tt>[out]</tt></td> - * <td>Pointer to the buffer holding the next set of elements to - * scatter. On entry, the value of where \c src_buf points to - * is undefined. The callback function should set \c src_buf - * to point to the next set of elements.</td></tr> - * <tr><td>\c src_buf_bytes_used</td> - * <td><tt>[out]</tt></td> - * <td>Pointer to the number of valid bytes in \c src_buf. On - * entry, the value where \c src_buf_bytes_used points to is - * undefined. The callback function should set - * \c src_buf_bytes_used to the of valid bytes in \c src_buf. - * This number must be a multiple of the datatype size. - * </td></tr> - * <tr><td>\c op_data</td> - * <td><tt>[in,out]</tt></td> - * <td>User-defined pointer to data required by the callback - * function. A pass-through of the \c op_data pointer provided - * with the H5Dscatter() function call.</td></tr> - * </table> - * - * The callback function should always return at least one - * element in \p src_buf, and must not return more elements - * than are remaining to be scattered. This function will be - * repeatedly called until all elements to be scattered have - * been returned. The callback function should return zero (0) - * to indicate success, and a negative value to indicate failure. + * enough data to fill the selection has been retrieved. * * \since 1.10.2 * @@ -1480,27 +1404,9 @@ H5_DLL herr_t H5Dscatter(H5D_scatter_func_t op, void *op_data, hid_t type_id, hi * If no callback function is provided, H5Dgather() simply gathers * the data into \p dst_buf and returns. If a callback function is * provided, H5Dgather() repeatedly gathers up to \p dst_buf_size - * bytes to process the serialized data. The prototype of the - * callback function \p op is as follows (as defined in the source - * code file H5Dpublic.h): - * \snippet this H5D_gather_func_t_snip - * The parameters of this callback function are described in the - * table below. - * <table> - * <tr><td>\c dst_buf</td> - * <td>Pointer to the destination buffer which has been filled - * with the next set of elements gathered. This will always be - * identical to the \p dst_buf passed to H5Dgather().</td></tr> - * <tr><td>\c dst_buf_bytes_used</td> - * <td>Pointer to the number of valid bytes in \p dst_buf. - * This number must be a multiple of the datatype - * size.</td></tr> - * <tr><td>\c op_data</td> - * <td>User-defined pointer to data required by the callback - * function; a pass-through of the \p op_data pointer - * provided with the H5Dgather() function call.</td></tr> - * </table> - * The callback function should process, store, or otherwise, + * bytes to process the serialized data. + * + * The callback function \p op should process, store, or otherwise, * make use of the data returned in \p dst_buf before it returns, * because the buffer will be overwritten unless it is the last * call to the callback. This function will be repeatedly called @@ -1524,11 +1430,11 @@ H5_DLL herr_t H5Dgather(hid_t src_space_id, const void *src_buf, hid_t type_id, * * \return \herr_t * - * \details H5Dclose() ends access to a dataset specified by \p dset_id - * and releases resources used by it. + * \details H5Dclose() terminates access to a dataset via the identifier + * \p dset_id and releases the underlying resources. * - * \attention Further use of a released dataset identifier is illegal; a - * function using such an identifier will generate an error. + * \par Example + * \snippet H5D_examples.c read * * \since 1.8.0 * @@ -1544,12 +1450,14 @@ H5_DLL herr_t H5Dclose(hid_t dset_id); */ H5_DLL herr_t H5Dclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t dset_id, hid_t es_id); - +/// \cond DEV /* Internal API routines */ H5_DLL herr_t H5Ddebug(hid_t dset_id); H5_DLL herr_t H5Dformat_convert(hid_t dset_id); H5_DLL herr_t H5Dget_chunk_index_type(hid_t did, H5D_chunk_index_t *idx_type); +/// \endcond +/// \cond DEV /* API Wrappers for async routines */ /* (Must be defined _after_ the function prototype) */ /* (And must only defined when included in application code, not the library) */ @@ -1573,6 +1481,7 @@ H5_DLL herr_t H5Dget_chunk_index_type(hid_t did, H5D_chunk_index_t *idx_type); #define H5Dset_extent_async_wrap H5_NO_EXPAND(H5Dset_extent_async) #define H5Dclose_async_wrap H5_NO_EXPAND(H5Dclose_async) #endif /* H5D_MODULE */ +/// \endcond /* Symbols defined for compatibility with previous versions of the HDF5 API. * @@ -1613,8 +1522,7 @@ H5_DLL herr_t H5Dget_chunk_index_type(hid_t did, H5D_chunk_index_t *idx_type); * * \return \hid_t{dataset} * - * \deprecated This function is deprecated in favor of the function H5Dcreate2() - * or the macro H5Dcreate(). + * \deprecation_note{H5Dcreate2() or the macro H5Dcreate()} * * \details H5Dcreate1() creates a data set with a name, \p name, in the * location specified by the identifier \p loc_id. \p loc_id may be a @@ -1680,8 +1588,7 @@ H5_DLL hid_t H5Dcreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t spa * * \return \hid_t{dataset} * - * \deprecated This function is deprecated in favor of the function H5Dopen2() - * or the macro H5Dopen(). + * \deprecation_note{H5Dopen2() or the macro H5Dopen()} * * \details H5Dopen1() opens an existing dataset for access at the location * specified by \p loc_id. \p loc_id may be a file, group, dataset, @@ -1711,10 +1618,10 @@ H5_DLL hid_t H5Dopen1(hid_t loc_id, const char *name); * * \return \herr_t * - * \deprecated This function is deprecated in favor of the function H5Dset_extent(). + * \deprecation_note{H5Dset_extent()} * * \details H5Dextend() verifies that the dataset is at least of size \p size, - * extending it if necessary. The dimensionality of size is the same as + * extending it if necessary. The length of \p size is the same as * that of the dataspace of the dataset being changed. * * This function can be applied to the following datasets: @@ -1734,7 +1641,7 @@ H5_DLL hid_t H5Dopen1(hid_t loc_id, const char *name); * the sizes specified in size. The function H5Dset_extent() must be * used if the dataset dimension sizes are are to be reduced. * - * \version 1.8.0 Function Function deprecated in this release. Parameter size + * \version 1.8.0 Function deprecated in this release. Parameter size * syntax changed to \Code{const hsize_t size[]} in this release. * */ @@ -1752,8 +1659,7 @@ H5_DLL herr_t H5Dextend(hid_t dset_id, const hsize_t size[]); * * \return \herr_t * - * \deprecated This function has been deprecated in HDF5-1.12 in favor of the - * function H5Treclaim(). + * \deprecation_note{H5Treclaim()} * * \details H5Dvlen_reclaim() reclaims memory buffers created to store VL * datatypes. @@ -1771,7 +1677,7 @@ H5_DLL herr_t H5Dextend(hid_t dset_id, const hsize_t size[]); * frees them from the bottom up, releasing all the memory without * creating memory leaks. * - * \version 1.12.0 Routine was deprecated + * \version 1.12.0 Function was deprecated * */ H5_DLL herr_t H5Dvlen_reclaim(hid_t type_id, hid_t space_id, hid_t dxpl_id, void *buf); diff --git a/src/H5ESmodule.h b/src/H5ESmodule.h index cbc812e..5169b52 100644 --- a/src/H5ESmodule.h +++ b/src/H5ESmodule.h @@ -29,8 +29,10 @@ #define H5_MY_PKG_ERR H5E_EVENTSET #define H5_MY_PKG_INIT YES -/** - * \defgroup H5ES H5ES +/**\defgroup H5ES H5ES + * + * \todo Add the event set life cycle. + * * \brief Event Set Interface * * \details \Bold{This interface can be only used with the HDF5 VOL connectors that diff --git a/src/H5Emodule.h b/src/H5Emodule.h index 43d5d36..58a3517 100644 --- a/src/H5Emodule.h +++ b/src/H5Emodule.h @@ -29,33 +29,54 @@ #define H5_MY_PKG_ERR H5E_ERROR #define H5_MY_PKG_INIT YES -/** - * \defgroup H5E H5E - * \brief Error Handling Interface - * - * \details The Error interface provides error handling in the form of a stack. - * The \Code{FUNC_ENTER} macro clears the error stack whenever an - * interface function is entered. When an error is detected, an entry - * is pushed onto the stack. As the functions unwind, additional - * entries are pushed onto the stack. The API function will return some - * indication that an error occurred and the application can print the - * error stack. - * - * Certain API functions in the \c H5E package, such as H5Eprint1(), do - * not clear the error stack. Otherwise, any function which does not - * have an underscore immediately after the package name will clear the - * error stack. For instance, H5Fopen() clears the error stack while - * \Code{H5F_open} does not. - * - * An error stack has a fixed maximum size. If this size is exceeded - * then the stack will be truncated and only the inner-most functions - * will have entries on the stack. This is expected to be a rare - * condition. - * - * Each thread has its own error stack, but since multi-threading has - * not been added to the library yet, this package maintains a single - * error stack. The error stack is statically allocated to reduce the - * complexity of handling errors within the \c H5E package. +/**\defgroup H5E H5E + * + * Use the functions in this module to manage HDF5 error stacks and error + * messages. + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5E_examples.c create + * </td> + * <td> + * \snippet{lineno} H5E_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5E_examples.c update + * </td> + * <td> + * \snippet{lineno} H5E_examples.c delete + * </td> + * </tr> + * </table> + * + * \internal The \c FUNC_ENTER macro clears the error stack whenever an + * interface function is entered. When an error is detected, an entry + * is pushed onto the stack. As the functions unwind, additional + * entries are pushed onto the stack. The API function will return + * some indication that an error occurred and the application can + * print the error stack. + * + * \internal Certain API functions in the \ref H5E package, such as H5Eprint(), + * do not clear the error stack. Otherwise, any function which does + * not have an underscore immediately after the package name will + * clear the error stack. For instance, H5Fopen() clears the error + * stack while \Code{H5F_open} does not. + * + * \internal An error stack has a fixed maximum size. If this size is exceeded + * then the stack will be truncated and only the inner-most functions + * will have entries on the stack. This is expected to be a rare + * condition. + * + * \internal Each thread has its own error stack, but since multi-threading has + * not been added to the library yet, this package maintains a single + * error stack. The error stack is statically allocated to reduce the + * complexity of handling errors within the \ref H5E package. + * */ #endif /* H5Emodule_H */ diff --git a/src/H5Epublic.h b/src/H5Epublic.h index 0294023..9dfd1fc 100644 --- a/src/H5Epublic.h +++ b/src/H5Epublic.h @@ -716,12 +716,13 @@ typedef herr_t (*H5E_auto1_t)(void *client_data); * * \return \herr_t * + * \deprecated 1.8.0 Function H5Eclear() renamed to H5Eclear1() and deprecated + * in this release. + * * \details H5Eclear1() clears the error stack for the current thread.\n * The stack is also cleared whenever an API function is called, with * certain exceptions (for instance, H5Eprint1()). * - * \deprecated 1.8.0 Function H5Eclear() renamed to H5Eclear1() and deprecated - * in this release. */ H5_DLL herr_t H5Eclear1(void); /** @@ -737,6 +738,9 @@ H5_DLL herr_t H5Eclear1(void); * function * \return \herr_t * + * \deprecated 1.8.0 Function H5Eget_auto() renamed to H5Eget_auto1() and + * deprecated in this release. + * * \details H5Eget_auto1() returns the current settings for the automatic error * stack traversal function, \p func, and its data, * \p client_data. Either or both arguments may be \c NULL, in which case the @@ -763,8 +767,6 @@ H5_DLL herr_t H5Eclear1(void); * H5Eprint2(), mixing H5Eset_auto1() and H5Eget_auto2() or mixing * H5Eset_auto2() and H5Eget_auto1() does not fail. * - * \deprecated 1.8.0 Function H5Eget_auto() renamed to H5Eget_auto1() and - * deprecated in this release. */ H5_DLL herr_t H5Eget_auto1(H5E_auto1_t *func, void **client_data); /** @@ -781,6 +783,9 @@ H5_DLL herr_t H5Eget_auto1(H5E_auto1_t *func, void **client_data); * \param[in] str Error description string * \return \herr_t * + * \deprecated 1.8.0 Function H5Epush() renamed to H5Epush1() and + * deprecated in this release. + * * \details H5Epush1() pushes a new error record onto the error stack for the * current thread.\n * The error has major and minor numbers \p maj_num @@ -791,8 +796,6 @@ H5_DLL herr_t H5Eget_auto1(H5E_auto1_t *func, void **client_data); * allocated. * * \since 1.4.0 - * \deprecated 1.8.0 Function H5Epush() renamed to H5Epush1() and - * deprecated in this release. */ H5_DLL herr_t H5Epush1(const char *file, const char *func, unsigned line, H5E_major_t maj, H5E_minor_t min, const char *str); @@ -805,6 +808,9 @@ H5_DLL herr_t H5Epush1(const char *file, const char *func, unsigned line, H5E_ma * \param[in] stream File pointer, or \c NULL for \c stderr * \return \herr_t * + * \deprecated 1.8.0 Function H5Eprint() renamed to H5Eprint1() and + * deprecated in this release. + * * \details H5Eprint1() prints prints the error stack for the current thread * on the specified stream, \p stream. Even if the error stack is empty, a * one-line message of the following form will be printed: @@ -815,8 +821,6 @@ H5_DLL herr_t H5Epush1(const char *file, const char *func, unsigned line, H5E_ma * that prints error messages. Users are encouraged to write their own * more specific error handlers. * - * \deprecated 1.8.0 Function H5Eprint() renamed to H5Eprint1() and - * deprecated in this release. */ H5_DLL herr_t H5Eprint1(FILE *stream); /** @@ -829,6 +833,9 @@ H5_DLL herr_t H5Eprint1(FILE *stream); * \param[in] client_data Data passed to the error function * \return \herr_t * + * \deprecated 1.8.0 Function H5Eset_auto() renamed to H5Eset_auto1() and + * deprecated in this release. + * * \details H5Eset_auto1() turns on or off automatic printing of errors. When * turned on (non-null \p func pointer), any API function which returns * an error indication will first call \p func, passing it \p @@ -845,8 +852,6 @@ H5_DLL herr_t H5Eprint1(FILE *stream); * Automatic stack traversal is always in the #H5E_WALK_DOWNWARD * direction. * - * \deprecated 1.8.0 Function H5Eset_auto() renamed to H5Eset_auto1() and - * deprecated in this release. */ H5_DLL herr_t H5Eset_auto1(H5E_auto1_t func, void *client_data); /** @@ -860,6 +865,9 @@ H5_DLL herr_t H5Eset_auto1(H5E_auto1_t func, void *client_data); * \param[in] client_data Data to be passed to \p func * \return \herr_t * + * \deprecated 1.8.0 Function H5Ewalk() renamed to H5Ewalk1() and + * deprecated in this release. + * * \details H5Ewalk1() walks the error stack for the current thread and calls * the function specified in \p func for each error along the way. * @@ -877,8 +885,6 @@ H5_DLL herr_t H5Eset_auto1(H5E_auto1_t func, void *client_data); * is as follows: * \snippet this H5E_walk1_t_snip * - * \deprecated 1.8.0 Function H5Ewalk() renamed to H5Ewalk1() and - * deprecated in this release. */ H5_DLL herr_t H5Ewalk1(H5E_direction_t direction, H5E_walk1_t func, void *client_data); /** @@ -891,6 +897,8 @@ H5_DLL herr_t H5Ewalk1(H5E_direction_t direction, H5E_walk1_t func, void *client * \param[in] maj Major error number * \return \herr_t * + * \deprecated 1.8.0 Function deprecated in this release. + * * \details Given a major error number, H5Eget_major() returns a constant * character string that describes the error. * @@ -898,7 +906,6 @@ H5_DLL herr_t H5Ewalk1(H5E_direction_t direction, H5E_walk1_t func, void *client * array). An application calling this function must free the memory * associated with the return value to prevent a memory leak. * - * \deprecated 1.8.0 Function deprecated in this release. */ H5_DLL char *H5Eget_major(H5E_major_t maj); /** @@ -911,6 +918,8 @@ H5_DLL char *H5Eget_major(H5E_major_t maj); * \param[in] min Minor error number * \return \herr_t * + * \deprecated 1.8.0 Function deprecated and return type changed in this release. + * * \details Given a minor error number, H5Eget_minor() returns a constant * character string that describes the error. * @@ -920,7 +929,6 @@ H5_DLL char *H5Eget_major(H5E_major_t maj); * the memory associated with the return value to prevent a memory * leak. This is a change from the 1.6.x release series. * - * \deprecated 1.8.0 Function deprecated and return type changed in this release. */ H5_DLL char *H5Eget_minor(H5E_minor_t min); #endif /* H5_NO_DEPRECATED_SYMBOLS */ diff --git a/src/H5Fmodule.h b/src/H5Fmodule.h index 7f0299a..81c1ede 100644 --- a/src/H5Fmodule.h +++ b/src/H5Fmodule.h @@ -29,8 +29,7 @@ #define H5_MY_PKG_ERR H5E_FILE #define H5_MY_PKG_INIT YES -/** - * \defgroup H5F H5F +/**\defgroup H5F H5F * * Use the functions in this module to manage HDF5 files. * @@ -41,15 +40,23 @@ * creation or access \c mode control the interaction with the underlying * storage such as file systems. * - * \Emph{Proper error handling is part of the life cycle.} * <table> - * <tr><th>Create</th><th>Open</th></tr> + * <tr><th>Create</th><th>Read</th></tr> * <tr valign="top"> * <td> - * \snippet H5F_examples.c life_cycle + * \snippet{lineno} H5F_examples.c create * </td> * <td> - * \snippet H5F_examples.c life_cycle_w_open + * \snippet{lineno} H5F_examples.c read + * </td> + * </tr> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5F_examples.c update + * </td> + * <td> + * \snippet{lineno} H5F_examples.c delete * </td> * </tr> * </table> diff --git a/src/H5Fpublic.h b/src/H5Fpublic.h index 98d2a9f..c3230e1 100644 --- a/src/H5Fpublic.h +++ b/src/H5Fpublic.h @@ -1777,6 +1777,7 @@ H5_DLL herr_t H5Fset_mpi_atomicity(hid_t file_id, hbool_t flag); H5_DLL herr_t H5Fget_mpi_atomicity(hid_t file_id, hbool_t *flag); #endif /* H5_HAVE_PARALLEL */ +/// \cond DEV /* API Wrappers for async routines */ /* (Must be defined _after_ the function prototype) */ /* (And must only defined when included in application code, not the library) */ @@ -1796,6 +1797,7 @@ H5_DLL herr_t H5Fget_mpi_atomicity(hid_t file_id, hbool_t *flag); #define H5Fflush_async_wrap H5_NO_EXPAND(H5Fflush_async) #define H5Fclose_async_wrap H5_NO_EXPAND(H5Fclose_async) #endif /* H5F_MODULE */ +/// \endcond /* Symbols defined for compatibility with previous versions of the HDF5 API. * diff --git a/src/H5Gmodule.h b/src/H5Gmodule.h index fe26bd2..a0e121d 100644 --- a/src/H5Gmodule.h +++ b/src/H5Gmodule.h @@ -29,8 +29,29 @@ #define H5_MY_PKG_ERR H5E_SYM #define H5_MY_PKG_INIT YES -/** - * \defgroup H5G H5G +/** \defgroup H5G H5G + * + * Use the functions in this module to manage HDF5 groups. + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5G_examples.c create + * </td> + * <td> + * \snippet{lineno} H5G_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5G_examples.c update + * </td> + * <td> + * \snippet{lineno} H5G_examples.c delete + * </td> + * </tr> + * </table> * * \details \Bold{Groups in HDF5:} A group associates names with objects and * provides a mechanism for mapping a name to an object. Since all diff --git a/src/H5Gpublic.h b/src/H5Gpublic.h index b009d41..d9c29f6 100644 --- a/src/H5Gpublic.h +++ b/src/H5Gpublic.h @@ -467,6 +467,7 @@ H5_DLL herr_t H5Gclose(hid_t group_id); H5_DLL herr_t H5Gclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t group_id, hid_t es_id); +/// \cond DEV /* API Wrappers for async routines */ /* (Must be defined _after_ the function prototype) */ /* (And must only defined when included in application code, not the library) */ @@ -488,6 +489,7 @@ H5_DLL herr_t H5Gclose_async(const char *app_file, const char *app_func, unsigne #define H5Gget_info_by_idx_async_wrap H5_NO_EXPAND(H5Gget_info_by_idx_async) #define H5Gclose_async_wrap H5_NO_EXPAND(H5Gclose_async) #endif /* H5G_MODULE */ +/// \endcond /* Symbols defined for compatibility with previous versions of the HDF5 API. * diff --git a/src/H5Imodule.h b/src/H5Imodule.h index 8db31c8..08f8bb0 100644 --- a/src/H5Imodule.h +++ b/src/H5Imodule.h @@ -30,8 +30,85 @@ #define H5_MY_PKG_INIT NO /**\defgroup H5I H5I - * \brief Identifier Interface - * \todo Describe concisely what the functions in this module are about. + * + * Use the functions in this module to manage identifiers defined by the HDF5 + * library. See \ref H5IUD for user-defined identifiers and identifier + * types. + * + * HDF5 identifiers are usually created as a side-effect of creating HDF5 + * entities such as groups, datasets, attributes, or property lists. + * + * Identifiers defined by the HDF5 library can be used to retrieve information + * such as path names and reference counts, and their validity can be checked. + * + * Identifiers can be updated by manipulating their reference counts. + * + * Unused identifiers should be reclaimed by closing the associated item, e.g., + * HDF5 object, or decrementing the reference count to 0. + * + * \note Identifiers (of type \ref hid_t) are run-time auxiliaries and + * not persisted in the file. + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5I_examples.c create + * </td> + * <td> + * \snippet{lineno} H5I_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5I_examples.c update + * </td> + * <td> + * \snippet{lineno} H5I_examples.c delete + * </td> + * </tr> + * </table> + * + * \defgroup H5IUD User-defined ID Types + * \ingroup H5I + * + * The \ref H5I module contains functions to define new identifier types. + * For convenience, handles of type \ref hid_t can then be associated with the + * new identifier types and user objects. + * + * New identifier types can be created by registering a new identifier type + * with the HDF5 library. Once a new identifier type has bee registered, + * it can be used to generate identifiers for user objects. + * + * User-defined identifier types can be searched and iterated. + * + * Like library-defined identifiers, user-defined identifiers \Emph{and} + * identifier types are reference counted, and the reference counts can be + * manipulated accordingly. + * + * User-defined identifiers no longer in use should be deleted or reclaimed, + * and identifier types should be destroyed if they are no longer required. + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5I_examples.c create_ud + * </td> + * <td> + * \snippet{lineno} H5I_examples.c read_ud + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5I_examples.c update_ud + * </td> + * <td> + * \snippet{lineno} H5I_examples.c delete_ud + * </td> + * </tr> + * </table> + * */ #endif /* H5Imodule_H */ diff --git a/src/H5Ipublic.h b/src/H5Ipublic.h index a5f830b..8d4dbf8 100644 --- a/src/H5Ipublic.h +++ b/src/H5Ipublic.h @@ -106,7 +106,7 @@ extern "C" { /* Public API functions */ /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Registers an object under a type and returns an ID for it * @@ -128,7 +128,7 @@ extern "C" { */ H5_DLL hid_t H5Iregister(H5I_type_t type, const void *object); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Returns the object referenced by an ID * @@ -151,7 +151,7 @@ H5_DLL hid_t H5Iregister(H5I_type_t type, const void *object); */ H5_DLL void *H5Iobject_verify(hid_t id, H5I_type_t type); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Removes an ID from its type * @@ -190,12 +190,7 @@ H5_DLL void *H5Iremove_verify(hid_t id, H5I_type_t type); * \return Returns the object type if successful; otherwise #H5I_BADID. * * \details H5Iget_type() retrieves the type of the object identified by - * \p id. - * - * Valid types returned by the function are: - * \id_types - * - * If no valid type can be determined or the identifier submitted is + * \p id. If no valid type can be determined or the identifier submitted is * invalid, the function returns #H5I_BADID. * * This function is of particular use in determining the type of @@ -391,7 +386,7 @@ H5_DLL int H5Idec_ref(hid_t id); */ H5_DLL int H5Iget_ref(hid_t id); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Creates and returns a new ID type * @@ -423,7 +418,7 @@ H5_DLL int H5Iget_ref(hid_t id); */ H5_DLL H5I_type_t H5Iregister_type(size_t hash_size, unsigned reserved, H5I_free_t free_func); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Deletes all identifiers of the given type * @@ -447,7 +442,7 @@ H5_DLL H5I_type_t H5Iregister_type(size_t hash_size, unsigned reserved, H5I_free */ H5_DLL herr_t H5Iclear_type(H5I_type_t type, hbool_t force); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Removes an identifier type and all identifiers within that type * @@ -470,7 +465,7 @@ H5_DLL herr_t H5Iclear_type(H5I_type_t type, hbool_t force); */ H5_DLL herr_t H5Idestroy_type(H5I_type_t type); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Increments the reference count on an ID type * @@ -489,7 +484,7 @@ H5_DLL herr_t H5Idestroy_type(H5I_type_t type); */ H5_DLL int H5Iinc_type_ref(H5I_type_t type); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Decrements the reference count on an identifier type * @@ -509,7 +504,7 @@ H5_DLL int H5Iinc_type_ref(H5I_type_t type); */ H5_DLL int H5Idec_type_ref(H5I_type_t type); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Retrieves the reference count on an ID type * @@ -528,7 +523,7 @@ H5_DLL int H5Idec_type_ref(H5I_type_t type); */ H5_DLL int H5Iget_type_ref(H5I_type_t type); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Finds the memory referred to by an ID within the given ID type such * that some criterion is satisfied @@ -569,7 +564,7 @@ H5_DLL int H5Iget_type_ref(H5I_type_t type); */ H5_DLL void *H5Isearch(H5I_type_t type, H5I_search_func_t func, void *key); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Calls a callback for each member of the identifier type specified * @@ -598,7 +593,7 @@ H5_DLL void *H5Isearch(H5I_type_t type, H5I_search_func_t func, void *key); */ H5_DLL herr_t H5Iiterate(H5I_type_t type, H5I_iterate_func_t op, void *op_data); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Returns the number of identifiers in a given identifier type * @@ -618,7 +613,7 @@ H5_DLL herr_t H5Iiterate(H5I_type_t type, H5I_iterate_func_t op, void *op_data); */ H5_DLL herr_t H5Inmembers(H5I_type_t type, hsize_t *num_members); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Determines whether an identifier type is registered * diff --git a/src/H5Lmodule.h b/src/H5Lmodule.h index 16f1f34..cffd25c 100644 --- a/src/H5Lmodule.h +++ b/src/H5Lmodule.h @@ -30,8 +30,29 @@ #define H5_MY_PKG_INIT YES /**\defgroup H5L H5L - * \brief Link Interface - * \todo Describe concisely what the functions in this module are about. + * + * Use the functions in this module to manage HDF5 links and link types. + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5L_examples.c create + * </td> + * <td> + * \snippet{lineno} H5L_examples.c iter_cb + * \snippet{lineno} H5L_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5L_examples.c update + * </td> + * <td> + * \snippet{lineno} H5L_examples.c delete + * </td> + * </tr> + * </table> * * \defgroup TRAV Link Traversal * \ingroup H5L diff --git a/src/H5Lpublic.h b/src/H5Lpublic.h index f665526..72b0182 100644 --- a/src/H5Lpublic.h +++ b/src/H5Lpublic.h @@ -1380,6 +1380,7 @@ H5_DLL herr_t H5Lunpack_elink_val(const void *ext_linkval /*in*/, size_t link_si H5_DLL herr_t H5Lcreate_external(const char *file_name, const char *obj_name, hid_t link_loc_id, const char *link_name, hid_t lcpl_id, hid_t lapl_id); +/// \cond DEV /* API Wrappers for async routines */ /* (Must be defined _after_ the function prototype) */ /* (And must only defined when included in application code, not the library) */ @@ -1401,6 +1402,7 @@ H5_DLL herr_t H5Lcreate_external(const char *file_name, const char *obj_name, hi #define H5Lexists_async_wrap H5_NO_EXPAND(H5Lexists_async) #define H5Literate_async_wrap H5_NO_EXPAND(H5Literate_async) #endif /* H5L_MODULE */ +/// \endcond /* Symbols defined for compatibility with previous versions of the HDF5 API. * diff --git a/src/H5Mmodule.h b/src/H5Mmodule.h index 3dae3e2..848f63f 100644 --- a/src/H5Mmodule.h +++ b/src/H5Mmodule.h @@ -26,9 +26,9 @@ #define H5_MY_PKG_ERR H5E_MAP #define H5_MY_PKG_INIT YES -/** - * \defgroup H5M H5M - * \brief Map Interface +/**\defgroup H5M H5M + * + * \todo Describe the map life cycle. * * \details \Bold{The interface can only be used with the HDF5 VOL connectors that * implement map objects.} The native HDF5 library does not support this diff --git a/src/H5Mpublic.h b/src/H5Mpublic.h index b3a0903..3f94edb 100644 --- a/src/H5Mpublic.h +++ b/src/H5Mpublic.h @@ -588,6 +588,7 @@ H5_DLL herr_t H5Miterate_by_name(hid_t loc_id, const char *map_name, hsize_t *id */ H5_DLL herr_t H5Mdelete(hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t dxpl_id); +/// \cond DEV /* API Wrappers for async routines */ /* (Must be defined _after_ the function prototype) */ /* (And must only defined when included in application code, not the library) */ @@ -606,6 +607,7 @@ H5_DLL herr_t H5Mdelete(hid_t map_id, hid_t key_mem_type_id, const void *key, hi #define H5Mput_async_wrap H5_NO_EXPAND(H5Mput_async) #define H5Mget_async_wrap H5_NO_EXPAND(H5Mget_async) #endif /* H5M_MODULE */ +/// \endcond /* Symbols defined for compatibility with previous versions of the HDF5 API. * diff --git a/src/H5Omodule.h b/src/H5Omodule.h index 134aa92..8afba29 100644 --- a/src/H5Omodule.h +++ b/src/H5Omodule.h @@ -30,9 +30,46 @@ #define H5_MY_PKG_INIT YES /**\defgroup H5O H5O - * \brief Object Interface * - * \todo Describe concisely what the functions in this module are about. + * Use the functions in this module to manage HDF5 objects. + * + * HDF5 objects (groups, datasets, datatype objects) are usually created + * using functions in the object-specific modules (\ref H5G, \ref H5D, + * \ref H5T). However, new objects can also be created by copying existing + * objects. + * + * Many functions in this module are variations on object introspection, + * that is, the retrieval of detailed information about HDF5 objects in a file. + * Objects in an HDF5 file can be "visited" in an iterative fashion. + * + * HDF5 objects are usually updated using functions in the object-specific + * modules. However, there are certain generic object properties, such as + * reference counts, that can be manipulated using functions in this module. + * + * HDF5 objects are deleted as a side effect of rendering them unreachable + * from the root group. The net effect is the diminution of the object's + * reference count to zero, which can (but should not usually) be effected + * by a function in this module. + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5O_examples.c create + * </td> + * <td> + * \snippet{lineno} H5O_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5O_examples.c update + * </td> + * <td> + * \snippet{lineno} H5O_examples.c delete + * </td> + * </tr> + * </table> * */ #endif /* H5Omodule_H */ diff --git a/src/H5Opublic.h b/src/H5Opublic.h index 7bc7784..0fcedb2 100644 --- a/src/H5Opublic.h +++ b/src/H5Opublic.h @@ -35,14 +35,14 @@ /*****************/ /* Flags for object copy (H5Ocopy) */ -#define H5O_COPY_SHALLOW_HIERARCHY_FLAG (0x0001u) /* Copy only immediate members */ -#define H5O_COPY_EXPAND_SOFT_LINK_FLAG (0x0002u) /* Expand soft links into new objects */ -#define H5O_COPY_EXPAND_EXT_LINK_FLAG (0x0004u) /* Expand external links into new objects */ -#define H5O_COPY_EXPAND_REFERENCE_FLAG (0x0008u) /* Copy objects that are pointed by references */ -#define H5O_COPY_WITHOUT_ATTR_FLAG (0x0010u) /* Copy object without copying attributes */ -#define H5O_COPY_PRESERVE_NULL_FLAG (0x0020u) /* Copy NULL messages (empty space) */ -#define H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG (0x0040u) /* Merge committed datatypes in dest file */ -#define H5O_COPY_ALL (0x007Fu) /* All object copying flags (for internal checking) */ +#define H5O_COPY_SHALLOW_HIERARCHY_FLAG (0x0001u) /**< Copy only immediate members */ +#define H5O_COPY_EXPAND_SOFT_LINK_FLAG (0x0002u) /**< Expand soft links into new objects */ +#define H5O_COPY_EXPAND_EXT_LINK_FLAG (0x0004u) /**< Expand external links into new objects */ +#define H5O_COPY_EXPAND_REFERENCE_FLAG (0x0008u) /**< Copy objects that are pointed by references */ +#define H5O_COPY_WITHOUT_ATTR_FLAG (0x0010u) /**< Copy object without copying attributes */ +#define H5O_COPY_PRESERVE_NULL_FLAG (0x0020u) /**< Copy NULL messages (empty space) */ +#define H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG (0x0040u) /**< Merge committed datatypes in dest file */ +#define H5O_COPY_ALL (0x007Fu) /**< All object copying flags (for internal checking) */ /* Flags for shared message indexes. * Pass these flags in using the mesg_type_flags parameter in @@ -51,22 +51,26 @@ * but we need to assign each kind of message to a different bit so that * one index can hold multiple types.) */ -#define H5O_SHMESG_NONE_FLAG 0x0000 /* No shared messages */ -#define H5O_SHMESG_SDSPACE_FLAG ((unsigned)1 << 0x0001) /* Simple Dataspace Message. */ -#define H5O_SHMESG_DTYPE_FLAG ((unsigned)1 << 0x0003) /* Datatype Message. */ -#define H5O_SHMESG_FILL_FLAG ((unsigned)1 << 0x0005) /* Fill Value Message. */ -#define H5O_SHMESG_PLINE_FLAG ((unsigned)1 << 0x000b) /* Filter pipeline message. */ -#define H5O_SHMESG_ATTR_FLAG ((unsigned)1 << 0x000c) /* Attribute Message. */ +#define H5O_SHMESG_NONE_FLAG 0x0000 /**< No shared messages */ +#define H5O_SHMESG_SDSPACE_FLAG ((unsigned)1 << 0x0001) /**< Simple Dataspace Message. */ +#define H5O_SHMESG_DTYPE_FLAG ((unsigned)1 << 0x0003) /**< Datatype Message. */ +#define H5O_SHMESG_FILL_FLAG ((unsigned)1 << 0x0005) /**< Fill Value Message. */ +#define H5O_SHMESG_PLINE_FLAG ((unsigned)1 << 0x000b) /**< Filter pipeline message. */ +#define H5O_SHMESG_ATTR_FLAG ((unsigned)1 << 0x000c) /**< Attribute Message. */ #define H5O_SHMESG_ALL_FLAG \ (H5O_SHMESG_SDSPACE_FLAG | H5O_SHMESG_DTYPE_FLAG | H5O_SHMESG_FILL_FLAG | H5O_SHMESG_PLINE_FLAG | \ H5O_SHMESG_ATTR_FLAG) /* Object header status flag definitions */ -#define H5O_HDR_CHUNK0_SIZE 0x03 /* 2-bit field indicating # of bytes to store the size of chunk 0's data */ -#define H5O_HDR_ATTR_CRT_ORDER_TRACKED 0x04 /* Attribute creation order is tracked */ -#define H5O_HDR_ATTR_CRT_ORDER_INDEXED 0x08 /* Attribute creation order has index */ -#define H5O_HDR_ATTR_STORE_PHASE_CHANGE 0x10 /* Non-default attribute storage phase change values stored */ -#define H5O_HDR_STORE_TIMES 0x20 /* Store access, modification, change & birth times for object */ +#define H5O_HDR_CHUNK0_SIZE \ + 0x03 /**< 2-bit field indicating # of bytes to store the size of chunk 0's data \ + */ +#define H5O_HDR_ATTR_CRT_ORDER_TRACKED 0x04 /**< Attribute creation order is tracked */ +#define H5O_HDR_ATTR_CRT_ORDER_INDEXED 0x08 /**< Attribute creation order has index */ +#define H5O_HDR_ATTR_STORE_PHASE_CHANGE \ + 0x10 /**< Non-default attribute storage phase change values stored \ + */ +#define H5O_HDR_STORE_TIMES 0x20 /**< Store access, modification, change & birth times for object */ #define H5O_HDR_ALL_FLAGS \ (H5O_HDR_CHUNK0_SIZE | H5O_HDR_ATTR_CRT_ORDER_TRACKED | H5O_HDR_ATTR_CRT_ORDER_INDEXED | \ H5O_HDR_ATTR_STORE_PHASE_CHANGE | H5O_HDR_STORE_TIMES) @@ -81,9 +85,9 @@ * Theses flags determine which fields will be filled in in the H5O_info_t * struct. */ -#define H5O_INFO_BASIC 0x0001u /* Fill in the fileno, addr, type, and rc fields */ -#define H5O_INFO_TIME 0x0002u /* Fill in the atime, mtime, ctime, and btime fields */ -#define H5O_INFO_NUM_ATTRS 0x0004u /* Fill in the num_attrs field */ +#define H5O_INFO_BASIC 0x0001u /**< Fill in the fileno, addr, type, and rc fields */ +#define H5O_INFO_TIME 0x0002u /**< Fill in the atime, mtime, ctime, and btime fields */ +#define H5O_INFO_NUM_ATTRS 0x0004u /**< Fill in the num_attrs field */ #define H5O_INFO_ALL (H5O_INFO_BASIC | H5O_INFO_TIME | H5O_INFO_NUM_ATTRS) //! <!-- [H5O_native_info_fields_snip] --> @@ -91,8 +95,8 @@ * Flags for H5Oget_native_info(). Theses flags determine which fields will be * filled in in the \ref H5O_native_info_t struct. */ -#define H5O_NATIVE_INFO_HDR 0x0008u /* Fill in the hdr field */ -#define H5O_NATIVE_INFO_META_SIZE 0x0010u /* Fill in the meta_size field */ +#define H5O_NATIVE_INFO_HDR 0x0008u /**< Fill in the hdr field */ +#define H5O_NATIVE_INFO_META_SIZE 0x0010u /**< Fill in the meta_size field */ #define H5O_NATIVE_INFO_ALL (H5O_NATIVE_INFO_HDR | H5O_NATIVE_INFO_META_SIZE) //! <!-- [H5O_native_info_fields_snip] --> @@ -146,15 +150,15 @@ typedef struct H5O_hdr_info_t { * (For H5Oget_info(), H5Oget_info_by_name(), H5Oget_info_by_idx() version 3) */ typedef struct H5O_info2_t { - unsigned long fileno; /* File number that object is located in */ - H5O_token_t token; /* Token representing the object */ - H5O_type_t type; /* Basic object type (group, dataset, etc.) */ - unsigned rc; /* Reference count of object */ - time_t atime; /* Access time */ - time_t mtime; /* Modification time */ - time_t ctime; /* Change time */ - time_t btime; /* Birth time */ - hsize_t num_attrs; /* # of attributes attached to object */ + unsigned long fileno; /**< File number that object is located in */ + H5O_token_t token; /**< Token representing the object */ + H5O_type_t type; /**< Basic object type (group, dataset, etc.) */ + unsigned rc; /**< Reference count of object */ + time_t atime; /**< Access time */ + time_t mtime; /**< Modification time */ + time_t ctime; /**< Change time */ + time_t btime; /**< Birth time */ + hsize_t num_attrs; /**< Number of attributes attached to object */ } H5O_info2_t; //! <!-- [H5O_info2_t_snip] --> @@ -165,11 +169,10 @@ typedef struct H5O_info2_t { */ typedef struct H5O_native_info_t { H5O_hdr_info_t hdr; /**< Object header information */ - /* Extra metadata storage for obj & attributes */ struct { H5_ih_info_t obj; /**< v1/v2 B-tree & local/fractal heap for groups, B-tree for chunked datasets */ H5_ih_info_t attr; /**< v2 B-tree & heap for attributes */ - } meta_size; + } meta_size; /**< Extra metadata storage for obj & attributes */ } H5O_native_info_t; //! <!-- [H5O_native_info_t_snip] --> @@ -181,6 +184,17 @@ typedef uint32_t H5O_msg_crt_idx_t; //! <!-- [H5O_iterate2_t_snip] --> /** * Prototype for H5Ovisit(), H5Ovisit_by_name() operator (version 3) + * + * \param[in] obj Object that serves as the root of the iteration; + * the same value as the H5Ovisit3() \c obj_id parameter + * \param[in] name Name of object, relative to \p obj, being examined at current + * step of the iteration + * \param[out] info Information about that object + * \param[in,out] op_data User-defined pointer to data required by the application + * in processing the object; a pass-through of the \c op_data + * pointer provided with the H5Ovisit3() function call + * \return \herr_t_iter + * */ typedef herr_t (*H5O_iterate2_t)(hid_t obj, const char *name, const H5O_info2_t *info, void *op_data); //! <!-- [H5O_iterate2_t_snip] --> @@ -460,28 +474,7 @@ H5_DLL htri_t H5Oexists_by_name(hid_t loc_id, const char *name, hid_t lapl_id); * \return \herr_t * * \details H5Oget_info3() specifies an object by its identifier, \p loc_id , and - * retrieves the metadata describing that object in \p oinfo , an H5O_info2_t \c struct. - * - * The H5O_info2_t \c struct is defined in H5Opublic.h as follows : - * \snippet this H5O_info2_t_snip - * - * Note the following about H5O_info2_t : - * - Of the four time fields (\c atime, \c mtime, \c ctime, and \c btime) - * only \c ctime has been implemented. - * - The \c atime value is the last time the object was read or written. - * - The \c mtime value is the last time the raw data in the object was changed. - * - The \c ctime value is the last time the metadata for the object was changed. - * - The \c btime value is the time the object was created. - * - * The H5O_token_t is defined in H5public.h as follows: - * \snippet H5public.h H5O_token_t_snip - * - * The H5O_type_t \c enum indicates the object type and - * is defined in H5Opublic.h as follows: - * \snippet this H5O_type_t_snip - * - * Note that the object retrieved as indicated by \p loc_id - * refers only to the types specified by H5O_type_t. + * retrieves the metadata describing that object in \p oinfo. * * The \p fields parameter contains flags to determine which fields will be filled in * the H5O_info2_t \c struct returned in \p oinfo. @@ -530,29 +523,6 @@ H5_DLL herr_t H5Oget_info3(hid_t loc_id, H5O_info2_t *oinfo, unsigned fields); * \p loc_id and \p name, respectively, and retrieves the metadata * describing that object in \p oinfo, an H5O_info2_t struct. * - * \p oinfo, in which the object information is returned, is a \c struct of - * type H5O_info2_t, which is defined in H5Opublic.h in the HDF5 source code: - * - * \snippet this H5O_info2_t_snip - * - * Note the following about H5O_info2_t : - * - Of the four time fields (\c atime, \c mtime, \c ctime, and \c btime) - * only \c ctime has been implemented. - * - The \c atime value is the last time the object was read or written. - * - The \c mtime value is the last time the raw data in the object was changed. - * - The \c ctime value is the last time the metadata for the object was changed. - * - The \c btime value is the time the object was created. - * - * The H5O_token_t is defined in H5public.h as follows: - * \snippet H5public.h H5O_token_t_snip - * - * The H5O_type_t \c enum indicates the object type and - * is defined in H5Opublic.h as follows: - * \snippet this H5O_type_t_snip - * - * Note that the object retrieved as indicated by \p loc_id - * refers only to the types specified by H5O_type_t. - * * The \p fields parameter contains flags to determine which fields will be filled in * the H5O_info2_t \c struct returned in \p oinfo. * These flags are defined in the H5Opublic.h file: @@ -608,34 +578,6 @@ H5_DLL herr_t H5Oget_info_by_name_async(const char *app_file, const char *app_fu * If \p loc_id fully specifies the group in which the object resides, * \p group_name can be a dot (\c .). * - * \p idx_type is of type #H5_index_t, defined in H5public.h as: - * \snippet H5public.h H5_index_t_snip - * - * \p order is of type #H5_iter_order_t defined in H5public.h as: - * \snippet H5public.h H5_iter_order_t_snip - * - * \p oinfo, in which the object information is returned, is a \c struct of - * type H5O_info2_t, which is defined in H5Opublic.h in the HDF5 source code: - * \snippet this H5O_info2_t_snip - * - * Note the following about H5O_info2_t : - * - Of the four time fields (\c atime, \c mtime, \c ctime, and \c btime) - * only \c ctime has been implemented. - * - The \c atime value is the last time the object was read or written. - * - The \c mtime value is the last time the raw data in the object was changed. - * - The \c ctime value is the last time the metadata for the object was changed. - * - The \c btime value is the time the object was created. - * - * H5O_token_t is defined in H5public.h as follows: - * \snippet H5public.h H5O_token_t_snip - * - * The #H5O_type_t \c enum indicates the object type and - * is defined in H5Opublic.h as follows: - * \snippet this H5O_type_t_snip - * - * Note that the object retrieved as indicated by \p loc_id - * refers only to the types specified by #H5O_type_t. - * * The \p fields parameter contains flags to determine which fields will be filled in * the H5O_info2_t \c struct returned in \p oinfo. * These flags are defined in the H5Opublic.h file: @@ -668,11 +610,7 @@ H5_DLL herr_t H5Oget_info_by_idx3(hid_t loc_id, const char *group_name, H5_index * \return \herr_t * * \details H5Oget_native_info() retrieves the native file format information for an object - * specified by \p loc_id. The information is retrieved into the - * buffer specified by \p oinfo, which is defined as a \c struct of - * type H5O_native_info_t in H5Opublic.h: - * - * \snippet this H5O_native_info_t_snip + * specified by \p loc_id. * * The \p fields parameter indicates which fields to fill in * H5O_native_info_t. Possible values defined in H5Opublic.h are: @@ -703,12 +641,9 @@ H5_DLL herr_t H5Oget_native_info(hid_t loc_id, H5O_native_info_t *oinfo, unsigne * * \return \herr_t * - * \details H5Oget_native_info_by_name() retrieves the native file format information for an object - * specified by \p loc_id and the name \p name. The information is - * retrieved into the buffer specified by \p oinfo, which is defined - * as a \c struct of type H5O_native_info_t in H5Opublic.h: - * - * \snippet this H5O_native_info_t_snip + * \details H5Oget_native_info_by_name() retrieves the native file format + * information for an object specified by \p loc_id and the name \p + * name. * * The \p fields parameter which fields to fill in H5O_native_info_t. * Possible values defined in H5Opublic.h are: @@ -747,16 +682,7 @@ H5_DLL herr_t H5Oget_native_info_by_name(hid_t loc_id, const char *name, H5O_nat * specified by \p loc_id, group name, \p group_name, the index by which * objects in the group are tracked, \p idx_type, the order by which * the index is to be traversed, \p order , and an object's position - * \p n within that index. The information is retrieved into the - * buffer specified by \p oinfo, which is defined as a \c struct of - * type H5O_native_info_t in H5Opublic.h: - * \snippet this H5O_native_info_t_snip - * - * \p idx_type is of type #H5_index_t, defined in H5public.h as: - * \snippet H5public.h H5_index_t_snip - * - * \p order is of type #H5_iter_order_t defined in H5public.h as: - * \snippet H5public.h H5_iter_order_t_snip + * \p n within that index. * * The \p fields parameter indicates which fields to fill in H5O_native_info_t. * Possible values defined in H5Opublic.h are: @@ -1236,11 +1162,8 @@ H5_DLL ssize_t H5Oget_comment_by_name(hid_t loc_id, const char *name, char *comm * a group have not been indexed by the index type, they will * first be sorted by that index then the iteration will begin; * if the links have been so indexed, the sorting step will be - * unnecessary, so the iteration may begin more quickly. Valid - * values include the following: - * - * \indexes - * + * unnecessary, so the iteration may begin more quickly. + * Note that the index type passed in \p idx_type is a * <em>best effort</em> setting. If the application passes in * a value indicating iteration in creation order and a group is @@ -1250,62 +1173,7 @@ H5_DLL ssize_t H5Oget_comment_by_name(hid_t loc_id, const char *name, char *comm * used by the HDF5 library and is always available.) * * \p order specifies the order in which objects are to be inspected - * along the index specified in \p idx_type. Valid values include - * the following: - * - * \orders - * - * The prototype of the callback function op is as follows (as - * defined in the source code file H5Opublic.h): - * - * \snippet this H5O_iterate2_t_snip - * - * The parameters of this callback function have the following values - * or meanings: - * <table> - * <tr> - * <td>\c obj</td> - * <td>Object that serves as root of the iteration; - * same value as the H5Ovisit() \p obj_id parameter</td> - * </tr> - * <tr> - * <td>\c name</td> - * <td>Name of object, relative to \c obj, being examined at - * current step of the iteration</td> - * </tr> - * <tr> - * <td>\c info</td> - * <td>H5O_info2_t \c struct containing information - * regarding that object</td> - * </tr> - * <tr> - * <td>\c op_data</td> - * <td>User-defined pointer to data required by the application in - * processing the object; a pass-through of the \c op_data pointer - * provided with the H5Ovisit() function call</td> - * </tr> - * </table> - * - * The H5O_info2_t \c struct is defined in H5Opublic.h as follows: - * \snippet this H5O_info2_t_snip - * - * H5O_token_t is defined in H5public.h as follows: - * \snippet H5public.h H5O_token_t_snip - * - * The #H5O_type_t enum indicates the object type and is - * defined in H5Opublic.h as follows: - * \snippet this H5O_type_t_snip - * - * Note that the object retrieved as indicated by \p obj_id - * refers only to the types specified by #H5O_type_t. - * - * The return values from an operator are: - * - Zero causes the visit iterator to continue, returning zero when all - * group members have been processed. - * - A positive value causes the visit iterator to immediately return that - * positive value, indicating short-circuit success. - * - A negative value causes the visit iterator to immediately return that - * value, indicating failure. + * along the index specified in \p idx_type. * * The H5Ovisit3() \p op_data parameter is a user-defined pointer to the data * required to process objects in the course of the iteration. This pointer @@ -1329,24 +1197,6 @@ H5_DLL ssize_t H5Oget_comment_by_name(hid_t loc_id, const char *name, char *comm * group change during the iteration, the resulting behavior * is undefined. * - * \note \Bold{Programming Note for C++ Developers Using C Functions:} - * \note If a C routine that takes a function pointer as an argument is - * called from within C++ code, the C routine should be returned - * from normally. - * - * \note Examples of this kind of routine include callbacks such as - * H5Pset_elink_cb() and H5Pset_type_conv_cb() and - * functions such as H5Tconvert() and H5Ewalk2(). - * - * \note Exiting the routine in its normal fashion allows the HDF5 - * C library to clean up its work properly. In other words, if - * the C++ application jumps out of the routine back to the C++ - * “catch” statement, the library is not given the opportunity - * to close any temporary data structures that were set up when - * the routine was called. The C++ application should save some - * state as the routine is started so that any problem that occurs - * might be diagnosed. - * * \par Example * An example snippet from test/links.c: * \snippet links.c H5Ovisit3_snip @@ -1411,10 +1261,7 @@ H5_DLL herr_t H5Ovisit3(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * a group have not been indexed by the index type, they will * first be sorted by that index then the iteration will begin; * if the links have been so indexed, the sorting step will be - * unnecessary, so the iteration may begin more quickly. Valid - * values include the following: - * - * \indexes + * unnecessary, so the iteration may begin more quickly. * * Note that the index type passed in \p idx_type is a * <em>best effort</em> setting. If the application passes in a @@ -1425,49 +1272,7 @@ H5_DLL herr_t H5Ovisit3(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * used by the HDF5 library and is always available.) * * \p order specifies the order in which objects are to be inspected - * along the index specified in \p idx_type. Valid values include - * the following: - * - * \orders - * - * The prototype of the callback function op is as follows (as - * defined in the source code file H5Opublic.h): - * - * \snippet this H5O_iterate2_t_snip - * - * The parameters of this callback function have the following - * values or meanings: - * <table> - * <tr> - * <td>\c obj</td> - * <td>Object that serves as root of the iteration</td> - * </tr> - * <tr> - * <td>\c name</td> - * <td>Name of object, relative to \c obj, being examined at - * current step of the iteration</td> - * </tr> - * <tr> - * <td>\c info</td> - * <td>H5O_info2_t \c struct containing information - * regarding that object</td> - * </tr> - * <tr> - * <td>\c op_data</td> - * <td>User-defined pointer to data required by the application in - * processing the object</td> - * </tr> - * </table> - * - * The H5O_info2_t \c struct is defined in H5Opublic.h as follows: - * \snippet this H5O_info2_t_snip - * - * H5O_token_t is defined in H5public.h as follows: - * \snippet H5public.h H5O_token_t_snip - * - * The #H5O_type_t enum indicates the object type and is - * defined in H5Opublic.h as follows: - * \snippet this H5O_type_t_snip + * along the index specified in \p idx_type. * * The H5Ovisit_by_name3() \p op_data parameter is a user-defined * pointer to the data required to process objects in the course @@ -1495,24 +1300,6 @@ H5_DLL herr_t H5Ovisit3(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * in the file has been presented to the application for whatever * processing the application requires. * - * \note \Bold{Programming Note for C++ Developers Using C Functions:} - * \note If a C routine that takes a function pointer as an argument is - * called from within C++ code, the C routine should be returned - * from normally. - * - * \note Examples of this kind of routine include callbacks such as - * H5Pset_elink_cb() and H5Pset_type_conv_cb() and - * functions such as H5Tconvert() and H5Ewalk2(). - * - * \note Exiting the routine in its normal fashion allows the HDF5 - * C library to clean up its work properly. In other words, if - * the C++ application jumps out of the routine back to the C++ - * “catch” statement, the library is not given the opportunity - * to close any temporary data structures that were set up when - * the routine was called. The C++ application should save some - * state as the routine is started so that any problem that occurs - * might be diagnosed. - * * \par Example * An example snippet from test/links.c: * \snippet links.c H5Ovisit_by_name3_snip @@ -1579,26 +1366,11 @@ H5_DLL herr_t H5Oclose_async(const char *app_file, const char *app_func, unsigne * files. After that, the OS is responsible for ensuring that * the data is actually flushed to disk. * - * \par See Also: - * - H5Dflush() - * - H5Drefresh() - * - H5Oflush() - * - H5Grefresh() - * - H5Oflush() - * - H5Orefresh() - * - H5Tflush() - * - H5Trefresh() - * \par - * - \c H5DOappend() - * - H5Fstart_swmr_write() - * - H5Pget_append_flush() - * - H5Pget_object_flush_cb() - * - H5Pset_append_flush() - * - H5Pset_object_flush_cb() - * \par - * - H5Oare_mdc_flushes_disabled() - * - H5Odisable_mdc_flushes() - * - H5Oenable_mdc_flushes() + * \see H5Dflush(), H5Drefresh(), H5Oflush(), H5Grefresh(), H5Oflush(), + * H5Orefresh(), H5Tflush(), H5Trefresh() + * \see H5DOappend(), H5Fstart_swmr_write(), H5Pget_append_flush(), + * H5Pget_object_flush_cb(), H5Pset_append_flush(), H5Pset_object_flush_cb() + * \see H5Oare_mdc_flushes_disabled(), H5Odisable_mdc_flushes(), H5Oenable_mdc_flushes() * * \since 1.10.0 * @@ -1670,21 +1442,17 @@ H5_DLL herr_t H5Orefresh_async(const char *app_file, const char *app_func, unsig * HDF5 object level (datasets, groups, committed datatypes) * and the entire metadata cache level. * - * \note HDF5 objects include datasets, groups, and committed datatypes. - * Only #hid_t identifiers that represent these objects can be passed to the function. - * \note Passing in a #hid_t identifier that represents any other HDF5 entity is - * considered an error. - * \note It is an error to pass an HDF5 file identifier - * (obtained from H5Fopen() or H5Fcreate()) - * to this function. - * \note Misuse of this function can cause the cache to exhaust - * available memory. - * \note Objects can be returned to the default automatic flush behavior - * with H5Oenable_mdc_flushes(). - * \note Flush prevention only pertains to new or dirty metadata entries. - * Clean entries can be evicted from the cache. - * \note Calling this function on an object that has already had flushes - * disabled will return an error. + * \note HDF5 objects include datasets, groups, and committed datatypes. Only + * #hid_t identifiers that represent these objects can be passed to the + * function. Passing in a #hid_t identifier that represents any other + * HDF5 entity is considered an error. It is an error to pass an HDF5 + * file identifier (obtained from H5Fopen() or H5Fcreate()) to this + * function. Misuse of this function can cause the cache to exhaust + * available memory. Objects can be returned to the default automatic + * flush behavior with H5Oenable_mdc_flushes(). Flush prevention only + * pertains to new or dirty metadata entries. Clean entries can be + * evicted from the cache. Calling this function on an object that has + * already had flushes disabled will return an error. * * \since 1.10.0 * @@ -1714,28 +1482,18 @@ H5_DLL herr_t H5Odisable_mdc_flushes(hid_t object_id); * metadata cache level. * * - * \note HDF5 objects include datasets, groups, and committed datatypes. - * Only #hid_t identifiers that represent these objects can be - * passed to the function. - * - * \note Passing in a #hid_t identifier that represents any other HDF5 entity - * is considered an error. - * - * \note It is an error to pass an HDF5 file identifier - * (obtained from H5Fopen() or H5Fcreate()) - * to this function. - * - * \note Using this function on an object that has not had flushes disabled - * is considered an error. The state of an object can be determined - * with H5Oare_mdc_flushes_disabled(). - * - * \note An object will be returned to the default flush algorithm when it is closed. - * - * \note All objects will be returned to the default flush algorithm when - * the file is closed. - * - * \note An object’s entries will not necessarily be flushed as a result of - * calling this function. + * \note HDF5 objects include datasets, groups, and committed datatypes. Only + * #hid_t identifiers that represent these objects can be passed to the + * function. Passing in a #hid_t identifier that represents any other + * HDF5 entity is considered an error. It is an error to pass an HDF5 + * file identifier (obtained from H5Fopen() or H5Fcreate()) to this + * function. Using this function on an object that has not had flushes + * disabled is considered an error. The state of an object can be + * determined with H5Oare_mdc_flushes_disabled(). An object will be + * returned to the default flush algorithm when it is closed. All objects + * will be returned to the default flush algorithm when the file is + * closed. An object’s entries will not necessarily be flushed as a + * result of calling this function. * * \since 1.10.0 * @@ -1871,6 +1629,7 @@ H5_DLL herr_t H5Otoken_to_str(hid_t loc_id, const H5O_token_t *token, char **tok */ H5_DLL herr_t H5Otoken_from_str(hid_t loc_id, const char *token_str, H5O_token_t *token); +/// \cond DEV /* API Wrappers for async routines */ /* (Must be defined _after_ the function prototype) */ /* (And must only defined when included in application code, not the library) */ @@ -1894,6 +1653,7 @@ H5_DLL herr_t H5Otoken_from_str(hid_t loc_id, const char *token_str, H5O_token_t #define H5Orefresh_async_wrap H5_NO_EXPAND(H5Orefresh_async) #define H5Ocopy_async_wrap H5_NO_EXPAND(H5Ocopy_async) #endif +/// \endcond /* The canonical 'undefined' token value */ #define H5O_TOKEN_UNDEF (H5OPEN H5O_TOKEN_UNDEF_g) @@ -1908,8 +1668,8 @@ H5_DLLVAR const H5O_token_t H5O_TOKEN_UNDEF_g; /* Macros */ /* Deprecated flags for earlier versions of H5Oget_info* */ -#define H5O_INFO_HDR 0x0008u /* Fill in the hdr field */ -#define H5O_INFO_META_SIZE 0x0010u /* Fill in the meta_size field */ +#define H5O_INFO_HDR 0x0008u /**< Fill in the hdr field */ +#define H5O_INFO_META_SIZE 0x0010u /**< Fill in the meta_size field */ #undef H5O_INFO_ALL #define H5O_INFO_ALL (H5O_INFO_BASIC | H5O_INFO_TIME | H5O_INFO_NUM_ATTRS | H5O_INFO_HDR | H5O_INFO_META_SIZE) @@ -1942,7 +1702,7 @@ typedef struct H5O_info1_t { time_t mtime; /**< Modification time */ time_t ctime; /**< Change time */ time_t btime; /**< Birth time */ - hsize_t num_attrs; /**< # of attributes attached to object */ + hsize_t num_attrs; /**< Number of attributes attached to object */ H5O_hdr_info_t hdr; /**< Object header information */ /* Extra metadata storage for obj & attributes */ struct { @@ -1955,6 +1715,16 @@ typedef struct H5O_info1_t { //! <!-- [H5O_iterate1_t_snip] --> /** * Prototype for H5Ovisit(), H5Ovisit_by_name() operator (versions 1 & 2) + * + * \param[in] obj Object that serves as the root of the iteration; + * the same value as the H5Ovisit1() \c obj_id parameter + * \param[in] name Name of object, relative to \p obj, being examined at current + * step of the iteration + * \param[out] info Information about that object + * \param[in,out] op_data User-defined pointer to data required by the application + * in processing the object + * \return \herr_t_iter + * */ typedef herr_t (*H5O_iterate1_t)(hid_t obj, const char *name, const H5O_info1_t *info, void *op_data); //! <!-- [H5O_iterate1_t_snip] --> @@ -2027,36 +1797,7 @@ H5_DLL hid_t H5Oopen_by_addr(hid_t loc_id, haddr_t addr); * the function H5Oget_info3() or the macro #H5Oget_info. * * \details H5Oget_info1() specifies an object by its identifier, \p loc_id , and - * retrieves the metadata describing that object in \p oinfo , - * defined as a \c struct of type H5O_info1_t : - * - * \snippet this H5O_info1_t_snip - * - * Note the following about H5O_info1_t : - * - Of the four time fields (\c atime, \c mtime, \c ctime, and \c btime) - * only \c ctime has been implemented. - * - The \c atime value is the last time the object was read or written. - * - The \c mtime value is the last time the raw data in the object was changed. - * - The \c ctime value is the last time the metadata for the object was changed. - * - The \c btime value is the time the object was created. - * - The fields nested in the \c meta_size field are for internal library use only. - * - * The #H5O_type_t \c enum indicates the object type and - * is defined in H5Opublic.h as follows: - * \snippet this H5O_type_t_snip - * - * Note that the object retrieved as indicated by \p loc_id - * refers only to the types specified by #H5O_type_t. - * - * An H5O_hdr_info_t \c struct holds object header metadata and is - * defined in H5Opublic.h as follows: - * \snippet this H5O_hdr_info_t_snip - * - * Valid values for the \c version field are \c H5O_VERSION_1 and \c H5O_VERSION_2. - * Version 2 of the object header is smaller and more efficient than version 1. - * - * Please be aware that the information held by H5O_hdr_info_t may only be useful to - * developers with extensive HDF5 experience. + * retrieves the metadata describing that object in \p oinfo. * * \note If you are iterating through a lot of different objects to * retrieve information via the H5Oget_info() family of routines, @@ -2156,16 +1897,6 @@ H5_DLL herr_t H5Oget_info_by_name1(hid_t loc_id, const char *name, H5O_info1_t * * If \p loc_id fully specifies the group in which the object resides, * \p group_name can be a dot (\c .). * - * \p idx_type is of type #H5_index_t, defined in H5public.h as: - * \snippet H5public.h H5_index_t_snip - * - * \p order is of type #H5_iter_order_t defined in H5public.h as: - * \snippet H5public.h H5_iter_order_t_snip - * - * \p oinfo, in which the object information is returned, is a \c struct of - * type H5O_info1_t . - * \snippet this H5O_info1_t_snip - * * The link access property list, \c lapl_id, is not currently used; * it should be passed in as #H5P_DEFAULT. * @@ -2361,10 +2092,7 @@ H5_DLL herr_t H5Oget_info_by_idx2(hid_t loc_id, const char *group_name, H5_index * a group have not been indexed by the index type, they will * first be sorted by that index then the iteration will begin; * if the links have been so indexed, the sorting step will be - * unnecessary, so the iteration may begin more quickly. Valid - * values include the following: - * - * \indexes + * unnecessary, so the iteration may begin more quickly. * * Note that the index type passed in \p idx_type is a * <em>best effort</em> setting. If the application passes in @@ -2375,56 +2103,7 @@ H5_DLL herr_t H5Oget_info_by_idx2(hid_t loc_id, const char *group_name, H5_index * used by the HDF5 library and is always available.) * * \p order specifies the order in which objects are to be inspected - * along the index specified in \p idx_type. Valid values include - * the following: - * - * \orders - * - * The prototype of the callback function op is as follows (as - * defined in the source code file H5Opublic.h): - * - * \snippet this H5O_iterate1_t_snip - * - * The parameters of this callback function have the following values - * or meanings: - * <table> - * <tr> - * <td>\c obj</td> - * <td>Object that serves as root of the iteration; - * same value as the H5Ovisit1() \p obj_id parameter</td> - * </tr> - * <tr> - * <td>\c name</td> - * <td>Name of object, relative to \c obj, being examined at - * current step of the iteration</td> - * </tr> - * <tr> - * <td>\c info</td> - * <td>H5O_info1_t \c struct containing information - * regarding that object</td> - * </tr> - * <tr> - * <td>\c op_data</td> - * <td>User-defined pointer to data required by the application in - * processing the object</td> - * </tr> - * </table> - * - * The H5O_info1_t \c struct is defined in H5Opublic.h: - * \snippet this H5O_info1_t_snip - * - * The return values from an operator are: - * - Zero causes the visit iterator to continue, returning zero when all - * group members have been processed. - * - A positive value causes the visit iterator to immediately return that - * positive value, indicating short-circuit success. - * - A negative value causes the visit iterator to immediately return that - * value, indicating failure. - * - * The H5Ovisit1() \p op_data parameter is a user-defined pointer to the data - * required to process objects in the course of the iteration. This pointer - * is passed back to each step of the iteration in the callback - * function’s \p op_data parameter. + * along the index specified in \p idx_type. * * H5Lvisit1() and H5Ovisit1() are companion functions: one for * examining and operating on links; the other for examining @@ -2438,24 +2117,6 @@ H5_DLL herr_t H5Oget_info_by_idx2(hid_t loc_id, const char *group_name, H5_index * group change during the iteration, the resulting behavior * is undefined. * - * \note \Bold{Programming Note for C++ Developers Using C Functions:} - * \note If a C routine that takes a function pointer as an argument is - * called from within C++ code, the C routine should be returned - * from normally. - * - * \note Examples of this kind of routine include callbacks such as - * H5Pset_elink_cb() and H5Pset_type_conv_cb() and - * functions such as H5Tconvert() and H5Ewalk2(). - * - * \note Exiting the routine in its normal fashion allows the HDF5 - * C library to clean up its work properly. In other words, if - * the C++ application jumps out of the routine back to the C++ - * “catch” statement, the library is not given the opportunity - * to close any temporary data structures that were set up when - * the routine was called. The C++ application should save some - * state as the routine is started so that any problem that occurs - * might be diagnosed. - * * \version 1.10.5 The macro #H5Ovisit was removed and the function * H5Ovisit1() was copied to H5Ovisit(). * \version 1.10.3 Function H5Ovisit() was copied to H5Ovisit1(), @@ -2523,10 +2184,7 @@ H5_DLL herr_t H5Ovisit1(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * a group have not been indexed by the index type, they will * first be sorted by that index then the iteration will begin; * if the links have been so indexed, the sorting step will be - * unnecessary, so the iteration may begin more quickly. Valid - * values include the following: - * - * \indexes + * unnecessary, so the iteration may begin more quickly. * * Note that the index type passed in \p idx_type is a * <em>best effort</em> setting. If the application passes in a @@ -2537,10 +2195,7 @@ H5_DLL herr_t H5Ovisit1(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * used by the HDF5 library and is always available.) * * \p order specifies the order in which objects are to be inspected - * along the index specified in \p idx_type. Valid values include - * the following: - * - * \orders + * along the index specified in \p idx_type. * * The \p op callback function and the effect of the callback * function’s return value on the application are described @@ -2570,24 +2225,6 @@ H5_DLL herr_t H5Ovisit1(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * in the file has been presented to the application for whatever * processing the application requires. * - * \note \Bold{Programming Note for C++ Developers Using C Functions:} - * \note If a C routine that takes a function pointer as an argument is - * called from within C++ code, the C routine should be returned - * from normally. - * - * \note Examples of this kind of routine include callbacks such as - * H5Pset_elink_cb() and H5Pset_type_conv_cb() and - * functions such as H5Tconvert() and H5Ewalk2(). - * - * \note Exiting the routine in its normal fashion allows the HDF5 - * C library to clean up its work properly. In other words, if - * the C++ application jumps out of the routine back to the C++ - * “catch” statement, the library is not given the opportunity - * to close any temporary data structures that were set up when - * the routine was called. The C++ application should save some - * state as the routine is started so that any problem that occurs - * might be diagnosed. - * * \version 1.10.5 The macro #H5Ovisit_by_name was removed and the function * H5Ovisit_by_name1() was copied to #H5Ovisit_by_name. * \version 1.10.3 The H5Ovisit_by_name() function was renamed to H5Ovisit_by_name1(), @@ -2650,10 +2287,7 @@ H5_DLL herr_t H5Ovisit_by_name1(hid_t loc_id, const char *obj_name, H5_index_t i * a group have not been indexed by the index type, they will * first be sorted by that index then the iteration will begin; * if the links have been so indexed, the sorting step will be - * unnecessary, so the iteration may begin more quickly. Valid - * values include the following: - * - * \indexes + * unnecessary, so the iteration may begin more quickly. * * Note that the index type passed in \p idx_type is a * <em>best effort</em> setting. If the application passes in @@ -2664,57 +2298,7 @@ H5_DLL herr_t H5Ovisit_by_name1(hid_t loc_id, const char *obj_name, H5_index_t i * used by the HDF5 library and is always available.) * * \p order specifies the order in which objects are to be inspected - * along the index specified in \p idx_type. Valid values include - * the following: - * - * \orders - * - * The prototype of the callback function op is as follows (as - * defined in the source code file H5Opublic.h): - * - * \snippet this H5O_iterate1_t_snip - * - * The parameters of this callback function have the following values - * or meanings: - * <table> - * <tr> - * <td>\c obj</td> - * <td>Object that serves as root of the iteration; - * same value as the H5Ovisit1() \p obj_id parameter</td> - * </tr> - * <tr> - * <td>\c name</td> - * <td>Name of object, relative to \c obj, being examined at - * current step of the iteration</td> - * </tr> - * <tr> - * <td>\c info</td> - * <td>H5O_info1_t \c struct containing information - * regarding that object</td> - * </tr> - * <tr> - * <td>\c op_data</td> - * <td>User-defined pointer to data required by the application in - * processing the object; a pass-through of the \c op_data pointer - * provided with the H5Ovisit() function call</td> - * </tr> - * </table> - * - * The H5O_info1_t \c struct is defined in H5Opublic.h and - * described in the H5Oget_info1() function entry. - * - * The return values from an operator are: - * - Zero causes the visit iterator to continue, returning zero when all - * group members have been processed. - * - A positive value causes the visit iterator to immediately return that - * positive value, indicating short-circuit success. - * - A negative value causes the visit iterator to immediately return that - * value, indicating failure. - * - * The H5Ovisit2() \p op_data parameter is a user-defined pointer to the data - * required to process objects in the course of the iteration. This pointer - * is passed back to each step of the iteration in the callback - * function’s \p op_data parameter. + * along the index specified in \p idx_type. * * The \p fields parameter contains flags to determine which fields will * be retrieved by the \p op callback function. These flags are defined @@ -2733,23 +2317,6 @@ H5_DLL herr_t H5Ovisit_by_name1(hid_t loc_id, const char *obj_name, H5_index_t i * group change during the iteration, the resulting behavior * is undefined. * - * \note \Bold{Programming Note for C++ Developers Using C Functions:} - * \note If a C routine that takes a function pointer as an argument is - * called from within C++ code, the C routine should be returned - * from normally. - * - * \note Examples of this kind of routine include callbacks such as - * H5Pset_elink_cb() and H5Pset_type_conv_cb() and - * functions such as H5Tconvert() and H5Ewalk2(). - * - * \note Exiting the routine in its normal fashion allows the HDF5 - * C library to clean up its work properly. In other words, if - * the C++ application jumps out of the routine back to the C++ - * “catch” statement, the library is not given the opportunity - * to close any temporary data structures that were set up when - * the routine was called. The C++ application should save some - * state as the routine is started so that any problem that occurs - * might be diagnosed. * * \since 1.10.3 * @@ -2814,10 +2381,7 @@ H5_DLL herr_t H5Ovisit2(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * a group have not been indexed by the index type, they will * first be sorted by that index then the iteration will begin; * if the links have been so indexed, the sorting step will be - * unnecessary, so the iteration may begin more quickly. Valid - * values include the following: - * - * \indexes + * unnecessary, so the iteration may begin more quickly. * * Note that the index type passed in \p idx_type is a * <em>best effort</em> setting. If the application passes in a @@ -2828,10 +2392,7 @@ H5_DLL herr_t H5Ovisit2(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * used by the HDF5 library and is always available.) * * \p order specifies the order in which objects are to be inspected - * along the index specified in \p idx_type. Valid values include - * the following: - * - * \orders + * along the index specified in \p idx_type. * * The \p op callback function and the effect of the callback * function’s return value on the application are described @@ -2866,24 +2427,6 @@ H5_DLL herr_t H5Ovisit2(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * in the file has been presented to the application for whatever * processing the application requires. * - * \note \Bold{Programming Note for C++ Developers Using C Functions:} - * \note If a C routine that takes a function pointer as an argument is - * called from within C++ code, the C routine should be returned - * from normally. - * - * \note Examples of this kind of routine include callbacks such as - * H5Pset_elink_cb() and H5Pset_type_conv_cb() and - * functions such as H5Tconvert() and H5Ewalk2(). - * - * \note Exiting the routine in its normal fashion allows the HDF5 - * C library to clean up its work properly. In other words, if - * the C++ application jumps out of the routine back to the C++ - * “catch” statement, the library is not given the opportunity - * to close any temporary data structures that were set up when - * the routine was called. The C++ application should save some - * state as the routine is started so that any problem that occurs - * might be diagnosed. - * * \since 1.10.3 * */ diff --git a/src/H5PLmodule.h b/src/H5PLmodule.h index ab9f1d5..a093096 100644 --- a/src/H5PLmodule.h +++ b/src/H5PLmodule.h @@ -28,8 +28,34 @@ #define H5_MY_PKG_INIT YES /**\defgroup H5PL H5PL - * \brief Plugins - * \todo Describe what programmatically controlling dynamically loaded plugins (H5PL) is all about + * + * Use the functions in this module to manage the loading behavior of HDF5 + * plugins. + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet H5PL_examples.c create + * </td> + * <td> + * \snippet H5PL_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet H5PL_examples.c update + * </td> + * <td> + * \snippet H5PL_examples.c delete + * </td> + * </tr> + * </table> + * + * \attention The loading behavior of HDF5 plugins can be controlled via the + * functions described below and certain environment variables, such + * as \c HDF5_PLUGIN_PRELOAD and \c HDF5_PLUGIN_PATH. + * */ #endif /* H5PLmodule_H */ diff --git a/src/H5Pmodule.h b/src/H5Pmodule.h index 18f30c6..6e92e66 100644 --- a/src/H5Pmodule.h +++ b/src/H5Pmodule.h @@ -30,49 +30,165 @@ #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. + * Use the functions in this module to manage HDF5 property lists and property + * list classes. HDF5 property lists are the main vehicle to configure the + * behavior of HDF5 API functions. * - * 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. + * Typically, property lists are created by instantiating one of the built-in + * or user-defined property list classes. After adding suitable properties, + * property lists are used when opening or creating HDF5 items, or when reading + * or writing data. Property lists can be modified by adding or changing + * properties. Property lists are deleted by closing the associated handles. * - * \todo Describe concisely what the functions in this module are about. + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5P_examples.c create + * </td> + * <td> + * \snippet{lineno} H5P_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5P_examples.c update + * </td> + * <td> + * \snippet{lineno} H5P_examples.c delete + * </td> + * </tr> + * </table> * - * \defgroup GPLO General Property List Operations + * \defgroup ALCAPL Attribute and Link Creation Properties * \ingroup H5P - * \defgroup GPLOA General Property List Operations (Advanced) + * Currently, there are only two creation properties that you can use to control + * the creation of HDF5 attributes and links. The first creation property, the + * choice of a character encoding, applies to both attributes and links. + * The second creation property applies to links only, and advises the library + * to automatically create missing intermediate groups when creating new objects. + * + * \defgroup DAPL Dataset Access Properties * \ingroup H5P - * \defgroup FCPL File Creation Properties + * Use dataset access properties to modify the default behavior of the HDF5 + * library when accessing datasets. The properties include adjusting the size + * of the chunk cache, providing prefixes for external content and virtual + * dataset file paths, and controlling flush behavior, etc. These properties + * are \Emph{not} persisted with datasets, and can be adjusted at runtime before + * a dataset is created or opened. + * + * \defgroup DCPL Dataset Creation Properties + * \ingroup H5P + * Use dataset creation properties to control aspects of dataset creation such + * as fill time, storage layout, compression methods, etc. + * Unlike dataset access and transfer properties, creation properties \Emph{are} + * stored with the dataset, and cannot be changed once a dataset has been + * created. + * + * \defgroup DXPL Dataset Transfer Properties * \ingroup H5P + * Use dataset transfer properties to customize certain aspects of reading + * and writing datasets such as transformations, MPI-IO I/O mode, error + * detection, etc. These properties are \Emph{not} persisted with datasets, + * and can be adjusted at runtime before a dataset is read or written. + * * \defgroup FAPL File Access Properties * \ingroup H5P - * \defgroup GCPL Group Creation Properties + * Use file access properties to modify the default behavior of the HDF5 + * library when accessing files. The properties include selecting a virtual + * file driver (VFD), configuring the metadata cache (MDC), control + * file locking, etc. These properties are \Emph{not} persisted with files, and + * can be adjusted at runtime before a file is created or opened. + * + * \defgroup FCPL File Creation Properties * \ingroup H5P - * \defgroup ALCAPL Attribute and Link Creation Properties + * Use file creation properties to control aspects of file creation such + * as setting a file space management strategy or creating a user block. + * Unlike file access properties, creation properties \Emph{are} + * stored with the file, and cannot be changed once a file has been + * created. + * + * \defgroup GAPL General Access Properties * \ingroup H5P - * \defgroup LAPL Link Access Properties + * \todo Should this be as standalone page? + * + * \defgroup GCPL Group Creation Properties * \ingroup H5P - * \defgroup DCPL Dataset Creation Properties + * Use group creation properties to control aspects of group creation such + * as storage layout, compression, and link creation order tracking. + * Unlike file access properties, creation properties \Emph{are} + * stored with the group, and cannot be changed once a group has been + * created. + * + * \defgroup GPLO General Property List Operations * \ingroup H5P - * \defgroup DAPL Dataset Access Properties + * + * Use the functions in this module to manage HDF5 property lists. + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5P_examples.c create + * </td> + * <td> + * \snippet{lineno} H5P_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5P_examples.c update + * </td> + * <td> + * \snippet{lineno} H5P_examples.c delete + * </td> + * </tr> + * </table> + * + * \defgroup GPLOA General Property List Operations (Advanced) * \ingroup H5P - * \defgroup DXPL Dataset Transfer Properties + * + * You can create and customize user-defined property list classes using the + * functions described below. Arbitrary user-defined properties can also + * be inserted into existing property lists as so-called temporary properties. + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * + * <tr valign="top"> + * <td> + * \snippet{lineno} H5P_examples.c create_class + * </td> + * <td> + * \snippet{lineno} H5P_examples.c read_class + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5P_examples.c update_class + * </td> + * <td> + * \snippet{lineno} H5P_examples.c delete_class + * </td> + * </tr> + * </table> + * + * \defgroup LAPL Link Access Properties * \ingroup H5P + * + * + * \defgroup MAPL Map Access Properties + * \ingroup H5P + * \defgroup OCPL Object Creation Properties * \ingroup H5P + * + * * \defgroup OCPPL Object Copy Properties * \ingroup H5P - * \defgroup GACPL General Access Properties - * \ingroup H5P - * \defgroup MAPL Map Access Properties - * \ingroup H5P + * + * */ #endif /* H5Pmodule_H */ diff --git a/src/H5Ppublic.h b/src/H5Ppublic.h index 10609b2..5e9c4ab 100644 --- a/src/H5Ppublic.h +++ b/src/H5Ppublic.h @@ -100,7 +100,9 @@ #define H5P_CRT_ORDER_TRACKED 0x0001 #define H5P_CRT_ORDER_INDEXED 0x0002 -/* Default value for all property list classes */ +/** + * Default value of type \ref hid_t for all property list classes + */ #define H5P_DEFAULT 0 /* (hid_t) */ #ifdef __cplusplus @@ -113,14 +115,23 @@ extern "C" { /* Define property list class callback function pointer types */ //! <!-- [H5P_cls_create_func_t_snip] --> +/** + * \todo Document me! + */ 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] --> +/** + * \todo Document me! + */ 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] --> +/** + * \todo Document me! + */ typedef herr_t (*H5P_cls_close_func_t)(hid_t prop_id, void *close_data); //! <!-- [H5P_cls_close_func_t_snip] --> @@ -159,12 +170,25 @@ typedef herr_t (*H5P_prp_cb2_t)(hid_t prop_id, const char *name, size_t size, vo 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; +//! <!-- [H5P_prp_encode_func_t_snip] --> +/** + * \todo Document me! + */ typedef herr_t (*H5P_prp_encode_func_t)(const void *value, void **buf, size_t *size); +//! <!-- [H5P_prp_encode_func_t_snip] --> +//! <!-- [H5P_prp_decode_func_t_snip] --> +/** + * \todo Document me! + */ typedef herr_t (*H5P_prp_decode_func_t)(const void **buf, void *value); +//! <!-- [H5P_prp_decode_func_t_snip] --> 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] --> +/** + * \todo Document me! + */ typedef int (*H5P_prp_compare_func_t)(const void *value1, const void *value2, size_t size); //! <!-- [H5P_prp_compare_func_t_snip] --> @@ -172,6 +196,9 @@ typedef H5P_prp_cb1_t H5P_prp_close_func_t; /* Define property list iteration function type */ //! <!-- [H5P_iterate_t_snip] --> +/** + * \todo Document me! + */ typedef herr_t (*H5P_iterate_t)(hid_t id, const char *name, void *iter_data); //! <!-- [H5P_iterate_t_snip] --> @@ -2211,7 +2238,7 @@ H5_DLL herr_t H5Pset_attr_creation_order(hid_t plist_id, unsigned crt_order_flag */ H5_DLL herr_t H5Pset_attr_phase_change(hid_t plist_id, unsigned max_compact, unsigned min_dense); /** - * \ingroup OCPL + * \ingroup DCPL * * \brief Sets deflate (GNU gzip) compression method and compression level * @@ -2220,6 +2247,8 @@ H5_DLL herr_t H5Pset_attr_phase_change(hid_t plist_id, unsigned max_compact, uns * * \return \herr_t * + * \par_compr_note + * * \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. @@ -5237,7 +5266,7 @@ H5_DLL herr_t H5Pget_vol_cap_flags(hid_t plist_id, unsigned *cap_flags); #ifdef H5_HAVE_PARALLEL /** - * \ingroup GACPL + * \ingroup GAPL * * \brief Sets metadata I/O mode for read operations to collective or independent (default) * @@ -5306,7 +5335,7 @@ H5_DLL herr_t H5Pget_vol_cap_flags(hid_t plist_id, unsigned *cap_flags); */ H5_DLL herr_t H5Pset_all_coll_metadata_ops(hid_t plist_id, hbool_t is_collective); /** - * \ingroup GACPL + * \ingroup GAPL * * \brief Retrieves metadata read mode setting * @@ -6266,6 +6295,8 @@ H5_DLL herr_t H5Pset_fill_value(hid_t plist_id, hid_t type_id, const void *value * * \return \herr_t * + * \par_compr_note + * * \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. @@ -6337,6 +6368,8 @@ H5_DLL herr_t H5Pset_layout(hid_t plist_id, H5D_layout_t layout); * * \return \herr_t * + * \par_compr_note + * * \details H5Pset_nbit() sets the N-Bit filter, #H5Z_FILTER_NBIT, in the * dataset creation property list \p plist_id. * @@ -6430,6 +6463,8 @@ H5_DLL herr_t H5Pset_nbit(hid_t plist_id); * * \return \herr_t * + * \par_compr_note + * * \details H5Pset_scaleoffset() sets the scale-offset filter, * #H5Z_FILTER_SCALEOFFSET, for a dataset. * @@ -6539,6 +6574,8 @@ H5_DLL herr_t H5Pset_scaleoffset(hid_t plist_id, H5Z_SO_scale_type_t scale_type, * * \return \herr_t * + * \par_compr_note + * * \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. @@ -9455,9 +9492,6 @@ H5_DLL herr_t H5Pset_mcdt_search_cb(hid_t plist_id, H5O_mcdt_search_cb_t func, v * The #H5P_prp_cb2_t is as follows: * \snippet this H5P_prp_cb2_t_snip * - * - * \cpp_c_api_note - * */ /* Function prototypes */ @@ -9571,8 +9605,7 @@ H5_DLL herr_t H5Pregister1(hid_t cls_id, const char *name, size_t size, void *de * * The #H5P_prp_cb2_t is as follows: * \snippet this H5P_prp_cb2_t_snip - - * \cpp_c_api_note + * */ 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, diff --git a/src/H5Rmodule.h b/src/H5Rmodule.h index 2a34d56..fe28bb2 100644 --- a/src/H5Rmodule.h +++ b/src/H5Rmodule.h @@ -27,9 +27,32 @@ /** * \defgroup H5R H5R - * \brief Reference Interface - * \details The HDF5 Reference Interface, H5R, provides a mechanism for managing - * HDF5 referenced objects. + * + * Use the functions in this module to manage HDF5 references. Referents can + * be HDF5 objects, attributes, and selections on datasets a.k.a. dataset + * regions. + * + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5R_examples.c create + * </td> + * <td> + * \snippet{lineno} H5R_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5R_examples.c update + * </td> + * <td> + * \snippet{lineno} H5R_examples.c delete + * </td> + * </tr> + * </table> + * */ #endif /* H5Rmodule_H */ diff --git a/src/H5Rpublic.h b/src/H5Rpublic.h index b33960e..ef798ea 100644 --- a/src/H5Rpublic.h +++ b/src/H5Rpublic.h @@ -30,9 +30,11 @@ #define H5R_OBJ_REF_BUF_SIZE sizeof(haddr_t) #define H5R_DSET_REG_REF_BUF_SIZE (sizeof(haddr_t) + 4) -/* Default reference buffer size. - * Note! Be careful with the sizes of the references because they should really - * depend on the run-time values in the file. +/** + * Default reference buffer size. + * + * \internal Note! Be careful with the sizes of the references because they + * should really depend on the run-time values in the file. */ #define H5R_REF_BUF_SIZE (64) @@ -560,6 +562,7 @@ H5_DLL ssize_t H5Rget_obj_name(H5R_ref_t *ref_ptr, hid_t rapl_id, char *name, si */ H5_DLL ssize_t H5Rget_attr_name(const H5R_ref_t *ref_ptr, char *name, size_t size); +/// \cond DEV /* API Wrappers for async routines */ /* (Must be defined _after_ the function prototype) */ /* (And must only defined when included in application code, not the library) */ @@ -574,6 +577,7 @@ H5_DLL ssize_t H5Rget_attr_name(const H5R_ref_t *ref_ptr, char *name, size_t siz #define H5Ropen_region_async_wrap H5_NO_EXPAND(H5Ropen_region_async) #define H5Ropen_attr_async_wrap H5_NO_EXPAND(H5Ropen_attr_async) #endif /* H5R_MODULE */ +/// \endcond /* Symbols defined for compatibility with previous versions of the HDF5 API. * diff --git a/src/H5Smodule.h b/src/H5Smodule.h index bb33eb8..010f4a6 100644 --- a/src/H5Smodule.h +++ b/src/H5Smodule.h @@ -30,29 +30,36 @@ #define H5_MY_PKG_INIT YES /**\defgroup H5S H5S - * \brief Dataspace Interface * - * \details The Dataspace Interface provides functions for creating and - * working with dataspaces. + * Use the functions in this module to manage HDF5 dataspaces \Emph{and} selections. * - * A dataspace has two roles: + * HDF5 dataspaces describe the \Emph{shape} of datasets in memory or in HDF5 + * files. Dataspaces can be empty (#H5S_NULL), a singleton (#H5S_SCALAR), or + * a multi-dimensional, regular grid (#H5S_SIMPLE). Dataspaces can be re-shaped. * - * \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. + * Subsets of dataspaces can be "book-marked" or used to restrict I/O operations + * using \Emph{selections}. Furthermore, certain set operations are supported + * for selections. * - * 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. + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5S_examples.c create + * </td> + * <td> + * \snippet{lineno} H5S_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5S_examples.c update + * </td> + * <td> + * \snippet{lineno} H5S_examples.c delete + * </td> + * </tr> + * </table> * */ diff --git a/src/H5Spublic.h b/src/H5Spublic.h index 7962035..30ca813 100644 --- a/src/H5Spublic.h +++ b/src/H5Spublic.h @@ -26,98 +26,101 @@ #define H5S_BLOCK 1 /* (hid_t) */ #define H5S_PLIST 2 /* (hid_t) */ -/* Define value for 'unlimited' dimensions */ -#define H5S_UNLIMITED HSIZE_UNDEF +#define H5S_UNLIMITED HSIZE_UNDEF /**< Value for 'unlimited' dimensions */ -/* Define user-level maximum number of dimensions */ +/** + * The maximum dataspace rank or number of dimensions + */ #define H5S_MAX_RANK 32 /* Flags for selection iterators */ #define H5S_SEL_ITER_GET_SEQ_LIST_SORTED \ - 0x0001 /* Retrieve elements from iterator \ - * in increasing offset order, for \ - * each call to retrieve sequences. \ - * Currently, this only applies to \ - * point selections, as hyperslab \ - * selections are always returned \ - * in increasing offset order. \ - * \ - * Note that the order is only \ - * increasing for each call to \ - * get_seq_list, the next set of \ - * sequences could start with an \ - * earlier offset than the previous \ - * one. \ + 0x0001 /**< Retrieve elements from iterator in increasing offset order, for \ + * each call to retrieve sequences. Currently, this only applies to \ + * point selections, as hyperslab selections are always returned in \ + * increasing offset order. Note that the order is only increasing \ + * for each call to H5Sget_seq_list(), the next set of sequences \ + * could start with an earlier offset than the previous one. \ */ #define H5S_SEL_ITER_SHARE_WITH_DATASPACE \ - 0x0002 /* Don't copy the dataspace \ - * selection when creating the \ - * selection iterator. \ - * \ - * This can improve performance \ - * of creating the iterator, but \ - * the dataspace _MUST_NOT_ be \ - * modified or closed until the \ - * selection iterator is closed \ - * or the iterator's behavior \ - * will be undefined. \ + 0x0002 /**< Don't copy the dataspace selection when creating the selection \ + * iterator. This can improve performance of creating the iterator, \ + * but the dataspace \Bold{MUST NOT} be modified or closed until the \ + * selection iterator is closed or the iterator's behavior will be \ + * undefined. \ */ -/* Different types of dataspaces */ +/** + * Types of dataspaces + */ typedef enum H5S_class_t { - H5S_NO_CLASS = -1, /*error */ - H5S_SCALAR = 0, /*scalar variable */ - H5S_SIMPLE = 1, /*simple dataspace */ - H5S_NULL = 2 /*null dataspace */ + H5S_NO_CLASS = -1, /**< Error */ + H5S_SCALAR = 0, /**< Singleton (scalar) */ + H5S_SIMPLE = 1, /**< Regular grid */ + H5S_NULL = 2 /**< Empty set */ } H5S_class_t; -/* Different ways of combining selections */ +/** + * Different ways of combining selections + */ typedef enum H5S_seloper_t { - H5S_SELECT_NOOP = -1, /* error */ - H5S_SELECT_SET = 0, /* Select "set" operation */ - H5S_SELECT_OR, /* Binary "or" operation for hyperslabs + H5S_SELECT_NOOP = -1, /**< Error */ + H5S_SELECT_SET = 0, /**< Select "set" operation */ + H5S_SELECT_OR, /**< Binary "or" operation for hyperslabs * (add new selection to existing selection) + * \code * Original region: AAAAAAAAAA * New region: BBBBBBBBBB * A or B: CCCCCCCCCCCCCCCC + * \endcode */ - H5S_SELECT_AND, /* Binary "and" operation for hyperslabs + H5S_SELECT_AND, /**< Binary "and" operation for hyperslabs * (only leave overlapped regions in selection) + * \code * Original region: AAAAAAAAAA * New region: BBBBBBBBBB * A and B: CCCC + * \endcode */ - H5S_SELECT_XOR, /* Binary "xor" operation for hyperslabs + H5S_SELECT_XOR, /**< Binary "xor" operation for hyperslabs * (only leave non-overlapped regions in selection) + * \code * Original region: AAAAAAAAAA * New region: BBBBBBBBBB * A xor B: CCCCCC CCCCCC + * \endcode */ - H5S_SELECT_NOTB, /* Binary "not" operation for hyperslabs + H5S_SELECT_NOTB, /**< Binary "not" operation for hyperslabs * (only leave non-overlapped regions in original selection) + * \code * Original region: AAAAAAAAAA * New region: BBBBBBBBBB * A not B: CCCCCC + * \endcode */ - H5S_SELECT_NOTA, /* Binary "not" operation for hyperslabs + H5S_SELECT_NOTA, /**< Binary "not" operation for hyperslabs * (only leave non-overlapped regions in new selection) + * \code * Original region: AAAAAAAAAA * New region: BBBBBBBBBB * B not A: CCCCCC + * \endcode */ - H5S_SELECT_APPEND, /* Append elements to end of point selection */ - H5S_SELECT_PREPEND, /* Prepend elements to beginning of point selection */ - H5S_SELECT_INVALID /* Invalid upper bound on selection operations */ + H5S_SELECT_APPEND, /**< Append elements to end of point selection */ + H5S_SELECT_PREPEND, /**< Prepend elements to beginning of point selection */ + H5S_SELECT_INVALID /**< Invalid upper bound on selection operations */ } H5S_seloper_t; -/* Enumerated type for the type of selection */ +/** + * Selection type + */ typedef enum { - H5S_SEL_ERROR = -1, /* Error */ - H5S_SEL_NONE = 0, /* Nothing selected */ - H5S_SEL_POINTS = 1, /* Points / elements selected */ - H5S_SEL_HYPERSLABS = 2, /* Hyperslab selected */ - H5S_SEL_ALL = 3, /* Entire extent selected */ - H5S_SEL_N /*THIS MUST BE LAST */ + H5S_SEL_ERROR = -1, /**< Error */ + H5S_SEL_NONE = 0, /**< Empty selection */ + H5S_SEL_POINTS = 1, /**< Set of points */ + H5S_SEL_HYPERSLABS = 2, /**< Hyperslab */ + H5S_SEL_ALL = 3, /**< Everything */ + H5S_SEL_N /**< Sentinel \internal THIS MUST BE LAST */ } H5S_sel_type; #ifdef __cplusplus @@ -1318,9 +1321,6 @@ H5_DLL herr_t H5Sset_extent_none(hid_t space_id); * \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 @@ -1329,10 +1329,6 @@ H5_DLL herr_t H5Sset_extent_none(hid_t space_id); * 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 * diff --git a/src/H5Tmodule.h b/src/H5Tmodule.h index c489edc..73424fb 100644 --- a/src/H5Tmodule.h +++ b/src/H5Tmodule.h @@ -29,10 +29,38 @@ #define H5_MY_PKG_ERR H5E_DATATYPE #define H5_MY_PKG_INIT YES -/** - * \defgroup H5T H5T - * \brief Datatype Interface - * \todo Describe concisely what the functions in this module are about. +/**\defgroup H5T H5T + * + * Use the functions in this module to manage HDF5 datatypes. + * + * HDF5 datatypes describe the element type of HDF5 datasets and attributes. + * There's a large set of predefined datatypes, but users may find it useful + * to define new datatypes through a process called \Emph{derivation}. + * + * The element type is automatically persisted as part of the HDF5 metadata of + * attributes and datasets. Additionally, datatype definitions can be persisted + * to HDF5 files and linked to groups as HDF5 datatype objects or so-called + * \Emph{committed datatypes}. + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5T_examples.c create + * </td> + * <td> + * \snippet{lineno} H5T_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5T_examples.c update + * </td> + * <td> + * \snippet{lineno} H5T_examples.c delete + * </td> + * </tr> + * </table> * * \defgroup ARRAY Array Datatypes * \ingroup H5T diff --git a/src/H5VLmodule.h b/src/H5VLmodule.h index 009c0e5..8fcb961 100644 --- a/src/H5VLmodule.h +++ b/src/H5VLmodule.h @@ -27,14 +27,12 @@ #define H5_MY_PKG_ERR H5E_VOL #define H5_MY_PKG_INIT YES -/** - * \defgroup H5VL H5VL - * \brief Virtual Object Layer Interface - * \todo Describe concisely what the functions in this module are about. +/**\defgroup H5VL H5VL + * + * \todo Describe the VOL plugin life cycle. * * \defgroup ASYNC Asynchronous Functions * \brief Asynchronous Functions - * \todo Describe concisely what the functions in this module are about. * * \defgroup H5VLDEF Definitions * \ingroup H5VL diff --git a/src/H5Zmodule.h b/src/H5Zmodule.h index 76a2380..9312b72 100644 --- a/src/H5Zmodule.h +++ b/src/H5Zmodule.h @@ -29,57 +29,80 @@ #define H5_MY_PKG_ERR H5E_PLINE #define H5_MY_PKG_INIT YES -/** - * \defgroup H5Z H5Z +/**\defgroup H5Z H5Z * + * Use the functions in this module to manage HDF5 filters. * - * \brief Filter and Compression Interface + * User-defined filters are created by registering a filter descriptor of + * type #H5Z_class_t with the library. * - * \details The functions in this module let you configure filters that process - * data during I/O operation. + * Available filters can be read or examined at runtime. * - * HDF5 supports a filter pipeline that provides the capability for - * standard and customized raw data processing during I/O operations. - * HDF5 is distributed with a small set of standard filters such as - * compression (gzip, SZIP, and a shuffling algorithm) and error - * checking (Fletcher32 checksum). For further flexibility, the - * library allows a user application to extend the pipeline through - * the creation and registration of customized filters. + * It is conceivable that filters are stateful and that that state be + * updated at runtime. * - * The flexibility of the filter pipeline implementation enables the - * definition of additional filters by a user application. A filter - * \li is associated with a dataset when the dataset is created, - * \li can be used only with chunked data (i.e., datasets stored in - * the #H5D_CHUNKED storage layout), and - * \li is applied independently to each chunk of the dataset. + * Filters are deleted by unregistering. * - * The HDF5 library does not support filters for contiguous datasets - * because of the difficulty of implementing random access for partial - * I/O. Compact dataset filters are not supported because it would not - * produce significant results. + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5Z_examples.c filter + * \snippet{lineno} H5Z_examples.c create + * </td> + * <td> + * \snippet{lineno} H5Z_examples.c read + * </td> + * </tr> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5Z_examples.c update + * </td> + * <td> + * \snippet{lineno} H5Z_examples.c delete + * </tr> + * </table> * - * Filter identifiers for the filters distributed with the HDF5 - * Library are as follows: - * <table> - * <tr><td>#H5Z_FILTER_DEFLATE</td><td>The gzip compression, or - * deflation, filter</td></tr> - * <tr><td>#H5Z_FILTER_SZIP</td><td>The SZIP compression - * filter</td></tr> - * <tr><td>#H5Z_FILTER_NBIT</td><td>The N-bit compression - * filter</td></tr> - * <tr><td>#H5Z_FILTER_SCALEOFFSET</td><td>The scale-offset - * compression filter</td></tr> - * <tr><td>#H5Z_FILTER_SHUFFLE</td><td>The shuffle algorithm - * filter</td></tr> - * <tr><td>#H5Z_FILTER_FLETCHER32</td><td>The Fletcher32 checksum, - * or error checking, filter</td></tr> - * </table> - * Custom filters that have been registered with the library will have - * additional unique identifiers. + * HDF5 supports a filter pipeline that provides the capability for standard and + * customized raw data processing during I/O operations. HDF5 is distributed + * with a small set of standard filters such as compression (gzip, SZIP, and a + * shuffling algorithm) and error checking (Fletcher32 checksum). For further + * flexibility, the library allows a user application to extend the pipeline + * through the creation and registration of customized filters. * - * See \ref_dld_filters for more information on how an HDF5 - * application can apply a filter that is not registered with the HDF5 - * library. + * The flexibility of the filter pipeline implementation enables the definition + * of additional filters by a user application. A filter + * \li is associated with a dataset when the dataset is created, + * \li can be used only with chunked data (i.e., datasets stored in the + * #H5D_CHUNKED storage layout), and + * \li is applied independently to each chunk of the dataset. + * + * The HDF5 library does not support filters for contiguous datasets because of + * the difficulty of implementing random access for partial I/O. Compact dataset + * filters are not supported because it would not produce significant results. + * + * Filter identifiers for the filters distributed with the HDF5 + * Library are as follows: + * <table> + * <tr><td>#H5Z_FILTER_DEFLATE</td><td>The gzip compression, or + * deflation, filter</td></tr> + * <tr><td>#H5Z_FILTER_SZIP</td><td>The SZIP compression + * filter</td></tr> + * <tr><td>#H5Z_FILTER_NBIT</td><td>The N-bit compression + * filter</td></tr> + * <tr><td>#H5Z_FILTER_SCALEOFFSET</td><td>The scale-offset + * compression filter</td></tr> + * <tr><td>#H5Z_FILTER_SHUFFLE</td><td>The shuffle algorithm + * filter</td></tr> + * <tr><td>#H5Z_FILTER_FLETCHER32</td><td>The Fletcher32 checksum, + * or error checking, filter</td></tr> + * </table> + * Custom filters that have been registered with the library will have + * additional unique identifiers. + * + * See \ref_dld_filters for more information on how an HDF5 application can + * apply a filter that is not registered with the HDF5 library. * * \defgroup H5ZPRE Predefined Filters * \ingroup H5Z diff --git a/src/H5module.h b/src/H5module.h index 64081bf..6d3cba8 100644 --- a/src/H5module.h +++ b/src/H5module.h @@ -27,8 +27,31 @@ #define H5_MY_PKG_INIT YES /**\defgroup H5 H5 - * \brief General Library Functions - * \todo Describe concisely what the functions in this module are about. + * + * Use the functions in this module to manage the life cycle of HDF5 library + * instances. + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5_examples.c create + * </td> + * <td> + * \snippet{lineno} H5_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5_examples.c update + * </td> + * <td> + * \snippet{lineno} H5_examples.c closing_shop + * \snippet{lineno} H5_examples.c delete + * </td> + * </tr> + * </table> + * */ #endif /* H5module_H */ diff --git a/src/H5public.h b/src/H5public.h index e7ed518..65709c6 100644 --- a/src/H5public.h +++ b/src/H5public.h @@ -172,8 +172,9 @@ * Status return values. Failed integer functions in HDF5 result almost * always in a negative value (unsigned failing functions sometimes return * zero for failure) while successful return is non-negative (often zero). - * The negative failure value is most commonly -1, but don't bet on it. The - * proper way to detect failure is something like: + * The negative failure value is most commonly -1, but don't bet on it. + * + * The proper way to detect failure is something like: * \code * if((dset = H5Dopen2(file, name)) < 0) * fprintf(stderr, "unable to open the requested dataset\n"); @@ -182,11 +183,17 @@ typedef int herr_t; /** - * Boolean type. Successful return values are zero (false) or positive - * (true). The typical true value is 1 but don't bet on it. Boolean - * functions cannot fail. Functions that return #htri_t however return zero - * (false), positive (true), or negative (failure). The proper way to test - * for truth from a #htri_t function is: + * C99-style Boolean type. Successful return values are zero (false) or positive + * (true). The typical true value is 1 but don't bet on it. + * \attention Boolean functions cannot fail. + */ +#include <stdbool.h> +typedef bool hbool_t; +/** + * Three-valued Boolean type. Functions that return #htri_t however return zero + * (false), positive (true), or negative (failure). + * + * The proper way to test for truth from a #htri_t function is: * \code * if ((retval = H5Tcommitted(type)) > 0) { * printf("data type is committed\n"); @@ -197,8 +204,7 @@ typedef int herr_t; * } * \endcode */ -typedef bool hbool_t; -typedef int htri_t; +typedef int htri_t; /* The signed version of size_t * @@ -285,9 +291,9 @@ typedef enum { /* (Actually, any positive value will cause the iterator to stop and pass back * that positive value to the function that called the iterator) */ -#define H5_ITER_ERROR (-1) -#define H5_ITER_CONT (0) -#define H5_ITER_STOP (1) +#define H5_ITER_ERROR (-1) /**< Error, stop iteration */ +#define H5_ITER_CONT (0) /**< Continue iteration */ +#define H5_ITER_STOP (1) /**< Stop iteration, short-circuit success */ //! <!-- [H5_index_t_snip] --> /** |