path: root/src/H5Opublic.h

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * 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 */
/*******************/

//! <!-- [H5O_type_t_snip] -->
/**
 * 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;
//! <!-- [H5O_type_t_snip] -->

//! <!-- [H5O_hdr_info_t_snip] -->
/**
 * 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;
//! <!-- [H5O_hdr_info_t_snip] -->

//! <!-- [H5O_info_t_snip] -->
/**
 * 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;
//! <!-- [H5O_info_t_snip] -->

/**
 * Typedef for message creation indexes
 */
typedef uint32_t H5O_msg_crt_idx_t;

//! <!-- [H5O_iterate_t_snip] -->
/**
 * 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);
//! <!-- [H5O_iterate_t_snip] -->

//! <!-- [H5O_mcdt_search_ret_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
                           */
    H5O_MCDT_SEARCH_STOP  /**< Stop the search, but continue copying.  The committed datatype will be copied
                             but not merged. */
} H5O_mcdt_search_ret_t;
//! <!-- [H5O_mcdt_search_ret_t_snip] -->

//! <!-- [H5O_mcdt_search_cb_t_snip] -->
/**
 * 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);
//! <!-- [H5O_mcdt_search_cb_t_snip] -->

/********************/
/* 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 <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 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 -- <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);

/**
 *-------------------------------------------------------------------------
 * \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
 *
 * \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
 *          <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_iterate_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_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_info_t \c struct is defined in H5Opublic.h:
 *          \snippet this H5O_info_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 H5Ovisit() \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.
 *
 *          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.
 *
 * \version 1.8.8 Fortran subroutine introduced in this release.
 *
 * \since 1.8.0
 *
 */
H5_DLL herr_t H5Ovisit(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate_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.
 *
 * \details H5Ovisit_by_name() 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 H5Ovisit() 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 H5Ovisit().
 *
 *          The H5O_info_t \c struct is defined in H5Opublic.h
 *          and described in the H5Oget_info() function entry.
 *
 *          The H5Ovisit_by_name() \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_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.
 *
 * \version 1.8.11 Fortran subroutine introduced in this release.
 *
 * \since 1.8.0
 *
 */
H5_DLL herr_t H5Ovisit_by_name(hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order,
                               H5O_iterate_t op, void *op_data, 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);

/* Symbols defined for compatibility with previous versions of the HDF5 API.
 *
 * Use of these symbols is deprecated.
 */
#ifndef H5_NO_DEPRECATED_SYMBOLS

/* Macros */

/* Typedefs */

//! <!-- [H5O_stat_t_snip] -->
/**
 * A struct that's part of the \ref H5G_stat_t structure
 * \deprecated
 */
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] -->

/* Function prototypes */
#endif /* H5_NO_DEPRECATED_SYMBOLS */

#ifdef __cplusplus
}
#endif
#endif /* H5Opublic_H */