Name: H5Lmove
Signature:
herr_t H5Lmove( hid_t src_loc_id, const char *src_name, hid_t dest_loc_id, const char *dest_name, hid_t lcpl, hid_t lapl )

Purpose:
Renames a link within an HDF5 file.

Description:
H5Lmove renames a link within an HDF5 file. The original link, src_name, is removed from the group graph and the new link, dest_name, is inserted; this change is accomplished as an atomic operation.

src_loc_id and src_name identify the existing link. src_loc_id is either a file or group identifier; src_name is the path to the link and is interpreted relative to src_loc_id.

dest_loc_id and dest_name identify the new link. dest_loc_id is either a file or group identifier; dest_name is the path to the link and is interpreted relative to dest_loc_id.

lcpl and lapl are the link creation and link access property lists, respectively, associated with the new link, dest_name.

Through these property lists, several properties are available to govern the behavior of H5Lmove. The property controlling creation of missing intermediate groups is set in the link creation property list with H5Pset_create_intermediate_group; H5Lmove ignores any other properties in the link creation property list. Properties controlling character encoding, link traversals, and external link prefixes are set in the link access property list with H5Pset_char_encoding, H5Pset_nlinks, and H5Pset_elink_prefix, respectively.

Warning:
Exercise care in moving links as it is possible to render data in a file inaccessible with H5Lmove. If the link being moved is on the only path leading to an HDF5 object, that object may become permanently inaccessible in the file.

Parameters:
hid_t src_loc_id IN: Original file or group identifier.
const char *src_name     IN: Original link name.
hid_t dest_loc_id IN: Destination file or group identifier.
const char *dest_name IN: New link name.
hid_t lcpl_id IN: Link creation property list identifier to be associated with the new link.
hid_t lapl_id IN: Link access property list identifier to be associated with the new link.

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

Fortran90 Interface: h5lmove_f
SUBROUTINE h5lmove_f(src_loc_id, src_name, dest_loc_id, dest_name, hdferr, &
    lcpl_id, lapl_id)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: src_loc_id  
                                        ! Original file or group identifier.
  CHARACTER(LEN=*), INTENT(IN) :: src_name  
                                        ! Original link name.
  INTEGER(HID_T), INTENT(IN) :: dest_loc_id 
                                        ! Destination file or group identifier.
  CHARACTER(LEN=*), INTENT(IN) :: dest_name 
                                        ! new link name.
  INTEGER(HID_T), 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 
                                        ! to be associated with the new link.
  INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id 
                                        ! Link access property list identifier 
                                        ! to be associated with the new link.
END SUBROUTINE h5lmove_f
    

History:
Release     C
1.8.0 Function introduced in this release.