/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * * terms governing use, modification, and redistribution, is contained in * * the COPYING file, which can be found at the root of the source code * * distribution tree, or in https://www.hdfgroup.org/licenses. * * If you do not have access to either file, you may request a copy from * * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /*------------------------------------------------------------------------- * * Created: H5Opublic.h * Aug 5 1997 * Robb Matzke * * Purpose: Public declarations for the H5O (object header) * package. * *------------------------------------------------------------------------- */ #ifndef H5Opublic_H #define H5Opublic_H /* Public headers needed by this file */ #include "H5public.h" /* Generic Functions */ #include "H5Ipublic.h" /* IDs */ #include "H5Lpublic.h" /* Links */ /*****************/ /* Public Macros */ /*****************/ /* Flags for object copy (H5Ocopy) */ #define H5O_COPY_SHALLOW_HIERARCHY_FLAG (0x0001u) /* Copy only immediate members */ #define H5O_COPY_EXPAND_SOFT_LINK_FLAG (0x0002u) /* Expand soft links into new objects */ #define H5O_COPY_EXPAND_EXT_LINK_FLAG (0x0004u) /* Expand external links into new objects */ #define H5O_COPY_EXPAND_REFERENCE_FLAG (0x0008u) /* Copy objects that are pointed by references */ #define H5O_COPY_WITHOUT_ATTR_FLAG (0x0010u) /* Copy object without copying attributes */ #define H5O_COPY_PRESERVE_NULL_FLAG (0x0020u) /* Copy NULL messages (empty space) */ #define H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG (0x0040u) /* Merge committed datatypes in dest file */ #define H5O_COPY_ALL (0x007Fu) /* All object copying flags (for internal checking) */ /* Flags for shared message indexes. * Pass these flags in using the mesg_type_flags parameter in * H5P_set_shared_mesg_index. * (Developers: These flags correspond to object header message type IDs, * but we need to assign each kind of message to a different bit so that * one index can hold multiple types.) */ #define H5O_SHMESG_NONE_FLAG 0x0000 /* No shared messages */ #define H5O_SHMESG_SDSPACE_FLAG ((unsigned)1 << 0x0001) /* Simple Dataspace Message. */ #define H5O_SHMESG_DTYPE_FLAG ((unsigned)1 << 0x0003) /* Datatype Message. */ #define H5O_SHMESG_FILL_FLAG ((unsigned)1 << 0x0005) /* Fill Value Message. */ #define H5O_SHMESG_PLINE_FLAG ((unsigned)1 << 0x000b) /* Filter pipeline message. */ #define H5O_SHMESG_ATTR_FLAG ((unsigned)1 << 0x000c) /* Attribute Message. */ #define H5O_SHMESG_ALL_FLAG \ (H5O_SHMESG_SDSPACE_FLAG | H5O_SHMESG_DTYPE_FLAG | H5O_SHMESG_FILL_FLAG | H5O_SHMESG_PLINE_FLAG | \ H5O_SHMESG_ATTR_FLAG) /* Object header status flag definitions */ #define H5O_HDR_CHUNK0_SIZE 0x03 /* 2-bit field indicating # of bytes to store the size of chunk 0's data */ #define H5O_HDR_ATTR_CRT_ORDER_TRACKED 0x04 /* Attribute creation order is tracked */ #define H5O_HDR_ATTR_CRT_ORDER_INDEXED 0x08 /* Attribute creation order has index */ #define H5O_HDR_ATTR_STORE_PHASE_CHANGE 0x10 /* Non-default attribute storage phase change values stored */ #define H5O_HDR_STORE_TIMES 0x20 /* Store access, modification, change & birth times for object */ #define H5O_HDR_ALL_FLAGS \ (H5O_HDR_CHUNK0_SIZE | H5O_HDR_ATTR_CRT_ORDER_TRACKED | H5O_HDR_ATTR_CRT_ORDER_INDEXED | \ H5O_HDR_ATTR_STORE_PHASE_CHANGE | H5O_HDR_STORE_TIMES) /* Maximum shared message values. Number of indexes is 8 to allow room to add * new types of messages. */ #define H5O_SHMESG_MAX_NINDEXES 8 #define H5O_SHMESG_MAX_LIST_SIZE 5000 /*******************/ /* Public Typedefs */ /*******************/ //! /** * Types of objects in file */ typedef enum H5O_type_t { H5O_TYPE_UNKNOWN = -1, /**< Unknown object type */ H5O_TYPE_GROUP, /**< Object is a group */ H5O_TYPE_DATASET, /**< Object is a dataset */ H5O_TYPE_NAMED_DATATYPE, /**< Object is a named data type */ H5O_TYPE_NTYPES /**< Number of different object types (must be last!) */ } H5O_type_t; //! //! /** * Information struct for object header metadata (for * H5Oget_info(), H5Oget_info_by_name(), H5Oget_info_by_idx()) */ typedef struct H5O_hdr_info_t { unsigned version; /**< Version number of header format in file */ unsigned nmesgs; /**< Number of object header messages */ unsigned nchunks; /**< Number of object header chunks */ unsigned flags; /**< Object header status flags */ struct { hsize_t total; /**< Total space for storing object header in file */ hsize_t meta; /**< Space within header for object header metadata information */ hsize_t mesg; /**< Space within header for actual message information */ hsize_t free; /**< Free space within object header */ } space; struct { uint64_t present; /**< Flags to indicate presence of message type in header */ uint64_t shared; /**< Flags to indicate message type is shared in header */ } mesg; } H5O_hdr_info_t; //! //! /** * Data model information struct for objects * (For H5Oget_info(), H5Oget_info_by_name(), H5Oget_info_by_idx() version 3) */ typedef struct H5O_info_t { unsigned long fileno; /**< File number that object is located in */ haddr_t addr; /**< Object address in file */ H5O_type_t type; /**< Basic object type (group, dataset, etc.) */ unsigned rc; /**< Reference count of object */ time_t atime; /**< Access time */ time_t mtime; /**< Modification time */ time_t ctime; /**< Change time */ time_t btime; /**< Birth time */ hsize_t num_attrs; /**< # of attributes attached to object */ H5O_hdr_info_t hdr; /**< Object header information */ /* Extra metadata storage for obj & attributes */ struct { H5_ih_info_t obj; /**< v1/v2 B-tree & local/fractal heap for groups, B-tree for chunked datasets */ H5_ih_info_t attr; /**< v2 B-tree & heap for attributes */ } meta_size; } H5O_info_t; //! /** * Typedef for message creation indexes */ typedef uint32_t H5O_msg_crt_idx_t; //! /** * Prototype for H5Ovisit(), H5Ovisit_by_name() operator */ typedef herr_t (*H5O_iterate_t)(hid_t obj, const char *name, const H5O_info_t *info, void *op_data); //! //! 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 */ H5O_MCDT_SEARCH_STOP /**< Stop the search, but continue copying. The committed datatype will be copied but not merged. */ } H5O_mcdt_search_ret_t; //! //! /** * Callback to invoke when completing the search for a matching committed * datatype from the committed dtype list */ typedef H5O_mcdt_search_ret_t (*H5O_mcdt_search_cb_t)(void *op_data); //! /********************/ /* Public Variables */ /********************/ /*********************/ /* Public Prototypes */ /*********************/ #ifdef __cplusplus 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); /** *------------------------------------------------------------------------- * \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} * * \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 HDF5 User's Guide.) * * \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 file corruption. * \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 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); /** *------------------------------------------------------------------------- * \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 * * \return \herr_t * * \details H5Oget_info() 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_info_t : * * \snippet this H5O_info_t_snip * * Note the following about H5O_info_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.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_info(hid_t loc_id, H5O_info_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 * * \details H5Oget_info_by_name() 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_info_t is defined in H5Opublic.h and described * in the H5Oget_info() function entry. * * The link access property list, \p lapl_id, is not currently used; * it should be passed in as #H5P_DEFAULT. * * \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_name(hid_t loc_id, const char *name, H5O_info_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 * * \details H5Oget_info_by_idx() 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_info_t . * \snippet this H5O_info_t_snip * * The link access property list, \c lapl_id, is not currently used; * it should be passed in as #H5P_DEFAULT. * * \version 1.8.11 Fortran subroutine introduced in this release. * * \since 1.8.0 * */ H5_DLL herr_t H5Oget_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_info_t *oinfo, 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 -- HDF5 User’s Guide * 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 file corruption. * * \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 HDF5 User’s Guide * 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 file corruption. * * \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); /** *------------------------------------------------------------------------- * \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 without * 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 without * 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 * * \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() 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 H5Literate(). * * 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 * best effort setting. If the application passes in * a value indicating iteration in creation order and a group is * encountered that was not tracked in creation order, that group * will be iterated over in alpha-numeric order by name, or * name order. (Name order is the native order * used by the HDF5 library and is always available.) * * \p order specifies the order in which objects are to be inspected * along the index specified in \p idx_type. Valid values include * the following: * * \orders * * The prototype of the callback function op is as follows (as * defined in the source code file H5Opublic.h): * * \snippet this H5O_iterate_t_snip * * The parameters of this callback function have the following values * or meanings: *
\c obj | *Object that serves as root of the iteration; * same value as the H5Ovisit() \p obj_id parameter | *
\c name | *Name of object, relative to \c obj, being examined at * current step of the iteration | *
\c info | *H5O_info1_t \c struct containing information * regarding that object | *
\c op_data | *User-defined pointer to data required by the application in * processing the object | *