H5Oexists_by_name
(
hid_t loc_id
,
const char * name
,
hid_t lapl_id
)
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.
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
:
H5Lexists
to verify that
a link named group1
exists.
group1
exists,
use H5Oexists_by_name
to verify that
the link group1
resolves to an object.
group1
exists,
use H5Lexists
again, this time
with name
set to group1/group2
,
to verify that the link group2
exists
in group1
.
group2
link exists,
use H5Oexists_by_name
to verify that
group1/group2
resolves to an object.
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
.
softlink_to_group3
link exists,
use H5Oexists_by_name
to verify that
group1/group2/softlink_to_group3
resolves to
an object.
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.
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.
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. |
TRUE
or FALSE
if successful;
otherwise returns a negative value.
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
.
H5Lexists
“Discovering Objects in a Group” in the “Groups” chapter of the HDF5 User’s Guide
Release | Change |
1.8.11 | Fortran subroutine introduced in this release. |
1.8.5 | C function introduced in this release. |