Last modified: 10 April 2013
Name: H5Oexists_by_name
Signature:
htri_t H5Oexists_by_name( hid_t loc_id, const char * name, hid_t lapl_id )

Purpose:
Determines whether a link resolves to an actual object.

Motivation:
H5Oexists_by_name is used by an application to check that an existing link resolves to an object. Primarily, it is designed to check for dangling soft, external, or user-defined links.

Description:
H5Oexists_by_name allows an application to determine whether the link name in the group or file specified with loc_id resolves to an HDF5 object to open or if the link dangles. The link may be of any type, but hard links will always resolve to objects and do not need to be verified.

Note that H5Oexists_by_name verifies only that the target object exists. If name includes either a relative path or an absolute path to the target link, intermediate steps along the path must be verified before the existence of the target link can be safely checked. If the path is not verified and an intermediate element of the path does not exist, H5Oexists_by_name will fail. The example in the next paragraph illustrates one step-by-step method for verifying the existence of a link with a relative or absolute path.

Example: Use the following steps to verify the existence of the link datasetD in the group group1/group2/softlink_to_group3/, where group1 is a member of the group specified by loc_id:

If the link to be verified is specified with an absolute path, the same approach should be used, but starting with the first link in the file’s root group. For instance, if datasetD were in /group1/group2/softlink_to_group3, the first call to H5Lexists would have name set to /group1.

Note that this is an outline and does not include all necessary details. Depending on circumstances, for example, an application may need to verify the type of an object also.

Parameters:
hid_t loc_id      IN: Identifier of the file or group to query.
const char *name   IN: The name of the link to check.
hid_t lapl_id   IN: Link access property list identifier.

Returns:
Returns TRUE or FALSE if successful; otherwise returns a negative value.

Failure Modes:
If the link specified by the loc_id and name does not exist, an error will be returned. If the link exists but does not resolve to an object for any reason, this routine will return FALSE, not FAIL.

See Also:
H5Lexists

“Discovering Objects in a Group” in the “Groups” chapter of the HDF5 User’s Guide

Fortran90 Interface: h5oexists_by_name_f

History:
Release     Change
1.8.11 Fortran subroutine introduced in this release.
1.8.5 C function introduced in this release.