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

  - First use `H5Lexists` to verify that a link named `group1` exists.
  - If `group1` exists, use `H5Oexists_by_name` to verify that the link `group1` resolves to an object.
  - If `group1` exists, use `H5Lexists` again, this time with `name` set to `group1/group2`, to verify that the link `group2` exists in `group1`.
  - If the `group2` link exists, use `H5Oexists_by_name` to verify that `group1/group2` resolves to an object.
  - If `group2` exists, use `H5Lexists` again, this time with `name` set to `group1/group2/softlink_to_group3`, to verify that the link `softlink_to_group3` exists in `group2`.
  - If the `softlink_to_group3` link exists, use `H5Oexists_by_name` to verify that `group1/group2/softlink_to_group3` resolves to an object.
  - 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.
  - And finally, if the link `datasetD` exists, use `H5Oexists_by_name` to verify that `group1/group2/softlink_to_group3/datasetD` resolves to an object.

  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.