Page tree

The license could not be verified: License Certificate has expired!









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


H5O_GET_INFO_BY_NAME3  ( loc_id, name, oinfo, fields, lapl_id )


herr_t H5Oget_info_by_name3 ( hid_t loc_id, const char *name, H5O_info2_t *oinfo, unsigned fields, hid_t lapl_id )

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

    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
    INTEGER         , INTENT(IN) , OPTIONAL :: fields

Related Fortran2003 Derived Type:  h5o_info_t


  TYPE, BIND(C) :: h5o_info_t
     INTEGER(C_LONG)     :: fileno     ! File number that object is located in
     TYPE(H5O_TOKEN_T_F) :: token      ! Token for object 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 array
     INTEGER, DIMENSION(8) :: ctime ! Change time         ! as specified in the Fortran
     INTEGER, DIMENSION(8) :: btime ! Birth time          ! intrinsic DATE_AND_TIME(VALUES)

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

hid_t loc_idIN: Location identifier specifying group in which object is located; may be a file, group, dataset, named datatype or attribute identifier
const char *nameIN: Name of group, relative to loc_id
H5O_info2_t *oinfo    OUT: Buffer in which to return object information
unsigned int fieldsIN: Flags specifying the fields to include in oinfo
hid_t lapl_idIN: Link access property list
(Not currently used; pass as H5P_DEFAULT.)


H5O_GET_INFO_BY_NAME3  specifies an object’s location and name, loc_id and name, respectively, and retrieves the metadata describing that object in oinfo, an H5O_info2_t struct.

oinfo, in which the object information is returned, is a struct of type H5O_info2_t, which is defined in H5Opublic.h in the HDF5 source code:  

src / H5Opublic.h [129:141]  hdf5_1_12  HDFFV/hdf5
/* Data model information struct for objects */
/* (For H5Oget_info / H5Oget_info_by_name / H5Oget_info_by_idx version 3) */
typedef struct H5O_info2_t {
    unsigned long   fileno;     /* File number that object is located in */
    H5O_token_t     token;      /* Token representing the object        */
    H5O_type_t 	    type;       /* Basic object type (group, dataset, etc.) */
    unsigned        rc;         /* Reference count of object            */
    time_t          atime;      /* Access time                          */
    time_t          mtime;      /* Modification time                    */
    time_t          ctime;      /* Change time                          */
    time_t          btime;      /* Birth time                           */
    hsize_t         num_attrs;  /* # of attributes attached to object   */
} H5O_info2_t;

Note the following about  H50_info2_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.

H5O_token_t is defined in H5public.h as follows:

src / H5public.h [337:341]  hdf5_1_12  HDFFV/hdf5
/* Type for object tokens */
/* (Hoisted here, since it's used by both the H5Lpublic.h and H5Opublic.h headers) */
typedef struct H5O_token_t {
    uint8_t __data[H5O_MAX_TOKEN_SIZE];
} H5O_token_t;

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

src / H5Opublic.h [101:109]  hdf5_1_12  HDFFV/hdf5
/* 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_MAP,               /* Object is a map */
    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.

The fields parameter contains flags to determine which fields will be filled in in the H5O_info2_t struct returned in oinfo. These flags are defined in the H5Opublic.h file:

H5O_INFO_BASICFill in the fileno, addr, type, and rc fields
H5O_INFO_TIMEFill in the atime, mtime, ctime, and btime fields
H5O_INFO_NUM_ATTRSFill in the num_attrs field
H5O_INFO_HDRFill in the hdr field
H5O_INFO_META_SIZEFill in the meta_size field

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


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


test / vol.c [917:920]  1.12/master  HDFFV/hdf5
    /* H5Oget_info_by_name */
    if (H5Oget_info_by_name3(fid, NATIVE_VOL_TEST_GROUP_NAME, &object_info, H5O_INFO_ALL, H5P_DEFAULT) < 0)

fortran / test / tH5O_F03.F90 [330:331]  1.12/master  HDFFV/hdf5
  ! Get ref counts for each object.  They should all be 1, since each object has a hard link.
  CALL h5oget_info_by_name_f(fid, "group", oinfo, error)

Release    Change
1.12.0Function introduced in this release.

--- Last Modified: March 17, 2020 | 11:08 AM