Page tree









Copies an object in an HDF5 file


H5O_COPY(src_loc_id, src_name, dst_loc_id, dst_name, ocpypl_id, lcpl_id)


herr_t H5Ocopy(
            hid_t src_loc_id,
            const char *src_name,
            hid_t dst_loc_id,
            const char *dst_name,
            hid_t ocpypl_id,
            hid_t lcpl_id

 SUBROUTINE h5ocopy_f(src_loc_id, src_name, dst_loc_id,    &
        dst_name, hdferr, ocpypl_id, lcpl_id)
    INTEGER(HID_T)  , INTENT(IN)  :: src_loc_id
    CHARACTER(LEN=*), INTENT(IN)  :: src_name
    INTEGER(HID_T)  , INTENT(IN)  :: dst_loc_id
    CHARACTER(LEN=*), INTENT(IN)  :: dst_name
    INTEGER         , INTENT(OUT) :: hdferr
    INTEGER(HID_T)  , INTENT(IN), OPTIONAL :: ocpypl_id

hid_t src_loc_idIN: Object identifier indicating the location of the source object to be copied
const char *src_nameIN: Name of the source object to be copied
hid_t dst_loc_idIN: Location identifier specifying the destination
const char *dst_name    IN: Name to be assigned to the new copy
hid_t ocpypl_idIN: Object copy property list
hid_t lcpl_idIN: Link creation property list for the new hard link


H5Ocopy copies the group, dataset or committed datatype specified by src_name from the file or group specified by src_loc_id to the destination location dst_loc_id.

The destination location, as specified in dst_loc_id, may be a group in the current file or a location in a different file. If dst_loc_id is a file identifier, the copy will be placed in that file’s root group.

The copy will be created with the path specified in dst_name, which must not pre-exist in the destination location. If dst_name already exists at the location dst_loc_id, H5Ocopy will fail. If dst_name is an absolute path, the copy will be created relative to the file’s root group.

The copy of the object is created with the creation property lists specified by ocpypl_id and lcpl_id.

H5Ocopy will always try to make a copy of the object specified in src_name.

  • If the object specified by src_name is a group containing a soft or external link, the default is that the new copy will contain a soft or external link with the same value as the original. See H5Pset_copy_object for optional settings.
  • If the path specified in src_name is or contains a soft link or an external link, H5Ocopy will copy the target object. Use H5Lcopy if the intent is to create a new soft or external link with the same value as the original link.

Several flags are available to govern the behavior of H5Ocopy:

  • A flag controlling the creation of intermediate groups that may not yet exist is set in the link creation property list lcpl_id with H5Pset_create_intermediate_group.
  • Copying of committed datatypes can be tuned through the use of H5Pset_copy_object, H5Padd_merge_committed_dtype_path, H5Pset_mcdt_search_cb, and related functions.
  • Flags controlling other aspects of object copying are set in the object copy property list ocpypl_id with H5Pset_copy_object.

H5Ocopy can be used to copy an object in an HDF5 file. If an object has been changed since it was opened, it should be written back to the file before using H5Ocopy. The object can be written back either by closing the object (H5Gclose, H5Oclose, H5Dclose, or H5Tclose) or by flushing the HDF5 file (H5Fflush).


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


Coming Soon!

Release    C
1.8.0Function introduced in this release.
1.8.9Fortran subroutine introduced in this release.

--- Last Modified: February 19, 2018 | 02:34 PM