Last modified: 5 November 2009
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.

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.

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.