Last modified: 2 July 2012
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_id`, hid_t `lapl_id` )

Purpose:
  Moves a link within an HDF5 file.

Description:
  `H5Lmove` moves a link within an HDF5 file. The original link, `src_name`, is removed from `src_loc_id` and the new link, `dest_name`, is inserted at `dest_loc_id`. This change is accomplished as an atomic operation.

  `src_loc_id` and `src_name` identify the original 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`.

  Note that `H5Lmove` does not modify the value of the link; the new link points to the same object as the original link pointed to. Furthermore, if the object pointed to by the original link was already open with a valid object identifier, that identifier will remain valid after the call to `H5Lmove`.

  `lcpl_id` and `lapl_id` 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.