Help us improve by taking our short survey: https://www.hdfgroup.org/website-survey/

| HDF5 Last Updated on 2025-11-11 The HDF5 Field Guide

- Main Page
- Getting started
- User Guide
- Reference Manual
- Cookbook
- Technical Notes
- RFCs
- Specifications
- Glossary
- Full-Text Search
- About

Loading...
Searching...
No Matches
Macros | Functions
References (H5R)

## Detailed Description

Use the functions in this module to manage HDF5 references. Referents can be HDF5 objects, attributes, and selections on datasets a.k.a. dataset regions.

## Macros
#define | H5Rdereference H5Rdereference2
#define | H5Rget_obj_type H5Rget_obj_type2

## Functions
herr_t | H5Rcopy (const H5R_ref_t *src_ref_ptr, H5R_ref_t *dst_ref_ptr)
| Copies an existing reference.
herr_t | H5Rcreate (void *ref, hid_t loc_id, const char *name, H5R_type_t ref_type, hid_t space_id)
| Creates a reference.
herr_t | H5Rcreate_attr (hid_t loc_id, const char *name, const char *attr_name, hid_t oapl_id, H5R_ref_t *ref_ptr)
| Creates an attribute reference.
herr_t | H5Rcreate_object (hid_t loc_id, const char *name, hid_t oapl_id, H5R_ref_t *ref_ptr)
| Creates an object reference.
herr_t | H5Rcreate_region (hid_t loc_id, const char *name, hid_t space_id, hid_t oapl_id, H5R_ref_t *ref_ptr)
| Creates a region reference.
hid_t | H5Rdereference1 (hid_t obj_id, H5R_type_t ref_type, const void *ref)
| Opens the HDF5 object referenced.
hid_t | H5Rdereference2 (hid_t obj_id, hid_t oapl_id, H5R_type_t ref_type, const void *ref)
| Opens the HDF5 object referenced.
herr_t | H5Rdestroy (H5R_ref_t *ref_ptr)
| Closes a reference.
htri_t | H5Requal (const H5R_ref_t *ref1_ptr, const H5R_ref_t *ref2_ptr)
| Determines whether two references are equal.
ssize_t | H5Rget_attr_name (const H5R_ref_t *ref_ptr, char *name, size_t size)
| Retrieves the attribute name for a referenced object.
ssize_t | H5Rget_file_name (const H5R_ref_t *ref_ptr, char *name, size_t size)
| Retrieves the file name for a referenced object.
ssize_t | H5Rget_name (hid_t loc_id, H5R_type_t ref_type, const void *ref, char *name, size_t size)
| Retrieves a name for a referenced object.
ssize_t | H5Rget_obj_name (H5R_ref_t *ref_ptr, hid_t rapl_id, char *name, size_t size)
| Retrieves the object name for a referenced object.
H5G_obj_t | H5Rget_obj_type1 (hid_t id, H5R_type_t ref_type, const void *ref)
| Retrieves the type of object that an object reference points to.
herr_t | H5Rget_obj_type2 (hid_t id, H5R_type_t ref_type, const void *ref, H5O_type_t *obj_type)
| Retrieves the type of object that an object reference points to.
herr_t | H5Rget_obj_type3 (H5R_ref_t *ref_ptr, hid_t rapl_id, H5O_type_t *obj_type)
| Retrieves the type of object that an object reference points to.
hid_t | H5Rget_region (hid_t dataset, H5R_type_t ref_type, const void *ref)
| Sets up a dataspace and selection as specified by a region reference.
H5R_type_t | H5Rget_type (const H5R_ref_t *ref_ptr)
| Retrieves the type of a reference.
hid_t | H5Ropen_attr (H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t aapl_id)
| Opens the HDF5 attribute referenced.
hid_t | H5Ropen_object (H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id)
| Opens the HDF5 object referenced.
hid_t | H5Ropen_region (H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id)
| Sets up a dataspace and selection as specified by a region reference.

## Macro Definition Documentation

## ◆ H5Rdereference

#define H5Rdereference H5Rdereference2

H5Rdereference() is a macro that is mapped to either H5Rdereference1() or H5Rdereference2().

See also
  API Compatibility Macros

## ◆ H5Rget_obj_type

#define H5Rget_obj_type H5Rget_obj_type2

H5Rget_obj_type() is a macro that is mapped to either H5Rget_obj_type1() or H5Rget_obj_type2() or H5Rget_obj_type3().

See also
  API Compatibility Macros

## Function Documentation

## ◆ H5Rcopy()

herr_t H5Rcopy | ( | const H5R_ref_t * | src_ref_ptr,
|  | H5R_ref_t * | dst_ref_ptr )

Copies an existing reference.

Parameters

  [in] | src_ref_ptr | Pointer to reference to copy
  [out] | dst_ref_ptr | Pointer to output reference

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

H5Rcopy() creates a copy of an existing reference. `src_ref_ptr` points to the reference to copy, and `dst_ref_ptr` is the pointer to the destination reference.

The function returns a `dst_ref_ptr` pointer, which must be released using H5Rdestroy() to avoid resource leaks and possible HDF5 library shutdown issues.

Since
  1.12.0

## ◆ H5Rcreate()

herr_t H5Rcreate | ( | void * | ref,
|  | hid_t | loc_id,
|  | const char * | name,
|  | H5R_type_t | ref_type,
|  | hid_t | space_id )

Creates a reference.

Parameters

  [out] | ref | Reference created by the function call
  [in] | loc_id | Location identifier used to locate the object being pointed to
  [in] | name | Name of object at location `loc_id`
  [in] | ref_type | Type of reference
  [in] | space_id | 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.

Deprecated
  As of HDF5-1.12, this function has been deprecated in favor of H5Rcreate_object(), H5Rcreate_region() and H5Rcreate_attr().

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 the following:

typedef enum {
H5R_BADTYPE = (-1),
H5R_OBJECT1 = 0,
H5R_DATASET_REGION1 = 1,
H5R_OBJECT2 = 2,
H5R_DATASET_REGION2 = 3,
H5R_ATTR = 4,
H5R_MAXTYPE = 5
} H5R_type_t;

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.

Since
  1.0.0

## ◆ H5Rcreate_attr()

herr_t H5Rcreate_attr | ( | hid_t | loc_id,
|  | const char * | name,
|  | const char * | attr_name,
|  | hid_t | oapl_id,
|  | H5R_ref_t * | ref_ptr )

Creates an attribute reference.

Parameters

  [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | name | Name of object
  [in] | attr_name | Name of attribute
  [in] | oapl_id | Object access property list identifier
  [out] | ref_ptr | Pointer to reference

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

H5Rcreate_attr() creates the reference, `ref_ptr`, pointing to the attribute named `attr_name` and attached to the object named `name` located at `loc_id`.

The parameters `loc_id` and `name` locate the object. The parameter `attr_name` specifies the attribute within the object.

The parameter `oapl_id` is an object access property list identifier for the object that the referenced attribute is attached to. The access property list must be of the same type as that object, that is a group, dataset or committed datatype property list.

H5R_ref_t is defined in H5Rpublic.h as:

typedef struct {
union {
uint8_t __data[H5R_REF_BUF_SIZE];
int64_t align;
} u;
} H5R_ref_t;

The function returns a `ref_ptr` pointer, which must be released using H5Rdestroy() to avoid resource leaks and possible HDF5 library shutdown issues.

Since
  1.12.0

## ◆ H5Rcreate_object()

herr_t H5Rcreate_object | ( | hid_t | loc_id,
|  | const char * | name,
|  | hid_t | oapl_id,
|  | H5R_ref_t * | ref_ptr )

Creates an object reference.

Parameters

  [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | name | Name of object
  [in] | oapl_id | Object access property list identifier
  [out] | ref_ptr | Pointer to reference

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

H5Rcreate_object() creates a reference pointing to the object named `name` located at `loc_id`. The parameters `loc_id` and `name` are used to locate the object.

The parameter `oapl_id` is an object access property list identifier for the referenced object. The access property list must be of the same type as the object being referenced, that is a group, dataset or committed datatype property list.

H5R_ref_t is defined in H5Rpublic.h as:

typedef struct {
union {
uint8_t __data[H5R_REF_BUF_SIZE];
int64_t align;
} u;
} H5R_ref_t;

The function returns a `ref_ptr` pointer, which must be released using H5Rdestroy() to avoid resource leaks and possible HDF5 library shutdown issues.

Since
  1.12.0

## ◆ H5Rcreate_region()

herr_t H5Rcreate_region | ( | hid_t | loc_id,
|  | const char * | name,
|  | hid_t | space_id,
|  | hid_t | oapl_id,
|  | H5R_ref_t * | ref_ptr )

Creates a region reference.

Parameters

  [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | name | Name of object
  [in] | space_id | Dataspace identifier
  [in] | oapl_id | Object access property list identifier
  [out] | ref_ptr | Pointer to reference

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

H5Rcreate_region() creates the reference, `ref_ptr`, pointing to the region represented by `space_id` within the object named name located at `loc_id`.

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.

The parameter `oapl_id` is an object access property list identifier for the referenced object. The access property list must be of the same type as the object being referenced, that is a dataset property list in this case.

H5R_ref_t is defined in H5Rpublic.h as:

typedef struct {
union {
uint8_t __data[H5R_REF_BUF_SIZE];
int64_t align;
} u;
} H5R_ref_t;

The function returns a `ref_ptr` pointer, which must be released using H5Rdestroy() to avoid resource leaks and possible HDF5 library shutdown issues.

Since
  1.12.0

## ◆ H5Rdereference1()

hid_t H5Rdereference1 | ( | hid_t | obj_id,
|  | H5R_type_t | ref_type,
|  | const void * | ref )

Opens the HDF5 object referenced.

Parameters

  [in] | obj_id | Object identifier
  [in] | ref_type | The reference type of `ref`
  [in] | ref | Reference to open

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

Deprecated
  This function has been renamed from H5Rdereference() and is deprecated in favor of the macro H5Rdereference() or the function H5Rdereference2().

Given a reference, `ref`, to an object or a region in an object, H5Rdereference1() 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:

- H5R_OBJECT
- H5R_DATASET_REGION

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.

Version
  1.10.0 Function H5Rdereference() renamed to H5Rdereference1() and deprecated in this release.

Since
  1.0.0

## ◆ H5Rdereference2()

hid_t H5Rdereference2 | ( | hid_t | obj_id,
|  | hid_t | oapl_id,
|  | H5R_type_t | ref_type,
|  | const void * | ref )

Opens the HDF5 object referenced.

Parameters

  [in] | obj_id | Object identifier
  [in] | oapl_id | Object access property list identifier
  [in] | ref_type | The reference type of `ref`
  [in] | ref | Reference to open

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

Deprecated
  As of HDF5-1.12, this function and H5Rdereference1() have been deprecated in favor of H5Ropen_attr(), H5Ropen_object() and H5Ropen_region().

Given a reference, `ref`, to an object or a region in an object, H5Rdereference2() opens that object and returns an identifier.

The parameter `obj_id` must be a valid identifier for the HDF5 file containing the referenced object or for any object in that HDF5 file.

The parameter `oapl_id` is an object access property list identifier for the referenced object. The access property list must be of the same type as the object being referenced, that is a group, dataset, or datatype property list.

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

- H5R_OBJECT
- H5R_DATASET_REGION

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.

Since
  1.10.0

## ◆ H5Rdestroy()

herr_t H5Rdestroy | ( | H5R_ref_t * | ref_ptr | ) |

Closes a reference.

Parameters

  [in] | ref_ptr | Pointer to reference

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

Given a reference, `ref_ptr`, to an object, region or attribute attached to an object, H5Rdestroy() releases allocated resources from a previous create call.

H5R_ref_t is defined in H5Rpublic.h as:

typedef struct {
union {
uint8_t __data[H5R_REF_BUF_SIZE];
int64_t align;
} u;
} H5R_ref_t;

Since
  1.12.0

## ◆ H5Requal()

htri_t H5Requal | ( | const H5R_ref_t * | ref1_ptr,
|  | const H5R_ref_t * | ref2_ptr )

Determines whether two references are equal.

Parameters

  [in] | ref1_ptr | Pointer to reference to compare
  [in] | ref2_ptr | Pointer to reference to compare

Returns
  Returns a positive value if the references are equal. Returns 0 if the references are not equal. Returns a negative value when the function fails.

H5Requal() determines whether two references point to the same object, region or attribute.

H5R_ref_t is defined in H5Rpublic.h as:

typedef struct {
union {
uint8_t __data[H5R_REF_BUF_SIZE];
int64_t align;
} u;
} H5R_ref_t;

Since
  1.12.0

## ◆ H5Rget_attr_name()

ssize_t H5Rget_attr_name | ( | const H5R_ref_t * | ref_ptr,
|  | char * | name,
|  | size_t | size )

Retrieves the attribute name for a referenced object.

Parameters

  [in] | ref_ptr | Pointer to reference to query
  [in,out] | name | Buffer to place the attribute name of the reference
  [in] | size | Size of the `name` buffer

Returns
  Returns the length of the name if successful, otherwise, a negative value.

H5Rget_attr_name() retrieves the attribute name for the attribute reference pointed to by `ref_ptr`.

Up to `size` characters of the attribute name are returned in `name`; additional characters, if any, are not returned to the user application.
If the length of the attribute name, which determines the required value of `size`, is unknown, a preliminary call to H5Rget_attr_name() with the last two parameters set to NULL and zero respectively can be made. The return value of this call will be the size in bytes of the attribute name. That value, plus 1 for a NULL terminator, must then be assigned to `size` for a second H5Rget_attr_name() call, which will retrieve the actual attribute name.

Since
  1.12.0

## ◆ H5Rget_file_name()

ssize_t H5Rget_file_name | ( | const H5R_ref_t * | ref_ptr,
|  | char * | name,
|  | size_t | size )

Retrieves the file name for a referenced object.

Parameters

  [in] | ref_ptr | Pointer to reference to query
  [in,out] | name | Buffer to place the file name of the reference
  [in] | size | 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, otherwise, a negative value.

H5Rget_file_name() retrieves the file name for the object, region or attribute reference pointed to by `ref_ptr`.

Up to `size` characters of the file name are returned in `name`; additional characters, if any, are not returned to the user application.
If the length of the file name, which determines the required value of `size`, is unknown, a preliminary call to H5Rget_file_name() with the last two parameters set to NULL and zero respectively can be made. The return value of this call will be the size in bytes of the file name. That value, plus 1 for a NULL terminator, must then be assigned to `size` for a second H5Rget_file_name() call, which will retrieve the actual file name.

Since
  1.12.0

## ◆ H5Rget_name()

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

Retrieves a name for a referenced object.

Parameters

  [in] | loc_id | Identifier for the file containing the reference or for any object in that file
  [in] | ref_type | Type of reference
  [in] | ref | An object or dataset region reference
  [out] | name | 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.
  [in] | size | 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.

Deprecated
  As of HDF5-1.12, this function has been deprecated in favor of H5Rget_file_name(), H5Rget_obj_name() and H5Rget_attr_name().

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:

typedef enum {
H5R_BADTYPE = (-1),
H5R_OBJECT1 = 0,
H5R_DATASET_REGION1 = 1,
H5R_OBJECT2 = 2,
H5R_DATASET_REGION2 = 3,
H5R_ATTR = 4,
H5R_MAXTYPE = 5
} H5R_type_t;

`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 call to H5Rget_name() with the last two parameters set to NULL and zero respectively can be made. The return value of this call will be the size in bytes of the name. That value, plus 1 for a NULL terminator, must then be assigned to `size` for a second H5Rget_name() call, which will retrieve the actual name.

Note
  An object in an HDF5 file may have multiple paths if multiple links point to it. This function may return any one of these paths.

Since
  1.8.0

## ◆ H5Rget_obj_name()

ssize_t H5Rget_obj_name | ( | H5R_ref_t * | ref_ptr,
|  | hid_t | rapl_id,
|  | char * | name,
|  | size_t | size )

Retrieves the object name for a referenced object.

Parameters

  [in] | ref_ptr | Pointer to reference to query
  [in] | rapl_id | Reference access property list identifier
  [in,out] | name | Buffer to place the object name of the reference
  [in] | size | 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.

H5Rget_obj_name() retrieves the object name for the object, region or attribute reference pointed to by `ref_ptr`.

The parameter `rapl_id` is a reference access property list identifier for the reference. The access property list can be used to access external files that the reference points to (through a file access property list).

Up to `size` characters of the object name are returned in `name`; additional characters, if any, are not returned to the user application.
If the length of the object name, which determines the required value of `size`, is unknown, a preliminary call to H5Rget_obj_name() with the last two parameters set to NULL and zero respectively can be made. The return value of this call will be the size in bytes of the object name. That value, plus 1 for a NULL terminator, must then be assigned to `size` for a second H5Rget_obj_name() call, which will retrieve the actual object name.

If `ref_ptr` is an object reference, `name` will be returned with a name for the referenced object. If `ref_ptr` is a dataset region reference, `name` will contain a name for the object containing the referenced region. If `ref_ptr` is an attribute reference, `name` will contain a name for the object the attribute is attached to. 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.

Since
  1.12.0

## ◆ H5Rget_obj_type1()

H5G_obj_t H5Rget_obj_type1 | ( | hid_t | id,
|  | H5R_type_t | ref_type,
|  | const void * | ref )

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

Parameters

  [in] | id | The dataset containing the reference object or the group containing that dataset
  [in] | ref_type | Type of reference to query
  [in] | ref | Reference to query

Returns
  Returns a valid object type if successful; otherwise returns a negative value (H5G_UNKNOWN).

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

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, `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:

typedef enum {
H5R_BADTYPE = (-1),
H5R_OBJECT1 = 0,
H5R_DATASET_REGION1 = 1,
H5R_OBJECT2 = 2,
H5R_DATASET_REGION2 = 3,
H5R_ATTR = 4,
H5R_MAXTYPE = 5
} H5R_type_t;

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

- Call H5Dget_type() on the dataset containing the reference to get a datatype identifier for the dataset's datatype.
- Using that datatype identifier, H5Tget_class() returns a datatype class.
  If the datatype class is H5T_REFERENCE, H5Tequal() can then be used to determine whether the reference's datatype is H5T_STD_REF_OBJ or H5T_STD_REF_DSETREG:
  - If the datatype is H5T_STD_REF_OBJ, the reference object type is H5R_OBJECT.
  - If the datatype is H5T_STD_REF_DSETREG, the reference object type is H5R_DATASET_REGION.

When the function completes successfully, it returns one of the following valid object type values (defined in H5Gpublic.h):

typedef enum H5G_obj_t {
H5G_UNKNOWN = -1,
H5G_GROUP,
H5G_DATASET,
H5G_TYPE,
H5G_LINK,
H5G_UDLINK,
H5G_RESERVED_5,
H5G_RESERVED_6,
H5G_RESERVED_7
} H5G_obj_t;

Version
  1.8.0 Function H5Rget_obj_type() renamed to H5Rget_obj_type1() and deprecated in this release.

Since
  1.2.0

## ◆ H5Rget_obj_type2()

herr_t H5Rget_obj_type2 | ( | hid_t | id,
|  | H5R_type_t | ref_type,
|  | const void * | ref,
|  | H5O_type_t * | obj_type )

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

Parameters

  [in] | id | The dataset containing the reference object or the group containing that dataset
  [in] | ref_type | Type of reference to query
  [in] | ref | Reference to query
  [out] | obj_type | Type of referenced object

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

Given an object reference, `ref`, H5Rget_obj_type2() returns 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, `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:

typedef enum {
H5R_BADTYPE = (-1),
H5R_OBJECT1 = 0,
H5R_DATASET_REGION1 = 1,
H5R_OBJECT2 = 2,
H5R_DATASET_REGION2 = 3,
H5R_ATTR = 4,
H5R_MAXTYPE = 5
} H5R_type_t;

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

- Call H5Dget_type() on the dataset containing the reference to get a datatype identifier for the dataset's datatype.
- Using that datatype identifier, H5Tget_class() returns a datatype class.
  If the datatype class is H5T_REFERENCE, H5Tequal() can then be used to determine whether the reference's datatype is H5T_STD_REF_OBJ or H5T_STD_REF_DSETREG:
  - If the datatype is H5T_STD_REF_OBJ, the reference object type is H5R_OBJECT.
  - If the datatype is H5T_STD_REF_DSETREG, the reference object type is H5R_DATASET_REGION.

When the function completes successfully, it returns one of the following valid object type values (defined in H5Opublic.h):

typedef enum H5O_type_t {
H5O_TYPE_UNKNOWN = -1,
H5O_TYPE_GROUP,
H5O_TYPE_DATASET,
H5O_TYPE_NAMED_DATATYPE,
H5O_TYPE_MAP,
H5O_TYPE_NTYPES
} H5O_type_t;

Since
  1.8.0

## ◆ H5Rget_obj_type3()

herr_t H5Rget_obj_type3 | ( | H5R_ref_t * | ref_ptr,
|  | hid_t | rapl_id,
|  | H5O_type_t * | obj_type )

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

Parameters

  [in] | ref_ptr | Pointer to reference to query
  [in] | rapl_id | Reference access property list identifier
  [out] | obj_type | Type of referenced object

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

Given a reference, `ref_ptr`, H5Rget_obj_type3() retrieves the type of the referenced object in `obj_type`.

The parameter `rapl` id is a reference access property list identifier for the reference. The access property list can be used to access external files that the reference points to (through a file access property list).

Upon success, the function returns in `obj_type` the type of the object that the reference points to. Valid values for this referenced object type are as followed (defined in H5Opublic.h):

typedef enum H5O_type_t {
H5O_TYPE_UNKNOWN = -1,
H5O_TYPE_GROUP,
H5O_TYPE_DATASET,
H5O_TYPE_NAMED_DATATYPE,
H5O_TYPE_MAP,
H5O_TYPE_NTYPES
} H5O_type_t;

Since
  1.12.0

## ◆ H5Rget_region()

hid_t H5Rget_region | ( | hid_t | dataset,
|  | H5R_type_t | ref_type,
|  | const void * | ref )

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

Parameters

  [in] | dataset | File identifier or identifier for any object in the file containing the referenced region
  [in] | ref_type | Reference type of `ref`, which must be H5R_DATASET_REGION
  [in] | ref | Region reference to open

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

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.

`dataset` 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 value H5R_DATASET_REGION.

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

Since
  1.0.0

## ◆ H5Rget_type()

H5R_type_t H5Rget_type | ( | const H5R_ref_t * | ref_ptr | ) |

Retrieves the type of a reference.

Parameters

  [in] | ref_ptr | Pointer to reference

Returns
  Returns a valid reference type if successful; otherwise returns H5R_BADTYPE .

Given a reference, `ref_ptr`, H5Rget_type() returns the type of the reference.

Valid returned reference types are:

typedef enum {
H5R_BADTYPE = (-1),
H5R_OBJECT1 = 0,
H5R_DATASET_REGION1 = 1,
H5R_OBJECT2 = 2,
H5R_DATASET_REGION2 = 3,
H5R_ATTR = 4,
H5R_MAXTYPE = 5
} H5R_type_t;

Note that H5R_OBJECT1 and H5R_DATASET_REGION1 can never be associated with an H5R_ref_t reference and can, therefore, never be returned through that function.

H5R_ref_t is defined in H5Rpublic.h as:

typedef struct {
union {
uint8_t __data[H5R_REF_BUF_SIZE];
int64_t align;
} u;
} H5R_ref_t;

Since
  1.12.0

## ◆ H5Ropen_attr()

hid_t H5Ropen_attr | ( | H5R_ref_t * | ref_ptr,
|  | hid_t | rapl_id,
|  | hid_t | aapl_id )

Opens the HDF5 attribute referenced.

Parameters

  [in] | ref_ptr | Pointer to reference to open
  [in] | rapl_id | Reference access property list identifier
  [in] | aapl_id | Attribute access property list identifier

Returns
  Returns a attribute identifier if successful; otherwise returns H5I_INVALID_HID.

Given a reference, `ref_ptr`, to an attribute attached to an object, H5Ropen_attr() opens the attribute attached to that object and returns an identifier.

The parameter `rapl` id is a reference access property list identifier for the reference. The access property list can be used to access external files that the reference points to (through a file access property list).

The parameter `aapl_id` is an attribute access property list identifier for the referenced attribute.

The attribute opened with this function should be closed with H5Aclose() when it is no longer needed.

Since
  1.12.0

## ◆ H5Ropen_object()

hid_t H5Ropen_object | ( | H5R_ref_t * | ref_ptr,
|  | hid_t | rapl_id,
|  | hid_t | oapl_id )

Opens the HDF5 object referenced.

Parameters

  [in] | ref_ptr | Pointer to reference to open
  [in] | rapl_id | Reference access property list identifier
  [in] | oapl_id | Object access property list identifier

Returns
  Returns a object identifier if successful; otherwise returns H5I_INVALID_HID.

Given a reference, `ref_ptr`, to an object, a region in an object, or an attribute attached to an object, H5Ropen_object() opens that object and returns an identifier.

The parameter `oapl_id` is an object access property list identifier for the referenced object. The access property list must be of the same type as the object being referenced, that is a group or dataset property list.

H5R_ref_t is defined in H5Rpublic.h as:

typedef struct {
union {
uint8_t __data[H5R_REF_BUF_SIZE];
int64_t align;
} u;
} H5R_ref_t;

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.

Since
  1.12.0

## ◆ H5Ropen_region()

hid_t H5Ropen_region | ( | H5R_ref_t * | ref_ptr,
|  | hid_t | rapl_id,
|  | hid_t | oapl_id )

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

Parameters

  [in] | ref_ptr | Pointer to reference to open
  [in] | rapl_id | Reference access property list identifier
  [in] | oapl_id | Object access property list identifier

Returns
  Returns a dataspace identifier if successful; otherwise returns H5I_INVALID_HID.

H5Ropen_region() creates a copy of the dataspace of the dataset pointed to by a region reference, `ref_ptr`, and defines a selection matching the selection pointed to by `ref_ptr` within the dataspace copy.

The parameter `rapl` id is a reference access property list identifier for the reference. The access property list can be used to access external files that the reference points to (through a file access property list).

The parameter `oapl` id is an object access property list identifier for the referenced object. The access property list must be of the same type as the object being referenced, that is a dataset property list in that case.

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

Since
  1.12.0