Describes HDF5 Release 1.10.
and the Board of Trustees of the University of Illinois
The C Interfaces:
H5Lcopy(
hid_t src_loc_id,
const char *src_name,
hid_t dest_loc_id,
const char *dest_name,
hid_t lcpl_id,
hid_t lapl_id
)
H5Lcopy copies the link
specified by src_name
from the file or group specified by src_loc_id
to the file or group specified by dest_loc_id.
The new copy of the link is created with the name dest_name.
If dest_loc_id is a file identifier,
dest_name will be interpreted relative to
that file’s root group.
The new link is created with the creation and access property lists
specified by lcpl_id and lapl_id.
The interpretation of lcpl_id is limited in the manner
described in the next paragraph.
H5Lcopy retains the creation time and the target of
the original link.
However, since the link may be renamed, the character encoding
is that specified in lcpl_id rather than that of
the original link. Other link creation properties are ignored.
If the link is a soft link, also known as a symbolic link, its target is interpreted relative to the location of the copy.
Several properties are available to govern the behavior of
H5Lcopy.
These properties are set in the link creation and access property lists,
lcpl_id and lapl_id, respectively.
The property controlling creation of missing intermediate groups
is set in the link creation property list with
H5Pset_create_intermediate_group;
this function ignores any other properties in the link creation
property list.
Properties controlling character encoding, link traversals, and
external link prefixes are set in the link access property list with
H5Pset_char_encoding,
H5Pset_nlinks, and
H5Pset_elink_prefix.
H5Lcopy does not affect the object that the link points to.
H5Lcopy cannot copy hard links across files as a hard link
is not valid without a target object;
to copy objects from one file to another, see
H5Ocopy.
hid_t src_loc_id
|
IN: Location identifier of the source link |
const char *src_name
|
IN: Name of the link to be copied |
hid_t dest_loc_id
|
IN: Location identifier specifying the destination of the copy |
const char *dest_name
|
IN: Name to be assigned to the new copy |
hid_t lcpl_id
|
IN: Link creation property list identifier |
hid_t lapl_id
|
IN: Link access property list identifier |
SUBROUTINE h5lcopy_f(src_loc_id, src_name, dest_loc_id, dest_name, hdferr, &
lcpl_id, lapl_id)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: src_loc_id
! Location identifier of the source link
CHARACTER(LEN=*), INTENT(IN) :: src_name
! Name of the link to be copied
INTEGER(HID_T), INTENT(IN) :: dest_loc_id
! Location identifier specifying the
! destination of the copy
CHARACTER(LEN=*), INTENT(IN) :: dest_name
! Name to be assigned to the new copy
INTEGER, INTENT(OUT) :: hdferr ! Error code:
! 0 on success and -1 on failure
INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id
! Link creation property list identifier
INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id
! Link access property list identifier
END SUBROUTINE h5lcopy_f
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lcreate_external(
const char *target_file_name,
const char *target_obj_name,
hid_t link_loc_id,
const char *link_name,
hid_t lcpl_id,
hid_t lapl_id
)
H5Lcreate_external creates a new external link.
An external link is a soft link to an object in a different HDF5 file
from the location of the link, i.e., to an external object.
target_file_name identifies the target file containing the
target object;
target_obj_name specifies the path of the target object
within that file.
target_obj_name must be an absolute pathname in
target_file_name, i.e., it must start at the target
file’s root group, but it is not interpreted until an application
attempts to traverse it.
link_loc_id and link_name specify the
location and name, respectively, of the new link.
link_name is interpreted relative to
link_loc_id
lcpl_id is the link creation property list used in creating
the new link.
lapl_id is the link access property list used in traversing
the new link.
Note that an external file opened by the traversal of an external link
is always opened with the weak file close degree property setting,
H5F_CLOSE_WEAK (see
H5Pset_fclose_degree);
any file close degree property setting in lapl_id
is ignored.
An external link behaves similarly to a soft link, and like a soft link in an HDF5 file, it may dangle: the target file and object need not exist at the time that the external link is created.
When the external link link_name is accessed,
the library will search for the target file target_file_name
as described below:
target_file_name is a relative pathname, the
following steps are performed:
HDF5_EXT_PREFIX and
will try to prepend each prefix to
target_file_name
to form a new target_file_name.
target_file_name does not exist
or if HDF5_EXT_PREFIX is not set,
the library will get the prefix set via
H5Pset_elink_prefix and
prepend it to target_file_name
to form a new target_file_name.
target_file_name does not exist
or no prefix is being set
by
H5Pset_elink_prefix,
then the path of the file associated with
link_loc_id is obtained.
This path can be the absolute path or the
current working directory plus the relative path
of that file when it is created/opened.
The library will
prepend this path to target_file_name
to form a new target_file_name.
target_file_name does not exist,
then the library will look for
target_file_name
and will return failure/success accordingly.
target_file_name is an absolute pathname, the
library will first try to find target_file_name.
If target_file_name does not exist,
target_file_name is stripped of directory paths
to form a new target_file_name.
The search for the new target_file_name then follows
the same steps as described above for a relative pathname.
See examples below illustrating how target_file_name
is stripped to form a new target_file_name.
Note that target_file_name is considered to be an absolute
pathname when the following condition is true:
target_file_name
is a slash ( / ).
For example, consider a target_file_name
of /tmp/A.h5.
If that target file does not exist,
the new target_file_name after stripping
will be A.h5.
target_file_name is an absolute drive with
absolute pathname.
For example, consider a target_file_name
of /tmp/A.h5.
If that target file does not exist,
the new target_file_name after stripping
will be A.h5.
target_file_name is an absolute pathname
without specifying drive name.
For example, consider a target_file_name
of /tmp/A.h5.
If that target file does not exist,
the new target_file_name after stripping
will be A.h5.
target_file_name is an absolute drive with
relative pathname.
For example, consider a target_file_name
of /tmp/A.h5.
If that target file does not exist,
the new target_file_name after stripping
will be tmp\A.h5.
target_file_name is in UNC (Uniform Naming
Convention) format with server name, share name,
and pathname.
For example, consider a target_file_name
of /tmp/A.h5.
If that target file does not exist,
the new target_file_name after stripping
will be A.h5.
target_file_name is in Long UNC
(Uniform Naming Convention) format with server name,
share name, and pathname.
For example, consider a target_file_name
of /tmp/A.h5.
If that target file does not exist,
the new target_file_name after stripping
will be A.h5
target_file_name is in Long UNC
(Uniform Naming Convention) format with an absolute drive
and an absolute pathname.
For example, consider a target_file_name
of /tmp/A.h5.
If that target file does not exist,
the new target_file_name after stripping
will be A.h5
The library opens target file target_file_name
with the file access property list that is set via
H5Pset_elink_fapl
when the external link link_name is accessed.
If no such property list is set, the library uses the
file access property list associated with the file of
link_loc_id to open the target file.
If an application requires additional control over file access flags
or the file access property list, see
H5Pset_elink_cb; this function enables the use of an
external link callback function as described in
H5L_elink_traverse_t.
Restriction:
A file close degree property setting
(H5Pset_fclose_degree)
in the external link file access property list
or in the external link callback function will be ignored.
A file opened by means of traversing an external link
is always opened with the weak file close degree property setting,
H5F_CLOSE_WEAK.
const char * target_file_name
|
IN: Name of the target file containing the target object |
const char *target_obj_name |
IN: Path within the target file to the target object |
hid_t link_loc_id |
IN: File or group identifier where the new link is to be created |
const char * link_name |
IN: Name of the new link,
relative to link_loc_id |
hid_t lcpl_id |
IN: Link creation property list identifier |
hid_t lapl_id |
IN: Link access property list identifier |
SUBROUTINE h5lcreate_external_f(file_name, obj_name, link_loc_id, link_name, &
hdferr, lcpl_id, lapl_id)
IMPLICIT NONE
CHARACTER(LEN=*), INTENT(IN) :: file_name
! Name of the file containing the target object. Neither
! the file nor the target object is required to exist.
! May be the file the link is being created in.
CHARACTER(LEN=*), INTENT(IN) :: obj_name
! Name of the target object, which need not already exist.
INTEGER(HID_T), INTENT(IN) :: link_loc_id
! The file or group identifier for the new link.
CHARACTER(LEN=*), INTENT(IN) :: link_name
! The name of the new link.
INTEGER, INTENT(OUT) :: hdferr
! Error code:
! 0 on success and -1 on failure
INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id
! Link creation property list identifier.
INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id
! Link access property list identifier.
END SUBROUTINE h5lcreate_external_f
H5Pset_elink_fapl,
H5Pset_elink_cb
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lcreate_hard(
hid_t obj_loc_id,
const char *obj_name,
hid_t link_loc_id,
const char *link_name,
hid_t lcpl_id,
hid_t lapl_id
)
H5Lcreate_hard creates a new hard link to a
pre-existing object in an HDF5 file.
The new link may be one of many that point to that object.
The target object must already exist in the file.
obj_loc_id and obj_name specify the
location and name, respectively, of the target object,
i.e., the object that the new hard link points to.
link_loc_id and link_name specify the
location and name, respectively, of the new hard link.
obj_name and link_name are interpreted
relative to obj_loc_id and link_loc_id,
respectively.
If obj_loc_id and link_loc_id are
the same location, the HDF5 macro H5L_SAME_LOC
can be used for either parameter (but not both).
lcpl_id and lapl_id are the
link creation and access property lists associated with the
new link.
Hard and soft links are for use only if the target object
is in the current file.
If the desired target object is in a different file from the
new link, an external link may be created with
H5Lcreate_external.
The HDF5 library keeps a count of all hard links pointing to an
object; if the hard link count reaches zero (0),
the object will be deleted from the file. Creating new hard links
to an object will prevent it from being deleted if other links
are removed.
The library maintains no similar count for soft links and they
can dangle.
hid_t obj_loc_id |
IN: The file or group identifier for the target object. |
const char *obj_name |
IN: Name of the target object, which must already exist. |
hid_t link_loc_id |
IN: The file or group identifier for the new link. |
const char * link_name |
IN: The name of the new link. |
hid_t lcpl_id |
IN: Link creation property list identifier. |
hid_t lapl_id |
IN: Link access property list identifier. |
SUBROUTINE h5lcreate_hard_f(obj_loc_id, obj_name, link_loc_id, link_name, &
hdferr, lcpl_id, lapl_id)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: obj_loc_id
! The file or group identifier for the target object.
CHARACTER(LEN=*), INTENT(IN) :: obj_name
! Name of the target object, which must already exist.
INTEGER(HID_T), INTENT(IN) :: link_loc_id
! The file or group identifier for the new link.
CHARACTER(LEN=*), INTENT(IN) :: link_name
! The name of the new link.
INTEGER, INTENT(OUT) :: hdferr
! Error code:
! 0 on success and -1 on failure
INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id
! Link creation property list identifier.
INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id
! Link access property list identifier.
END SUBROUTINE h5lcreate_hard_f
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lcreate_soft(
const char *target_path,
hid_t link_loc_id,
const char *link_name,
hid_t lcpl_id,
hid_t lapl_id
)
H5Lcreate_soft creates a new soft link
to an object in an HDF5 file.
The new link may be one of many that point to that object.
target_path specifies the path to the target object,
i.e., the object that the new soft link points to.
target_path can be anything and is interpreted at
lookup time. This path may be absolute in the file or relative
to link_loc_id.
link_loc_id must be a file or group identifier.
link_loc_id and link_name specify the
location and name, respectively, of the new soft link.
link_name is interpreted relative to
link_loc_id
and must contain only the name of the soft link;
link_name may not contain any additional path elements.
If link_loc_id is a group identifier, the object pointed
to by link_name will be accessed as a member of that group.
If link_loc_id is a file identifier, the object will be
accessed as a member of the file’s root group.
lcpl_id and lapl_id are the
link creation and access property lists associated with the
new link.
For instance, if target_path is ./foo,
link_loc_id specifies ./x/y/bar,
and the name of the new link is new_link, then
a subsequent request for ./x/y/bar/new_link will
return same the object as would be found at ./foo.
H5Lcreate_soft is for use only if the target object
is in the current file.
If the desired target object is in a different file from the
new link, use
H5Lcreate_external
to create an external link.
Soft links and external links are also known as symbolic links as they use a name to point to an object; hard links employ an object’s address in the file.
Unlike hard links, a soft link in an HDF5 file is allowed to dangle, meaning that the target object need not exist at the time that the link is created.
The HDF5 library does not keep a count of soft links as it does of hard links.
const char *target_path |
IN: Path to the target object, which is not required to exist. |
hid_t link_loc_id |
IN: The file or group identifier for the new link. |
const char * link_name |
IN: The name of the new link. |
hid_t lcpl_id |
IN: Link creation property list identifier. |
hid_t lapl_id |
IN: Link access property list identifier. |
SUBROUTINE h5lcreate_soft_f(target_path, link_loc_id, link_name, hdferr, &
lcpl_id, lapl_id)
IMPLICIT NONE
CHARACTER(LEN=*), INTENT(IN) :: target_path
! Path to the target object,
! which is not required to exist.
INTEGER(HID_T), INTENT(IN) :: link_loc_id
! The file or group identifier for the new link.
CHARACTER(LEN=*), INTENT(IN) :: link_name
! The name of the new link.
INTEGER, INTENT(OUT) :: hdferr ! Error code:
! 0 on success and -1 on failure
INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id
! Link creation property list identifier.
INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id
! Link access property list identifier.
END SUBROUTINE h5lcreate_soft_f
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lcreate_ud(
hid_t link_loc_id,
const char *link_name,
H5L_type_t link_type,
const char *udata,
size_t udata_size,
hid_t lcpl_id,
hid_t lapl_id
)
H5Lcreate_ud creates a link
of user-defined type link_type
named link_name
at the location specified in link_loc_id
with user-specified data udata.
link_name is interpreted relative to
link_loc_id.
Valid values for the link class of the new link,
link_type, include H5L_TYPE_EXTERNAL
and any user-defined link classes that have been registered
with the library.
See H5Lregister
for further information.
The format of the information pointed to by udata is
defined by the user.
udata_size specifies the size of the udata
buffer.
udata may be NULL if
udata_size is zero (0).
The property lists specified by lcpl_id and
lapl_id specify properties used to create and access
the link.
H5L_TYPE_EXTERNAL,
included in the HDF5 Library distribution, is implemented as a
user-defined link type.
This was done, in part, to provide a model for the implementation
of other user-defined links.
hid_t link_loc_id
|
IN: Link location identifier |
const char *link_name
|
IN: Link name |
H5L_type_t link_type
|
IN: User-defined link class |
const char *udata
|
IN: User-supplied link information |
size_t udata_size
|
IN: Size of udata buffer
|
hid_t lcpl_id
|
IN: Link creation property list identifier |
hid_t lapl_id
|
IN: Link access property list identifier |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Ldelete(
hid_t loc_id,
const char *name,
hid_t lapl_id
)
H5Ldelete removes the link specified by
name from the location loc_id.
If the link being removed is a hard link, H5Ldelete
also decrements the link count for the object to which
name points. Unless there is a duplicate hard link
in that group, this action removes the object to which
name points from the group that previously contained it.
Object headers keep track of how many hard links refer to an object; when the hard link count, also referred to as the reference count, reaches zero, the object can be removed from the file. The file space associated will then be released, i.e., identified in memory as freespace. Objects which are open are not removed until all identifiers to the object are closed.
H5Ldelete;
if the link being removed is on the only path leading to an
HDF5 object, that object may become permanently inaccessible in
the file.
hid_t loc_id |
IN: Identifier of the file or group containing the object. |
const char *name |
IN: Name of the link to delete. |
hid_t lapl_id |
IN: Link access property list identifier. |
SUBROUTINE h5ldelete_f(loc_id, name, hdferr, lapl_id)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: loc_id ! Identifier of the file or group
! containing the object
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the link to delete
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 h5ldelete_f
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Ldelete_by_idx(
hid_t loc_id,
const char *group_name,
H5_index_t index_field,
H5_iter_order_t order,
hsize_t n,
hid_t lapl_id
)
H5Ldelete_by_idx removes the nth link in a group
according to the specified order, order,
in the specified index, index.
If loc_id specifies the group in which the link
resides, group_name can be a dot (.).
hid_t loc_id |
IN: File or group identifier specifying location of subject group |
const char *group_name |
IN: Name of subject group |
H5_index_t index_field |
IN: Index or field which determines the order |
H5_iter_order_t order |
IN: Order within field or index |
hsize_t n |
IN: Link for which to retrieve information |
hid_t lapl_id |
IN: Link access property list |
SUBROUTINE h5ldelete_by_idx_f(loc_id, group_name, index_field, order, n, &
hdferr, lapl_id)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: loc_id
! Identifer for object to which attribute is attached.
CHARACTER(LEN=*), INTENT(IN) :: group_name
! Name of object, relative to location,
! from which attribute is to be removed
INTEGER, INTENT(IN) :: index_field
! Type of index; Possible values are:
! H5_INDEX_UNKNOWN_F - Unknown index type
! H5_INDEX_NAME_F - Index on names
! H5_INDEX_CRT_ORDER_F - Index on creation order
! H5_INDEX_N_F - Number of indices defined
INTEGER, INTENT(IN) :: order
! Order in which to iterate over index;
! Possible values are:
! H5_ITER_UNKNOWN_F - Unknown order
! H5_ITER_INC_F - Increasing order
! H5_ITER_DEC_F - Decreasing order
! H5_ITER_NATIVE_F - No particular order,
! whatever is fastest
! H5_ITER_N_F - Number of iteration orders
INTEGER(HSIZE_T), INTENT(IN) :: n
! Offset within index
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 h5ldelete_by_idx_f
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lexists(
hid_t loc_id,
const char *name,
hid_t lapl_id
)
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:
H5Lexists to verify that
group1 exists.
group1 exists,
use H5Lexists again, this time
with name set to group1/group2,
to verify thatgroup2 exists.
group2 exists,
use H5Lexists with name
set to group1/group2/softlink_to_group3
to verify that softlink_to_group3 exists.
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.
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:
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.
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.
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. |
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.
name, except the target link, does not exist.
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
| 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. |
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 |
H5Pset_char_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. |
H5Lget_info_by_idx(
hid_t loc_id,
const char *group_name,
H5_index_t index_field,
H5_iter_order_t order,
hsize_t n,
H5L_info_t *link_val,
hid_t lapl_id
)
H5Lget_info_by_idx returns the metadata for a link
in a group according to a specified field or index and a specified
order.
The link for which information is to be returned is specified by
index_field, order, and n
as follows:
index_field specifies the field by which
the links in group_name are ordered.
The links may be indexed on this field, in which case
operations seeking specific links are likely to complete
more quickly.
order specifies the order in which the links
are to be referenced for the purposes of this function.
n specifies the position of the subject link.
Note that this count is zero-based;
0 (zero) indicates that the function will return
the value of the first link;
if n is 5, the function will return
the value of the sixth link; etc.
For example, assume that
index_field, order, and n are
H5_INDEX_NAME, H5_ITER_DEC, and 5,
respectively.
H5_INDEX_NAME indicates that the links are accessed
in alpha-numeric order by their names.
H5_ITER_DEC specifies that the list be traversed in
reverse order, or in decremented order.
And 5 specifies that this call to the function will
return the metadata for the 6th link (n + 1) from the end.
See H5Literate
for a list of valid values and further discussion regarding
index_field and order.
If loc_id specifies the group in which the link
resides, group_name can be a dot (.).
hid_t loc_id |
IN: File or group identifier specifying location of subject group |
const char *group_name |
IN: Name of subject group |
H5_index_t index_field |
IN: Index or field which determines the order |
H5_iter_order_t order |
IN: Order within field or index |
hsize_t n |
IN: Link for which to retrieve information |
H5L_info_t *link_val |
OUT: Buffer in which link value is returned |
hid_t lapl_id |
IN: Link access property list |
SUBROUTINE h5lget_info_by_idx_f(loc_id, group_name, index_field, order, n, &
link_type, f_corder_valid, corder, cset, address, val_size, &
hdferr, lapl_id)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: loc_id
! File or group identifier specifying
! location of subject group
CHARACTER(LEN=*), INTENT(IN) :: group_name
! Name of subject group
INTEGER, INTENT(IN) :: index_field
! Index/field which determines the order
! H5_INDEX_UNKNOWN_F - Unknown index type
! H5_INDEX_NAME_F - Index on names
! H5_INDEX_CRT_ORDER_F - Index on creation order
! H5_INDEX_N_F - Number of indices defined
INTEGER, INTENT(IN) :: order
! Order in which to iterate over index;
! Possible values are:
! H5_ITER_UNKNOWN_F - Unknown order
! H5_ITER_INC_F - Increasing order
! H5_ITER_DEC_F - Decreasing order
! H5_ITER_NATIVE_F - No particular order,
! whatever is fastest
INTEGER(HSIZE_T), INTENT(IN) :: n
! Attribute’s position in index
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
LOGICAL, INTENT(OUT) :: f_corder_valid
! Indicates whether the creation order data is
! valid for this attribute
INTEGER, INTENT(OUT) :: corder
! Is a positive integer containing the creation
! order of the attribute
INTEGER, INTENT(OUT) :: cset
! Indicates the character set used for the
! attribute’s name
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_by_idx_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. |
H5Lget_name_by_idx(
hid_t loc_id,
const char *group_name,
H5_index_t index_field,
H5_iter_order_t order,
hsize_t n,
char *name,
size_t size,
hid_t lapl_id
)
H5Lget_name_by_idx retrieves the name of the nth
link in a group, according to the specified order, order,
within a specified field or index, index_field.
If loc_id specifies the group in which the link
resides, group_name can be a dot (.).
The size in bytes of name is specified in
size.
If size is unknown, it can be determined via an
initial H5Lget_name_by_idx call with name
set to NULL; the function's return value will be the
size of the name.
hid_t loc_id |
IN: File or group identifier specifying location of subject group |
const char *group_name |
IN: Name of subject group |
H5_index_t index_field |
IN: Index or field which determines the order |
H5_iter_order_t order |
IN: Order within field or index |
hsize_t n |
IN: Link for which to retrieve information |
char *name |
OUT: Buffer in which link value is returned |
size_t size |
IN: Size in bytes of name |
hid_t lapl_id |
IN: Link access property list |
SUBROUTINE h5lget_info_by_idx_f(loc_id, group_name, index_field, order, n, &
f_corder_valid, corder, cset, data_size, hdferr, lapl_id)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: loc_id
! File/group identifier specifying location of subject group
CHARACTER(LEN=*), INTENT(IN) :: group_name
! Name of subject group
INTEGER, INTENT(IN) :: index_field
! Index or field which determines the order
! H5_INDEX_UNKNOWN_F - Unknown index type
! H5_INDEX_NAME_F - Index on names
! H5_INDEX_CRT_ORDER_F - Index on creation order
! H5_INDEX_N_F - Number of indices defined
INTEGER, INTENT(IN) :: order
! Order in which to iterate over index; Possible values are:
! H5_ITER_UNKNOWN_F - Unknown order
! H5_ITER_INC_F - Increasing order
! H5_ITER_DEC_F - Decreasing order
! H5_ITER_NATIVE_F - No particular order
! whatever is fastest
INTEGER(HSIZE_T), INTENT(IN) :: n
! Attribute’s position in index
LOGICAL, INTENT(OUT) :: f_corder_valid
! Indicates whether the creation order data is valid for
! this attribute
INTEGER, INTENT(OUT) :: corder
! Is a positive integer containing the creation order of the
! attribute
INTEGER, INTENT(OUT) :: cset
! Indicates the character set used for the attribute’s name
INTEGER(HSIZE_T), INTENT(OUT) :: data_size
! Indicates the size, in the number of characters, of
! the attribute
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_by_idx_f
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lget_val(
hid_t link_loc_id,
const char *link_name,
void *linkval_buff,
size_t size,
hid_t lapl_id
)
H5Lget_val returns the link value of the link
link_name.
The parameter link_loc_id is a file or group identifier.
link_name identifies a symbolic link and is defined
relative to link_loc_id.
Symbolic links include soft and external links and some user-defined
links.
This function is not for use with hard links.
The link value is returned in the buffer linkval_buff.
For soft links, this is the path to which the link points,
including the null terminator; for external and user-defined links,
it is the link buffer.
size is the size of linkval_buff
and should be the size of the link value being returned.
This size value can be determined through a call to
H5Lget_info; it is returned in the
val_size field of the H5L_info_t struct.
If size is smaller than the size of the returned
value, then the string stored in linkval_buff
will be truncated to size bytes.
For soft links, this means that the value will not be null terminated.
In the case of external links, the target file and object names
are extracted from linkval_buff by calling
H5Lunpack_elink_val.
The link class of link_name can be determined with a call
to H5Lget_info.
lapl_id specifies 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).
This function should be used only after
H5Lget_info has been called to verify that
link_name is a symbolic link.
This can be deteremined from the link_type field
of the H5L_info_t struct.
hid_t link_loc_id |
IN: File or group identifier. |
const char *link_name |
IN: Link whose value is to be returned. |
void *linkval_buff |
OUT: The buffer to hold the returned link value. |
size_t size |
IN: Maximum number of characters of link value to be returned. |
hid_t lapl_id |
IN: List access property list identifier. |
linkval_buff, if successful.
Otherwise returns a negative value.
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lget_val_by_idx(
hid_t loc_id,
const char *group_name,
H5_index_t index_type,
H5_iter_order_t order,
hsize_t n,
void *link_val,
size_t size,
hid_t lapl_id
)
H5Lget_val_by_idx retrieves the value of the nth
link in a group, according to the specified order, order,
within an index, index.
H5Lunpack_elink_val
loc_id specifies the file or group in which the group
specified by group_name is located.
group_name specifies the group in which the link exists.
If loc_id already specifies the group in which the link
exists, group_name must be a dot (.).
The size in bytes of group_name is specified in
size.
If size is unknown, it can be determined via an
initial H5Lget_val_by_idx call with size
set to NULL; size will be returned with
the actual size of group_name.
If the type of the link is unknown or uncertain,
H5Lget_val_by_idx should be called only after the type
has been determined via a call to
H5Lget_info_by_idx.
hid_t loc_id |
IN: File or group identifier specifying location of subject group |
const char *group_name |
IN: Name of subject group |
H5_index_t index_type |
IN: Type of index; valid values include:
NAME
Indexed by name
CORDER
Indexed by creation order
|
H5_iter_order_t order |
IN: Order within field or index; valid values include:
H5_ITER_INC
Iterate in increasing order
H5_ITER_DEC
Iterate in decreasing order
H5_ITER_NATIVE
Iterate in fastest order
|
hsize_t n |
IN: Link for which to retrieve information |
void *link_val |
OUT: Pointer to buffer in which link value is returned |
size_t size |
IN: Size in bytes of group_name |
hid_t lapl_id |
IN: Link access property list |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lis_registered(
H5L_type_t link_cls_id
)
H5Lis_registered tests whether a user-defined link
class is currently registered, either by the HDF5 Library
or by the user through the use of
H5Lregister.
A link class must be registered to create new links of that type or to traverse exisitng links of that type.
H5L_type_t link_cls_id
|
IN: User-defined link class identifier |
SUBROUTINE H5Lis_registered_f(link_cls_id, registered, hdferr)
IMPLICIT NONE
INTEGER, INTENT(IN) :: link_cls_id ! User-defined link class identifier
LOGICAL, INTENT(OUT) :: registered ! .TRUE. - if the link class is registered
! .FALSE. - if it is unregistered
INTEGER, INTENT(OUT) :: hdferr ! Error code:
! 0 on success and -1 on failure
END SUBROUTINE H5Lis_registered_f
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Literate(
hid_t group_id,
H5_index_t index_type,
H5_iter_order_t order,
hsize_t *idx,
H5L_iterate_t op,
void *op_data
)
H5Literate iterates through the links
in a group, specified by group_id,
in the order of the specified index, index_type,
using a user-defined callback routine op.
H5Literate does not recursively follow links into
subgroups of the specified group.
Three parameters are used to manage progress of the iteration:
index_type, order, and idx.
index_type specifies the index to be used.
If the links have not been indexed by the index type, they will first
be sorted by that index then the iteration will begin;
if the links have been so indexed, the sorting step will be
unnecessary, so the iteration may begin more quickly.
Valid values include the following:
H5_INDEX_NAME
| Alpha-numeric index on name | |
H5_INDEX_CRT_ORDER
| Index on creation order |
order specifies the order in which objects are to be
inspected along the index specified in index_type.
Valid values include the following:
H5_ITER_INC
| Increasing order | |
H5_ITER_DEC
| Decreasing order | |
H5_ITER_NATIVE
| Fastest available order |
idx allows an interrupted iteration to be resumed;
it is passed in by the application with a starting point and
returned by the library with the point at which the iteration stopped.
The op callback function,
the related H5L_info_t struct,
and the effect of the callback function’s return value
on the application are described in
H5Lvisit.
op_data is a user-defined pointer to the data required
to process links in the course of the iteration.
This pointer is passed back to each step of the iteration in the
op callback function’s op_data parameter.
As mentioned above, H5Literate is not recursive.
In particular, if a member of group_id is found to be
a group, call it subgroup_a, H5Literate
does not examine the members of subgroup_a.
When recursive iteration is required, the application can
do either of the following:
H5Literate:
H5Lvisit
H5Lvisit_by_name
H5Ovisit
H5Ovisit_by_name
H5Literate on discovered subgroups.
H5Literate assumes that the membership of the group
being iterated over remains unchanged through the iteration;
if any of the links in the group change during the iteration,
the function’s behavior is undefined.
Note, however, that objects pointed to by the links can be modified.
H5Literate is the same as deprecated function
H5Giterate, except that H5Giterate always
proceeded in alphanumeric order.
If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.
Examples of this kind of routine include callbacks such as
H5Pset_elink_cb and H5Pset_type_conv_cb
and functions such as H5Tconvert and
H5Ewalk2.
Exiting the routine in its normal fashion allows the HDF5 C Library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.
hid_t group_id |
IN: Identifier specifying subject group |
H5_index_t index_type |
IN: Type of index which determines the order |
H5_iter_order_t order |
IN: Order within index |
hsize_t *idx |
IN: Iteration position at which to start
OUT: Position at which an interrupted iteration may be restarted |
H5L_iterate_t op |
IN: Callback function passing data regarding the link to the calling application |
void *op_data |
IN: User-defined pointer to data required by the application for its processing of the link |
On failure, returns a negative value if something goes wrong within the library, or the first negative value returned by an operator.
SUBROUTINE h5literate_f(group_id, index_type, order, idx, &
op, op_data, return_value, hdferr)
INTEGER(HID_T) , INTENT(IN) :: group_id
INTEGER , INTENT(IN) :: index_type
INTEGER , INTENT(IN) :: order
INTEGER(HSIZE_T), INTENT(INOUT) :: idx
TYPE(C_FUNPTR) , INTENT(IN) :: op
TYPE(C_PTR) , INTENT(IN) :: op_data
INTEGER , INTENT(OUT) :: return_value
INTEGER , INTENT(OUT) :: hdferr
Inputs:
group_id - Identifier specifying subject group
index_type - Type of index which determines the order:
H5_INDEX_NAME_F - Alpha-numeric index on name
H5_INDEX_CRT_ORDER_F - Index on creation order
order - Order within index:
H5_ITER_INC_F - Increasing order
H5_ITER_DEC_F - Decreasing order
H5_ITER_NATIVE_F - Fastest available order
idx - IN: Iteration position at which to start
op - Callback function passing data regarding the link to the
calling application
op_data - User-defined pointer to data required by the application
for its processing of the link
Outputs:
idx - OUT: Position at which an interrupted iteration may
be restarted
return_value - Success: The return value of the first operator that
returns non-zero, or zero if all members were
processed with no operator returning non-zero.
Failure: Negative if something goes wrong within the
library, or the negative value returned by one
of the operators.
hdferr - Returns 0 if successful and -1 if fails
The integer type of the callback function must match the C
integer type. Therefore, for portability, all Fortran callback
functions used by h5literate_f should be declared as
INTEGER(KIND=C_INT).
| Release | Change |
| 1.8.8 | Fortran subroutine added. |
| 1.8.0 | C function introduced. |
H5Literate_by_name(
hid_t loc_id,
const char *group_name,
H5_index_t index_type,
H5_iter_order_t order,
hsize_t *idx,
H5L_iterate_t op,
void *op_data,
hid_t lapl_id
)
H5Literate_by_name iterates through the links
in a group, specified by loc_id and group_name,
in the order of the specified index, index_type,
using a user-defined callback routine op.
H5Literate_by_name does not recursively follow links into
subgroups of the specified group.
index_type specifies the index to be used.
If the links have not been indexed by the index type, they will first
be sorted by that index then the iteration will begin;
if the links have been so indexed, the sorting step will be
unnecesary, so the iteration may begin more quickly.
Valid values include the following:
H5_INDEX_NAME
| Alpha-numeric index on name | |
H5_INDEX_CRT_ORDER
| Index on creation order |
order specifies the order in which objects are to be
inspected along the index specified in index_type.
Valid values include the following:
H5_ITER_INC
| Increasing order | |
H5_ITER_DEC
| Decreasing order | |
H5_ITER_NATIVE
| Fastest available order |
idx allows an interrupted iteration to be resumed;
it is passed in by the application with a starting point and
returned by the library with the point at which the iteration stopped.
H5Literate_by_name is not recursive.
In particular, if a member of group_name is found to be
a group, call it subgroup_a, H5Literate_by_name
does not examine the members of subgroup_a.
When recursive iteration is required, the application must handle
the recursion, explicitly calling H5Literate_by_name
on discovered subgroups.
H5Literate_by_name assumes that the membership of the group
being iterated over remains unchanged through the iteration;
if any of the links in the group change during the iteration,
the function’s behavior is undefined.
Note, however, that objects pointed to by the links can be modified.
H5Literate_by_name is the same as H5Giterate,
except that H5Giterate always proceeds in alphanumeric
order.
If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.
Examples of this kind of routine include callbacks such as
H5Pset_elink_cb and H5Pset_type_conv_cb
and functions such as H5Tconvert and
H5Ewalk2.
Exiting the routine in its normal fashion allows the HDF5 C Library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.
hid_t loc_id |
IN: File or group identifier specifying location of subject group |
const char *group_name |
IN: Name of subject group |
H5_index_t index_type |
IN: Type of index which determines the order |
H5_iter_order_t order |
IN: Order within index |
hsize_t *idx |
IN: Iteration position at which to start
OUT: Position at which an interrupted iteration may be restarted |
H5L_iterate_t op |
IN: Callback function passing data regarding the link to the calling application |
void *op_data |
IN: User-defined pointer to data required by the application for its processing of the link |
hid_t lapl_id |
IN: Link access property list |
On failure, returns a negative value if something goes wrong within the library, or the first negative value returned by an operator.
SUBROUTINE h5literate_by_name_f(loc_id, group_name, index_type, &
order, idx, op, op_data, return_value, hdferr, lapl_id)
INTEGER(HID_T), INTENT(IN) :: loc_id
CHARACTER(LEN=*) :: group_name
INTEGER, INTENT(IN) :: index_type
INTEGER, INTENT(IN) :: order
INTEGER(HSIZE_T), INTENT(INOUT) :: idx
TYPE(C_FUNPTR):: op
TYPE(C_PTR) :: op_data
INTEGER, INTENT(OUT) :: return_value
INTEGER, INTENT(OUT) :: hdferr
INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id
Inputs:
loc_id - File or group identifier specifying location of subject group
group_name - Name of subject group
index_type - Type of index which determines the order:
H5_INDEX_NAME_F - Alpha-numeric index on name
H5_INDEX_CRT_ORDER_F - Index on creation order
order - Order within index:
H5_ITER_INC_F - Increasing order
H5_ITER_DEC_F - Decreasing order
H5_ITER_NATIVE_F - Fastest available order
idx - IN: Iteration position at which to start
op - Callback function passing data regarding the link to the
calling application
op_data - User-defined pointer to data required by the application for
its processing of the link
Outputs:
idx - OUT: Position at which an interrupted iteration
may be restarted
return_value - Success: The return value of the first operator that
returns non-zero, or zero if all members were
processed with no operator returning non-zero.
Failure: Negative if something goes wrong within the
library, or the negative value returned by one
of the operators.
hdferr - Returns 0 if successful and -1 if fails
Optional parameters:
lapl_id - Link access property list
The integer type of the callback function must match the C
integer type. Therefore, for portability, all Fortran callback
functions used by h5literate_by_name_f should be declared as
INTEGER(KIND=C_INT).
| Release | Change |
| 1.8.8 | Fortran subroutine added. |
| 1.8.0 | C function introduced. |
H5Lmove(
hid_t src_loc_id,
const char *src_name,
hid_t dest_loc_id,
const char *dest_name,
hid_t lcpl_id,
hid_t lapl_id
)
H5Lmove moves a link within an HDF5 file.
The original link, src_name,
is removed from src_loc_id and
the new link, dest_name,
is inserted at dest_loc_id.
This change is accomplished as an atomic operation.
src_loc_id and src_name identify the
original link.
src_loc_id is either a file or group identifier;
src_name is the path to the link and is interpreted
relative to src_loc_id.
dest_loc_id and dest_name identify the
new link.
dest_loc_id is either a file or group identifier;
dest_name is the path to the link and is interpreted
relative to dest_loc_id.
Note that H5Lmove does not modify the value of the link;
the new link points to the same object as the original link pointed to.
Furthermore, if the object pointed to by the original link
was already open with a valid object identifier,
that identifier will remain valid after the call to
H5Lmove.
lcpl_id and lapl_id are the link creation
and link access property lists, respectively, associated with
the new link, dest_name.
Through these property lists, several properties are available to
govern the behavior of H5Lmove.
The property controlling creation of missing intermediate groups
is set in the link creation property list with
H5Pset_create_intermediate_group;
H5Lmove ignores any other properties in the link creation
property list.
Properties controlling character encoding, link traversals, and
external link prefixes are set in the link access property list with
H5Pset_char_encoding,
H5Pset_nlinks, and
H5Pset_elink_prefix, respectively.
H5Lmove.
If the link being moved is on the only path leading to an HDF5 object,
that object may become permanently inaccessible in the file.
hid_t src_loc_id |
IN: Original file or group identifier. |
const char *src_name |
IN: Original link name. |
hid_t dest_loc_id |
IN: Destination file or group identifier. |
const char *dest_name |
IN: New link name. |
hid_t lcpl_id |
IN: Link creation property list identifier to be associated with the new link. |
hid_t lapl_id |
IN: Link access property list identifier to be associated with the new link. |
SUBROUTINE h5lmove_f(src_loc_id, src_name, dest_loc_id, dest_name, hdferr, &
lcpl_id, lapl_id)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: src_loc_id
! Original file or group identifier.
CHARACTER(LEN=*), INTENT(IN) :: src_name
! Original link name.
INTEGER(HID_T), INTENT(IN) :: dest_loc_id
! Destination file or group identifier.
CHARACTER(LEN=*), INTENT(IN) :: dest_name
! New link name.
INTEGER(HID_T), INTENT(OUT) :: hdferr ! Error code:
! 0 on success and -1 on failure
INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id
! Link creation property list identifier
! to be associated with the new link.
INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id
! Link access property list identifier
! to be associated with the new link.
END SUBROUTINE h5lmove_f
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lregister(
const H5L_class_t * link_class
)
H5Lregister registers a class of user-defined links,
or changes the behavior of an existing class.
link_class is a pointer to a buffer containing
a copy of the H5L_class_t struct.
This struct is defined in H5Lpublic.h as follows:
typedef struct H5L_class_t {
int version; /* Version number of this struct */
H5L_type_t class_id; /* Link class identifier */
const char *comment; /* Comment for debugging */
H5L_create_func_t create_func; /* Callback during link creation */
H5L_move_func_t move_func; /* Callback after moving link */
H5L_copy_func_t copy_func; /* Callback after copying link */
H5L_traverse_func_t trav_func; /* The main traversal function */
H5L_delete_func_t del_func; /* Callback for link deletion */
H5L_query_func_t query_func; /* Callback for queries */
} H5L_class_t;
link_class must include
at least the following:
H5L_class_t version
(which should be H5L_LINK_CLASS_T_VERS)
class_id
trav_func
NULL.
The link class passed in class_id
must be in the user-definable range between
H5L_TYPE_UD_MIN and H5L_TYPE_UD_MAX
(see the “Link Class Identifiers...” table below)
and will override any existing link class with that identifier.
As distributed, valid values of class_id used in HDF5
include the following (defined in H5Lpublic.h):
H5L_TYPE_HARD
| Hard link | |
H5L_TYPE_SOFT
| Soft link | |
H5L_TYPE_EXTERNAL
| External link |
H5Lregister is used to register additional link classes.
It could also be used to modify the behavior of the external link
class, though that is not recommended.
The following table summarizes existing link types and values and the reserved and user-definable link class identifier value ranges.
|
Link Class Identifiers or Value Ranges,
Descriptions, and Class Names
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Note that HDF5 internally registers user-defined link classes only
by the numeric value of the link class identifier.
An application, on the other hand, will generally use a name for a
user-defined class, if for no other purpose than as a variable name.
Assume, for example, that a complex link type is registered
with the link class identifier 73
and that the code includes the following assignment:
H5L_TYPE_COMPLEX_A = 73
The application can refer to the link class with a term,
H5L_TYPE_COMPLEX_A, that conveys meaning
to a human reviewing the code, while HDF5 recognizes it
by the more cryptic numeric identifier, 73.
class_id values.
See below.
H5L_LINK_EXTERNAL
equal to H5L_LINK_UD_MIN.
class_id in the H5L_class_t struct
must not equal H5L_LINK_UD_MIN unless you intend to
overwrite or modify the behavior of external links.
H5Lregister can be used only with
link class identifiers in the user-definable range
(see table above).
H5L_TYPE_HARD and H5L_TYPE_SOFT,
reside in the reserved range below H5L_TYPE_UD_MIN
and cannot be redefined or modified.
H5Lis_registered
can be used to determine whether a desired link class identifier
is available.
H5L_TYPE_MAX is the maximum allowed value for a
link type identifier.
H5L_TYPE_UD_MIN equals H5L_TYPE_EXTERNAL.
H5L_TYPE_UD_MAX equals H5L_TYPE_MAX.
H5L_TYPE_ERROR indicates that an error has occurred.
const H5L_class_t *link_class
|
IN: Pointer to a buffer containing the struct describing the user-defined link class |
H5Lregister. For example:
In such cases, you are encouraged to register that link class
with The HDF Group’s Helpdesk
(contact).
The HDF Group maintains a registry of known user-defined
link classes and tracks the selected link class identifiers.
This registry is intended to reduce the risk of collisions
between class_id values and to help coordinate the
use of specialized link classes.
H5Lis_registered
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lunpack_elink_val(
char *ext_linkval,
size_t link_size,
unsigned *flags,
const char **filename,
const char **obj_path
)
H5Lunpack_elink_val decodes the external link
information returned by H5Lget_val in
the ext_linkval buffer.
ext_linkval should be the buffer set by
H5Lget_val
and will consist of two NULL-terminated strings,
the filename and object path, one after the other.
Given this buffer, H5Lunpack_elink_val creates
pointers to the filename and object path within the buffer
and returns them in filename and obj_path,
unless they are passed in as NULL.
H5Lunpack_elink_val requires that ext_linkval
contain a concatenated pair of null-terminated strings, so use of
this function on a string that is not an external link
udata buffer may result in a segmentation fault.
This failure can be avoided by adhering to the following procedure:
H5Lget_info to get the link type
and the size of the link value.
H5L_TYPE_EXTERNAL.
H5Lget_val to get the link value.
H5Lunpack_elink_val to unpack that value.
const char *ext_linkval
|
IN: Buffer containing external link information |
size_t link_size
|
IN: Size, in bytes, of the ext_linkval
buffer
|
unsigned *flags
|
OUT: External link flags, packed as a bitmap
(Reserved as a bitmap for flags; no flags are currently defined, so the only valid value is 0.) |
const char **filename
|
OUT: Returned filename |
const char **obj_path
|
OUT: Returned object path, relative to
filename
|
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lunregister(
H5L_type_t link_cls_id
)
H5Lunregister unregisters a class of user-defined links,
preventing them from being traversed, queried, moved, etc.
A link class can be re-registered using H5Lregister.
H5L_type_t link_cls_id
|
IN: User-defined link class identifier |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lvisit(
hid_t group_id,
H5_index_t index_type,
H5_iter_order_t order,
H5L_iterate_t op,
void *op_data
)
H5Lvisit is a recursive iteration function
to visit all links in and below a group in an HDF5 file,
thus providing a mechanism for an application to perform
a common set of operations across all of those links
or a dynamically selected subset.
For non-recursive iteration across the members of a group,
see H5Literate.
The group serving as the root of the iteration is specified by
its group identifier, group_id.
Two parameters are used to establish the iteration:
index_type and order.
index_type specifies the index to be used.
If the links have not been indexed by the index type, they will first
be sorted by that index then the iteration will begin;
if the links have been so indexed, the sorting step will be
unnecesary, so the iteration may begin more quickly.
Valid values include the following:
H5_INDEX_NAME
| Alpha-numeric index on name | |
H5_INDEX_CRT_ORDER
| Index on creation order |
Note that the index type passed in index_type is a
best effort setting.
If the application passes in a value indicating iteration in
creation order and a group is encountered that was not tracked
in creation order, that group will be iterated over in
alpha-numeric order by name, or name order.
(Name order is the native order used by the HDF5 Library
and is always available.)
order specifies the order in which objects are to be
inspected along the index specified in index_type.
Valid values include the following:
H5_ITER_INC
| Increasing order | |
H5_ITER_DEC
| Decreasing order | |
H5_ITER_NATIVE
| Fastest available order |
The protoype of the callback function op is as follows
(as defined in the source code file H5Lpublic.h):
(*H5L_iterate_t)(
hid_t g_id,
const char *name,
const H5L_info_t *info,
void *op_data)
The parameters of this callback function have the following values or meanings:
|
g_id
|
Group that serves as root of the iteration; same value
as the H5Lvisit group_id parameter
|
|
name
|
Name of link, relative to g_id,
being examined at current step of the iteration
|
|
info
| H5L_info_t struct containing information regarding that link |
|
op_data
|
User-defined pointer to data required by the application
in processing the link;
a pass-through of the op_data pointer provided
with the H5Lvisit function call
|
The H5L_info_t struct is defined (in H5Lpublic.h)
as follows:
typedef struct {
H5L_type_t type; /* Type of link */
hbool_t corder_valid; /* Indicates whether creation */
/* order is valid */
int64_t corder; /* Creation order */
H5T_cset_t cset; /* Character set of link name */
union {
haddr_t address; /* Address hard link points to */
size_t val_size; /* Size of soft link or */
/* user-defined link value */
} u;
} H5L_info_t;
The possible return values from the callback function, and the effect of each, are as follows:
The H5Lvisit op_data parameter is a
user-defined pointer to the data required to process links
in the course of the iteration.
This pointer is passed back to each step of the iteration in the
op callback function’s op_data parameter.
H5Lvisit and
H5Ovisit
are companion functions:
one for examining and operating on links;
the other for examining and operating on the objects that
those links point to.
Both functions ensure that by the time the function completes
successfully, every link or object below the specified point in the
file has been presented to the application for whatever
processing the application requires.
If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.
Examples of this kind of routine include callbacks such as
H5Pset_elink_cb and H5Pset_type_conv_cb
and functions such as H5Tconvert and
H5Ewalk2.
Exiting the routine in its normal fashion allows the HDF5 C Library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.
hid_t group_id
|
IN: Identifier of the group at which the recursive iteration begins. |
H5_index_t index_type
|
IN: Type of index; valid values include:
H5_INDEX_NAME
H5_INDEX_CRT_ORDER
|
H5_iter_order_t order
|
IN: Order in which index is traversed;
valid values include:
H5_ITER_DEC
H5_ITER_INC
H5_ITER_NATIVE
|
H5L_iterate_t op
|
IN: Callback function passing data regarding the link to the calling application |
void *op_data
|
IN: User-defined pointer to data required by the application for its processing of the link |
On failure, returns a negative value if something goes wrong within the library, or the first negative value returned by an operator.
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Lvisit_by_name(
hid_t loc_id,
const char *group_name,
H5_index_t index_type,
H5_iter_order_t order,
H5L_iterate_t op,
void *op_data,
hid_t lapl_id
)
H5Lvisit_by_name is a recursive iteration function
to visit all links in and below a group in an HDF5 file,
thus providing a mechanism for an application to perform
a common set of operations across all of those links
or a dynamically selected subset.
For non-recursive iteration across the members of a group,
see H5Literate.
The group serving as the root of the iteration is specified by
the loc_id / group_name parameter pair.
loc_id specifies a file or group;
group_name specifies either
a group in the file (with an absolute name based in the
file’s root group) or
a group relative to loc_id.
If loc_id fully specifies the group that is to
serve as the root of the iteration, group_name should
be '.' (a dot).
(Note that when loc_id fully specifies the the
group that is to serve as the root of the iteration,
the user may wish to consider using
H5Lvisit
instead of H5Lvisit_by_name.)
Two parameters are used to establish the iteration:
index_type and order.
index_type specifies the index to be used.
If the links have not been indexed by the index type, they will first
be sorted by that index then the iteration will begin;
if the links have been so indexed, the sorting step will be
unnecesary, so the iteration may begin more quickly.
Valid values include the following:
H5_INDEX_NAME
| Alpha-numeric index on name | |
H5_INDEX_CRT_ORDER
| Index on creation order |
Note that the index type passed in index_type is a
best effort setting.
If the application passes in a value indicating iteration in
creation order and a group is encountered that was not tracked
in creation order, that group will be iterated over in
alpha-numeric order by name, or name order.
(Name order is the native order used by the HDF5 Library
and is always available.)
order specifies the order in which objects are to be
inspected along the index specified in index_type.
Valid values include the following:
H5_ITER_INC
| Increasing order | |
H5_ITER_DEC
| Decreasing order | |
H5_ITER_NATIVE
| Fastest available order |
The op callback funtion,
the related H5L_info_t struct,
and the effect that the callback function’s return value has
on the application are described in
H5Lvisit.
The H5Lvisit_by_name op_data parameter is a
user-defined pointer to the data required to process links
in the course of the iteration.
This pointer is passed back to each step of the iteration in
the callback function’s op_data parameter.
lapl_id is a link access property list.
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).
H5Lvisit_by_name and
H5Ovisit_by_name
are companion functions:
one for examining and operating on links;
the other for examining and operating on the objects that
those links point to.
Both functions ensure that by the time the function completes
successfully, every link or object below the specified point in the
file has been presented to the application for whatever
processing the application requires.
If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.
Examples of this kind of routine include callbacks such as
H5Pset_elink_cb and H5Pset_type_conv_cb
and functions such as H5Tconvert and
H5Ewalk2.
Exiting the routine in its normal fashion allows the HDF5 C Library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.
hid_t loc_id
|
IN: Identifier of a file or group |
const char *name
|
IN: Name of the group,
generally relative to loc_id,
that will serve as root of the iteration
|
H5_index_t index_type
|
IN: Type of index; valid values include:
H5_INDEX_NAME
H5_INDEX_CRT_ORDER
|
H5_iter_order_t order
|
IN: Order in which index is traversed;
valid values include:
H5_ITER_DEC
H5_ITER_INC
H5_ITER_NATIVE
|
H5L_iterate_t op
|
IN: Callback function passing data regarding the link to the calling application |
void *op_data
|
IN: User-defined pointer to data required by the application for its processing of the link |
hid_t lapl_id
|
IN: Link access property list identifier |
On failure, returns a negative value if something goes wrong within the library, or the first negative value returned by an operator.
| Release | C |
| 1.8.0 | Function introduced in this release. |
|
The HDF Group Help Desk:
Describes HDF5 Release 1.10. |
Copyright by
The HDF Group
and the Board of Trustees of the University of Illinois |