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