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

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	H5Rdestroy (H5R_ref_t *ref_ptr)
	Closes a reference.

H5R_type_t	H5Rget_type (const H5R_ref_t *ref_ptr)
	Retrieves the type of a reference.

htri_t	H5Requal (const H5R_ref_t ref1_ptr, const H5R_ref_t ref2_ptr)
	Determines whether two references are equal.

herr_t	H5Rcopy (const H5R_ref_t src_ref_ptr, H5R_ref_t dst_ref_ptr)
	Copies an existing reference.

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.

hid_t	H5Ropen_attr (H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t aapl_id)
	Opens the HDF5 attribute referenced.

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.

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_obj_name (H5R_ref_t ref_ptr, hid_t rapl_id, char name, size_t size)
	Retrieves the object name for a referenced object.

ssize_t	H5Rget_attr_name (const H5R_ref_t ref_ptr, char name, size_t size)
	Retrieves the attribute 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.

hid_t	H5Rdereference1 (hid_t obj_id, H5R_type_t ref_type, const void *ref)
	Opens the HDF5 object referenced.

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

hid_t	H5Rdereference2 (hid_t obj_id, hid_t oapl_id, H5R_type_t ref_type, const void *ref)
	Opens the HDF5 object referenced.

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.

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.

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:

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:

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

Detailed Description

Macros

Functions

Macro Definition Documentation

◆ H5Rdereference

◆ H5Rget_obj_type

Function Documentation

◆ H5Rcopy()

◆ H5Rcreate()

◆ H5Rcreate_attr()

◆ H5Rcreate_object()

◆ H5Rcreate_region()

◆ H5Rdereference1()

◆ H5Rdereference2()

◆ H5Rdestroy()

◆ H5Requal()

◆ H5Rget_attr_name()

◆ H5Rget_file_name()

◆ H5Rget_name()

◆ H5Rget_obj_name()

◆ H5Rget_obj_type1()

◆ H5Rget_obj_type2()

◆ H5Rget_obj_type3()

◆ H5Rget_region()

◆ H5Rget_type()

◆ H5Ropen_attr()

◆ H5Ropen_object()

◆ H5Ropen_region()