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 

H5R: Reference Interface

Reference API Functions

The Reference interface allows the user to create references to specific objects and data regions in an HDF5 file.
In the following lists, italic type indicates a configurable macro.

The C Interfaces:
Use of this function is deprecated in Release 1.8.0.

Alphabetical Listing
             

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


Last modified: 19 July 2013
Name: H5Rcreate
Signature:
herr_t H5Rcreate( void *ref, hid_t loc_id, const char *name, H5R_type_t ref_type, hid_t space_id )

Purpose:
Creates a reference.

Description:
H5Rcreate creates the reference, ref, of the type specified in ref_type, pointing to the object name located at loc_id.

The HDF5 library maps the void type specified above for ref to the type specified in ref_type, which will be one of those appearing in the first column of the following table. The second column of the table lists the HDF5 constant associated with each reference type.

hdset_reg_ref_t   H5R_DATASET_REGION   Dataset region reference
hobj_ref_t H5R_OBJECT Object reference

The parameters loc_id and name are used to locate the object.

The parameter space_id identifies the dataset region that a dataset region reference points to. This parameter is used only with dataset region references and should be set to -1 if the reference is an object reference, H5R_OBJECT.

Warning:
Neither an object reference nor a dataset region reference may refer to an object that must be accessed through an external link.

More specifically, references can refer to objects only within the current logical HDF5 file while external links typically point to an object in a different logical HDF5 file. Therefore, neither an HDF5 object reference nor an HDF5 dataset region reference may refer to an object or to a region in any dataset, respectively, that is accessed by means of an external link.

Parameters:
void *ref OUT: Reference created by the function call.
hid_t loc_id IN: Location identifier used to locate the object being pointed to.
const char *name IN: Name of object at location loc_id.
H5R_type_t ref_type     IN: Type of reference.
hid_t space_id IN: Dataspace identifier with selection. Used only for dataset region references; pass as -1 if reference is an object reference, i.e., of type H5R_OBJECT.

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

Fortran90 Interface: h5rcreate_f

To create an object reference:
Signature:

  SUBROUTINE h5rcreate_f(loc_id, name, ref, hdferr)
    INTEGER(HID_T)    , INTENT(IN)    :: loc_id
    CHARACTER(LEN=*)  , INTENT(IN)    :: name
    TYPE(hobj_ref_t_f), INTENT(INOUT) :: ref
    INTEGER           , INTENT(OUT)   :: hdferr

Inputs:

  loc_id - Location identifier
  name   - Name of the object at location specified by loc_id identifier

Outputs:

  ref    - Object reference
  hdferr - Error code:
            0 on success and -1 on failure

 

To create a region reference:
Signature:

  SUBROUTINE h5rcreate_f(loc_id, name, space_id, ref, hdferr) 
    INTEGER(HID_T)         , INTENT(IN)  :: loc_id
    CHARACTER(LEN=*)       , INTENT(IN)  :: name
    INTEGER(HID_T)         , INTENT(IN)  :: space_id
    TYPE(hdset_reg_ref_t_f), INTENT(OUT) :: ref
    INTEGER                , INTENT(OUT) :: hdferr

Inputs:

  loc_id   - Location identifier
  name     - Name of the dataset at location specified by loc_id identifier 
  space_id - Dataset's dataspace identifier

Outputs:

  ref      - Dataset region reference
  hdferr   - Error code
              0 on success and -1 on failure

Fortran2003 Interface: h5rcreate_f
Signature:

  SUBROUTINE h5rcreate_f(loc_id, name, ref_type, ref, hdferr, space_id)
    INTEGER(HID_T)  , INTENT(IN)              :: loc_id
    CHARACTER(LEN=*), INTENT(IN)              :: name
    INTEGER         , INTENT(IN)              :: ref_type
    TYPE(C_PTR)     , INTENT(INOUT)           :: ref
    INTEGER         , INTENT(OUT)             :: hdferr
    INTEGER(HID_T)  , INTENT(IN)   , OPTIONAL :: space_id

Inputs:

  loc_id   - Location identifier used to locate the object being pointed to.
  name     - Name of object at location loc_id.
  ref_type - Type of reference:
              H5R_OBJECT
              H5T_STD_REF_DSETREG

Outputs:

  ref      - Reference created by the function call.
  hdferr   - Error code
              0 on success and -1 on failure

Optional Parameter:

  space_id - Dataspace identifier that describes selected region.

History:
Release     Change
1.8.8 Fortran updated to Fortran2003.
1.8.0 C function introduced in this release.

Last modified: 14 October 2014
Name: H5Rdereference

Signature:
hid_t H5Rdereference( hid_t obj_id, H5R_type_t ref_type, void *ref )

Purpose:
Opens the HDF5 object referenced.

Description:
Given a reference, ref, to an object or a region in an object, H5Rdereference opens that object and returns an identifier.

The parameter obj_id must be a valid identifier for an object in the HDF5 file containing the referenced object, including the file identifier.

The parameter ref_type specifies the reference type of the reference ref. ref_type may contain either of the following values:

The object opened with this function should be closed when it is no longer needed so that resource leaks will not develop. Use the appropriate close function such as H5Oclose or H5Dclose for datasets.

Parameters:
hid_t obj_id IN: Valid identifier for the file containing the referenced object or any object in that file.
H5R_type_t ref_type     IN: The reference type of ref.
void *ref IN: Reference to open.

Returns:
Returns identifier of referenced object if successful; otherwise returns a negative value.

Fortran90 Interface: h5rdereference_f

To dereference an object:
Signature:

  SUBROUTINE h5rdereference_f(obj_id, ref, ref_obj_id, hdferr) 
    INTEGER(HID_T)    , INTENT(IN)  :: obj_id
    TYPE(hobj_ref_t_f), INTENT(IN)  :: ref
    INTEGER(HID_T)    , INTENT(OUT) :: ref_obj_id
    INTEGER           , INTENT(OUT) :: hdferr

Inputs:

  obj_id      - Valid identifier in file
  ref         - Object reference

Outputs:

  ref_obj_id  - Identifier of referenced object 
  hdferr      - Error code 
                 0 on success and -1 on failure 

To dereference a region:
Signature:

  SUBROUTINE h5rdereference_f(obj_id, ref, ref_obj_id, hdferr)
    INTEGER(HID_T)         , INTENT(IN)  :: obj_id
    TYPE(hdset_reg_ref_t_f), INTENT(IN)  :: ref
    INTEGER(HID_T)         , INTENT(OUT) :: ref_obj_id
    INTEGER                , INTENT(OUT) :: hdferr 

Inputs:

  dset_id       - Valid identifier in file
  ref           - Object reference

Outputs:

  ref_obj_id    - Identifier of referenced object
  hdferr        - Error code 
                   0 on success and -1 on failure

Fortran2003 Interface: h5rdereference_f
Signature:

  SUBROUTINE h5rdereference_f(obj_id, ref_type, ref, ref_obj_id, hdferr)
    INTEGER(HID_T), INTENT(IN)  :: obj_id
    INTEGER       , INTENT(IN)  :: ref_type
    TYPE(C_PTR)   , INTENT(IN)  :: ref
    INTEGER(HID_T), INTENT(OUT) :: ref_obj_id
    INTEGER       , INTENT(OUT) :: hdferr

Inputs:

  obj_id     - Valid identifier for the file containing the
               referenced object or any object in that file.
  ref_type   - The reference type of ref.
  ref        - Object reference

Outputs:

  ref_obj_id - Identifier of referenced object
  hdferr     - Error code 
                0 on success and -1 on failure

See Also:
“Using Identifiers”

History:
Release     Change
1.8.8 Fortran updated to Fortran2003.
1.8.0 C function introduced in this release.

Last modified: 28 September 2011
Name: H5Rget_obj_type
Signature:
H5G_obj_t H5Rget_obj_type( hid_t loc_id, H5R_type_t ref_type, void *ref )

herr_t H5Rget_obj_type( hid_t loc_id, H5R_type_t ref_type, void *ref, H5O_type_t *obj_type )

Purpose:
Retrieves the type of object that an object reference points to.

Description:
H5Rget_obj_type is a macro that is mapped to either H5Rget_obj_type1 or H5Rget_obj_type2, depending on the needs of the application.

Such macros are provided to facilitate application compatibility. Their use and mappings are fully described in “API Compatibility Macros in HDF5”; we urge you to read that document closely.

When both the HDF5 Library and the application are built and installed with no specific compatibility flags, H5Rget_obj_type is mapped to the most recent version of the function, currently H5Rget_obj_type2. If the library and/or application is compiled for Release 1.6 emulation, H5Rget_obj_type will be mapped to H5Rget_obj_type1. Function-specific flags are available to override these settings on a function-by-function basis when the application is compiled.

Specific compile-time compatibility flags and the resulting mappings are as follows:

Compatibility setting H5Rget_obj_type mapping

Global settings
No compatibility flag H5Rget_obj_type2 
Enable deprecated symbols H5Rget_obj_type2 
Disable deprecated symbols H5Rget_obj_type2 
Emulate Release 1.6 interface     H5Rget_obj_type1 

Function-level macros
H5Rget_obj_type_vers = 2 H5Rget_obj_type2
H5Rget_obj_type_vers = 1 H5Rget_obj_type1

Fortran90 Interface: h5rget_object_type_f
Signature:

  SUBROUTINE h5rget_object_type_f(loc_id, ref, obj_type, hdferr)
    INTEGER(HID_T)    , INTENT(IN)  :: loc_id
    TYPE(hobj_ref_t_f), INTENT(IN)  :: ref
    INTEGER           , INTENT(OUT) :: obj_type
    INTEGER           , INTENT(OUT) :: hdferr

Inputs:

  loc_id   - Identifier for the dataset containing the reference or
             for the group that dataset is in.
  ref_type - Type of reference to query.
  ref      - Reference to query.

Outputs:

  obj_type - Type of referenced object. 
               H5G_UNKNOWN_F 
               H5G_LINK_F      
               H5G_GROUP_F     
               H5G_DATASET_F   
               H5G_TYPE_F      

  hdferr   - Returns 0 if successful and -1 if fails

Fortran2003 Interface: h5rget_object_type_f
Signature:

  SUBROUTINE h5rget_object_type_f(loc_id, ref_type, ref, obj_type, hdferr)
    INTEGER(HID_T), INTENT(IN)  :: loc_id
    INTEGER       , INTENT(IN)  :: ref_type
    TYPE(C_PTR)   , INTENT(IN)  :: ref
    INTEGER       , INTENT(OUT) :: obj_type
    INTEGER       , INTENT(OUT) :: hdferr

Inputs:

  loc_id   - Identifier for the dataset containing the reference or
             for the group that dataset is in.
  ref_type - Type of reference to query.
  ref      - Reference to query.

Outputs:

  obj_type - Type of referenced object. 
               H5G_UNKNOWN_F 
               H5G_LINK_F      
               H5G_GROUP_F     
               H5G_DATASET_F   
               H5G_TYPE_F      

  hdferr   - Returns 0 if successful and -1 if fails

History:
Release     Change
1.8.8 Fortran updated to Fortran2003.
1.8.0 The C function H5Rget_obj_type renamed to H5Rget_obj_type1 and deprecated in this release.
The C macro H5Rget_obj_type and the C function H5Rget_obj_type2 introduced in this release.

Name: H5Rget_obj_type1
Signature:
H5G_obj_t H5Rget_obj_type1( hid_t loc_id, H5R_type_t ref_type, void *ref )

Purpose:
Retrieves the type of object that an object reference points to.

Notice:
This function has been renamed from H5Rget_obj_type and is deprecated in favor of the macro H5Rget_obj_type or the function H5Rget_obj_type2.

Description:
Given an object reference, ref, H5Rget_obj_type1 returns the type of the referenced object.

A reference type is the type of reference, either an object reference or a dataset region reference. An object reference points to an HDF5 object while a dataset region reference points to a defined region within a dataset.

The referenced object is the object the reference points to. The referenced object type, or the type of the referenced object, is the type of the object that the reference points to.

The location identifier, loc_id, is the identifier for either the dataset containing the object reference or the group containing that dataset.

Valid reference types, to pass in as ref_type, include the following:
     H5R_OBJECT Object reference
  H5R_DATASET_REGION   Dataset region reference

If the application does not already know the object reference type, that can be determined with three preliminary calls:

When the function completes successfully, it returns one of the following valid object type values (defined in H5Gpublic.h):
     H5G_LINK Object is a symbolic link.
  H5G_GROUP Object is a group.
  H5G_DATASET   Object is a dataset.
  H5G_TYPE Object is a named datatype.

Parameters:

Returns:
Returns a valid object type if successful; otherwise returns H5G_UNKNOWN.

Fortran90 Interface: h5rget_object_type_f
See the H5Rget_obj_type macro description.

History:
Release     C
1.6.0 Function introduced in this release.
1.8.0 Function H5Rget_obj_type renamed to H5Rget_obj_type1 and deprecated in this release.

Name: H5Rget_obj_type2
Signature:
herr_t H5Rget_obj_type2( hid_t loc_id, H5R_type_t ref_type, void *ref, H5O_type_t *obj_type )

Purpose:
Retrieves the type of object that an object reference points to.

Description:
Given an object reference, ref, H5Rget_obj_type2 retrieves the type of the referenced object in obj_type.

A reference type is the type of reference, either an object reference or a dataset region reference. An object reference points to an HDF5 object while a dataset region reference points to a defined region within a dataset.

The referenced object is the object the reference points to. The referenced object type, or the type of the referenced object, is the type of the object that the reference points to.

The location identifier, loc_id, is the identifier for either the dataset containing the object reference or the group containing that dataset.

Valid reference types, to pass in as ref_type, include the following:
     H5R_OBJECT Object reference
  H5R_DATASET_REGION   Dataset region reference

If the application does not already know the object reference type, that can be determined with three preliminary calls:

When the function completes successfully, it returns one of the following valid object type values (defined in H5Opublic.h):
  H5O_TYPE_GROUP Object is a group.
  H5O_TYPE_DATASET   Object is a dataset.
  H5O_TYPE_NAMED_DATATYPE Object is a named datatype.

Parameters:
hid_t loc_id IN: The dataset containing the reference object or the group containing that dataset.
H5R_type_t ref_type     IN: Type of reference to query.
void *ref IN: Reference to query.
H5O_type_t *obj_type OUT: Type of referenced object.

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

Fortran90 Interface: h5rget_object_type_f
See the H5Rget_obj_type macro description.

History:

Last modified: 5 February 2013

Name: H5Rget_name

Signature:
ssize_t H5Rget_name(hid_t loc_id, H5R_type_t ref_type, void *ref, char *name, size_t size)

Purpose:
Retrieves a name for a referenced object.

Description:
H5Rget_name retrieves a name for the object identified by ref.

loc_id is used to identify the file containing the reference. It can be the file identifier for the file containing the reference or an identifier for any object in that file.

H5R_type_t is the reference type of ref. Valid values include the following:
     H5R_OBJECT Object reference
  H5R_DATASET_REGION   Dataset region reference

ref is the reference for which the target object’s name is sought.

If ref is an object reference, name will be returned with a name for the referenced object. If ref is a dataset region reference, name will contain a name for the object containing the referenced region.

Up to size characters of the name are returned in name; additional characters, if any, are not returned to the user application.

If the length of the name, which determines the required value of size, is unknown, a preliminary H5Rget_name call can be made. The return value of this call will be the size of the object name. That value can then be assigned to size for a second H5Rget_name call, which will retrieve the actual name.

If there is no name associated with the object identifier or if the name is NULL, H5Rget_name returns the size of the name buffer (the size does not include the NULL terminator).

Note that an object in an HDF5 file may have multiple paths if there are multiple links pointing to it. This function may return any one of these paths.

Parameters:
hid_t loc_id IN: Identifier for the file containing the reference or for any object in that file.
H5R_type_t ref_type IN: Type of reference.
void *ref IN: An object or dataset region reference.
char *name OUT: A buffer to place the name of the referenced object or dataset region. If NULL, then this call will return the size in bytes of the name.
size_t size IN: The size of the name buffer. When the size is passed in, the NULL terminator needs to be included.

Returns:
Returns the length of the name if successful, returning 0 (zero) if no name is associated with the identifier. Otherwise returns a negative value.

Fortran90 Interface: h5rget_name_object_f or h5rget_name_region_f

To get name of an object reference: h5rget_name_object_f
Signature:

  SUBROUTINE h5rget_name_object_f(loc_id,  ref, name, hdferr, size)
    INTEGER(HID_T)    , INTENT(IN)            :: loc_id 
    TYPE(hobj_ref_t_f), INTENT(IN)            :: ref
    CHARACTER(LEN=*)  , INTENT(OUT)           :: name
    INTEGER           , INTENT(OUT)           :: hdferr
    INTEGER(SIZE_T)   , INTENT(OUT), OPTIONAL :: size

Inputs:

  loc_id  - Identifier for the file containing the reference or
            for any object in that file.
  ref     - Object reference

Outputs:

  name    - A name associated with the referenced object or dataset region.
  hdferr  - Error code
             0 on success and -1 on failure

Optional parameters:

  size    - The size of the name buffer,
            returning 0 (zero) if no name is associated with the identifier

To get name of a region reference: h5rget_name_region_f
Signature:

  SUBROUTINE h5rget_name_region_f(loc_id, ref, name, hdferr, size)
    INTEGER(HID_T)         , INTENT(IN)            :: loc_id
    TYPE(hdset_reg_ref_t_f), INTENT(IN)            :: ref
    CHARACTER(LEN=*)       , INTENT(OUT)           :: name
    INTEGER(SIZE_T)        , INTENT(OUT), OPTIONAL :: size
    INTEGER                , INTENT(OUT)           :: hdferr

Inputs:

  loc_id  - Identifier for the file containing the reference or
            for any object in that file.
  ref     - Object reference

Outputs:

  name    - A name associated with the referenced object or dataset region.
  hdferr  - Error code
             0 on success and -1 on failure

Optional parameters:

  size    - The size of the name buffer,
            returning 0 (zero) if no name is associated with the identifier

Fortran2003 Interface: h5rget_name_f
Signature:

 SUBROUTINE h5rget_name_f(loc_id, ref_type, ref, name, hdferr, size)
   INTEGER(HID_T)  , INTENT(IN)            :: loc_id 
   INTEGER         , INTENT(IN)            :: ref_type
   TYPE(C_PTR)     , INTENT(IN)            :: ref
   CHARACTER(LEN=*), INTENT(OUT)           :: name
   INTEGER         , INTENT(OUT)           :: hdferr
   INTEGER(SIZE_T) , INTENT(OUT), OPTIONAL :: size

Inputs:

  loc_id   - Identifier for the file containing the reference or
             for any object in that file.
  ref_type - Type of reference.
  ref      - An object or dataset region reference.

Outputs:

  name     - A name associated with the referenced object or dataset ptr.
  hdferr   - Error code
              0 on success and -1 on failure

Optional parameters:

   size    - The size of the name buffer.

History:

Last modified: 14 October 2014
Name: H5Rget_region

Signature:
hid_t H5Rget_region( hid_t loc_id, H5R_type_t ref_type, void *ref )

Purpose:
Sets up a dataspace and selection as specified by a region reference.

Description:
H5Rget_region creates a copy of the dataspace of the dataset pointed to by a region reference, ref, and defines a selection matching the selection pointed to by ref within the dataspace copy.

loc_id is used to identify the file containing the referenced region; it can be a file identifier or an identifier for any object in the file.

The parameter ref_type specifies the reference type of ref and must contain the following value:

Use H5Sclose to release the dataspace identifier returned by this function when the identifier is no longer needed.

Parameters:
hid_t loc_id IN: File identifier or identifier for any object in the file containing the referenced region
H5R_type_t ref_type     IN: Reference type of ref, which must be H5R_DATASET_REGION
void *ref IN: Region reference to open

Returns:
Returns a valid dataspace identifier if successful; otherwise returns a negative value.

Fortran90 Interface: h5rget_region_f
SUBROUTINE h5rget_region_f(obj_id, ref, space_id, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: obj_id        ! Object identifier 
  TYPE(hdset_reg_ref_t_f), INTENT(IN) :: ref  ! Dataset region reference 
  INTEGER(HID_T), INTENT(OUT) :: space_id     ! Space identifier 
  INTEGER, INTENT(OUT) :: hdferr              ! Error code 
                                              ! 0 on success and -1 on failure
 
END SUBROUTINE h5rget_region_f
    
See Also:
“Using Identifiers”

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.20, November 2017.
  Copyright by The HDF Group
and the Board of Trustees of the University of Illinois