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