Last modified: 5 February 2013

Name: H5Rget_name

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

Purpose:
Retrieves a name for a referenced object.

Description:
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:
     H5R_OBJECT Object reference
  H5R_DATASET_REGION   Dataset region reference

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.

Parameters:
hid_t loc_id IN: Identifier for the file containing the reference or for any object in that file.
H5R_type_t ref_type IN: Type of reference.
void *ref IN: An object or dataset region reference.
char *name OUT: 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.
size_t size IN: 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.

Fortran90 Interface: h5rget_name_object_f or h5rget_name_region_f

To get name of an object reference: h5rget_name_object_f

 

To get name of a region reference: h5rget_name_region_f

Fortran2003 Interface: h5rget_name_f

History: