![]() |
HDF5
1.15.0
API Reference
|
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. More... | |
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. More... | |
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. More... | |
herr_t | H5Rdestroy (H5R_ref_t *ref_ptr) |
Closes a reference. More... | |
H5R_type_t | H5Rget_type (const H5R_ref_t *ref_ptr) |
Retrieves the type of a reference. More... | |
htri_t | H5Requal (const H5R_ref_t *ref1_ptr, const H5R_ref_t *ref2_ptr) |
Determines whether two references are equal. More... | |
herr_t | H5Rcopy (const H5R_ref_t *src_ref_ptr, H5R_ref_t *dst_ref_ptr) |
Copies an existing reference. More... | |
hid_t | H5Ropen_object (H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id) |
Opens the HDF5 object referenced. More... | |
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. More... | |
hid_t | H5Ropen_attr (H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t aapl_id) |
Opens the HDF5 attribute referenced. More... | |
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. More... | |
ssize_t | H5Rget_file_name (const H5R_ref_t *ref_ptr, char *name, size_t size) |
Retrieves the file name for a referenced object. More... | |
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. More... | |
ssize_t | H5Rget_attr_name (const H5R_ref_t *ref_ptr, char *name, size_t size) |
Retrieves the attribute name for a referenced object. More... | |
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. More... | |
hid_t | H5Rdereference1 (hid_t obj_id, H5R_type_t ref_type, const void *ref) |
Opens the HDF5 object referenced. More... | |
herr_t | H5Rcreate (void *ref, hid_t loc_id, const char *name, H5R_type_t ref_type, hid_t space_id) |
Creates a reference. More... | |
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. More... | |
hid_t | H5Rdereference2 (hid_t obj_id, hid_t oapl_id, H5R_type_t ref_type, const void *ref) |
Opens the HDF5 object referenced. More... | |
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. More... | |
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. More... | |
#define H5Rdereference H5Rdereference2 |
H5Rdereference() is a macro that is mapped to either H5Rdereference1() or H5Rdereference2().
#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 H5R_get_obj_type3().
Copies an existing reference.
[in] | src_ref_ptr | Pointer to reference to copy |
[out] | dst_ref_ptr | Pointer to output reference |
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.
herr_t H5Rcreate | ( | void * | ref, |
hid_t | loc_id, | ||
const char * | name, | ||
H5R_type_t | ref_type, | ||
hid_t | space_id | ||
) |
Creates a reference.
[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 |
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:
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.
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.
[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 |
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:
H5Rdestroy() should be used to release the resource from the reference.
Creates an object reference.
[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 |
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:
H5Rdestroy() should be used to release the resource from the 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.
[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 |
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:
H5Rdestroy() should be used to release the resource from the reference.
hid_t H5Rdereference1 | ( | hid_t | obj_id, |
H5R_type_t | ref_type, | ||
const void * | ref | ||
) |
Opens the HDF5 object referenced.
[in] | obj_id | Object identifier |
[in] | ref_type | The reference type of ref |
[in] | ref | Reference to open |
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.
hid_t H5Rdereference2 | ( | hid_t | obj_id, |
hid_t | oapl_id, | ||
H5R_type_t | ref_type, | ||
const void * | ref | ||
) |
Opens the HDF5 object referenced.
[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 |
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.
Closes a reference.
[in] | ref_ptr | Pointer to reference |
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:
Determines whether two references are equal.
[in] | ref1_ptr | Pointer to reference to compare |
[in] | ref2_ptr | Pointer to reference to compare |
H5Requal() determines whether two references point to the same object, region or attribute.
H5R_ref_t is defined in H5Rpublic.h as:
Retrieves the attribute name for a referenced object.
[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 |
H5Rget_attr_name() retrieves the attribute name for the attribute reference pointed to by ref_ptr
.
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_attr_name() call can be made. The return value of this call will be the size of the attribute name. That value can then be passed in for size in the second call to H5Rget_attr_name(), which will retrieve the actual name.
Retrieves the file name for a referenced object.
[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 |
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 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_file_name() call can be made. The return value of this call will be the size of the file name. That value can then be passed in for size in the second call to H5Rget_file_name(), which will retrieve the actual 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.
[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. |
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:
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.
Retrieves the object name for a referenced object.
[in] | ref_ptr | Pointer to reference to query |
[in] | rapl_id | Reference access property list identifier |
[in,out] | name | Buffer to place the file name of the reference |
[in] | size | Size of the name buffer |
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 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_obj_name() call can be made. The return value of this call will be the size of the object name. That value can then be passed in for size
in the second call to H5Rget_obj_name(), which will retrieve the actual name. If there is no name associated with the object identifier or if the name is NULL, H5Rget_obj_name() returns the size of the name buffer (the size does not include the \0
terminator).
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.
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.
[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 |
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:
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):
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.
[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 |
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:
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):
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.
[in] | ref_ptr | Pointer to reference to query |
[in] | rapl_id | Reference access property list identifier |
[out] | obj_type | Type of referenced object |
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):
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.
[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 |
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.
H5R_type_t H5Rget_type | ( | const H5R_ref_t * | ref_ptr | ) |
Retrieves the type of a reference.
[in] | ref_ptr | Pointer to reference |
Given a reference, ref_ptr
, H5Rget_type() returns the type of the reference.
Valid returned reference types are:
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:
Opens the HDF5 attribute referenced.
[in] | ref_ptr | Pointer to reference to open |
[in] | rapl_id | Reference access property list identifier |
[in] | aapl_id | Attribute access property list identifier |
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.
Opens the HDF5 object referenced.
[in] | ref_ptr | Pointer to reference to open |
[in] | rapl_id | Reference access property list identifier |
[in] | oapl_id | Object access property list identifier |
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:
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.
Sets up a dataspace and selection as specified by a region reference.
[in] | ref_ptr | Pointer to reference to open |
[in] | rapl_id | Reference access property list identifier |
[in] | oapl_id | Object access property list identifier |
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.