H5O_EXISTS_BY_NAME

Determines whether a link resolves to an actual object

Procedure:

H5O_EXISTS_BY_NAME(loc_id, name, lapl_id)

Signature:

htri_t H5Oexists_by_name( hid_t loc_id, const char * name, hid_t lapl_id )

  SUBROUTINE h5oexists_by_name_f(loc_id, name, link_exists, &
        hdferr, lapl_id)
    IMPLICIT NONE
    INTEGER(HID_T)  , INTENT(IN)  :: loc_id
    CHARACTER(LEN=*), INTENT(IN)  :: name
    LOGICAL         , INTENT(OUT) :: link_exists
    INTEGER         , INTENT(OUT) :: hdferr
    INTEGER(HID_T)  , INTENT(IN), OPTIONAL :: lapl_id

Parameters:

hid_t `loc_id`	IN: Location Identifier to query; may be a file, group, dataset, named datatype or attribute identifier
const char *`name`	IN: The name of the link to check
hid_t `lapl_id`	IN: Link access property list identifier

Description:

H5O_EXISTS_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 H5O_EXISTS_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, H5O_EXISTS_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 H5L_EXISTS to verify that a link named group1 exists.
If group1 exists, use H5O_EXISTS_BY_NAME to verify that the link group1 resolves to an object.
If group1 exists, use H5L_EXISTS again, this time with name set to group1/group2, to verify that the link group2 exists in group1.
If the group2 link exists, use H5O_EXISTS_BY_NAME to verify that group1/group2 resolves to an object.
If group2 exists, use H5L_EXISTS 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 H5O_EXISTS_BY_NAME to verify that group1/group2/softlink_to_group3 resolves to an object.
If softlink_to_group3 exists, you can now safely use H5L_EXISTS 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 H5O_EXISTS_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 H5L_EXISTS 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.

Returns:

Returns a positive value if the object pointed to by the loc_id and name combination exists.
Returns 0 if the object pointed to by the loc_id and name combination does not exist.
Returns a negative value when the function fails.

Failure Modes:

If loc_id and name both exist but the combination does not resolve to an object, the function will return 0 (zero); the function does not fail in this case.

If either the location or the link specified by the loc_id and name combination does not exist, the function will fail, returning a negative value.

Note that verifying the existence of an object within an HDF5 file is a multistep process. An application can be certain the object does not exist only if H5L_EXISTS and H5O_EXISTS_BY_NAME have been used to verify the existence of the links and groups in the hierarchy above that object. The example above, in the function description, provides a step-by-step description of that verification process.

Example:

Coming Soon!

History:

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

--- Last Modified: April 25, 2019 | 01:20 PM

Page tree

H5O_EXISTS_BY_NAME

Procedure:

Signature:

Parameters:

Description:

Returns:

Example:

History:

The HDF Group

Site

Resources

Connect