H5Lget_info
(
hid_t link_loc_id
,
const char *link_name
,
H5L_info_t *link_buff
,
hid_t lapl_id
)
H5Lget_info
returns information about the
specified link through the link_buff
argument.
A file or group identifier, link_loc_id
, specifies the
location of the link.
A link name, link_name
, interpreted relative to
loc_id
, specifies the link being queried.
lapl_id
is the link access property list associated
with the link link_name
.
In the general case, when default link access properties are
acceptable, this can be passed in as H5P_DEFAULT
.
An example of a situation that requires a non-default link access
property list is when the link is an external link; an external link
may require that a link prefix be set in a link access property list
(see
H5Pset_elink_prefix
).
H5Lget_info
returns information about
link_name
in the data structure
H5L_info_t
,
which is described below and defined in H5Lpublic.h
.
This structure is returned in the buffer link_buff
.
typedef struct { H5L_type_t type; hbool_t corder_valid; int64_t corder; H5T_cset_t cset; union { haddr_t address; size_t val_size; } u; } H5L_info_t;
In the above struct,
type
specifies the link class.
Valid values include the following:
H5L_TYPE_HARD
| Hard link | |
H5L_TYPE_SOFT
| Soft link | |
H5L_TYPE_EXTERNAL
| External link | |
H5L_TYPE_ERROR
| Error |
corder
specifies the link’s creation order
position while corder_valid
indicates whether
the value in corder
is valid.
If corder_valid
is TRUE
,
the value in corder
is known to be valid;
if corder_valid
is FALSE
,
the value in corder
is presumed to be invalid;
corder
starts at zero (0
)
and is incremented by one (1
) as new links are created.
But higher-numbered entries are not adjusted when a lower-numbered
link is deleted; the deleted link’s creation order position is
simply left vacant.
In such situations, the value of corder
for the
last link created will be larger than the number of links remaining
in the group.
cset
specifies the character set in which the link name
is encoded. Valid values include the following:
H5T_CSET_ASCII
| US ASCII | |
H5T_CSET_UTF8
| UTF-8 Unicode encoding |
address
and val_size
are returned
for hard and symbolic links, respectively.
Symbolic links include soft and external links and
some user-defined links.
If the link is a hard link, address
specifies
the file address that the link points to.
If the link is a symbolic link, val_size
will be
the length of the link value, e.g., the length of the name of
the pointed-to object with a null terminator.
hid_t link_loc_id |
IN: File or group identifier. |
const char *link_name |
IN: Name of the link for which information is being sought. |
H5L_info_t *link_buff |
OUT: Buffer in which link information is returned. |
hid_t lapl_id |
IN: Link access property list identifier. |
link_buff
(if non-null) initialized.
Otherwise returns a negative value.
SUBROUTINE h5lget_info_f(link_loc_id, link_name, & cset, corder, f_corder_valid, link_type, address, val_size, & hdferr, lapl_id) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: link_loc_id ! File or group identifier. CHARACTER(LEN=*), INTENT(IN) :: link_name ! Name of the link for which information is being sought. INTEGER, INTENT(OUT) :: cset ! Indicates the character set used for the link’s name. INTEGER, INTENT(OUT) :: corder ! Specifies the link’s creation order position. LOGICAL, INTENT(OUT) :: f_corder_valid ! Indicates whether the value in corder is valid. INTEGER, INTENT(OUT) :: link_type ! Specifies the link class: ! H5L_TYPE_HARD_F - Hard link ! H5L_TYPE_SOFT_F - Soft link ! H5L_TYPE_EXTERNAL_F - External link ! H5L_TYPE_ERROR_F - Error INTEGER(HADDR_T), INTENT(OUT) :: address ! If the link is a hard link, address specifies the file ! address that the link points to INTEGER(SIZE_T), INTENT(OUT) :: val_size ! If the link is a symbolic link, val_size will be the ! length of the link value, i.e. the length of the name ! of the pointed-to object with a null terminator.
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 END SUBROUTINE h5lget_info_f
Release | C |
1.8.0 | Function introduced in this release. |
1.8.2 | Fortran subroutine added in this release. |
1.8.4 | Fortran subroutine syntax changed in this release. |