Last modified: 18 June 2013
Name: H5Lcreate_external
Signature:
herr_t 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 )

Purpose:
Creates an external link, a soft link to an object in a different file.

Description:
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:

Note that target_file_name is considered to be an absolute pathname when the following condition is true:

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.

Parameters:
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

Returns:
Returns a non-negative value if successful; otherwise returns a negative value.

Fortran90 Interface: h5lcreate_external_f
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
    

See Also:
H5Pset_elink_fapl,   H5Pset_elink_cb

H5L_elink_traverse_t

History:
Release     C
1.8.0 Function introduced in this release.