Last modified: 1 April 2016
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`:

  - First use `H5Lexists` to verify that `group1` exists.
  - If `group1` exists, use `H5Lexists` again, this time with `name` set to `group1/group2`, to verify that`group2` exists.
  - If `group2` exists, use `H5Lexists` with `name` set to `group1/group2/softlink_to_group3` to verify that `softlink_to_group3` exists.
  - If `softlink_to_group3` exists, you can now safely use `H5Lexists` with `name` set to `group1/group2/softlink_to_group3/datasetD` to verify that the target link, `datasetD`, exists.

  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.

Note on Behavior Change:
  The behavior of `H5Lexists` was changed in the 1.10.0 release in the case where the root group, “/”, is the name of the link. This change is described below:
  1. Let ‘file’ denote a valid HDF5 file identifier, and let ‘lapl’ denote a valid link access property list identifier. A call to `H5Lexists` with arguments ‘file’, “/”, and ‘lapl’ returns a positive value; in other words, `H5Lexists(file, "/", lapl)` returns a positive value. In HDF5 version 1.8.16, this function returns 0.
  2. Let ‘root’ denote a valid HDF5 group identifier that refers to the root group of an HDF5 file, and let ‘lapl’ denote a valid link access property list identifier. A call to `H5Lexists` with arguments ‘root’, “/”, and ‘lapl’ returns a positive value; in other words, `H5Lexists(root, "/", lapl)` returns a postive value. In HDF5 version 1.8.16, this function returns 0.
  Note that the function accepts link names and path names. This is potentially misleading to callers, and we plan to separate the functionality for link names and path names in a future release.
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 a positive value if the link exists.
  Returns 0 if the link does not exist.
  Returns a negative value when the function fails and may return a negative value if the link does not exist. See “Failure Modes” below.

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:
  - `name` is not local to the group specified by `loc_id` or, if `loc_id` is something other than a group identifier, `name` is not local to the root group.
  - Any element of the relative path or absolute path in `name`, except the target link, does not 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.10.0 | Function behavior changed in this release. See the “Note on Behavior Change” section above.
  1.8.0 | Function introduced in this release.