diff options
Diffstat (limited to 'src/H5Opublic.h')
| -rw-r--r-- | src/H5Opublic.h | 2496 |
1 files changed, 2496 insertions, 0 deletions
diff --git a/src/H5Opublic.h b/src/H5Opublic.h index 2d2abdf..340f8d7 100644 --- a/src/H5Opublic.h +++ b/src/H5Opublic.h @@ -90,10 +90,14 @@ * Theses flags determine which fields will be filled in in the H5O_native_info_t * struct. */ +//! [H5O_native_info_fields_snip] + #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] + /* Convenience macro to check if the token is the 'undefined' token value */ #define H5O_IS_TOKEN_UNDEF(token) (!HDmemcmp(&(token), &(H5O_TOKEN_UNDEF), sizeof(H5O_token_t))) @@ -101,6 +105,8 @@ /* Public Typedefs */ /*******************/ +//! [H5O_type_t_snip] + /* Types of objects in file */ typedef enum H5O_type_t { H5O_TYPE_UNKNOWN = -1, /* Unknown object type */ @@ -111,7 +117,11 @@ typedef enum H5O_type_t { H5O_TYPE_NTYPES /* Number of different object types (must be last!) */ } H5O_type_t; +//! [H5O_type_t_snip] + /* Information struct for object header metadata (for H5Oget_info/H5Oget_info_by_name/H5Oget_info_by_idx) */ +//! [H5O_hdr_info_t_snip] + typedef struct H5O_hdr_info_t { unsigned version; /* Version number of header format in file */ unsigned nmesgs; /* Number of object header messages */ @@ -129,6 +139,10 @@ typedef struct H5O_hdr_info_t { } mesg; } H5O_hdr_info_t; +//! [H5O_hdr_info_t_snip] + +//! [H5O_info2_t_snip] + /* Data model information struct for objects */ /* (For H5Oget_info / H5Oget_info_by_name / H5Oget_info_by_idx version 3) */ typedef struct H5O_info2_t { @@ -143,6 +157,10 @@ typedef struct H5O_info2_t { hsize_t num_attrs; /* # of attributes attached to object */ } H5O_info2_t; +//! [H5O_info2_t_snip] + +//! [H5O_native_info_t_snip] + /* Native file format information struct for objects */ /* (For H5Oget_native_info / H5Oget_native_info_by_name / H5Oget_native_info_by_idx) */ typedef struct H5O_native_info_t { @@ -154,12 +172,18 @@ typedef struct H5O_native_info_t { } meta_size; } H5O_native_info_t; +//! [H5O_native_info_t_snip] + /* Typedef for message creation indexes */ typedef uint32_t H5O_msg_crt_idx_t; /* Prototype for H5Ovisit/H5Ovisit_by_name() operator (version 3) */ +//! [H5O_iterate2_t_snip] + typedef herr_t (*H5O_iterate2_t)(hid_t obj, const char *name, const H5O_info2_t *info, void *op_data); +//! [H5O_iterate2_t_snip] + typedef enum H5O_mcdt_search_ret_t { H5O_MCDT_SEARCH_ERROR = -1, /* Abort H5Ocopy */ H5O_MCDT_SEARCH_CONT, /* Continue the global search of all committed datatypes in the destination file */ @@ -182,64 +206,1621 @@ typedef H5O_mcdt_search_ret_t (*H5O_mcdt_search_cb_t)(void *op_data); extern "C" { #endif +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Opens an object in an HDF5 file by location identifier and path name. + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] name Path to the object; relative to \p loc_id + * \lapl_id + * + * \return \hid_tv{object} + * + * \details H5Oopen() opens a group, dataset, or committed (named) datatype + * specified by a location, \p loc_id, and a path name, \p name, in an HDF5 file. + * + * This function opens the object in the same manner as H5Gopen(), H5Topen(), and H5Dopen(). + * However, H5Oopen() does not require the type of object to be known beforehand. + * This can be useful with user-defined links, for instance, when only a path may be known. + * + * H5Oopen() cannot be used to open a dataspace, attribute, property list, or file. + * + * Once an object of unknown type has been opened with H5Oopen(), + * the type of that object can be determined by means of an H5Iget_type() call. + * + * \p loc_id may be a file, group, dataset, named datatype, or attribute. + * If an attribute is specified for \p loc_id then the object where the + * attribute is attached will be accessed. + * + * \p name must be the path to that object relative to \p loc_id. + * + * \p lapl_id is the link access property list associated with the link pointing to + * the object. If default link access properties are appropriate, this can be + * passed in as #H5P_DEFAULT. + * + * When it is no longer needed, the opened object should be closed with + * H5Oclose(), H5Gclose(), H5Tclose(), or H5Dclose(). + * + * \version 1.8.1 Fortran subroutine introduced in this release. + * + * \since 1.8.0 + * + */ H5_DLL hid_t H5Oopen(hid_t loc_id, const char *name, hid_t lapl_id); H5_DLL hid_t H5Oopen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *name, hid_t lapl_id, hid_t es_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Opens an object in an HDF5 file using its VOL independent token + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] token Object token + * + * \return \hid_ti{object} + * + * \details H5Oopen_by_token() opens an object specified by the object + * identifier, \p loc_id and object token, \p token. + * + * \par Example + * An example snippet from examples/h5_extlink.c: + * \snippet h5_extlink.c H5Open_by_token_snip + * + * \since 1.12.0 + * + */ H5_DLL hid_t H5Oopen_by_token(hid_t loc_id, H5O_token_t token); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Opens the nth object in a group + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] group_name Name of group, relative to \p loc_id, in which object is located + * \idx_type + * \order + * \param[in] n Object to open + * \lapl_id + * + * \return \hid_tv{object} + * + * \details H5Open_by_idx() opens the nth object in the group specified by \p loc_id + * and \p group_name. + * + * \p loc_id specifies a location identifier. \p group_name specifies the group relative to + * \p loc_id in which the object can be found. If \p loc_id fully specifies the group + * in which the object resides, \p group_name can be a dot (.). + * + * The specific object to be opened within the group is specified by the three parameters: + * \p idx_type, \p order and \p n. + * + * \p idx_type specifies the type of index by which objects are ordered. + * Valid index types include the following: + * + * \indexes + * + * \p order specifies the order in which the objects are to be referenced for the purposes + * of this function. Valid orders include the following: + * + * \orders + * + * Note that for #H5_ITER_NATIVE, rather than implying a particular order, + * it instructs the HDF5 library to iterate through the objects in the fastest + * available order, i.e., in a natural order. + * + * \p n specifies the position of the object within the index. Note that this count is + * zero-based; 0 (zero) indicates that the function will return the value of the first object; + * if \p n is 5, the function will return the value of the sixth object; etc. + * + * \p lapl_id specifies the link access property list to be used in accessing the object. + * + * An object opened with this function should be closed when it is no longer needed so that + * resource leaks will not develop. H5Oclose() can be used to close groups, datasets, + * or committed datatypes. + * + * \version 1.8.1 Fortran subroutine introduced in this release. + * + * \since 1.8.0 + * + */ H5_DLL hid_t H5Oopen_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t lapl_id); H5_DLL hid_t H5Oopen_by_idx_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t lapl_id, hid_t es_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Determines whether a link resolves to an actual object. + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] name The name of the link to check + * \lapl_id + * + * \return Returns a positive value if the object pointed to by the \p loc_id and \p name combination exists. + * \return Returns 0 if the object pointed to by the \p loc_id and \p name combination does not exist. + * \return Returns a negatvie value when the function fails. + * + * \details H5Oexists_by_name() allows an application to determine whether + * the link \p name in the group or file specified with \p loc_id + * resolves to an HDF5 object to open or if the link dangles. The + * link may be of any type, but hard links will always resolve + * to objects and do not need to be verified. + * + * Note that H5Oexists_by_name() verifies only that the target + * object exists. If \p name includes either a relative path or + * an absolute path to the target link, intermediate steps + * along the path must be verified before the existence of + * the target link can be safely checked. If the path is not + * verified and an intermediate element of the path does not + * exist, H5Oexists_by_name() will fail. The example in the next + * paragraph illustrates one step-by-step method for verifying + * the existence of a link with a relative or absolute path. + * + * \par Example + * Use the following steps to verify the existence of + * the link \c datasetD in the \c group group1/group2/softlink_to_group3/, + * where \c group1 is a member of the group specified by \c loc_id: + * + * \par + * - First use H5Lexists() to verify that a link named \c group1 exists. + * - If \c group1 exists, use H5Oexists_by_name() to verify that the + * link \c group1 resolves to an object. + * - If \c group1 exists, use H5Lexists() again, this time with name + * set to \c group1/group2, to verify that the link \c group2 exists + * in \c group1. + * - If the \c group2 link exists, use H5Oexists_by_name() to verify + * that \c group1/group2 resolves to an object. + * - If \c group2 exists, use H5Lexists() again, this time with name + * set to \c group1/group2/softlink_to_group3, to verify that the + * link \c softlink_to_group3 exists in \c group2. + * - If the \c softlink_to_group3 link exists, use H5Oexists_by_name() + * to verify that \c group1/group2/softlink_to_group3 resolves to + * an object. + * - If \c softlink_to_group3 exists, you can now safely use H5Lexists + * with name set to \c group1/group2/softlink_to_group3/datasetD to + * verify that the target link, \c datasetD, exists. + * - And finally, if the link \c datasetD exists, use H5Oexists_by_name + * to verify that \c group1/group2/softlink_to_group3/datasetD + * resolves to an object. + * + * \par + * If the link to be verified is specified with an absolute path, + * the same approach should be used, but starting with the first + * link in the file’s root group. For instance, if \c datasetD + * were in \c /group1/group2/softlink_to_group3, the first call to + * H5Lexists() would have name set to \c /group1. + * + * \par + * Note that this is an outline and does not include all necessary + * details. Depending on circumstances, for example, an application + * may need to verify the type of an object also. + * + * \warning \Bold{Failure Modes:} + * \warning If \p loc_id and \p name both exist but the combination does not + * resolve to an object, the function will return 0 (zero); + * the function does not fail in this case. + * \warning If either the location or the link specified by the \p loc_id + * and \p name combination does not exist, the function will fail, + * returning a negative value. + * \warning Note that verifying the existence of an object within an HDF5 + * file is a multistep process. An application can be certain the + * object does not exist only if H5Lexists() and H5Oexists_by_name() + * have been used to verify the existence of the links and groups + * in the hierarchy above that object. The example above, in the + * function description, provides a step-by-step description of + * that verification process. + * + * \version 1.8.11 Fortran subroutine introduced in this release. + * + * \since 1.8.5 + * + */ H5_DLL htri_t H5Oexists_by_name(hid_t loc_id, const char *name, hid_t lapl_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Retrieves the metadata for an object specified by an identifier + * + * \fgdta_loc_obj_id{loc_id} + * \param[out] oinfo Buffer in which to return object information + * \param[in] fields Flags specifying the fields to include in \p oinfo + * + * \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. + * + * 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: + * + * \obj_info_fields + * + * \par Example + * An example snippet from examples/h5_attribute.c: + * \par + * \snippet h5_attribute.c H5Oget_info3_snip + * + * \note If you are iterating through a lot of different objects to + * retrieve information via the H5Oget_info() family of routines, + * you may see memory building up. This can be due to memory + * allocation for metadata such as object headers and messages + * when the iterated objects are put into the metadata cache. + * \note + * If the memory buildup is not desirable, you can configure a + * smaller cache via H5Fset_mdc_config() or set the file access + * property list via H5Pset_mdc_config(). A smaller sized cache + * will force metadata entries to be evicted from the cache, + * thus freeing the memory associated with the entries. + * + * \since 1.12.0 + * + */ H5_DLL herr_t H5Oget_info3(hid_t loc_id, H5O_info2_t *oinfo, unsigned fields); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Retrieves the metadata for an object, identifying the object by + * location and relative name + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] name Name of group, relative to \p loc_id + * \param[out] oinfo Buffer in which to return object information + * \param[in] fields Flags specifying the fields to include in \p oinfo + * \lapl_id + * + * \return \herr_t + * + * \details H5Oget_info_by_name3() specifies an object’s location and name, + * \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: + * + * \obj_info_fields + * + * The link access property list, \c lapl_id, is not currently used; + * it should be passed in as #H5P_DEFAULT. + * + * \par Example + * An example snippet from test/vol.c: + * \snippet vol.c H5Oget_info_by_name3_snip + * + * \since 1.12.0 + * + */ H5_DLL herr_t H5Oget_info_by_name3(hid_t loc_id, const char *name, H5O_info2_t *oinfo, unsigned fields, hid_t lapl_id); H5_DLL herr_t H5Oget_info_by_name_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *name, H5O_info2_t *oinfo /*out*/, unsigned fields, hid_t lapl_id, hid_t es_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Retrieves the metadata for an object, identifying the object + * by an index position + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] group_name Name of group in which object is located + * \idx_type + * \order + * \param[in] n Position within the index + * \param[out] oinfo Buffer in which to return object information + * \param[in] fields Flags specifying the fields to include in \p oinfo + * \lapl_id + * + * \return \herr_t + * + * \details H5Oget_info_by_idx3() retrieves the metadata describing an + * object in the \c struct \p oinfo, as specified by the location, + * \p loc_id, group name, \p group_name, the index by which objects + * in that 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. + * + * 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: + * \obj_info_fields + * + * The link access property list, \c lapl_id, is not currently used; + * it should be passed in as #H5P_DEFAULT. + * + * \par Example + * An example snippet from test/titerate.c: + * \snippet titerate.c H5Oget_info_by_idx3_snip + * + * \since 1.12.0 + * + */ H5_DLL herr_t H5Oget_info_by_idx3(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5O_info2_t *oinfo, unsigned fields, hid_t lapl_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Retrieve native file format information about an object + * + * \fgdta_loc_obj_id{loc_id} + * \param[out] oinfo Buffer in which to return native object information + * \param[in] fields Flags to determine which fields in \p oinfo are filled in + * + * \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 + * + * The \p fields parameter indicates which fields to fill in + * H5O_native_info_t. Possible values defined in H5Opublic.h are: + * + * \snippet this H5O_native_info_fields_snip + * + * \par Example + * An example snippet from test/tfile.c: + * \par + * \snippet tfile.c H5Oget_native_info_snip + * + * \since 1.12.0 + * + */ H5_DLL herr_t H5Oget_native_info(hid_t loc_id, H5O_native_info_t *oinfo, unsigned fields); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Retrieve native file format information about an object given its name + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] name Name of object + * \param[out] oinfo Buffer in which to return native object information + * \param[in] fields Flags to determine which fields in \p oinfo are filled in + * \lapl_id + * + * \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 + * + * The \p fields parameter which fields to fill in H5O_native_info_t. + * Possible values defined in H5Opublic.h are: + * + * \snippet this H5O_native_info_fields_snip + * + * \par Example + * An example snippet from test/tfile.c: + * \snippet tfile.c H5Oget_native_info_by_name_snip + * + * \since 1.12.0 + * + */ H5_DLL herr_t H5Oget_native_info_by_name(hid_t loc_id, const char *name, H5O_native_info_t *oinfo, unsigned fields, hid_t lapl_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Retrieve native file format information about an object + * according to the order of an index + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] group_name Name of group in which object is located + * \idx_type + * \order + * \param[in] n Position within the index + * \param[out] oinfo Buffer in which to return native object information + * \param[in] fields Flags to determine which fields in \p oinfo are filled in + * \lapl_id + * + * \return \herr_t + * + * \details H5Oget_native_info_by_idx() retrieves the native file format information for an object + * 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 + * + * The \p fields parameter indicates which fields to fill in H5O_native_info_t. + * Possible values defined in H5Opublic.h are: + * \snippet this H5O_native_info_fields_snip + * + * The link access property list, \c lapl_id, is not currently used; + * it should be passed in as #H5P_DEFAULT. + * + * \since 1.12.0 + * + */ H5_DLL herr_t H5Oget_native_info_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5O_native_info_t *oinfo, unsigned fields, hid_t lapl_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Creates a hard link to an object in an HDF5 file + * + * \param[in] obj_id Object to be linked + * \param[in] new_loc_id Location identifier at which object is to be linked; + * may be a file, group, dataset, named datatype or attribute identifier. + * \param[in] new_name Name of link to be created, relative to \p new_loc_id. + * \lcpl_id + * \lapl_id + * + * \return \herr_t + * + * \details H5Olink() creates a new hard link to an object in an HDF5 file. + * \p new_loc_id and \p \p new_link_name specify the location and name of the + * new link while \p object_id identifies the object that the link + * points to. + * + * H5Olink() is designed for two purposes: + * - To create the first hard link to an object that has just + * been created with H5Dcreate_anon(), H5Gcreate_anon(), or + * H5Tcommit_anon(). + * - To add additional structure to an existing + * file so that, for example, an object can be shared among + * multiple groups. + * + * \p lcpl and \p lapl are the link creation and access property lists + * associated with the new link. + * + * \par Example: + * To create a new link to an object while simultaneously creating + * missing intermediate groups: Suppose that an application must + * create the group C with the path /A/B01/C but may not know + * at run time whether the groups A and B01 exist. The following + * code ensures that those groups are created if they are missing: + * \par + * \code + * + * // Creates a link creation property list (LCPL). + * hid_t lcpl_id = H5Pcreate(H5P_LINK_CREATE); + * + * // Sets "create missing intermediate groups" property in that LCPL. + * int status = H5Pset_create_intermediate_group(lcpl_id, TRUE); + * + * // Creates a group without linking it into the file structure. + * hid_t gid = H5Gcreate_anon(file_id, H5P_DEFAULT, H5P_DEFAULT); + * + * // Links group into file structure. + * status = H5Olink(gid, file_id, "/A/B01/C", lcpl_id, H5P_DEFAULT); + * + * \endcode + * + * \par + * Note that unless the object is intended to be temporary, + * the H5O_LINK call is mandatory if an object created with one + * of the H5*_CREATE_ANON functions (or with H5T_COMMIT_ANON) + * is to be retained in the file; without an H5O_LINK call, + * the object will not be linked into the HDF5 file structure + * and will be deleted when the file is closed. + * + * \version 1.8.1 Fortran subroutine introduced in this release. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Olink(hid_t obj_id, hid_t new_loc_id, const char *new_name, hid_t lcpl_id, hid_t lapl_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Increments an object reference count + * + * \fgdta_loc_obj_id{object_id} + * + * \return \herr_t + * + * \details H5Oincr_refcount() increments the hard link reference count for an object. + * It should be used any time a user-defined link that references + * an object by address is added. When the link is deleted, + * H5Odecr_refcount() should be used. + * + * An object’s reference count is the number of hard links in the + * file that point to that object. See the “Programming Model” + * section of the HDF5 Groups chapter in the -- <em>HDF5 User’s Guide</em> + * for a more complete discussion of reference counts. + * + * If a user application needs to determine an object’s reference + * count, an H5Oget_info() call is required; the reference count + * is returned in the \c rc field of the #H5O_info_t \c struct. + * + * \warning This function must be used with care! + * \warning Improper use can lead to inaccessible data, wasted space in the file, + * or <b><em>file corruption</em></b>. + * + * \version 1.8.11 Fortran subroutine introduced in this release. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Oincr_refcount(hid_t object_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Decrements an object reference count + * + * \fgdta_loc_obj_id{object_id} + * + * \return \herr_t + * + * \details H5Odecr_refcount() decrements the hard link reference count for an object. + * It should be used any time a user-defined link that references + * an object by address is deleted. In general, H5Oincr_refcount() will have + * been used previously, when the link was created. + * + * An object’s reference count is the number of hard links in the + * file that point to that object. See the “Programming Model” + * section of the HDF5 Groups chapter in the <em>HDF5 User’s Guide</em> + * for a more complete discussion of reference counts. + * + * If a user application needs to determine an object’s reference + * count, an H5Oget_info() call is required; the reference count + * is returned in the \c rc field of the #H5O_info_t \c struct. + * + * \warning This function must be used with care! + * \warning Improper use can lead to inaccessible data, wasted space in the file, + * or <b><em>file corruption</em></b>. + * + * \version 1.8.11 Fortran subroutine introduced in this release. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Odecr_refcount(hid_t object_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Copies an object in an HDF5 file + * + * \param[in] src_loc_id Object identifier indicating the location of the + * source object to be copied + * \param[in] src_name Name of the source object to be copied + * \param[in] dst_loc_id Location identifier specifying the destination + * \param[in] dst_name Name to be assigned to the new copy + * \param[in] ocpypl_id Object copy property list + * \lcpl_id + * + * \return \herr_t + * + * \details H5Ocopy() copies the group, dataset or committed datatype + * specified by \p src_name from the file or group specified by + * \p src_loc_id to the destination location \p dst_loc_id. + * + * The destination location, as specified in dst_loc_id, may + * be a group in the current file or a location in a different + * file. If dst_loc_id is a file identifier, the copy will be + * placed in that file’s root group. + * + * The copy will be created with the path specified in \p dst_name, + * which must not pre-exist in the destination location. If + * \p dst_name already exists at the location \p dst_loc_id, + * H5Ocopy() will fail. If \p dst_name is an absolute path, + * the copy will be created relative to the file’s root group. + * + * The copy of the object is created with the property lists + * specified by \p ocpypl_id and \p lcpl_id. #H5P_DEFAULT can be passed + * in for these property lists. The default behavior: + * + * - of the link creation property list is to NOT create + * intermediate groups. + * - of the flags specified by the object creation property list + * is described in H5Pset_copy_object(). + * + * These property lists or flags can be modified to govern the + * behavior of H5Ocopy() as follows: + * + * - A flag controlling the creation of intermediate groups that + * may not yet exist is set in the link creation property list + * \p lcpl_id with H5Pset_create_intermediate_group(). + * + * - Copying of committed datatypes can be tuned through the use + * of H5Pset_copy_object(), H5Padd_merge_committed_dtype_path(), + * H5Pset_mcdt_search_cb(), and related functions. + * + * - Flags controlling other aspects of object copying are set in the + * object copy property list \p ocpypl_id with H5Pset_copy_object(). + * + * H5Ocopy() will always try to make a copy of the object specified + * in \p src_name. + * + * - If the object specified by \p src_name is a group containing a + * soft or external link, the default is that the new copy will + * contain a soft or external link with the same value as the + * original. See H5Pset_copy_object() for optional settings. + * + * - If the path specified in \p src_name is or contains a soft link + * or an external link, H5Ocopy() will copy the target object. + * Use H5Lcopy() if the intent is to create a new soft or external + * link with the same value as the original link. + * + * H5Ocopy() can be used to copy an object in an HDF5 file. If + * an object has been changed since it was opened, it should be + * written back to the file before using H5Ocopy(). The object + * can be written back either by closing the object (H5Gclose(), + * H5Oclose(), H5Dclose(), or H5Tclose()) or by flushing + * the HDF5 file (H5Fflush()). + * + * \par See Also: + * - Functions to modify the behavior of H5Ocopy(): + * - H5Padd_merge_committed_dtype_path() + * - H5Pset_copy_object() + * - H5Pset_create_intermediate_group() + * - H5Pset_mcdt_search_cb() + * . + * - Copying Committed Datatypes with #H5Ocopy - A comprehensive + * discussion of copying committed datatypes (PDF) in + * Advanced Topics in HDF5 + * + * \version 1.8.9 Fortran subroutine introduced in this release. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Ocopy(hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, const char *dst_name, hid_t ocpypl_id, hid_t lcpl_id); H5_DLL herr_t H5Ocopy_async(const char *app_file, const char *app_func, unsigned app_line, hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, const char *dst_name, hid_t ocpypl_id, hid_t lcpl_id, hid_t es_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Sets comment for specified object + * + * \fgdta_loc_obj_id{obj_id} + * \param[in] comment The new comment + * + * \return \herr_t + * + * \details H5Oset_comment() sets the comment for the specified object + * to the contents of \p comment. Any previously existing comment + * is overwritten. + * + * The target object is specified by an identifier, \p obj_id. + * If \p comment is the empty string or a null pointer, any existing + * comment message is removed from the object. + * + * Comments should be relatively short, null-terminated, ASCII strings. + * + * Comments can be attached to any object that has an object + * header. Datasets, groups, and committed (named) datatypes have + * object headers. Symbolic links do not have object headers. + * + * If a comment is being added to an object attribute, this comment + * will be attached to the object to which the attribute belongs + * and not to the attribute itself. + * + * \version 1.8.11 Fortran subroutine introduced in this release. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Oset_comment(hid_t obj_id, const char *comment); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Sets comment for specified object + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] name Name of the object whose comment is to be set or reset + * \param[in] comment The new comment + * \lapl_id + * + * \return \herr_t + * + * \details H5Oset_comment_by_name() sets the comment for the specified object + * to the contents of \p comment. Any previously existing comment + * is overwritten. + * + * The target object is specified by \p loc_id and \p name. + * \p loc_id can specify any object in the file. + * \p name can be one of the following: + * + * - The name of the object specified as a path relative to \p loc_id + * - An absolute name of the object, starting from \c /, the file’s root group + * - A dot (\c .), if \p loc_id fully specifies the object + * + * If \p comment is the empty string or a null pointer, any existing + * comment message is removed from the object. + * + * Comments should be relatively short, null-terminated, ASCII strings. + * + * Comments can be attached to any object that has an object + * header. Datasets, groups, and committed (named) datatypes have + * object headers. Symbolic links do not have object headers. + * + * If a comment is being added to an object attribute, this comment + * will be attached to the object to which the attribute belongs + * and not to the attribute itself. + * + * \p lapl_id contains a link access property list identifier. A + * link access property list can come into play when traversing + * links to access an object. + * + * \version 1.8.11 Fortran subroutine introduced in this release. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Oset_comment_by_name(hid_t loc_id, const char *name, const char *comment, hid_t lapl_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Retrieves comment for specified object + * + * \fgdta_loc_obj_id{obj_id} + * \param[out] comment The comment + * \param[in] bufsize Anticipated required size of the comment buffer + * + * \return Upon success, returns the number of characters in the + * comment, not including the \c NULL terminator, or zero (\c 0) if + * the object has no comment. The value returned may be larger + * than \p bufsize. Otherwise returns a negative value. + * + * \details H5Oget_comment() retrieves the comment for the specified object in + * the buffer \p comment. + * + * The target object is specified by an identifier, \p object_id. + * + * The size in bytes of the buffer \p comment, including the \c NULL + * terminator, is specified in \p bufsize. If \p bufsize is unknown, + * a preliminary H5Oget_comment() call with the pointer \p comment + * set to \c NULL will return the size of the comment <em>without</em> + * the \c NULL terminator. + * + * If \p bufsize is set to a smaller value than described above, + * only \p bufsize bytes of the comment, without a \c NULL terminator, + * are returned in \p comment. + * + * If an object does not have a comment, the empty string is + * returned in \p comment. + * + * \version 1.8.11 Fortran subroutine introduced in this release. + * + * \since 1.8.0 + * + */ H5_DLL ssize_t H5Oget_comment(hid_t obj_id, char *comment, size_t bufsize); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Retrieves comment for specified object + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] name Name of the object whose comment is to be retrieved + * \param[out] comment The comment + * \param[in] bufsize Anticipated required size of the \p comment buffer + * \lapl_id + * + * \return Upon success, returns the number of characters in the comment, + * not including the \c NULL terminator, or zero (\c 0) if the object + * has no comment. The value returned may be larger than \c bufsize. + * Otherwise returns a negative value. + * + * \details H5Oget_comment_by_name() retrieves the comment for an object + * in the buffer \p comment. + * + * The target object is specified by \p loc_id and \p name. + * \p loc_id can specify any object in the file. + * \p name can be one of the following: + * + * - The name of the object relative to \p loc_id + * - An absolute name of the object, starting from \c /, the file’s root group + * - A dot (\c .), if \p loc_id fully specifies the object + * + * The size in bytes of the comment, including the \c NULL terminator, + * is specified in \p bufsize. If \p bufsize is unknown, a preliminary + * H5Oget_comment_by_name() call with the pointer \p comment set + * to \c NULL will return the size of the comment <em>without</em> + * the \c NULL terminator. + * + * If \p bufsize is set to a smaller value than described above, + * only \p bufsize bytes of the comment, without a \c NULL terminator, + * are returned in \p comment. + * + * If an object does not have a comment, the empty string is + * returned in \p comment. + * + * \p lapl_id contains a link access property list identifier. A + * link access property list can come into play when traversing + * links to access an object. + * + * \version 1.8.11 Fortran subroutine introduced in this release. + * + * \since 1.8.0 + * + */ H5_DLL ssize_t H5Oget_comment_by_name(hid_t loc_id, const char *name, char *comment, size_t bufsize, hid_t lapl_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Recursively visits all objects accessible from a specified object + * + * \fgdta_loc_obj_id{obj_id} + * \idx_type + * \order + * \param[in] op Callback function passing data regarding the object + * to the calling application + * \param[in] op_data User-defined pointer to data required by the application + * for its processing of the object + * \param[in] fields Flags specifying the fields to be retrieved to the + * callback \p op + * + * \return On success, returns the return value of the first operator + * that returns a positive value, or zero if all members were + * processed with no operator returning non-zero. + * + * \return On failure, returns a negative value if something goes wrong + * within the library, or the first negative value returned by + * an operator. + * + * \details H5Ovisit3() is a recursive iteration function to visit the + * object \p obj_id and, if \p obj_id is a group, all objects in + * and below it in an HDF5 file, thus providing a mechanism for + * an application to perform a common set of operations across + * all of those objects or a dynamically selected subset. + * For non-recursive iteration across the members of a group, + * see H5Literate2(). + * + * If \p obj_id is a group identifier, that group serves as the + * root of a recursive iteration. If \p obj_id is a file identifier, + * that file’s root group serves as the root of the recursive + * iteration. If \p obj_id is an attribute identifier, + * then the object where the attribute is attached will be iterated. + * If \p obj_id is any other type of object, such as a dataset or + * named datatype, there is no iteration. + * + * Two parameters are used to establish the iteration: \p idx_type + * and \p order. + * + * \p idx_type specifies the index to be used. If the links in + * 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 + * + * 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 + * encountered that was not tracked in creation order, that group + * will be iterated over in alpha-numeric order by name, or + * <em>name order</em>. (<em>Name order</em> is the native order + * used by the HDF5 library and is always available.) + * + * \p order specifies the order in which objects are to be inspected + * along the index specified in \p idx_type. Valid values include + * the following: + * + * \orders + * + * The 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. + * + * 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 + * is passed back to each step of the iteration in the callback + * function’s \p op_data parameter. + * + * The \p fields parameter contains flags to determine which fields will + * be retrieved by the \p op callback function. These flags are defined + * in the H5Opublic.h file: + * \obj_info_fields + * + * H5Lvisit2() and H5Ovisit3() are companion functions: one for + * examining and operating on links; the other for examining + * and operating on the objects that those links point to. Both + * functions ensure that by the time the function completes + * successfully, every link or object below the specified point + * in the file has been presented to the application for whatever + * processing the application requires. These functions assume + * that the membership of the group being iterated over remains + * unchanged through the iteration; if any of the links in the + * group change during the iteration, the 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 + * + * \since 1.12.0 + * + */ H5_DLL herr_t H5Ovisit3(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate2_t op, void *op_data, unsigned fields); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Recursively visits all objects accessible from a specified object + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] obj_name Name of the object, generally relative to + * \p loc_id, that will serve as root of the iteration + * \idx_type + * \order + * \param[in] op Callback function passing data regarding the object + * to the calling application + * \param[in] op_data User-defined pointer to data required by the application + * for its processing of the object + * \param[in] fields Flags specifying the fields to be retrieved to the + * callback function \p op + * \lapl_id + * + * \return On success, returns the return value of the first operator + * that returns a positive value, or zero if all members were + * processed with no operator returning non-zero. + * + * \return On failure, returns a negative value if something goes wrong + * within the library, or the first negative value returned by + * an operator. + * + * \details H5Ovisit_by_name3() is a recursive iteration function to visit + * the object specified by the \p loc_id / \p obj_name parameter + * pair and, if that object is a group, all objects in and below it + * in an HDF5 file, thus providing a mechanism for an application to + * perform a common set of operations across all of those objects or + * a dynamically selected subset. For non-recursive iteration across + * the members of a group, see H5Literate2(). + * + * The object serving as the root of the iteration is specified + * by the \p loc_id / \p obj_name parameter pair. \p loc_id specifies + * a file or an object in a file; if \p loc_id is an attribute identifier, + * the object where the attribute is attached will be used. + * \p obj_name specifies either an object in the file (with an absolute + * name based in the file’s root group) or an object name relative + * to \p loc_id. If \p loc_id fully specifies the object that is to serve + * as the root of the iteration, \p obj_name should be '\c .' (a dot). + * (Note that when \p loc_id fully specifies the object that is to serve + * as the root of the iteration, the user may wish to consider + * using H5Ovisit3() instead of H5Ovisit_by_name3().) + * + * Two parameters are used to establish the iteration: \p idx_type + * and \p order. + * + * \p idx_type specifies the index to be used. If the links in + * 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 + * + * 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 + * encountered that was not tracked in creation order, that group + * will be iterated over in alpha-numeric order by name, or + * <em>name order</em>. (<em>Name order</em> is the native order + * used by the HDF5 library and is always available.) + * + * \p order specifies the order in which objects are to be inspected + * along the index specified in \p idx_type. Valid values include + * the following: + * + * \orders + * + * The 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 + * + * The H5Ovisit_by_name3() \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. + * + * \p lapl_id is a link access property list. In the general case, + * when default link access properties are acceptable, this can + * be passed in as #H5P_DEFAULT. An example of a situation that + * requires a non-default link access property list is when + * the link is an external link; an external link may require + * that a link prefix be set in a link access property list + * (see H5Pset_elink_prefix()). + * + * The \p fields parameter contains flags to determine which fields will + * be retrieved by the \p op callback function. These flags are defined + * in the H5Opublic.h file: + * \obj_info_fields + * + * H5Lvisit_by_name2() and H5Ovisit_by_name3() are companion + * functions: one for examining and operating on links; the other + * for examining and operating on the objects that those links point to. + * Both functions ensure that by the time the function completes + * successfully, every link or object below the specified point + * in the file has been presented to the application for whatever + * processing the application requires. + * + * \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 + * + * \since 1.12.0 + * + */ H5_DLL herr_t H5Ovisit_by_name3(hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate2_t op, void *op_data, unsigned fields, hid_t lapl_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Closes an object in an HDF5 file + * + * \obj_id{object_id} + * + * \return \herr_t + * + * \details H5Oclose() closes the group, dataset, or named datatype specified by + * object_id. + * + * This function is the companion to H5Oopen(), and has the same + * effect as calling H5Gclose(), H5Dclose(), or H5Tclose(). + * + * H5Oclose() is not used to close a dataspace, attribute, property + * list, or file. + * + * \version 1.8.8 Fortran subroutine introduced in this release. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Oclose(hid_t object_id); H5_DLL herr_t H5Oclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t object_id, hid_t es_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Flushes all buffers associated with an HDF5 object to disk + * + * \fgdta_loc_obj_id{obj_id} + * + * \return \herr_t + * + * \details H5Oflush() causes all buffers associated with an object to be immediately + * flushed to disk without removing the data from the cache. + * + * The object associated with \p object_id can be any named object in an + * HDF5 file including a dataset, a group, or a committed datatype. + * + * \note HDF5 does not possess full control over buffering. H5Oflush() + * flushes the internal HDF5 buffers and then asks the operating + * system (the OS) to flush the system buffers for the open + * files. After that, the OS is responsible for ensuring that + * the data is actually flushed to disk. + * + * \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() + * + * \since 1.10.0 + * + */ H5_DLL herr_t H5Oflush(hid_t obj_id); H5_DLL herr_t H5Oflush_async(const char *app_file, const char *app_func, unsigned app_line, hid_t obj_id, hid_t es_id); +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Refreshes all buffers associated with an HDF5 object + * + * \fgdta_loc_obj_id{oid} + * + * \return \herr_t + * + * \details H5Orefresh() causes all buffers associated with an object to be cleared + * and immediately re-loaded with updated contents from disk. + * + * This function essentially closes the object, evicts all + * metadata associated with it from the cache, and then re-opens + * the object. The reopened object is automatically re-registered + * with the same identifier. + * + * The object associated with \p oid can be any named object in an + * HDF5 file including a dataset, a group, or a committed datatype. + * + * \since 1.10.0 + * + */ H5_DLL herr_t H5Orefresh(hid_t oid); H5_DLL herr_t H5Orefresh_async(const char *app_file, const char *app_func, unsigned app_line, hid_t oid, hid_t es_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Prevents metadata entries for an HDF5 object from being flushed + * from the metadata cache to storage + * + * \param[in] object_id Identifier of the object that will have flushes disabled; + * may be a group, named datatype, or dataset identifier + * + * \return \herr_t + * + * \details H5Odisable_mdc_flushes(), H5Oenable_mdc_flushes() and associated flush + * functions can be used to control the flushing of entries from + * a file’s metadata cache. + * + * This function prevents an object’s or cache’s dirty metadata + * entries from being flushed from the cache by the usual cache + * eviction/flush policy. Instead, users must manually flush the + * cache or entries for individual objects via the appropriate + * H5Fflush(), H5Dflush(), H5Gflush(), H5Tflush(), and H5Oflush() calls. + * + * Metadata cache entries can be controlled at both the individual + * 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. + * + * \since 1.10.0 + * + */ H5_DLL herr_t H5Odisable_mdc_flushes(hid_t object_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Enables flushing of dirty metadata entries from a file’s metadata cache + * + * \param[in] object_id Identifier of the object that will have flushes re-enabled; + * may be a group, named datatype, or dataset identifier + * + * \return \herr_t + * + * \details H5Oenable_mdc_flushes(), H5Odisable_mdc_flushes() + * and associated flush functions can be used to control the flushing + * of entries from a file’s metadata cache. + * + * This function allows an object or cache’s dirty metadata entries to be + * flushed from the cache by the usual cache eviction/flush policy. + * + * Metadata cache entries can be controlled at both the individual 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 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. + * + * \since 1.10.0 + * + */ H5_DLL herr_t H5Oenable_mdc_flushes(hid_t object_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Retrieves comment for specified object + * + * \param[in] object_id Identifier of an object in the cache; + * may be a group, named datatype, or dataset identifier + * \param[out] are_disabled Flushes enabled/disabled + * + * \return \p are_disabled will be set to \c 1 if an object has had flushes disabled + * and \c 0 if it has not had flushes disabled. + * \return \herr_t + * + * \details H5Oare_mdc_flushes_disabled() determines if an HDF5 object (dataset, group, committed + * datatype) has had flushes of metadata entries disabled. + * + * The H5Oenable_mdc_flushes(), H5Odisable_mdc_flushes() and + * associated flush functions can be used to control the flushing of + * entries from a file’s metadata cache. Metadata cache entries can be controlled + * at both the individual 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. + * + * \since 1.10.0 + * + */ H5_DLL herr_t H5Oare_mdc_flushes_disabled(hid_t object_id, hbool_t *are_disabled); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Compares two VOL connector object tokens + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] token1 First object token + * \param[in] token2 Second object token + * \param[out] cmp_value Comparison value + * + * \return \herr_t + * + * \details H5Otoken_cmp() compares two VOL connector object tokens, \p token1 + * and \p token2 for the file or group identifier specified by \p loc_id. + * Both object tokens must be from the same VOL connector class. + * + * H5O_token_t is defined in H5public.h as follows: + * \snippet H5public.h H5O_token_t_snip + * + * A comparison value, \p cmp_value, is returned, which indicates the + * result of the comparison: + * + * <table> + * <tr> + * <th>cmp_value</th> + * <th>Result</th> + * </tr> + * <tr> + * <td> > 0</td> + * <td> \p token1 > \p token2</td> + * </tr> + * <tr> + * <td> < 0</td> + * <td>\p token1 < \p token2</td> + * </tr> + * <tr> + * <td>0</td> + * <td>\p token1 = \p token2</td> + * </tr> + * </table> + * + * \par Example + * An example snippet from test/links.c: + * \snippet links.c H5Otoken_cmp_snip + * + * \since 1.12.0 + * + */ H5_DLL herr_t H5Otoken_cmp(hid_t loc_id, const H5O_token_t *token1, const H5O_token_t *token2, int *cmp_value); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Serializes a connector's object token into a string + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] token Connector object token + * \param[out] token_str String for connector object token \p token + * + * \return \herr_t + * + * \details H5Otoken_to_str() serializes a connector's object token specified by + * \p token and the location identifier for the object, \p loc_id, + * into a string, \p token_str. + * + * \since 1.12.0 + * + */ H5_DLL herr_t H5Otoken_to_str(hid_t loc_id, const H5O_token_t *token, char **token_str); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Deserializes a string into a connector object token + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] token_str Object token string + * \param[out] token Connector object token + * + * \return \herr_t + * + * \details H5Otoken_from_str() deserializes a string, \p token_str, into a + * connector object token, \p token, for the object specified by the + * location identifier, \p loc_id. + * + * \since 1.12.0 + * + */ H5_DLL herr_t H5Otoken_from_str(hid_t loc_id, const char *token_str, H5O_token_t *token); /* API Wrappers for async routines */ @@ -287,12 +1868,16 @@ H5_DLLVAR const H5O_token_t H5O_TOKEN_UNDEF_g; /* Typedefs */ /* A struct that's part of the H5G_stat_t structure (deprecated) */ +//! [H5O_stat_t_snip] typedef struct H5O_stat_t { hsize_t size; /* Total size of object header in file */ hsize_t free; /* Free space within object header */ unsigned nmesgs; /* Number of object header messages */ unsigned nchunks; /* Number of object header chunks */ } H5O_stat_t; +//! [H5O_stat_t_snip] + +//! [H5O_info1_t_snip] /* Information struct for object */ /* (For H5Oget_info/H5Oget_info_by_name/H5Oget_info_by_idx versions 1 & 2) */ @@ -314,27 +1899,938 @@ typedef struct H5O_info1_t { } meta_size; } H5O_info1_t; +//! [H5O_info1_t_snip] + /* Prototype for H5Ovisit/H5Ovisit_by_name() operator (versions 1 & 2) */ +//! [H5O_iterate1_t_snip] + typedef herr_t (*H5O_iterate1_t)(hid_t obj, const char *name, const H5O_info1_t *info, void *op_data); +//! [H5O_iterate1_t_snip] + /* Function prototypes */ + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Opens an object using its address within an HDF5 file. + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] addr Object's address in the file + * + * \return \hid_tv{object} + * + * \deprecated As of HDF5-1.12 this function has been deprecated in favor of + * the function H5Oopen_by_token(). + * + * \details H5Oopen_by_addr() opens a group, dataset, or committed (named) datatype using its + * address within an HDF5 file, \p addr. The resulting opened object is identical to + * an object opened with H5Oopen() and should be closed with H5Oclose() or an + * object-type-specific closing function (such as H5Gclose()) when no longer needed. + * + * \p loc_id is a location identifier in the file. + * + * The object’s address within the file, \p addr, is the byte offset of the first byte + * of the object header from the beginning of the HDF5 file space, i.e., from the + * beginning of the super block (see the “HDF5 Storage Model” section of the The + * HDF5 Data Model and File Structure chapter of the <em>HDF5 User's Guide</em>.) + * + * \p addr can be obtained via either of two function calls. H5Gget_objinfo() returns + * the object’s address in the \c objno field of the H5G_stat_t \c struct; + * H5Lget_info() returns the address in the \c address field of the #H5L_info_t \c struct. + * + * The address of the HDF5 file on a physical device has no effect on H5Oopen_by_addr(), + * nor does the use of any file driver. As stated above, the object address is its + * offset within the HDF5 file; HDF5’s file drivers will transparently map this to an + * address on a storage device. + * + * \warning This function must be used with care! + * \warning Improper use can lead to inaccessible data, wasted space in the file, + * or <b><em>file corruption</em></b>. + * \warning This function is dangerous if called on an invalid address. The risk can be safely + * overcome by retrieving the object address with H5Gget_objinfo() or H5Lget_info() + * immediately before calling H5Oopen_by_addr(). The immediacy of the operation can be + * important; if time has elapsed and the object has been deleted from the file, + * the address will be invalid and file corruption can result. + * + * \version 1.8.4 Fortran subroutine added in this release. + * + * \since 1.8.0 + * + */ H5_DLL hid_t H5Oopen_by_addr(hid_t loc_id, haddr_t addr); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Retrieves the metadata for an object specified by an identifier + * + * \fgdta_loc_obj_id{loc_id} + * \param[out] oinfo Buffer in which to return object information + * + * \return \herr_t + * + * \deprecated As of HDF5-1.12 this function has been deprecated in favor of + * 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. + * + * \note If you are iterating through a lot of different objects to + * retrieve information via the H5Oget_info() family of routines, + * you may see memory building up. This can be due to memory + * allocation for metadata such as object headers and messages + * when the iterated objects are put into the metadata cache. + * \note + * If the memory buildup is not desirable, you can configure a + * smaller cache via H5Fset_mdc_config() or set the file access + * property list via H5Pset_mdc_config(). A smaller sized cache + * will force metadata entries to be evicted from the cache, + * thus freeing the memory associated with the entries. + * + * \version 1.10.5 The macro #H5Oget_info was removed and the function H5Oget_info1() was copied to H5Oget_info(). + * \version 1.10.3 Function H5Oget_info() was copied to H5Oget_info1(), and the macro #H5Oget_info was created. + * \version 1.8.15 Added a note about the valid values for the \c version field in the H5O_hdr_info_t structure. + * \version 1.8.11 Fortran subroutine introduced in this release. + * \version 1.8.10 Added #H5O_type_t structure to the Description section. \n + * Separated H5O_hdr_info_t structure from #H5O_info_t in the Description section. \n + * Clarified the definition and implementation of the time fields. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Oget_info1(hid_t loc_id, H5O_info1_t *oinfo); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Retrieves the metadata for an object, identifying the object + * by location and relative name + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] name Name of group, relative to \p loc_id + * \param[out] oinfo Buffer in which to return object information + * \lapl_id + * + * \return \herr_t + * + * \deprecated As of HDF5-1.12 this function has been deprecated in favor of + * the function H5Oget_info_by_name2() or the macro #H5Oget_info_by_name. + * + * \details H5Oget_info_by_name1() specifies an object’s location and name, \p loc_id + * and \p name, respectively, and retrieves the metadata describing that object + * in \p oinfo, an H5O_info1_t \c struct. + * + * The \c struct H5O_info1_t is defined in H5Opublic.h and described + * in the H5Oget_info1() function entry. + * + * The link access property list, \p lapl_id, is not currently used; + * it should be passed in as #H5P_DEFAULT. + * + * \version 1.10.5 The macro #H5Oget_info_by_name was removed and the function + * H5Oget_info_by_name1() was copied to H5Oget_info_by_name(). + * \version 1.10.3 Function H5Oget_info_by_name() was copied to H5Oget_info_by_name1() + * and the macro #H5Oget_info_by_name was created. + * \version 1.8.8 Fortran 2003 subroutine and \c h5o_info_t derived type introduced + * in this release. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Oget_info_by_name1(hid_t loc_id, const char *name, H5O_info1_t *oinfo, hid_t lapl_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Retrieves the metadata for an object, identifying the object + * by an index position + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] group_name Name of group in which object is located + * \idx_type + * \order + * \param[in] n Position within the index + * \param[out] oinfo Buffer in which to return object information + * \lapl_id + * + * \return \herr_t + * + * \deprecated As of HDF5-1.12 this function has been deprecated in favor of + * the function H5Oget_info_by_idx3() or the macro H5Oget_info_by_idx(). + * + * \details H5Oget_info_by_idx1() retrieves the metadata describing an + * object in the \c struct \p oinfo, as specified by the location, + * \p loc_id, group name, \p group_name, the index by which objects + * in that 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. + * + * 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. + * + * \version 1.10.5 The macro #H5Oget_info_by_idx was removed and the function + * H5Oget_info_by_idx() was copied to H5Oget_info_by_idx1(). + * \version 1.10.3 Function H5Oget_info_by_idx() was copied to H5Oget_info_by_idx1() + * and the macro #H5Oget_info_by_idx was created. + * \version 1.8.11 Fortran subroutine introduced in this release. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Oget_info_by_idx1(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5O_info1_t *oinfo, hid_t lapl_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Retrieves the metadata for an object specified by an identifier + * + * \fgdta_loc_obj_id{loc_id} + * \param[out] oinfo Buffer in which to return object information + * \param[in] fields Flags specifying the fields to include in \p oinfo + * + * \return \herr_t + * + * \deprecated As of HDF5-1.12 this function has been deprecated in favor of + * the function H5Oget_info3() or the macro H5Oget_info(). + * + * \details H5Oget_info2() specifies an object by its identifier, \p loc_id , and + * retrieves the metadata describing that object in \p oinfo , an H5O_info1_t \c struct. + * This \c struct type is described in H5Oget_info1(). + * + * The \p fields parameter contains flags to determine which fields will be filled in + * the H5O_info1_t \c struct returned in \p oinfo. + * These flags are defined in the H5Opublic.h file: + * + * \obj_info_fields + * + * \note If you are iterating through a lot of different objects to + * retrieve information via the H5Oget_info() family of routines, + * you may see memory building up. This can be due to memory + * allocation for metadata such as object headers and messages + * when the iterated objects are put into the metadata cache. + * \note + * If the memory buildup is not desirable, you can configure a + * smaller cache via H5Fset_mdc_config() or set the file access + * property list via H5Pset_mdc_config(). A smaller sized cache + * will force metadata entries to be evicted from the cache, + * thus freeing the memory associated with the entries. + * + * \since 1.10.3 + * + */ H5_DLL herr_t H5Oget_info2(hid_t loc_id, H5O_info1_t *oinfo, unsigned fields); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Retrieves the metadata for an object, identifying the object + * by location and relative name + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] name Name of group, relative to \p loc_id + * \param[out] oinfo Buffer in which to return object information + * \param[in] fields Flags specifying the fields to include in \p oinfo + * \lapl_id + * + * \return \herr_t + * + * \deprecated As of HDF5-1.12 this function has been deprecated in favor of + * the function H5Oget_info_by_name3() or the macro H5Oget_info_by_name(). + * + * \details H5Oget_info_by_name2() specifies an object’s location and name, \p loc_id and + * \p name, respectively, and retrieves the metadata describing + * that object in \p oinfo, an H5O_info1_t \c struct. + * + * The \c struct H5O_info1_t is defined in H5Opublic.h and described + * in the H5Oget_info1() function entry. + * + * The \p fields parameter contains flags to determine which fields + * will be filled in in the H5O_info1_t \c struct returned in + * \p oinfo. These flags are defined in the H5Opublic.h file: + * + * \obj_info_fields + * + * The link access property list, \p lapl_id, is not currently used; + * it should be passed in as #H5P_DEFAULT. + * + * \since 1.10.3 + * + */ H5_DLL herr_t H5Oget_info_by_name2(hid_t loc_id, const char *name, H5O_info1_t *oinfo, unsigned fields, hid_t lapl_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Retrieves the metadata for an object, identifying the object + * by an index position + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] group_name Name of group in which object is located + * \idx_type + * \order + * \param[in] n Position within the index + * \param[out] oinfo Buffer in which to return object information + * \param[in] fields Flags specifying the fields to include in \p oinfo + * \lapl_id + * + * \return \herr_t + * + * \deprecated As of HDF5-1.12 this function is deprecated in favor of + * the function H5Oget_info_by_idx3() or the macro #H5Oget_info_by_idx. + * + * \details H5Oget_info_by_idx2() retrieves the metadata describing an + * object in the \c struct \p oinfo, as specified by the location, + * \p loc_id, group name, \p group_name, the index by which objects + * in that 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. + * + * \p oinfo, in which the object information is returned, is a \c struct of + * type H5O_info1_t. This and other \c struct types used + * by H5Oget_info_by_idx2() are described in H5Oget_info_by_idx1(). + * + * If \p loc_id fully specifies the group in which the object resides, + * i\p group_name can be a dot (\c .). + * + * The \p fields parameter contains flags to determine which fields will be + * filled in the H5O_info1_t \c struct returned in \p oinfo. + * These flags are defined in the H5Opublic.h file: + * \obj_info_fields + * + * The link access property list, \c lapl_id, is not currently used; + * it should be passed in as #H5P_DEFAULT. + * + * \since 1.10.3 + * + */ H5_DLL herr_t H5Oget_info_by_idx2(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5O_info1_t *oinfo, unsigned fields, hid_t lapl_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Recursively visits all objects accessible from a specified object + * + * \fgdta_loc_obj_id{obj_id} + * \idx_type + * \order + * \param[in] op Callback function passing data regarding the object + * to the calling application + * \param[in] op_data User-defined pointer to data required by the application + * for its processing of the object + * + * \return On success, returns the return value of the first operator + * that returns a positive value, or zero if all members were + * processed with no operator returning non-zero. + * + * \return On failure, returns a negative value if something goes wrong + * within the library, or the first negative value returned by + * an operator. + * + * \deprecated As of HDF5-1.12 this function has been deprecated in favor of + * the function H5Ovisit3() or the macro #H5Ovisit. + * + * \details H5Ovisit1() is a recursive iteration function to visit the + * object \p obj_id and, if \p obj_id is a group, all objects in + * and below it in an HDF5 file, thus providing a mechanism for + * an application to perform a common set of operations across all + * of those objects or a dynamically selected subset. For + * non-recursive iteration across the members of a group, + * see H5Literate1(). + * + * If \p obj_id is a group identifier, that group serves as the + * root of a recursive iteration. If \p obj_id is a file identifier, + * that file’s root group serves as the root of the recursive + * iteration. If \p obj_id is an attribute identifier, + * then the object where the attribute is attached will be iterated. + * If \p obj_id is any other type of object, such as a dataset or + * named datatype, there is no iteration. + * + * Two parameters are used to establish the iteration: \p idx_type + * and \p order. + * + * \p idx_type specifies the index to be used. If the links in + * 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 + * + * 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 + * encountered that was not tracked in creation order, that group + * will be iterated over in alpha-numeric order by name, or + * <em>name order</em>. (<em>Name order</em> is the native order + * used by the HDF5 library and is always available.) + * + * \p order specifies the order in which objects are to be inspected + * along the index specified in \p idx_type. Valid values include + * the following: + * + * \orders + * + * The 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. + * + * H5Lvisit1() and H5Ovisit1() are companion functions: one for + * examining and operating on links; the other for examining + * and operating on the objects that those links point to. Both + * functions ensure that by the time the function completes + * successfully, every link or object below the specified point + * in the file has been presented to the application for whatever + * processing the application requires. These functions assume + * that the membership of the group being iterated over remains + * unchanged through the iteration; if any of the links in the + * group change during the iteration, the 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(), + * and the macro #H5Ovisit was created. + * \version 1.8.8 Fortran subroutine introduced in this release. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Ovisit1(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate1_t op, void *op_data); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Recursively visits all objects starting from a specified object + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] obj_name Name of the object, generally relative to + * \p loc_id, that will serve as root of the iteration + * \idx_type + * \order + * \param[in] op Callback function passing data regarding the object + * to the calling application + * \param[in] op_data User-defined pointer to data required by the application + * for its processing of the object + * \lapl_id + * + * \return On success, returns the return value of the first operator + * that returns a positive value, or zero if all members were + * processed with no operator returning non-zero. + * + * \return On failure, returns a negative value if something goes wrong + * within the library, or the first negative value returned by + * an operator. + * + * \deprecated As of HDF5-1.12 this function has been deprecated in favor of + * the function H5Ovisit_by_name3() or the macro #H5Ovisit_by_name. + * + * \details H5Ovisit_by_name1() is a recursive iteration function to visit + * the object specified by the \p loc_id / \p obj_name parameter + * pair and, if that object is a group, all objects in and below it + * in an HDF5 file, thus providing a mechanism for an application to + * perform a common set of operations across all of those objects or + * a dynamically selected subset. For non-recursive iteration across + * the members of a group, see H5Literate1(). + * + * The object serving as the root of the iteration is specified + * by the \p loc_id / \p obj_name parameter pair. \p loc_id specifies + * a file or an object in a file; if \p loc_id is an attribute identifier, + * the object where the attribute is attached will be used. + * \p obj_name specifies either an object in the file (with an absolute + * name based in the file’s root group) or an object name relative + * to \p loc_id. If \p loc_id fully specifies the object that is to serve + * as the root of the iteration, \p obj_name should be '\c .' (a dot). + * (Note that when \p loc_id fully specifies the object that is to serve + * as the root of the iteration, the user may wish to consider + * using H5Ovisit1() instead of H5Ovisit_by_name1().) + * + * Two parameters are used to establish the iteration: \p idx_type + * and \p order. + * + * \p idx_type specifies the index to be used. If the links in + * 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 + * + * 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 + * encountered that was not tracked in creation order, that group + * will be iterated over in alpha-numeric order by name, or + * <em>name order</em>. (<em>Name order</em> is the native order + * used by the HDF5 library and is always available.) + * + * \p order specifies the order in which objects are to be inspected + * along the index specified in \p idx_type. Valid values include + * the following: + * + * \orders + * + * The \p op callback function and the effect of the callback + * function’s return value on the application are described + * in H5Ovisit1(). + * + * The H5O_info1_t \c struct is defined in H5Opublic.h + * and described in the H5Oget_info1() function entry. + * + * The H5Ovisit_by_name1() \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. + * + * \p lapl_id is a link access property list. In the general case, + * when default link access properties are acceptable, this can + * be passed in as #H5P_DEFAULT. An example of a situation that + * requires a non-default link access property list is when + * the link is an external link; an external link may require + * that a link prefix be set in a link access property list + * (see H5Pset_elink_prefix()). + * + * H5Lvisit_by_name1() and H5Ovisit_by_name1() are companion + * functions: one for examining and operating on links; the other + * for examining and operating on the objects that those links point to. + * Both functions ensure that by the time the function completes + * successfully, every link or object below the specified point + * in the file has been presented to the application for whatever + * processing the application requires. + * + * \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(), + * and the macro #H5Ovisit_by_name was created. + * \version 1.8.11 Fortran subroutine introduced in this release. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Ovisit_by_name1(hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate1_t op, void *op_data, hid_t lapl_id); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Recursively visits all objects accessible from a specified object + * + * \fgdta_loc_obj_id{obj_id} + * \idx_type + * \order + * \param[in] op Callback function passing data regarding the object + * to the calling application + * \param[in] op_data User-defined pointer to data required by the application + * for its processing of the object + * \param[in] fields Flags specifying the fields to be retrieved to the + * callback \p op + * + * \return On success, returns the return value of the first operator + * that returns a positive value, or zero if all members were + * processed with no operator returning non-zero. + * + * \return On failure, returns a negative value if something goes wrong + * within the library, or the first negative value returned by + * an operator. + * + * \deprecated As of HDF5-1.12 this function has been deprecated in favor of + * the function H5Ovisit3() or the macro #H5Ovisit. + * + * \details H5Ovisit2() is a recursive iteration function to visit the + * object \p obj_id and, if \p obj_id is a group, all objects in + * and below it in an HDF5 file, thus providing a mechanism for + * an application to perform a common set of operations across all + * of those objects or a dynamically selected subset. For + * non-recursive iteration across the members of a group, + * see H5Literate1(). + * + * If \p obj_id is a group identifier, that group serves as the + * root of a recursive iteration. If \p obj_id is a file identifier, + * that file’s root group serves as the root of the recursive + * iteration. If \p obj_id is an attribute identifier, + * then the object where the attribute is attached will be iterated. + * If \p obj_id is any other type of object, such as a dataset or + * named datatype, there is no iteration. + * + * Two parameters are used to establish the iteration: \p idx_type + * and \p order. + * + * \p idx_type specifies the index to be used. If the links in + * 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 + * + * 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 + * encountered that was not tracked in creation order, that group + * will be iterated over in alpha-numeric order by name, or + * <em>name order</em>. (<em>Name order</em> is the native order + * used by the HDF5 library and is always available.) + * + * \p order specifies the order in which objects are to be inspected + * along the index specified in \p idx_type. Valid values include + * the following: + * + * \orders + * + * The 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. + * + * The \p fields parameter contains flags to determine which fields will + * be retrieved by the \p op callback function. These flags are defined + * in the H5Opublic.h file: + * \obj_info_fields + * + * H5Lvisit() and H5Ovisit() are companion functions: one for + * examining and operating on links; the other for examining + * and operating on the objects that those links point to. Both + * functions ensure that by the time the function completes + * successfully, every link or object below the specified point + * in the file has been presented to the application for whatever + * processing the application requires. These functions assume + * that the membership of the group being iterated over remains + * unchanged through the iteration; if any of the links in the + * group change during the iteration, the 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 + * + */ H5_DLL herr_t H5Ovisit2(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate1_t op, void *op_data, unsigned fields); + +/** + *------------------------------------------------------------------------- + * \ingroup H5O + * + * \brief Recursively visits all objects starting from a specified object + * + * \fgdta_loc_obj_id{loc_id} + * \param[in] obj_name Name of the object, generally relative to + * \p loc_id, that will serve as root of the iteration + * \idx_type + * \order + * \param[in] op Callback function passing data regarding the object + * to the calling application + * \param[in] op_data User-defined pointer to data required by the application + * for its processing of the object + * \param[in] fields Flags specifying the fields to be retrieved to the + * callback function \p op + * \lapl_id + * + * \return On success, returns the return value of the first operator + * that returns a positive value, or zero if all members were + * processed with no operator returning non-zero. + * + * \return On failure, returns a negative value if something goes wrong + * within the library, or the first negative value returned by + * an operator. + * + * \deprecated As of HDF5-1.12 this function has been deprecated in favor of + * the function H5Ovisit_by_name3() or the macro #H5Ovisit_by_name. + * + * \details H5Ovisit_by_name2() is a recursive iteration function to visit + * the object specified by the \p loc_id / \p obj_name parameter + * pair and, if that object is a group, all objects in and below it + * in an HDF5 file, thus providing a mechanism for an application to + * perform a common set of operations across all of those objects or + * a dynamically selected subset. For non-recursive iteration across + * the members of a group, see #H5Literate. + * + * The object serving as the root of the iteration is specified + * by the \p loc_id / \p obj_name parameter pair. \p loc_id specifies + * a file or an object in a file; if \p loc_id is an attribute identifier, + * the object where the attribute is attached will be used. + * \p obj_name specifies either an object in the file (with an absolute + * name based in the file’s root group) or an object name relative + * to \p loc_id. If \p loc_id fully specifies the object that is to serve + * as the root of the iteration, \p obj_name should be '\c .' (a dot). + * (Note that when \p loc_id fully specifies the object that is to serve + * as the root of the iteration, the user may wish to consider + * using H5Ovisit2() instead of #H5Ovisit_by_name.) + * + * Two parameters are used to establish the iteration: \p idx_type + * and \p order. + * + * \p idx_type specifies the index to be used. If the links in + * 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 + * + * 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 + * encountered that was not tracked in creation order, that group + * will be iterated over in alpha-numeric order by name, or + * <em>name order</em>. (<em>Name order</em> is the native order + * used by the HDF5 library and is always available.) + * + * \p order specifies the order in which objects are to be inspected + * along the index specified in \p idx_type. Valid values include + * the following: + * + * \orders + * + * The \p op callback function and the effect of the callback + * function’s return value on the application are described + * in H5Ovisit2(). + * + * The H5O_info1_t \c struct is defined in H5Opublic.h + * and described in the H5Oget_info1() function entry. + * + * The H5Ovisit_by_name2() \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. + * + * \p lapl_id is a link access property list. In the general case, + * when default link access properties are acceptable, this can + * be passed in as #H5P_DEFAULT. An example of a situation that + * requires a non-default link access property list is when + * the link is an external link; an external link may require + * that a link prefix be set in a link access property list + * (see H5Pset_elink_prefix()). + * + * The \p fields parameter contains flags to determine which fields will + * be retrieved by the \p op callback function. These flags are defined + * in the H5Opublic.h file: + * \obj_info_fields + * + * #H5Lvisit_by_name and #H5Ovisit_by_name are companion + * functions: one for examining and operating on links; the other + * for examining and operating on the objects that those links point to. + * Both functions ensure that by the time the function completes + * successfully, every link or object below the specified point + * in the file has been presented to the application for whatever + * processing the application requires. + * + * \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 + * + */ H5_DLL herr_t H5Ovisit_by_name2(hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate1_t op, void *op_data, unsigned fields, hid_t lapl_id); |