HDF5 documents and links 
Introduction to HDF5 
HDF5 User’s Guide 
In the HDF5 Reference Manual 
H5DS   H5IM   H5LT   H5PT   H5TB  Optimized 
H5   H5A   H5D   H5E   H5F   H5G   H5I   H5L 
H5O   H5P   H5PL   H5R   H5S   H5T   H5Z 
Tools   Datatypes   Fortran   Compatibility Macros 
Collective Calls in Parallel 

H5O: Object Interface

Object API Functions

The Object interface, H5O, functions manipulate objects in an HDF5 file. This interface is designed to be used in conjunction with the Links interface (H5L).

The C Interfaces:
             
    Struct:        These functions have been deprecated.
Alphabetical Listing
             

The Fortran Interface:
In general, each Fortran subroutine performs exactly the same task as the corresponding C function.
                                         
    Fortran2003 Derived Type:

Accessing objects by location and name:
Many HDF5 function calls use a combination of a location and name to identify an HDF5 object.

The location will be specified by a location identifier, loc_id, and will be an HDF5 file or an object in a file, such as a group, dataset or named datatype.

The name, name, will be a character string and will specify an object in an HDF5 file, such as a group, dataset or named datatype. name will specify that object by either an absolute path in the file specified by loc_id or by a relative path relative to loc_id.

Sample file structure:
DATA_FILE1

The loc_id and name combination, as used in these function calls, can interact in any of several ways. To illustrate, the following combinations all identify dset3 in the illustrated file structure.

Many HDF5 functions accept loc_id and name in all of the above combinations. When accepted combinations are limited for a specific function, the limitations are mentioned in the function’s reference manual entry.

For a related discussion of the structure of HDF5 files and HDF5 path names, see “The Structure of an HDF5 File” (particularly the subsection “HDF5 Path Names and Navigation”) in the “HDF5 Data Model and File Structure” chapter of the HDF5 User’s Guide.


Last modified: 10 April 2013
Name: H5Oclose
Signature:
herr_t H5Oclose( hid_t object_id )

Purpose:
Closes an object in an HDF5 file.

Description:
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.

Parameters:
hid_t object_id     IN: Object identifier

Returns:
Returns a non-negative value if successful; otherwise returns a negative value.

Fortran90 Interface: h5oclose_f
Signature:

  SUBROUTINE h5oclose_f(object_id, hdferr)
    IMPLICIT NONE
    INTEGER(HID_T), INTENT(IN)   :: object_id
    INTEGER       , INTENT(OUT) :: hdferr

Inputs:

  object_id - Object identifier.

Outputs:

  hdferr    - Returns 0 if successful and -1 if fails.

History:
Release     C
1.8.8 Fortran subroutine introduced in this release.
1.8.0 Function introduced in this release.

Last modified: 28 June 2012
Name: H5Ocopy
Signature:
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 )

Purpose:
Copies an object in an HDF5 file.

Description:
H5Ocopy copies the group, dataset or committed datatype specified by src_name from the file or group specified by src_loc_id to the destination location 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 dst_name, which must not pre-exist in the destination location. If dst_name already exists at the location dst_loc_id, H5Ocopy will fail. If 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 creation property lists specified by ocpypl_id and lcpl_id.

H5Ocopy will always try to make a copy of the object specified in src_name.

Several flags are available to govern the behavior of H5Ocopy:

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).

Parameters:

Returns:
Returns a non-negative value if successful; otherwise returns a negative value.

See Also:
H5Pset_copy_object
H5Pset_create_intermediate_group
  H5Padd_merge_committed_dtype_path
H5Pset_mcdt_search_cb

Copying Committed Datatypes
    with H5Ocopy
 
A comprehensive discussion of copying committed datatypes (PDF) in Advanced Topics in HDF5

Fortran90 Interface: h5ocopy_f
Signature:

  SUBROUTINE h5ocopy_f(src_loc_id, src_name, dst_loc_id,    &
        dst_name, hdferr, ocpypl_id, lcpl_id)
    IMPLICIT NONE
    INTEGER(HID_T)  , INTENT(IN)  :: src_loc_id
    CHARACTER(LEN=*), INTENT(IN)  :: src_name
    INTEGER(HID_T)  , INTENT(IN)  :: dst_loc_id
    CHARACTER(LEN=*), INTENT(IN)  :: dst_name
    INTEGER         , INTENT(OUT) :: hdferr
    INTEGER(HID_T)  , INTENT(IN), OPTIONAL :: ocpypl_id
    INTEGER(HID_T)  , INTENT(IN), OPTIONAL :: lcpl_id

Inputs:

  src_loc_id - Object identifier indicating the location of the 
               source object to be copied.
  src_name   - Name of the source object to be copied.
  dst_loc_id - Location identifier specifying the destination.
  dst_name   - Name to be assigned to the new copy.

Outputs:

  hdferr     - Returns 0 if successful and -1 if fails.

Optional parameters:

  ocpypl_id  - Object copy property list.
  lcpl_id    - Link creation property list for the new hard link.

History:

Last modified: 10 April 2013
Name: H5Odecr_refcount
Signature:
herr_t H5Odecr_refcount( hid_t object_id )

Purpose:
Decrements an object reference count.

Description:
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 rc field of the H5O_info_t struct.

Warning: This function must be used with care!
Improper use can lead to inaccessible data, wasted space in the file, or file corruption.

Parameters:

Returns:
Returns a non-negative value if successful; otherwise returns a negative value.

Fortran90 Interface: h5odecr_refcount_f
Signature:

  SUBROUTINE h5odecr_refcount_f(object_id, hdferr)
    IMPLICIT NONE
    INTEGER(HID_T), INTENT(IN)  :: object_id
    INTEGER       , INTENT(OUT) :: hdferr

Inputs:

  object_id - Object identifier.

Outputs:

  hdferr    - Returns 0 if successful and -1 if fails.

History:
Release     Change
1.8.11 Fortran subroutine introduced in this release.
1.8.0 Function introduced in this release.

Last modified: 10 April 2013
Name: H5Oexists_by_name
Signature:
htri_t H5Oexists_by_name( hid_t loc_id, const char * name, hid_t lapl_id )

Purpose:
Determines whether a link resolves to an actual object.

Motivation:
H5Oexists_by_name is used by an application to check that an existing link resolves to an object. Primarily, it is designed to check for dangling soft, external, or user-defined links.

Description:
H5Oexists_by_name allows an application to determine whether the link name in the group or file specified with 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 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.

Example: Use the following steps to verify the existence of the link datasetD in the group group1/group2/softlink_to_group3/, where group1 is a member of the group specified by loc_id:

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 datasetD were in /group1/group2/softlink_to_group3, the first call to H5Lexists would have name set to /group1.

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.

Parameters:
hid_t loc_id      IN: Identifier of the file or group to query.
const char *name   IN: The name of the link to check.
hid_t lapl_id   IN: Link access property list identifier.

Returns:
Returns TRUE or FALSE if successful; otherwise returns a negative value.

Failure Modes:
If the link specified by the loc_id and name does not exist, an error will be returned. If the link exists but does not resolve to an object for any reason, this routine will return FALSE, not FAIL.

See Also:
H5Lexists

“Discovering Objects in a Group” in the “Groups” chapter of the HDF5 User’s Guide

Fortran90 Interface: h5oexists_by_name_f
Signature:

  SUBROUTINE h5oexists_by_name_f(loc_id, name, link_exists, &
        hdferr, lapl_id)
    IMPLICIT NONE
    INTEGER(HID_T)  , INTENT(IN)  :: loc_id
    CHARACTER(LEN=*), INTENT(IN)  :: name
    LOGICAL         , INTENT(OUT) :: link_exists
    INTEGER         , INTENT(OUT) :: hdferr
    INTEGER(HID_T)  , INTENT(IN), OPTIONAL :: lapl_id

Inputs:

  loc_id   - Identifier of the file or group to query. 
  name     - The name of the link to check. 

Outputs:

  link_exists - Existing link resolves to an object.
  hdferr      - Returns 0 if successful and -1 if fails.

Optional parameters:

  lapl_id  - Link access property list identifier.

History:
Release     Change
1.8.11 Fortran subroutine introduced in this release.
1.8.5 C function introduced in this release.

Last modified: 10 April 2013
Name: H5Oget_comment
Signature:
ssize_t H5Oget_comment( hid_t object_id, char *comment, size_t bufsize )

Purpose:
Retrieves comment for specified object.

Description:
H5Oget_comment retrieves the comment for the specified object in the buffer comment.

The target object is specified by an identifier, object_id.

The size in bytes of the buffer comment, including the NULL terminator, is specified in bufsize. If bufsize is unknown, a preliminary H5Oget_comment call with the pointer comment set to NULL will return the size of the comment without the NULL terminator.

If bufsize is set to a smaller value than described above, only bufsize bytes of the comment, without a NULL terminator, are returned in comment.

If an object does not have a comment, the empty string is returned in comment.

Parameters:
hid_t object_id     IN: Identifier for the target object.
char *comment OUT: The comment.
size_t bufsize IN: Anticipated required size of the comment buffer.

Returns:
Upon success, returns the number of characters in the comment, not including the NULL terminator, or zero (0) if the object has no comment. The value returned may be larger than bufsize. Otherwise returns a negative value.

Fortran90 Interface: h5oget_comment_f
Signature:

  SUBROUTINE h5oget_comment_f(obj_id, comment,        &
        hdferr, bufsize)
    IMPLICIT NONE
    INTEGER(HID_T)   , INTENT(IN)            :: obj_id
    CHARACTER(LEN=*) , INTENT(OUT)           :: comment
    INTEGER          , INTENT(OUT)           :: hdferr
    INTEGER(HSSIZE_T), INTENT(OUT), OPTIONAL :: bufsize 

Inputs:

  obj_id - Identifier for the target object.

Outputs:

  comment - The comment.
  hdferr  - Returns 0 if successful and -1 if fails.

Optional parameters:

  bufsize - Size of the comment buffer.

History:
Release     C
1.8.11 Fortran subroutine introduced in this release.
1.8.0 Function introduced in this release.

Last modified: 10 April 2013
Name: H5Oget_comment_by_name
Signature:
ssize_t H5Oget_comment_by_name( hid_t loc_id, const char *name, char *comment, size_t bufsize, hid_t lapl_id )

Purpose:
Retrieves comment for specified object.

Description:
H5Oget_comment_by_name retrieves the comment for an object in the buffer comment.

The target object is specified by loc_id and name. loc_id can specify any object in the file. name can be one of the following:
  — The name of the object relative to loc_id
  — An absolute name of the object, starting from /, the file’s root group
  — A dot (.), if loc_id fully specifies the object

The size in bytes of the comment, including the NULL terminator, is specified in bufsize. If bufsize is unknown, a preliminary H5Oget_comment_by_name call with the pointer comment set to NULL will return the size of the comment without the NULL terminator.

If bufsize is set to a smaller value than described above, only bufsize bytes of the comment, without a NULL terminator, are returned in comment.

If an object does not have a comment, the empty string is returned in comment.

lapl_id contains a link access property list identifier. A link access propety list can come into play when traversing links to access an object.

Parameters:
hid_t loc_id IN: Identifier of a file, group, dataset, or named datatype.
const char *name     IN: Name of the object whose comment is to be retrieved, specified as a path relative to loc_id.
name can be '.' (a dot) if loc_id fully specifies the object for which the associated comment is to be retrieved.
char *comment OUT: The comment.
size_t bufsize IN: Anticipated required size of the comment buffer.
hid_t lapl_id IN: Link access property list identifier.

Returns:
Upon success, returns the number of characters in the comment, not including the NULL terminator, or zero (0) if the object has no comment. The value returned may be larger than bufsize. Otherwise returns a negative value.

Fortran90 Interface: h5oget_comment_by_name_f
Signature:

  SUBROUTINE h5oget_comment_by_name_f(loc_id, name,    &
        comment, hdferr, bufsize, lapl_id)
    IMPLICIT NONE
    INTEGER(HID_T)  , INTENT(IN)            :: loc_id
    CHARACTER(LEN=*), INTENT(IN)            :: name
    CHARACTER(LEN=*), INTENT(OUT)           :: comment
    INTEGER         , INTENT(OUT)           :: hdferr
    INTEGER(SIZE_T) , INTENT(OUT), OPTIONAL :: bufsize 
    INTEGER(HID_T)  , INTENT(IN) , OPTIONAL :: lapl_id 

Inputs:

  loc_id   - Identifier of a file, group, dataset, or named datatype.
  name     - Name of the object whose comment is to be retrieved, 
             specified as a path relative to loc_id. 

Outputs:

  comment  - The comment.
  hdferr   - Returns 0 if successful and -1 if fails.

Optional parameters:

  bufsize  - Size of the comment buffer.

History:
Release     C
1.8.11 Fortran subroutine introduced in this release.
1.8.0 Function introduced in this release.

Last modified: 11 May 2015
Name: H5Oget_info
Signature:
herr_t H5Oget_info( hid_t object_id, H5O_info_t *object_info )

Purpose:
Retrieves the metadata for an object specified by an identifier.

Description:
H5Oget_info specifies an object by its identifier, object_id, and retrieves the metadata describing that object in object_info, an H5O_info_t struct.

An H5O_info_t struct is defined (in H5Opublic.h) as follows :

typedef struct H5O_info_t {
    unsigned long       fileno;     /* Number of file where object is       */
                                    /*   located                            */
    haddr_t             addr;       /* Object address in file               */
    H5O_type_t          type;       /* Basic object type                    */
                                    /*   (See H5O_type_t below)             */
    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            */
                                    /*   (See H5O_hdr_info_t below)         */
    struct {
                                    /* Extra metadata storage for obj &     */
                                    /*   attributes                         */
        H5_ih_info_t    obj;        /* v1/v2 B-tree & local/fractal heap    */
                                    /*   for groups, B-tree for chunked     */
                                    /*   datasets.                          */
                                    /*   For internal library use only.     */
        H5_ih_info_t    attr;       /* v2 B-tree & heap for attributes.     */
                                    /*   For internal library use only.     */
    } meta_size;
} H5O_info_t;
    

Note the following about H50_info_t:

Of the four time fields (atime, mtime, ctime, and btime) only ctime has been implemented.

The atime value is the last time the object was read or written.

The mtime value is the last time the raw data in the object was changed.

The ctime value is the last time the metadata for the object was changed.

The btime value is the time the object was created.

The fields nested in the meta_size field are for internal library use only.


An H5O_type_t enum indicates the object type and is defined (in H5Opublic.h) as follows:

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 committed (named) datatype   */
    H5O_TYPE_NTYPES             /* Number of different object types (must   */
                                /* be last!)                                */
} H5O_type_t;
    

Note that object_id refers only to the types specified by H5O_type_t.


An H5O_hdr_info_t struct holds object header metadata and is defined (in H5Opublic.h) as follows:

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;
    

Valid values for the version field are H5O_VERSION_1 and H5O_VERSION_2. Version 2 of the object header is smaller and more efficient than version 1.

Note that the information held by H5O_hdr_info_t might be useful only to developers with extensive HDF5 experience.


Parameters:
hid_t object_id IN: Identifier for object of type specified by H5O_type_t
H5O_info_t *object_info     OUT: Buffer in which to return object information

Returns:
Returns a non-negative value if successful; otherwise returns a negative value.

Fortran2003 Interface: h5oget_info_f
Signature:

  SUBROUTINE h5oget_info_f(object_id, object_info, hdferr)

    USE, INTRINSIC :: ISO_C_BINDING
    IMPLICIT NONE
    INTEGER(HID_T)  , INTENT(IN)            :: object_id
    TYPE(h5o_info_t), INTENT(OUT), TARGET   :: object_info
    INTEGER         , INTENT(OUT)           :: hdferr

Inputs:

  object_id   - Identifier for target object.

Outputs:

  object_info - Buffer in which to return object information.
  hdferr      - Returns 0 if successful and -1 if fails.

 

Related Fortran2003 Derived Type: h5o_info_t

  TYPE, BIND(C) :: space_t
     INTEGER(hsize_t) :: total ! Total space for storing object header in file
     INTEGER(hsize_t) :: meta  ! Space within header for object header metadata 
                               ! information
     INTEGER(hsize_t) :: mesg  ! Space within header for actual message 
                               ! information
     INTEGER(hsize_t) :: free  ! Free space within object header
  END TYPE space_t

  TYPE, BIND(C) :: mesg_t
     INTEGER(c_int64_t) :: present ! Flags to indicate presence of message type 
                                   ! in header 
     INTEGER(c_int64_t) :: shared  ! Flags to indicate message type is shared 
                                   ! in header
  END TYPE mesg_t
  
  TYPE, BIND(C) :: hdr_t
     INTEGER :: version ! Version number of header format in file
     INTEGER :: nmesgs  ! Number of object header messages
     INTEGER :: nchunks ! Number of object header chunks
     INTEGER :: flags   ! Object header status flags
     TYPE(space_t)  :: space   
     TYPE(mesg_t)   :: mesg
  END TYPE hdr_t

  ! Extra metadata storage for obj & attributes
  TYPE, BIND(C) :: H5_ih_info_t
     INTEGER(hsize_t) :: index_size ! btree and/or list
     INTEGER(hsize_t) :: heap_size
  END TYPE H5_ih_info_t

  TYPE, BIND(C) :: meta_size_t
     TYPE(H5_ih_info_t) :: obj  ! v1/v2 B-tree & local/fractal heap for 
                                ! groups, B-tree for chunked datasets
     TYPE(H5_ih_info_t) :: attr ! v2 B-tree & heap for attributes
  ENDTYPE meta_size_t
  
  TYPE, BIND(C) :: h5o_info_t
     INTEGER(C_LONG)  :: fileno     ! File number that object is located in
     INTEGER(haddr_t) :: addr       ! Object address in file  
     INTEGER(C_INT)   :: type       ! Basic object type (group, dataset, etc.) 
     INTEGER          :: rc         ! Reference count of object

     INTEGER, DIMENSION(8) :: atime ! Access time        !    -- NOTE --
     INTEGER, DIMENSION(8) :: mtime ! Modification time  ! Returns an integer 
     INTEGER, DIMENSION(8) :: ctime ! Change time        ! array as specified 
     INTEGER, DIMENSION(8) :: btime ! Birth time         ! in Fortran intrinsic 
                                                         ! DATE_AND_TIME(VALUES)

     INTEGER(hsize_t) :: num_attrs  ! # of attributes attached to object

     TYPE(hdr_t) :: hdr

     TYPE(meta_size_t) :: meta_size
  END TYPE h5o_info_t

History:
Release     Change
1.8.15 Added a note about the valid values for the version field in the H5O_hdr_info_t structure.
1.8.11 Fortran subroutine introduced in this release.
1.8.10 Added H5O_type_t structure to the Description section.
Separated H5O_hdr_info_t structure from H5O_info_t in the Description section.
Clarified the definition and implementation of the time fields.
1.8.0 Function introduced in this release.

Last modified: 15 April 2013
Name: H5Oget_info_by_idx
Signature:
herr_t H5Oget_info_by_idx( hid_t loc_id, const char *group_name, H5_index_t index_field, H5_iter_order_t order, hsize_t n, H5O_info_t *object_info, hid_t lapl_id )

Purpose:
Retrieves the metadata for an object, identifying the object by an index position.

Description:
H5Oget_info_by_idx specifies a location, loc_id; a group name, group_name; an index by which obects in that group are tracked, index_field; the order by which the index is to be traversed, order; and an object’s position n within that index and retrieves the metadata describing that object in the struct object_info.

object_info, in which the object information is returned, is a struct of type H5O_info_t. This struct type is described in the H5Oget_info function entry.

If loc_id fully specifies the group in which the object resides, group_name can be a dot (.).

The link access property list, lapl_id, is not currently used; it should be passed in as NULL.

Parameters:
hid_t loc_id IN: File or group identifier specifying location of group in which object is located
const char *group_name     IN: Name of group in which object is located
H5_index_t index_field IN: Index or field that determines the order
H5_iter_order_t order IN: Order within field or index
hsize_t n IN: Object for which information is to be returned
H5O_info_t *object_info OUT: Buffer in which to return object information
hid_t lapl_id IN: Link access property list
(Not currently used; pass as NULL.)

Returns:
Returns a non-negative value if successful; otherwise returns a negative value.

Fortran2003 Interface: h5oget_info_by_idx_f
Signature:

  SUBROUTINE h5oget_info_by_idx_f(loc_id, group_name, index_field, order, n, &
       object_info, hdferr, lapl_id)

    USE, INTRINSIC :: ISO_C_BINDING
    IMPLICIT NONE
    INTEGER(HID_T)  , INTENT(IN)            :: loc_id
    CHARACTER(LEN=*), INTENT(IN)            :: group_name
    INTEGER         , INTENT(IN)            :: index_field
    INTEGER         , INTENT(IN)            :: order
    INTEGER(HSIZE_T), INTENT(IN)            :: n
    TYPE(h5o_info_t), INTENT(OUT), TARGET   :: object_info
    INTEGER         , INTENT(OUT)           :: hdferr
    INTEGER(HID_T)  , INTENT(IN) , OPTIONAL :: lapl_id

Inputs:

  loc_id      - File or group identifier specifying location of group 
                in which object is located.
  group_name  - Name of group in which object is located.
  index_field - Index or field that determines the order.
  order       - Order within field or index.
  n           - Object for which information is to be returned

Outputs:

  object_info - Buffer in which to return object information.
  hdferr      - Returns 0 if successful and -1 if fails.

Optional parameters:

  lapl_id     - Link access property list. (Not currently used.)

 

Related Fortran2003 Derived Type: h5o_info_t

  TYPE, BIND(C) :: space_t
     INTEGER(hsize_t) :: total ! Total space for storing object header in file
     INTEGER(hsize_t) :: meta  ! Space within header for object header metadata 
                               ! information
     INTEGER(hsize_t) :: mesg  ! Space within header for actual message 
                               ! information
     INTEGER(hsize_t) :: free  ! Free space within object header
  END TYPE space_t

  TYPE, BIND(C) :: mesg_t
     INTEGER(c_int64_t) :: present ! Flags to indicate presence of message type 
                                   ! in header 
     INTEGER(c_int64_t) :: shared  ! Flags to indicate message type is shared 
                                   ! in header
  END TYPE mesg_t
  
  TYPE, BIND(C) :: hdr_t
     INTEGER :: version ! Version number of header format in file
     INTEGER :: nmesgs  ! Number of object header messages
     INTEGER :: nchunks ! Number of object header chunks
     INTEGER :: flags   ! Object header status flags
     TYPE(space_t)  :: space   
     TYPE(mesg_t)   :: mesg
  END TYPE hdr_t

  ! Extra metadata storage for obj & attributes
  TYPE, BIND(C) :: H5_ih_info_t
     INTEGER(hsize_t) :: index_size ! btree and/or list
     INTEGER(hsize_t) :: heap_size
  END TYPE H5_ih_info_t

  TYPE, BIND(C) :: meta_size_t
     TYPE(H5_ih_info_t) :: obj  ! v1/v2 B-tree & local/fractal heap for 
                                ! groups, B-tree for chunked datasets
     TYPE(H5_ih_info_t) :: attr ! v2 B-tree & heap for attributes
  ENDTYPE meta_size_t
  
  TYPE, BIND(C) :: h5o_info_t
     INTEGER(C_LONG)  :: fileno     ! File number that object is located in
     INTEGER(haddr_t) :: addr       ! Object address in file  
     INTEGER(C_INT)   :: type       ! Basic object type (group, dataset, etc.) 
     INTEGER          :: rc         ! Reference count of object

     INTEGER, DIMENSION(8) :: atime ! Access time        !    -- NOTE --
     INTEGER, DIMENSION(8) :: mtime ! Modification time  ! Returns an integer 
     INTEGER, DIMENSION(8) :: ctime ! Change time        ! array as specified 
     INTEGER, DIMENSION(8) :: btime ! Birth time         ! in Fortran intrinsic 
                                                         ! DATE_AND_TIME(VALUES)

     INTEGER(hsize_t) :: num_attrs  ! # of attributes attached to object

     TYPE(hdr_t) :: hdr

     TYPE(meta_size_t) :: meta_size
  END TYPE h5o_info_t

History:
Release     C
1.8.11 Fortran subroutine introduced in this release.
1.8.0 Function introduced in this release.

Last modified: 15 April 2013
Name: H5Oget_info_by_name
Signature:
herr_t H5Oget_info_by_name( hid_t loc_id, const char *object_name, H5O_info_t *object_info, hid_t lapl_id )

Purpose:
Retrieves the metadata for an object, identifying the object by location and relative name.

Description:
H5Oget_info_by_name specifies an object’s location and name, loc_id and object_name, respectively, and retrieves the metadata describing that object in object_info, an H5O_info_t struct.

The struct H5O_info_t is defined in H5Opublic.h and described in the H5Oget_info function entry.

The link access property list, lapl_id, is not currently used; it should be passed in as H5P_DEFAULT.

Parameters:
hid_t loc_id IN: File or group identifier specifying location of group in which object is located
const char *name IN: Name of group, relative to loc_id
H5O_info_t *object_info     OUT: Buffer in which to return object information
hid_t lapl_id IN: Link access property list
(Not currently used; pass as H5P_DEFAULT.)

Returns:
Returns a non-negative value if successful; otherwise returns a negative value.

Fortran2003 Interface: h5oget_info_by_name_f
Signature:

  SUBROUTINE h5oget_info_by_name_f(loc_id, name, object_info, hdferr,  &
        lapl_id)

    INTEGER(HID_T)  , INTENT(IN)            :: loc_id
    CHARACTER(LEN=*), INTENT(IN)            :: name
    TYPE(h5o_info_t), INTENT(OUT), TARGET   :: object_info
    INTEGER         , INTENT(OUT)           :: hdferr
    INTEGER(HID_T)  , INTENT(IN) , OPTIONAL :: lapl_id

Inputs:

  loc_id      - File or group identifier specifying location of group 
                in which object is located.
  name        - Name of group, relative to loc_id.

Outputs:

  object_info - Buffer in which to return object information.
  hdferr      - Returns 0 if successful and -1 if fails.

Optional parameters:

  lapl_id     - Link access property list.

 

Related Fortran2003 Derived Type: h5o_info_t

  TYPE, BIND(C) :: space_t
     INTEGER(hsize_t) :: total ! Total space for storing object header in file
     INTEGER(hsize_t) :: meta  ! Space within header for object header metadata 
                               ! information
     INTEGER(hsize_t) :: mesg  ! Space within header for actual message 
                               ! information
     INTEGER(hsize_t) :: free  ! Free space within object header
  END TYPE space_t

  TYPE, BIND(C) :: mesg_t
     INTEGER(c_int64_t) :: present ! Flags to indicate presence of message type 
                                   ! in header 
     INTEGER(c_int64_t) :: shared  ! Flags to indicate message type is shared 
                                   ! in header
  END TYPE mesg_t
  
  TYPE, BIND(C) :: hdr_t
     INTEGER :: version ! Version number of header format in file
     INTEGER :: nmesgs  ! Number of object header messages
     INTEGER :: nchunks ! Number of object header chunks
     INTEGER :: flags   ! Object header status flags
     TYPE(space_t)  :: space   
     TYPE(mesg_t)   :: mesg
  END TYPE hdr_t

  ! Extra metadata storage for obj & attributes
  TYPE, BIND(C) :: H5_ih_info_t
     INTEGER(hsize_t) :: index_size ! btree and/or list
     INTEGER(hsize_t) :: heap_size
  END TYPE H5_ih_info_t

  TYPE, BIND(C) :: meta_size_t
     TYPE(H5_ih_info_t) :: obj  ! v1/v2 B-tree & local/fractal heap for 
                                ! groups, B-tree for chunked datasets
     TYPE(H5_ih_info_t) :: attr ! v2 B-tree & heap for attributes
  ENDTYPE meta_size_t
  
  TYPE, BIND(C) :: h5o_info_t
     INTEGER(C_LONG)  :: fileno     ! File number that object is located in
     INTEGER(haddr_t) :: addr       ! Object address in file  
     INTEGER(C_INT)   :: type       ! Basic object type (group, dataset, etc.) 
     INTEGER          :: rc         ! Reference count of object

     INTEGER, DIMENSION(8) :: atime ! Access time        !    -- NOTE --
     INTEGER, DIMENSION(8) :: mtime ! Modification time  ! Returns an integer 
     INTEGER, DIMENSION(8) :: ctime ! Change time        ! array as specified 
     INTEGER, DIMENSION(8) :: btime ! Birth time         ! in Fortran intrinsic 
                                                         ! DATE_AND_TIME(VALUES)

     INTEGER(hsize_t) :: num_attrs  ! # of attributes attached to object

     TYPE(hdr_t) :: hdr

     TYPE(meta_size_t) :: meta_size
  END TYPE h5o_info_t

History:
Release     Change
1.8.0 C function introduced in this release.
1.8.8 Fortran 2003 subroutine and h5o_info_t derived type introduced in this release.

Last modified: 10 April 2013
Name: H5Oincr_refcount
Signature:
herr_t H5Oincr_refcount( hid_t object_id )

Purpose:
Increments an object reference count.

Description:
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 rc field of the H5O_info_t struct.

Warning: This function must be used with care!
Improper use can lead to inaccessible data, wasted space in the file, or file corruption.

Parameters:
    hid_t object_id     IN: Object identifier

Returns:
Returns a non-negative value if successful; otherwise returns a negative value.

Fortran90 Interface: h5oincr_refcount_f
Signature:

  SUBROUTINE h5oincr_refcount_f(obj_id, hdferr)
    IMPLICIT NONE
    INTEGER(HID_T), INTENT(IN)  :: obj_id
    INTEGER       , INTENT(OUT) :: hdferr

Inputs:

  obj_id  - Object identifier.

Outputs:

  hdferr  - Returns 0 if successful and -1 if fails.

History:
Release     Change
1.8.11 Fortran subroutine introduced in this release.
1.8.0 Function introduced in this release.

Last modified: 23 August 2013
Name: H5Olink
Signature:
herr_t H5Olink( hid_t object_id, hid_t new_loc_id, const char *new_link_name, hid_t lcpl, hid_t lapl )

Purpose:
Creates a hard link to an object in an HDF5 file.

Description:
H5Olink creates a new hard link to an object in an HDF5 file.

new_loc_id and new_name specify the location and name of the new link while 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.
  • lcpl and lapl are the link creation and access property lists associated with the new link.

    Parameters:
    hid_t object_id IN: Object to be linked.
    hid_t new_loc_id IN: File or group identifier specifying location at which object is to be linked.
    const char *new_link_name     IN: Name of link to be created, relative to new_loc_id.
    hid_t lcpl_id IN: Link creation property list identifier.
    hid_t lapl_id IN: Link access property list identifier.

    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:
        hid_t lcpl_id = H5Pcreate(H5P_LINK_CREATE);  
                                           /* Creates a link creation property
                                           * list (LCPL).                     */
        int status = H5Pset_create_intermediate_group(lcpl_id, TRUE);
                                           /* Sets "create missing intermediate
                                            * groups" property in that LCPL.  */
        hid_t gid  = H5Gcreate_anon(file_id, H5P_DEFAULT, H5P_DEFAULT);
                                           /* Creates a group without linking 
                                            * it into the file structure.     */
        status     = H5Olink(obj_id, file_id, "/A/B01/C", lcpl_id, H5P_DEFAULT);
                                           /* Links group into file structure.*/
    

    Note that unless the object is intended to be temporary, the H5Olink call is mandatory if an object created with one of the H5*create_anon functions (or with H5Tcommit_anon) is to be retained in the file; without an H5Olink call, the object will not be linked into the HDF5 file structure and will be deleted when the file is closed.

    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value.

    Fortran90 Interface: h5olink_f
    Signature:

      SUBROUTINE h5olink_f(object_id, new_loc_id, new_link_name,  &
                hdferr, lcpl_id, lapl_id)
        IMPLICIT NONE
        INTEGER(HID_T)  , INTENT(IN)  :: object_id
        INTEGER(HID_T)  , INTENT(IN)  :: new_loc_id
        CHARACTER(LEN=*), INTENT(IN)  :: new_link_name
        INTEGER         , INTENT(OUT) :: hdferr
        INTEGER(HID_T)  , INTENT(IN), OPTIONAL :: lcpl_id
        INTEGER(HID_T)  , INTENT(IN), OPTIONAL :: lapl_id
    

    Inputs:

      object_id     - Object to be linked.
      new_loc_id    - File or group identifier specifying location at 
                      which object is to be linked.
      new_link_name - Name of link to be created, relative to new_loc_id.
    

    Outputs:

      hdferr        - Returns 0 if successful and -1 if fails.
    

    Optional parameters:

      lcpl_id       - Link creation property list identifier.
      lapl_id       - Link access property list identifier.
    

    See Also:
    H5Dcreate_anon
    H5Gcreate_anon
    H5Tcommit_anon

    History:
    Release     C
    1.8.1 Fortran subroutine introduced in this release.
    1.8.0 Function introduced in this release.

    Last modified: 14 October 2014
    Name: H5Oopen

    Signature:
    hid_t H5Oopen( hid_t loc_id, const char *name, hid_t lapl_id )

    Purpose:
    Opens an object in an HDF5 file by location identifier and path name.

    Description:
    H5Oopen opens a group, dataset, or committed (named) datatype specified by a location, loc_id, and a path name, 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.

    loc_id can be either a file or group identifier. name must be the path to that object relative to loc_id.

    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.

    Parameters:
      hid_t loc_id IN: File or group identifier
      const char *name     IN: Path to the object, relative to loc_id.
      hid_t lapl_id IN: Access property list identifier for the link pointing to the object

    Returns:
    Returns an object identifier for the opened object if successful; otherwise returns a negative value.

    Fortran90 Interface: h5oopen_f
    Signature:

      SUBROUTINE h5oopen_f(loc_id, name, obj_id, hdferr, lapl_id)
        IMPLICIT NONE
        INTEGER(HID_T)  , INTENT(IN)  :: loc_id
        CHARACTER(LEN=*), INTENT(IN)  :: name
        INTEGER(HID_T)  , INTENT(OUT) :: obj_id
        INTEGER         , INTENT(OUT) :: hdferr
        INTEGER(HID_T)  , INTENT(IN), OPTIONAL :: lapl_id
    

    Inputs:

      loc_id  - File or group identifier.
      name    - Path to the object, relative to loc_id.
    

    Outputs:

      obj_id  - Object identifier for the opened object.
      hdferr  - Returns 0 if successful and -1 if fails.
    

    Optional parameters:

      lapl_id - Access property list identifier for the 
                link pointing to the object.
    

    See Also:
    “Using Identifiers”

    History:
    Release     C
    1.8.1 Fortran subroutine introduced in this release.
    1.8.0 Function introduced in this release.

    Last modified: 14 October 2014
    Name: H5Oopen_by_addr

    Signature:
    hid_t H5Oopen_by_addr( hid_t loc_id, haddr_t addr )

    Purpose:
    Opens an object using its address within an HDF5 file.

    Description:
    H5Oopen_by_addr opens a group, dataset, or committed (named) datatype using its address within an HDF5 file, 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.

    loc_id can be either the file identifier or a group identifier in the file. In either case, the HDF5 Library uses the identifier only to identify the file.

    The object’s address within the file, 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’ Guide).

    addr can be obtained via either of two function calls. H5Gget_objinfo returns the object’s address in the objno field of the H5G_stat_t struct; H5Lget_info returns the address in the address field of the H5L_linkinfo_t struct.

    Warning: This function must be used with care!
    Improper use can lead to inaccessible data, wasted space in the file, or file corruption.

    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_linkinfo 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.

     

    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.

    Parameters:
      hid_t loc_id IN: File or group identifier
      haddr_t addr     IN: Object’s address in the file

    Returns:
    Returns an object identifier for the opened object if successful; otherwise returns a negative value.

    Fortran90 Interface: h5oopen_by_addr_f
    Signature:

      SUBROUTINE h5oopen_by_addr_f(loc_id, addr, obj_id, hdferr)
        IMPLICIT NONE
        INTEGER(HID_T)  , INTENT(IN)  :: loc_id
        INTEGER(HADDR_T), INTENT(IN)  :: addr
        INTEGER(HID_T)  , INTENT(OUT) :: obj_id
        INTEGER         , INTENT(OUT) :: hdferr
    

    Inputs:

      loc_id - File or group identifier.
      addr   - Object's address in the file.
    

    Outputs:

      obj_id - Object identifier for the opened object.
      hdferr - Returns 0 if successful and -1 if fails.
    

    See Also:
    “Using Identifiers”

    History:
    Release     Change
    1.8.0 Function introduced in this release.
    1.8.4 Fortran subroutine added in this release.

    Last modified: 14 October 2014
    Name: H5Oopen_by_idx

    Signature:
    hid_t H5Oopen_by_idx( hid_t loc_id, const char *group_name, H5_index_t index_type, H5_iter_order_t order, hsize_t n, hid_t lapl_id )

    Purpose:
    Open the nth object in a group.

    Description:
    H5Oopen_by_idx opens the nth object in the group specified by loc_id and group_name.

    loc_id specifies a file or group. group_name specifies the group relative to loc_id in which the object can be found. If loc_id fully specifies the group in which the object resides, group_name can be a dot (.).

    The specific object to be opened within the group is specified by index_type, order, and n as follows:

    • index_type specifies the type of index by which objects are ordered. Valid index types include H5_INDEX_NAME, indexed by name, and H5_INDEX_CRT_ORDER, indexed by creation order.
    • order specifies the order in which the links are to be referenced for the purposes of this function. Valid orders include H5_ITER_INC for increasing order, H5_ITER_DEC for decreasing order, and H5_ITER_NATIVE. Rather than implying a particular order, H5_ITER_NATIVE instructs the HDF5 Library to iterate through the objects in the fastest available order, i.e., in a natural order.
    • 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 n is 5, the function will return the value of the sixth object; etc.

    If 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.

    Parameters:
    hid_t loc_id IN: A file or group identifier.
    const char *group_name     IN: Name of group, relative to loc_id, in which object is located
    H5_index_t index_type IN: Type of index by which objects are ordered
    H5_iter_order_t order IN: Order of iteration within index
    hsize_t n IN: Object to open
    hid_t lapl_id IN: Link access property list

    Returns:
    Returns an object identifier for the opened object if successful; otherwise returns a negative value.

    Fortran90 Interface: h5oopen_by_idx_f
    Signature:

      SUBROUTINE h5oopen_by_idx_f(loc_id, group_name, index_type, order, n, &
           obj_id, hdferr, lapl_id)
        IMPLICIT NONE
        INTEGER(HID_T)  , INTENT(IN)            :: loc_id
        CHARACTER(LEN=*), INTENT(IN)            :: group_name
        INTEGER         , INTENT(IN)            :: index_type
        INTEGER         , INTENT(IN)            :: order
        INTEGER(HSIZE_T), INTENT(IN)            :: n
        INTEGER(HID_T)  , INTENT(OUT)           :: obj_id
        INTEGER         , INTENT(OUT)           :: hdferr
        INTEGER(HID_T)  , INTENT(IN) , OPTIONAL :: lapl_id
    

    Inputs:

      loc_id      - A file or group identifier.
      group_name  - Name of group, relative to loc_id, in which object is located.
      index_type  - Type of index by which objects are ordered.
      order       - Order of iteration within index, NOTE: zero-based.
      n           - Object to open.
    

    Outputs:

      obj_id      - An object identifier for the opened object.
      hdferr      - Returns 0 if successful and -1 if fails.
    

    Optional parameters:

      lapl_id     - Link access property list.
    

    See Also:
    “Using Identifiers”

    History:
    Release     C
    1.8.11 Fortran subroutine introduced in this release.
    1.8.0 Function introduced in this release.

    Last modified: 10 April 2013
    Name: H5Oset_comment
    Signature:
    herr_t H5Oset_comment( hid_t object_id, const char *comment )

    Purpose:
    Sets comment for specified object.

    Deprecated Function:
    This function is deprecated in favor of object attributes.

    Description:
    H5Oset_comment sets the comment for the specified object to the contents of comment. Any previously existing comment is overwritten.

    The target object is specified by an identifier, object_id.

    If 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.

    Parameters:
    hid_t object_id     IN: Identifier of the target object
    const char *comment     IN: The new comment.

    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value.

    Fortran90 Interface: h5oset_comment_f
    Signature:

      SUBROUTINE h5oset_comment_f(obj_id, comment, hdferr)
        IMPLICIT NONE
        INTEGER(HID_T)  , INTENT(IN)  :: obj_id
        CHARACTER(LEN=*), INTENT(IN)  :: comment
        INTEGER         , INTENT(OUT) :: hdferr
    

    Inputs:

      obj_id    - Identifier of the target object.
      comment   - The new comment.
    

    Outputs:

      hdferr    - Returns 0 if successful and -1 if fails.
    

    History:
    Release     C
    1.8.11 Fortran subroutine introduced in this release.
    1.8.0 Function introduced in this release.

    Last modified: 10 April 2013
    Name: H5Oset_comment_by_name
    Signature:
    herr_t H5Oset_comment_by_name( hid_t loc_id, const char *name, const char *comment, hid_t lapl_id )

    Purpose:
    Sets comment for specified object.

    Deprecated Function:
    This function is deprecated in favor of object attributes.

    Description:
    H5Oset_comment_by_name sets the comment for the specified object to the contents of comment. Any previously existing comment is overwritten.

    The target object is specified by loc_id and name. loc_id can specify any object in the file. name can be one of the following:
      — The name of the object relative to loc_id
      — An absolute name of the object, starting from /, the file’s root group
      — A dot (.), if loc_id fully specifies the object

    If 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.

    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.

    Parameters:
    hid_t loc_id IN: Identifier of a file, group, dataset, or named datatype.
    const char *name IN: Name of the object whose comment is to be set or reset, specified as a path relative to loc_id.
    name can be '.' (a dot) if loc_id fully specifies the object for which the comment is to be set.
    const char *comment     IN: The new comment.
    hid_t lapl_id IN: Link access property list identifier.

    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value.

    Fortran90 Interface: h5oset_comment_by_name_f
    Signature:

      SUBROUTINE h5oset_comment_by_name_f(loc_id, name, comment, hdferr, &
            lapl_id)
        IMPLICIT NONE
        INTEGER(HID_T)  , INTENT(IN)  :: loc_id
        CHARACTER(LEN=*), INTENT(IN)  :: name
        CHARACTER(LEN=*), INTENT(IN)  :: comment
        INTEGER         , INTENT(OUT) :: hdferr
        INTEGER(HID_T)  , INTENT(IN), OPTIONAL :: lapl_id
    

    Inputs:

      loc_id   - Identifier of a file, group, dataset, or named datatype.
      name     - Name of the object whose comment is to be set or reset, 
                  specified as a path relative to loc_id. 
      comment  - The new comment.
    

    Outputs:

      hdferr   - Returns 0 if successful and -1 if fails.
    

    Optional parameters:

      lapl_id  - Link access property list identifier.
    

    History:
    Release     C
    1.8.11 Fortran subroutine introduced in this release.
    1.8.0 Function introduced in this release.

    Last modified: 10 April 2013
    Name: H5Ovisit
    Signature:
    herr_t H5Ovisit( hid_t object_id, H5_index_t index_type, H5_iter_order_t order, H5O_iterate_t op, void *op_data )

    Purpose:
    Recursively visits all objects accessible from a specified object.

    Description:
    H5Ovisit is a recursive iteration function to visit the object object_id and, if object_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 object_id is a group identifier, that group serves as the root of a recursive iteration. If object_id is a file identifier, that file’s root group serves as the root of the recursive iteration. If object_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: index_type and order.

    index_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 unnecesary, so the iteration may begin more quickly. Valid values include the following:
         H5_INDEX_NAME Alpha-numeric index on name
         H5_INDEX_CRT_ORDER     Index on creation order

    Note that the index type passed in index_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.)

    order specifies the order in which objects are to be inspected along the index specified in index_type. Valid values include the following:
         H5_ITER_INC Increasing order
         H5_ITER_DEC Decreasing order
         H5_ITER_NATIVE     Fastest available order

    The protoype of the callback function op is as follows (as defined in the source code file H5Opublic.h):

    herr_t (*H5O_iterate_t)( hid_t o_id, const char *name, const H5O_info_t *object_info, void *op_data)

    The parameters of this callback function have the following values or meanings:
         o_id Object that serves as root of the iteration; same value as the H5Ovisit object_id parameter
         name Name of object, relative to o_id, being examined at current step of the iteration
         object_info     H5O_info_t struct containing information regarding that object
         op_data User-defined pointer to data required by the application in processing the object; a pass-through of the op_data pointer provided with the H5Ovisit_by_name function call

    The H5O_info_t struct is defined in H5Opublic.h and described in the H5Oget_info function entry.

    The return values from an operator are:

    • Zero causes the visit iterator to continue, returning zero when all group members have been processed.
    • A positive value causes the visit iterator to immediately return that positive value, indicating short-circuit success.
    • A negative value causes the visit iterator to immediately return that value, indicating failure.

    The H5Ovisit 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 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.

    Programming Note for C++ Developers Using C Functions:

    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.

    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.

    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.

    Parameters:
    hid_t object_id IN: Identifier of the object at which the recursive iteration begins.
    H5_index_t index_type IN: Type of index; valid values include:
             H5_INDEX_NAME
             H5_INDEX_CRT_ORDER
    H5_iter_order_t order     IN: Order in which index is traversed; valid values include:
             H5_ITER_DEC
             H5_ITER_INC
             H5_ITER_NATIVE
    H5O_iterate_t op IN: Callback function passing data regarding the object to the calling application
    void *op_data IN: User-defined pointer to data required by the application for its processing of the object

    Returns:
    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.

    On failure, returns a negative value if something goes wrong within the library, or the first negative value returned by an operator.

    Fortran2003 Interface: h5ovisit_f
    Signature:

      SUBROUTINE h5ovisit_f(object_id, index_type, order, op, op_data, &
                return_value, hdferr)
        INTEGER(HID_T), INTENT(IN) :: object_id
        INTEGER, INTENT(IN) :: index_type 
        INTEGER, INTENT(IN) :: order
    
        TYPE(C_FUNPTR):: op
        TYPE(C_PTR)   :: op_data
        INTEGER, INTENT(OUT) :: return_value
        INTEGER, INTENT(OUT) :: hdferr
    

    Inputs:

      object_id  - Identifier of the object at which the recursive iteration 
                    begins.
      index_type - Type of index; valid values include:
                    H5_INDEX_NAME_F
                    H5_INDEX_CRT_ORDER_F
      order      - Order in which index is traversed; valid values include:
                    H5_ITER_DEC_F
                    H5_ITER_INC_F
                    H5_ITER_NATIVE_F
      op         - Callback function passing data regarding the group to the 
                   calling application
      op_data    - User-defined pointer to data required by the application 
                   for its processing of the group
    

    Outputs:

      return_value - 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.
      hdferr       - Returns 0 if successful and -1 if fails.
    

    History:
    Release     Change
    1.8.8 Fortran subroutine and data structure added.
    1.8.0 C function introduced.

    Last modified: 10 April 2013
    Name: H5Ovisit_by_name
    Signature:
    herr_t H5Ovisit_by_name( hid_t loc_id, const char *object_name, H5_index_t index_type, H5_iter_order_t order, H5O_iterate_t op, void *op_data, hid_t lapl_id )

    Purpose:
    Recursively visits all objects starting from a specified object.

    Description:
    H5Ovisit_by_name is a recursive iteration function to visit the object specified by the loc_id / object_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 loc_id / object_name parameter pair. loc_id specifies a file or an object in a file; object_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 loc_id. If loc_id fully specifies the object that is to serve as the root of the iteration, object_name should be '.' (a dot). (Note that when loc_id fully specifies the 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: index_type and order.

    index_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 unnecesary, so the iteration may begin more quickly. Valid values include the following:
         H5_INDEX_NAME Alpha-numeric index on name
         H5_INDEX_CRT_ORDER     Index on creation order

    Note that the index type passed in index_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.)

    order specifies the order in which objects are to be inspected along the index specified in index_type. Valid values include the following:
         H5_ITER_INC Increasing order
         H5_ITER_DEC Decreasing order
         H5_ITER_NATIVE     Fastest available order

    The op callback funtion and the effect of the callback function’s return value on the application are described in H5Ovisit.

    The H5O_info_t struct is defined in H5Opublic.h and described in the H5Oget_info function entry.

    The H5Ovisit_by_name 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 op_data parameter.

    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.

    Programming Note for C++ Developers Using C Functions:

    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.

    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.

    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.

    Parameters:
    hid_t loc_id IN: Identifier of a file or group
    const char *object_name IN: Name of the object, generally relative to loc_id, that will serve as root of the iteration
    H5_index_t index_type IN: Type of index; valid values include:
             H5_INDEX_NAME
             H5_INDEX_CRT_ORDER
    H5_iter_order_t order     IN: Order in which index is traversed; valid values include:
             H5_ITER_DEC
             H5_ITER_INC
             H5_ITER_NATIVE
    H5O_iterate_t op IN: Callback function passing data regarding the object to the calling application
    void *op_data IN: User-defined pointer to data required by the application for its processing of the object
    hid_t lapl_id IN: Link access property list identifier

    Returns:
    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.

    On failure, returns a negative value if something goes wrong within the library, or the first negative value returned by an operator.

    Fortran2003 Interface: h5ovisit_by_name_f
    Signature:

      SUBROUTINE h5ovisit_by_name_f(loc_id, object_name, index_type, order, &
           op, op_data, return_value, hdferr, lapl_id)
        USE, INTRINSIC :: ISO_C_BINDING
        IMPLICIT NONE
        INTEGER(HID_T)  , INTENT(IN)             :: loc_id
        CHARACTER(LEN=*), INTENT(IN)             :: object_name
        INTEGER         , INTENT(IN)             :: index_type 
        INTEGER         , INTENT(IN)             :: order
    
        TYPE(C_FUNPTR)                           :: op
        TYPE(C_PTR)                              :: op_data
        INTEGER         , INTENT(OUT)            :: return_value
        INTEGER         , INTENT(OUT)            :: hdferr
        INTEGER(HID_T)  , INTENT(IN) , OPTIONAL  :: lapl_id
    

    Inputs:

      loc_id      - Identifier of a file or group.
      object_name - Name of the object, generally relative to loc_id, that will 
                    serve as root of the iteration 
      index_type  - Type of index; valid values include:
                     H5_INDEX_NAME_F
                     H5_INDEX_CRT_ORDER_F
      order       - Order in which index is traversed; valid values include:
                     H5_ITER_DEC_F
                     H5_ITER_INC_F
                     H5_ITER_NATIVE_F
      op          - Callback function passing data regarding the group to the 
                    calling application
      op_data     - User-defined pointer to data required by the application for 
                    its processing of the group
    

    Outputs:

      return_value - 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.
      hdferr       - Returns 0 if successful and -1 if fails
    

    Optional parameters:

      lapl_id      - Link access property list identifier.
    

    History:
    Release     C
    1.8.11 Fortran subroutine introduced in this release.
    1.8.0 Function introduced in this release.

    Last modified: 17 April 2012
    Name: H5O_mcdt_search_cb_t
    Signature:
    typedef H5O_mcdt_search_ret_t ( *H5O_mcdt_search_cb_t )( void *op_data )

    Purpose:
    Provides the mechanism by which a user application may set an action for H5Ocopy to take after checking all suggested paths for a matching committed datatype but before starting the global search of the destination file.

    Description:
    H5O_mcdt_search_cb_t is the callback function that H5Ocopy will invoke if the callback is set and when the merge committed datatype feature is enabled in the object copy property list (see H5Pset_copy_object).

    After searching the list of suggested committed datatype paths, H5Ocopy will invoke this callback before searching all committed datatypes in the destination file. This allows a user application to add a customized step to the search process. The callback function is set with H5Pset_mcdt_search_cb and the search process is described in H5Padd_merge_committed_dtype_path.

    Valid return values from this callback function are as follows (defined in the enumerated datatype H5O_mcdt_search_ret_t in H5Opublic.h):
    H5O_MCDT_SEARCH_ERROR      Aborts H5Ocopy.
    H5O_MCDT_SEARCH_CONT   Continues the global search of all committed datatypes in the destination file.
    H5O_MCDT_SEARCH_STOP   Stops the search, but continues copying.

    Warning:
    If the callback’s return value is H5O_MCDT_SEARCH_ERROR, H5Ocopy will abort and the destination file may be left in an inconsistent or corrupted state.

    Parameters:
    void *op_data   IN/OUT: Pointer to user-defined input data. This is a pass-through of the data that was passed to H5Pset_mcdt_search_cb.

    Returns:
    Returns one of the H5O_MCDT_SEARCH_* values described above.

    Failure Modes:
    H5O_mcdt_search_cb_t failure modes are dependent on the implementation of the callback function.

    Example Usage:
    This example defines a callback function in the object copy property list to discontinue the global search if a matching committed datatype cannot be found among the suggested paths.
    /* The user-defined callback function */
    static H5O_mcdt_search_ret_t
    mcdt_search_cb(void *_udata)
    {
        H5O_mcdt_search_ret_t action = *((H5O_mcdt_search_ret_t *)_udata);
    
        return(action);
    }
    
    int main(void) {
        hid_t ocpypl_id = H5Pcreate(H5P_OBJECT_COPY);
    
        /* Enable the merging committed datatype feature. */
        H5Pset_copy_object(ocpypl_id, H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG);
    
        /* Add the path to search for a matching committed datatype. */
        H5Padd_merge_committed_dtype_path(ocpypl_id, "/group/committed_dtypeA");
    
        /*
         * Set the callback function to discontinue the global search
         * if H5Ocopy cannot find a matching committed datatype from the
         * above suggested path.
         */
        action = H5O_MCDT_SEARCH_STOP;
        H5Pset_mcdt_search_cb(ocpypl_id, mcdt_search_cb, &action);
    
        /* Do the copy. */
        H5Ocopy(...ocpypl_id...);
        ...
        ...
    }
            

    See Also:
    H5Ocopy
    H5Pset_copy_object
      H5Pset_mcdt_search_cb
    H5Pget_mcdt_search_cb

    Copying Committed Datatypes
        with H5Ocopy
     
    A comprehensive discussion of copying committed datatypes (PDF) in Advanced Topics in HDF5

    History:
    Release     Change
    1.8.9 C function type introduced in this release.

    HDF5 documents and links 
    Introduction to HDF5 
    HDF5 User’s Guide 
    In the HDF5 Reference Manual 
    H5DS   H5IM   H5LT   H5PT   H5TB  Optimized 
    H5   H5A   H5D   H5E   H5F   H5G   H5I   H5L 
    H5O   H5P   H5PL   H5R   H5S   H5T   H5Z 
    Tools   Datatypes   Fortran   Compatibility Macros 
    Collective Calls in Parallel 

    The HDF Group Help Desk:
    Describes HDF5 Release 1.8.18, November 2016.
      Copyright by The HDF Group
    and the Board of Trustees of the University of Illinois