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

Purpose:
Determine whether a link with the specified name exists in a group.

Description:
H5Lexists allows an application to determine whether the link name exists in the group or file specified with loc_id. The link may be of any type; only the presence of a link with that name is checked.

Note that H5Lexists verifies only that the target link exists. If name includes either a relative path or an absloute 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, H5Lexists 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, you may need to verify that an intermediate link points to a group and that a soft link points to an existing target.

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:
H5Lexists checks the existence of only the final element in a relative or absolute path; it does not check any other path elements. The function will therefore fail when both of the following conditions exist:

Fortran90 Interface: h5lexists_f
SUBROUTINE h5lexists_f(loc_id, name, link_exists, hdferr, lapl_id)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: loc_id ! Identifier of file or group to query.
  CHARACTER(LEN=*), INTENT(IN) :: name ! Link name to check.
  LOGICAL, INTENT(OUT) :: link_exists  ! .TRUE. if exists, .FALSE. otherwise
  INTEGER, INTENT(OUT) :: hdferr       ! Error code:
                                       ! 0 on success and -1 on failure
  INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id 
                                       ! Link access property list identifier.
END SUBROUTINE h5lexists_f 
    

History:
Release     C
1.8.0 Function introduced in this release.