Last modified: 28 June 2012
Name: H5Ocopy
Signature:
  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` )

Purpose:
  Copies an object in an HDF5 file.

Description:
  `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`).

Parameters:

hid_t `src_loc_id` | IN: Object identifier indicating the location of the source object to be copied
const char *`src_name` | IN: Name of the source object to be copied
hid_t `dst_loc_id` | IN: Location identifier specifying the destination
const char *`dst_name` | IN: Name to be assigned to the new copy
hid_t `ocpypl_id` | IN: Object copy property list
hid_t `lcpl_id` | IN: Link creation property list for the new hard link

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

See Also:

  `H5Pset_copy_object` `H5Pset_create_intermediate_group` |  | `H5Padd_merge_committed_dtype_path` `H5Pset_mcdt_search_cb`

  Copying Committed Datatypes with `H5Ocopy` |  | A comprehensive discussion of copying committed datatypes (PDF) in Advanced Topics in HDF5

Fortran90 Interface: h5ocopy_f

History:

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