Last modified: 28 September 2011
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 the identifier for the dataset containing the reference or for the group containing that dataset.

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 0 (zero).

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 dataset containing the reference or for the group that dataset is in.
H5R_type_t ref_type     IN: Type of reference.
void *ref IN: An object or dataset region reference.
char *name OUT: A name associated with the referenced object or dataset region.
size_t 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.

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: