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.
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
.
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. |