Last modified: 26 July 2011
Name: H5Lcopy
Signature:
  herr_t `H5Lcopy`( 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:
  Copies a link from one location to another.

Description:
  `H5Lcopy` copies the link specified by `src_name` from the file or group specified by `src_loc_id` to the file or group specified by `dest_loc_id`. The new copy of the link is created with the name `dest_name`.

  If `dest_loc_id` is a file identifier, `dest_name` will be interpreted relative to that file’s root group.

  The new link is created with the creation and access property lists specified by `lcpl_id` and `lapl_id`. The interpretation of `lcpl_id` is limited in the manner described in the next paragraph.

  `H5Lcopy` retains the creation time and the target of the original link. However, since the link may be renamed, the character encoding is that specified in `lcpl_id` rather than that of the original link. Other link creation properties are ignored.

  If the link is a soft link, also known as a symbolic link, its target is interpreted relative to the location of the copy.

  Several properties are available to govern the behavior of `H5Lcopy`. These properties are set in the link creation and access property lists, `lcpl_id` and `lapl_id`, respectively. The property controlling creation of missing intermediate groups is set in the link creation property list with `H5Pset_create_intermediate_group`; this function 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`.

  `H5Lcopy` does not affect the object that the link points to.

  `H5Lcopy` cannot copy hard links across files as a hard link is not valid without a target object; to copy objects from one file to another, see `H5Ocopy`.

Parameters:

  hid_t `src_loc_id` | IN: Location identifier of the source link
  const char *`src_name` | IN: Name of the link to be copied
  hid_t `dest_loc_id` | IN: Location identifier specifying the destination of the copy
  const char *`dest_name` | IN: Name to be assigned to the new copy
  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: h5lcopy_f

      SUBROUTINE h5lcopy_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
                                         ! Location identifier of the source link
        CHARACTER(LEN=*), INTENT(IN) :: src_name
                                         ! Name of the link to be copied
        INTEGER(HID_T), INTENT(IN) :: dest_loc_id
                                         ! Location identifier specifying the
                                         ! destination of the copy
        CHARACTER(LEN=*), INTENT(IN) :: dest_name
                                         ! Name to be assigned to the new copy
        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 h5lcopy_f

History:

  Release | C
  1.8.0 | Function introduced in this release.