H5Lcreate_external
(
const char *file_name
,
const char *object_name
,
hid_t link_loc_id
,
const char *link_name
,
hid_t lcpl_id
,
hid_t lapl_id
)
H5Lcreate_external
creates a new soft link to an
external object, which is an object in a different HDF5 file
from the location of the link.
file_name
identifies the target file containing the
target object;
object_name
specifies the path of the target object
within that file.
object_name
must start at the target file’s
root group but is not interpreted until lookup time.
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
to the place where the new link is to be created.
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 file_name
as
described below:
file_name
is a relative pathname, the following
steps are performed:
HDF5_EXT_PREFIX
and
will try to prepend each prefix to file_name
to form a new file_name
.
file_name
does not exist or
HDF5_EXT_PREFIX
is not set,
the library will get the prefix set via
H5Pset_elink_prefix
and
prepend it to file_name
to form a new file_name
.
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 file_name
to form a new file_name
.
file_name
does not exist,
then the library will look for file_name
and will return failure/success accordingly.
file_name
is an absolute pathname, the library
will try to find file_name
.
If file_name
does not exist,
the file_name
is stripped of the directory paths
to form a new file_name
.
See examples below on how file_name
is stripped
to form a new file_name
.
The search for the new file_name
then follows the
same steps as described above for a relative pathname.
Note that file_name
is considered to be an absolute pathname
when the following condition is true:
file_name
is a
slash ( /
). For example:
/tmp/A.h5
.
If file_name
does not exist,
the new file_name
after stripping
file_name
will be A.h5
.
file_name
is an absolute drive with
absolute pathname. For example:
C:\tmp\A.h5
.
If file_name
does not exist,
the new file_name
after stripping
file_name
will be A.h5
.
file_name
is an absolute pathname without
specifying drive name. For example:
\tmp\A.h5
.
If file_name
does not exist,
the new file_name
after stripping
file_name
will be A.h5
.
file_name
is an absolute drive with
relative pathname. For example:
C:tmp\A.h5
.
If file_name
does not exist,
the new file_name
after stripping
file_name
will be tmp\A.h5
.
file_name
is in UNC (Uniform Naming
Convention) format with server name, share name,
and pathname. For example:
\\serverA\shareB\tmp\A.h5
.
If file_name
does not exist, the new
file_name
after stripping
file_name
will be A.h5
.
file_name
is in Long UNC (Uniform Naming
Convention) format with server name, share name, and
pathname. For example:
\\?\serverA\shareB\tmp\A.h5
.
If file_name
does not exist, the new
file_name
after stripping
file_name
will be A.h5
.
file_name
is in Long UNC (Uniform Naming
Convention) format with an absolute drive with
absolute pathname. For example:
\\?\C:\tmp\A.h5
.
If file_name
does not exist, the new
file_name
after stripping
file_name
will be A.h5
.
The library opens the target file 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 identifier is set, the library uses the
file access property list identifier of the file associated with
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 * file_name |
IN: Name of the target file containing the target object. |
const char *object_name |
IN: Path within the target file to the target object. |
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_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 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_external_f
H5Pset_elink_fapl
,
H5Pset_elink_cb
Release | C |
1.8.0 | Function introduced in this release. |