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
Functions
Java Reference (H5R) Interface

## Detailed Description

See also
  References (H5R), C-API
  HDF5 References, User Guide

## Functions
static synchronized native byte[] | H5Rcopy (byte[] src_ref_ptr) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
static synchronized byte[] | H5Rcreate (long loc_id, String name, int ref_type, long space_id) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
static synchronized native byte[] | H5Rcreate_attr (long loc_id, String name, String attr_name, long access_id) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
static synchronized native byte[] | H5Rcreate_object (long loc_id, String name, long access_id) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
static synchronized native byte[] | H5Rcreate_region (long loc_id, String name, long space_id, long access_id) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
static long | H5Rdereference (long dataset, long access_list, int ref_type, byte[] ref) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
static synchronized native void | H5Rdestroy (byte[] ref_ptr) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
static synchronized native boolean | H5Requal (byte[] ref1_ptr, byte[] ref2_ptr) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
static synchronized native String | H5Rget_attr_name (byte[] ref_ptr) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
static synchronized native String | H5Rget_file_name (byte[] ref_ptr) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
static synchronized native long | H5Rget_name (long loc_id, int ref_type, byte[] ref, String[] name, long size) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
static synchronized native String | H5Rget_name_string (long loc_id, int ref_type, byte[] ref) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
static synchronized native String | H5Rget_obj_name (byte[] ref_ptr, long rapl_id) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
static synchronized native int | H5Rget_obj_type (long loc_id, int ref_type, byte ref[]) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
static synchronized native int | H5Rget_obj_type3 (byte[] ref_ptr, long rapl_id) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
static long | H5Rget_region (long loc_id, int ref_type, byte[] ref) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
static synchronized native int | H5Rget_type (byte[] ref_ptr) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
static long | H5Ropen_attr (byte[] ref_ptr, long rapl_id, long aapl_id) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
static long | H5Ropen_object (byte[] ref_ptr, long rapl_id, long oapl_id) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
static long | H5Ropen_region (byte[] ref_ptr, long rapl_id, long oapl_id) throws HDF5LibraryException, NullPointerException, IllegalArgumentException

## Function Documentation

## ◆ H5Rcopy()

static synchronized native byte[] H5Rcopy | ( | byte[] | src_ref_ptr | ) | throws HDF5LibraryException, NullPointerException, IllegalArgumentException
| static

H5Rcopy creates a copy of an existing reference.

Parameters

  src_ref_ptr | IN: Reference to an object, region or attribute attached to an object.

Returns
  a valid copy of the reference (byte[]) if successful.

Exceptions

  HDF5LibraryException | Error from the HDF5 Library.
  NullPointerException | an input array is null.
  IllegalArgumentException | an input array is invalid.

## ◆ H5Rcreate()

static synchronized byte[] H5Rcreate | ( | long | loc_id,
|  | String | name,
|  | int | ref_type,
|  | long | space_id ) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
| static

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

Parameters

  loc_id | IN: Location identifier used to locate the object being pointed to.
  name | IN: Name of object at location loc_id.
  ref_type | IN: Type of reference.
  space_id | IN: Dataspace identifier with selection.

Returns
  the reference (byte[]) if successful

Exceptions

  HDF5LibraryException | Error from the HDF5 Library.
  NullPointerException | an input array is null.
  IllegalArgumentException | an input array is invalid.

## ◆ H5Rcreate_attr()

static synchronized native byte[] H5Rcreate_attr | ( | long | loc_id,
|  | String | name,
|  | String | attr_name,
|  | long | access_id ) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
| static

H5Rcreate_attr creates the reference, pointing to the attribute named attr name and attached to the object named name located at loc id.

Parameters

  loc_id | IN: Location identifier used to locate the object being pointed to.
  name | IN: Name of object at location loc_id.
  attr_name | IN: Name of the attribute within the object.
  access_id | IN: Object access identifier to the object being pointed to.

Returns
  the reference (byte[]) if successful

Exceptions

  HDF5LibraryException | Error from the HDF5 Library.
  NullPointerException | an input array is null.
  IllegalArgumentException | an input array is invalid.

## ◆ H5Rcreate_object()

static synchronized native byte[] H5Rcreate_object | ( | long | loc_id,
|  | String | name,
|  | long | access_id ) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
| static

H5Rcreate_object creates a reference pointing to the object named name located at loc id.

Parameters

  loc_id | IN: Location identifier used to locate the object being pointed to.
  name | IN: Name of object at location loc_id.
  access_id | IN: Object access identifier to the object being pointed to.

Returns
  the reference (byte[]) if successful

Exceptions

  HDF5LibraryException | Error from the HDF5 Library.
  NullPointerException | an input array is null.
  IllegalArgumentException | an input array is invalid.

## ◆ H5Rcreate_region()

static synchronized native byte[] H5Rcreate_region | ( | long | loc_id,
|  | String | name,
|  | long | space_id,
|  | long | access_id ) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
| static

H5Rcreate_region creates the reference, pointing to the region represented by space id within the object named name located at loc id.

Parameters

  loc_id | IN: Location identifier used to locate the object being pointed to.
  name | IN: Name of object at location loc_id.
  space_id | IN: Identifies the dataset region that a dataset region reference points to.
  access_id | IN: Object access identifier to the object being pointed to.

Returns
  the reference (byte[]) if successful

Exceptions

  HDF5LibraryException | Error from the HDF5 Library.
  NullPointerException | an input array is null.
  IllegalArgumentException | an input array is invalid.

## ◆ H5Rdereference()

static long H5Rdereference | ( | long | dataset,
|  | long | access_list,
|  | int | ref_type,
|  | byte[] | ref ) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
| static

Given a reference to some object, H5Rdereference opens that object and return an identifier.

Parameters

  dataset | IN: Dataset containing reference object.
  access_list | IN: Property list of the object being referenced.
  ref_type | IN: The reference type of ref.
  ref | IN: reference to an object

Returns
  valid identifier if successful

Exceptions

  HDF5LibraryException | Error from the HDF5 Library.
  NullPointerException | output array is null.
  IllegalArgumentException | output array is invalid.

## ◆ H5Rdestroy()

static synchronized native void H5Rdestroy | ( | byte[] | ref_ptr | ) | throws HDF5LibraryException, NullPointerException, IllegalArgumentException
| static

H5Rdestroy destroys a reference and releases resources.

Parameters

  ref_ptr | IN: Reference to an object, region or attribute attached to an object.

Exceptions

  HDF5LibraryException | Error from the HDF5 Library.
  NullPointerException | an input array is null.
  IllegalArgumentException | an input array is invalid.

## ◆ H5Requal()

static synchronized native boolean H5Requal | ( | byte[] | ref1_ptr,
|  | byte[] | ref2_ptr ) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
| static

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

Parameters

  ref1_ptr | IN: Reference to an object, region or attribute attached to an object.
  ref2_ptr | IN: Reference to an object, region or attribute attached to an object.

Returns
  true if equal, else false

Exceptions

  HDF5LibraryException | Error from the HDF5 Library.
  NullPointerException | an input array is null.
  IllegalArgumentException | an input array is invalid.

## ◆ H5Rget_attr_name()

static synchronized native String H5Rget_attr_name | ( | byte[] | ref_ptr | ) | throws HDF5LibraryException, NullPointerException, IllegalArgumentException
| static

H5Rget_attr_name retrieves the attribute name for the object, region or attribute reference pointed to.

Parameters

  ref_ptr | IN: Reference to an object, region or attribute attached to an object.

Returns
  Returns the attribute name of the reference

Exceptions

  HDF5LibraryException | Error from the HDF5 Library.
  NullPointerException | array is null.
  IllegalArgumentException | array is invalid.

## ◆ H5Rget_file_name()

static synchronized native String H5Rget_file_name | ( | byte[] | ref_ptr | ) | throws HDF5LibraryException, NullPointerException, IllegalArgumentException
| static

H5Rget_file_name retrieves the file name for the object, region or attribute reference pointed to.

Parameters

  ref_ptr | IN: Reference to an object, region or attribute attached to an object.

Returns
  Returns the file name of the reference

Exceptions

  HDF5LibraryException | Error from the HDF5 Library.
  NullPointerException | array is null.
  IllegalArgumentException | array is invalid.

## ◆ H5Rget_name()

static synchronized native long H5Rget_name | ( | long | loc_id,
|  | int | ref_type,
|  | byte[] | ref,
|  | String[] | name,
|  | long | size ) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
| static

H5Rget_name retrieves a name for the object identified by ref.

Parameters

  loc_id | IN: Identifier for the dataset containing the reference or for the group that dataset is in.
  ref_type | IN: Type of reference.
  ref | IN: An object or dataset region reference.
  name | OUT: A name associated with the referenced object or dataset region.
  size | IN: The size of the name buffer.

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.

Exceptions

  HDF5LibraryException | Error from the HDF5 Library.
  NullPointerException | size is null.
  IllegalArgumentException | Argument is illegal.

## ◆ H5Rget_name_string()

static synchronized native String H5Rget_name_string | ( | long | loc_id,
|  | int | ref_type,
|  | byte[] | ref ) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
| static

H5Rget_name_string retrieves a name for the object identified by ref.

Parameters

  loc_id | IN: Identifier for the dataset containing the reference or for the group that dataset is in.
  ref_type | IN: Type of reference.
  ref | IN: An object or dataset region reference.

Returns
  Returns the name if successful, returning null if no name is associated with the identifier.

Exceptions

  HDF5LibraryException | Error from the HDF5 Library.
  NullPointerException | size is null.
  IllegalArgumentException | Argument is illegal.

## ◆ H5Rget_obj_name()

static synchronized native String H5Rget_obj_name | ( | byte[] | ref_ptr,
|  | long | rapl_id ) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
| static

H5Rget_obj_name retrieves the object name for the object, region or attribute reference pointed to.

Parameters

  ref_ptr | IN: Reference to an object, region or attribute attached to an object.
  rapl_id | IN: 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).

Returns
  Returns the object name of the reference

Exceptions

  HDF5LibraryException | Error from the HDF5 Library.
  NullPointerException | array is null.
  IllegalArgumentException | array is invalid.

## ◆ H5Rget_obj_type()

static synchronized native int H5Rget_obj_type | ( | long | loc_id,
|  | int | ref_type,
|  | byte | ref[] ) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
| static

H5Rget_obj_type Given a reference to an object ref, H5Rget_obj_type returns the type of the object pointed to.

Parameters

  loc_id | IN: loc_id of the reference object.
  ref_type | IN: Type of reference to query.
  ref | IN: the reference

Returns
  Returns the object type

Exceptions

  HDF5LibraryException | Error from the HDF5 Library.
  NullPointerException | an input array is null.
  IllegalArgumentException | an input array is invalid.

## ◆ H5Rget_obj_type3()

static synchronized native int H5Rget_obj_type3 | ( | byte[] | ref_ptr,
|  | long | rapl_id ) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
| static

H5Rget obj type3 retrieves the type of the referenced object pointed to.

Parameters

  ref_ptr | IN: Reference to an object, region or attribute attached to an object.
  rapl_id | IN: 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).

Returns
  Returns the object type

Exceptions

  HDF5LibraryException | Error from the HDF5 Library.
  NullPointerException | array is null.
  IllegalArgumentException | array is invalid.

## ◆ H5Rget_region()

static long H5Rget_region | ( | long | loc_id,
|  | int | ref_type,
|  | byte[] | ref ) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
| static

Given a reference to an object ref, H5Rget_region creates a copy of the dataspace of the dataset pointed to and defines a selection in the copy which is the region pointed to.

Parameters

  loc_id | IN: loc_id of the reference object.
  ref_type | IN: The reference type of ref.
  ref | OUT: the reference to the object and region

Returns
  a valid identifier if successful

Exceptions

  HDF5LibraryException | Error from the HDF5 Library.
  NullPointerException | an input array is null.
  IllegalArgumentException | an input array is invalid.

## ◆ H5Rget_type()

static synchronized native int H5Rget_type | ( | byte[] | ref_ptr | ) | throws HDF5LibraryException, NullPointerException, IllegalArgumentException
| static

H5Rget_type retrieves the type of a reference.

Parameters

  ref_ptr | IN: Reference to an object, region or attribute attached to an object.

Returns
  a valid reference type if successful; otherwise returns H5R UNKNOWN.

Exceptions

  HDF5LibraryException | Error from the HDF5 Library.
  NullPointerException | an input array is null.
  IllegalArgumentException | an input array is invalid.

## ◆ H5Ropen_attr()

static long H5Ropen_attr | ( | byte[] | ref_ptr,
|  | long | rapl_id,
|  | long | aapl_id ) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
| static

H5Ropen_attr opens the attribute attached to the object and returns an identifier. The attribute opened with this function should be closed with H5Aclose when it is no longer needed so that resource leaks will not develop.

Parameters

  ref_ptr | IN: Reference to an object, region or attribute attached to an object.
  rapl_id | IN: 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).
  aapl_id | IN: An attribute access property list identifier for the reference. The access property property list must be of the same type as the object being referenced, that is a group or dataset property list.

Returns
  a valid attribute identifier if successful

Exceptions

  HDF5LibraryException | Error from the HDF5 Library.
  NullPointerException | an input array is null.
  IllegalArgumentException | an input array is invalid.

## ◆ H5Ropen_object()

static long H5Ropen_object | ( | byte[] | ref_ptr,
|  | long | rapl_id,
|  | long | oapl_id ) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
| static

H5Ropen_object opens that object and returns an identifier. 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

  ref_ptr | IN: Reference to an object, region or attribute attached to an object.
  rapl_id | IN: 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).
  oapl_id | IN: An object access property list identifier for the reference. The access property property list must be of the same type as the object being referenced, that is a group or dataset property list.

Returns
  a valid identifier if successful

Exceptions

  HDF5LibraryException | Error from the HDF5 Library.
  NullPointerException | an input array is null.
  IllegalArgumentException | an input array is invalid.

## ◆ H5Ropen_region()

static long H5Ropen_region | ( | byte[] | ref_ptr,
|  | long | rapl_id,
|  | long | oapl_id ) throws HDF5LibraryException, NullPointerException, IllegalArgumentException
| static

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. Use H5Sclose to release the dataspace identifier returned by this function when the identifier is no longer needed.

Parameters

  ref_ptr | IN: Reference to an object, region or attribute attached to an object.
  rapl_id | IN: 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).
  oapl_id | IN: An object access property list identifier for the reference. The access property property list must be of the same type as the object being referenced, that is a group or dataset property list.

Returns
  a valid dataspace identifier if successful

Exceptions

  HDF5LibraryException | Error from the HDF5 Library.
  NullPointerException | an input array is null.
  IllegalArgumentException | an input array is invalid.