Retrieves the object name for a referenced object
Procedure:
H5R_GET_OBJ_NAME ( ref_ptr, rapl_id, name, size )
Signature:
ssize_t H5Rget_obj_name ( H5R_ref_t *ref_ptr, hid_t rapl_id, char *name, size_t size )
Parameters:
H5R_ref_t * ref_ptr | IN: Pointer to reference to query.
H5R_ref_t is defined in H5Rpublic.h as: typedef unsigned char H5R_ref_t[H5R_REF_BUF_SIZE]; |
hid_t rapl_id | IN: Valid reference access property list identifier |
char * name | IN/OUT: A buffer to place the object name of the reference |
size_t size | IN: The size of the name buffer |
Description:
H5R_GET_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 H5R_GET_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 assigned to size for a second H5R_GET_OBJ_NAME call, which will retrieve the actual name. If there is no name associated with the object identifier or if the name is NULL, H5R_GET_OBJ_NAME returns the size of the name buffer (the size does not include the NULL 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.
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.
Example:
History:
| Release | Change |
|---|
| 1.12.0 | C function was introduced in this release. |
--- Last Modified: July 10, 2020 | 08:59 AM
