Help us improve by taking our short survey: https://www.hdfgroup.org/website-survey/

| HDF5 Last Updated on 2026-07-28 The HDF5 Field Guide

Loading...
Searching...
No Matches
Object Copy Properties
Property Lists (H5P)

## Detailed Description

Object copy property list functions (H5P)
Function | Purpose
--- | ---
H5Padd_merge_committed_dtype_path | Adds a path to the list of paths that will be searched in the destination file for a matching committed datatype.
H5Pfree_merge_committed_dtype_paths | Clears the list of paths stored in the object copy property list.
H5Pset_copy_object/H5Pget_copy_object | Sets/gets the properties to be used when an object is copied.
H5Pset_mcdt_search_cb/H5Pget_mcdt_search_cb | Sets/gets the callback function that H5Ocopy() will invoke before searching for a matching committed datatype.

## Functions
herr_t | H5Padd_merge_committed_dtype_path (hid_t plist_id, const char *path)
| Adds a path to the list of paths that will be searched in the destination file for a matching committed datatype.
herr_t | H5Pfree_merge_committed_dtype_paths (hid_t plist_id)
| Clears the list of paths stored in the object copy property list.
herr_t | H5Pget_copy_object (hid_t plist_id, unsigned *copy_options)
| Retrieves the properties to be used when an object is copied.
herr_t | H5Pget_mcdt_search_cb (hid_t plist_id, H5O_mcdt_search_cb_t *func, void **op_data)
| Retrieves the callback function from the specified object copy property list.
herr_t | H5Pset_copy_object (hid_t plist_id, unsigned copy_options)
| Sets properties to be used when an object is copied.
herr_t | H5Pset_mcdt_search_cb (hid_t plist_id, H5O_mcdt_search_cb_t func, void *op_data)
| Sets the callback function that H5Ocopy() will invoke before searching the entire destination file for a matching committed datatype.

## Function Documentation

## ◆ H5Padd_merge_committed_dtype_path()

herr_t H5Padd_merge_committed_dtype_path | ( | hid_t | plist_id,
|  | const char * | path )

Adds a path to the list of paths that will be searched in the destination file for a matching committed datatype.

Parameters

  [in] | plist_id | Object copy property list identifier
  [in] | path | The path to be added

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

H5Padd_merge_committed_dtype_path() adds a path, `path`, which points to a committed datatype, to the current list of suggested paths stored in the object copy property list `plist_id`. The search as described in the next paragraph is effective only if the H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG is enabled in the object copy property list via H5Pset_copy_object().

When copying a committed datatype, a dataset with a committed datatype, or an object with an attribute of a committed datatype, the default behavior of H5Ocopy() is to search for a matching committed datatype:

1. First search the list of suggested paths in the object copy property list.
2. Then, if no match has been found, search all the committed datatypes in the destination file.

The default Step 2 in this search process can be changed by setting a callback function (see H5Pset_mcdt_search_cb()).

Two datatypes are determined equal if their descriptions are identical, in a manner similar to H5Tequal(). If either committed datatype has one or more attributes, then all attributes must be present in both committed datatypes and they must be identical. Two attributes are considered identical if their datatype description, dataspace, and raw data values are the same. However, if an attribute uses a committed datatype, that committed datatype's attributes will not be compared.

If a match is found, H5Ocopy() will perform the following in the destination file:

- For a committed datatype, the library will create a hard link to the found datatype.
- For a dataset that uses a committed datatype, the library will modify the copied dataset to use the found committed datatype as its datatype.
- For an object with an attribute of a committed datatype, the library will modify the copied object's attribute to use the found committed datatype as its datatype.

If no match is found, H5Ocopy() will perform the following in the destination file:

- For a committed datatype, the library will copy it as it would any other object, creating a named committed datatype at the destination. That is, the library will create a committed datatype that is accessible in the file by a unique path.
- For a dataset that uses a committed datatype, the library will copy the datatype as an anonymous committed datatype and use that as the dataset's datatype.
- For an object with an attribute of a committed datatype, the library will copy the datatype as an anonymous committed datatype and use that as the attribute's datatype.

Motivation: H5Padd_merge_committed_dtype_path() provides a means to override the default behavior of H5Ocopy() when H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG is set in an object copy property list. H5Padd_merge_committed_dtype_path() is the mechanism for suggesting search paths where H5Ocopy() will look for a matching committed datatype. This can be substantially faster than the default approach of searching the entire destination file for a match.

Example Usage: This example adds two paths to the object copy property list. H5Ocopy() will search the two suggested paths for a match before searching all the committed datatypes in the destination file.

        int main(void) {
        hid_t ocpypl_id = H5Pcreate(H5P_OBJECT_COPY);

           H5Pset_copy_object(ocpypl_id, H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG);
           H5Padd_merge_committed_dtype_path(ocpypl_id, "/group/committed_dtypeA");
           H5Padd_merge_committed_dtype_path(ocpypl_id, "/group2/committed_dset");
           H5Ocopy(...ocpypl_id...);
           ...
           ...
        }

Note
  H5Padd_merge_committed_dtype_path() will fail if the object copy property list is invalid. It will also fail if there is insufficient memory when duplicating `path`.

See also
  - H5Ocopy()
  - H5O_mcdt_search_cb_t
  - H5Padd_merge_committed_dtype_path()
  - H5Pfree_merge_committed_dtype_paths()
  - H5Pget_mcdt_search_cb()
  - H5Pset_copy_object()
  - H5Pset_mcdt_search_cb()
  - Copying Committed Datatypes with H5Ocopy

Since
  1.8.9

## ◆ H5Pfree_merge_committed_dtype_paths()

herr_t H5Pfree_merge_committed_dtype_paths | ( | hid_t | plist_id | ) |

Clears the list of paths stored in the object copy property list.

Parameters

  [in] | plist_id | Object copy property list identifier

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

H5Pfree_merge_committed_dtype_paths() clears the suggested paths stored in the object copy property list `plist_id`. These are the suggested paths previously set with H5Padd_merge_committed_dtype_path().

Example Usage: This example adds a suggested path to the object copy property list, does the copy, clears the list, and then adds a new suggested path to the list for another copy.

          int main(void) {
              hid_t ocpypl_id = H5Pcreate(H5P_OBJECT_COPY);

              H5Pset_copy_object(ocpypl_id, H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG);
              H5Padd_merge_committed_dtype_path(ocpypl_id, "/group/committed_dtypeA");
              H5Ocopy(...ocpypl_id...);
              ...
              ...
              H5Pfree_merge_committed_dtype_paths(ocpypl_id);
              H5Padd_merge_committed_dtype_path(ocpypl_id, "/group2/committed_dtypeB");
              H5Ocopy(...ocpypl_id...);
              ...
              ...
          }

Note
  H5Pfree_merge_committed_dtype_paths() will fail if the object copy property list is invalid.

See also
  - H5Ocopy()
  - H5O_mcdt_search_cb_t
  - H5Padd_merge_committed_dtype_path()
  - H5Pfree_merge_committed_dtype_paths()
  - H5Pget_mcdt_search_cb()
  - H5Pset_copy_object()
  - H5Pset_mcdt_search_cb()

Since
  1.8.9

## ◆ H5Pget_copy_object()

herr_t H5Pget_copy_object | ( | hid_t | plist_id,
|  | unsigned * | copy_options )

Retrieves the properties to be used when an object is copied.

Parameters

  [in] | plist_id | Object copy property list identifier
  [out] | copy_options | Copy option(s) set in the object copy property list

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

H5Pget_copy_object() retrieves the properties currently specified in the object copy property list `plist_id`, which will be invoked when a new copy is made of an existing object.

`copy_options` is a bit map indicating the flags, or properties, governing object copying that are set in the property list `plist_id`.

The available flags are described in H5Pset_copy_object().

Since
  1.8.0

## ◆ H5Pget_mcdt_search_cb()

herr_t H5Pget_mcdt_search_cb | ( | hid_t | plist_id,
|  | H5O_mcdt_search_cb_t * | func,
|  | void ** | op_data )

Retrieves the callback function from the specified object copy property list.

Parameters

  [in] | plist_id | Object copy property list identifier
  [out] | func | User-defined callback function
  [out] | op_data | User-defined data for the callback function

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

H5Pget_mcdt_search_cb() retrieves the user-defined callback function and the user data that are set via H5Pset_mcdt_search_cb() in the object copy property list `plist_id`.

The callback function will be returned in the parameter `func` and the user data will be returned in the parameter `op_data`.

Note
  H5Pget_mcdt_search_cb() will fail if the object copy property list is invalid.

See also
  - H5Ocopy()
  - H5O_mcdt_search_cb_t
  - H5Padd_merge_committed_dtype_path()
  - H5Pfree_merge_committed_dtype_paths()
  - H5Pget_mcdt_search_cb()
  - H5Pset_copy_object()
  - H5Pset_mcdt_search_cb()
  - Copying Committed Datatypes with H5Ocopy

Since
  1.8.9

## ◆ H5Pset_copy_object()

herr_t H5Pset_copy_object | ( | hid_t | plist_id,
|  | unsigned | copy_options )

Sets properties to be used when an object is copied.

Parameters

  [in] | plist_id | Object copy property list identifier
  [out] | copy_options | Copy option(s) to be set

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

H5Pset_copy_object() sets properties in the object copy property list `plist_id`. When an existing object is copied, that property list will determine how the new copy is created.

The following flags are available for use in an object copy property list:

H5O_COPY_SHALLOW_HIERARCHY_FLAG | Copy only immediate members of a group Default behavior, without flag: Recursively copy all objects in and below the group.
H5O_COPY_EXPAND_SOFT_LINK_FLAG | Expand soft links into new objects Default behavior, without flag: Copy soft links as they are.
H5O_COPY_EXPAND_EXT_LINK_FLAG | Expand external link into new objects Default behavior, without flag: Copy external links as they are.
H5O_COPY_EXPAND_REFERENCE_FLAG | Copy objects that are pointed to by references and update reference values in destination file Default behavior, without flag: Set reference values in destination file to zero (0)
H5O_COPY_WITHOUT_ATTR_FLAG | Copy object without copying attributes Default behavior, without flag: Copy object with all its attributes
H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG | Use a matching committed datatype in the destination file when copying a committed datatype, a dataset with a committed datatype, or an object with an attribute of committed datatype Default behavior without flag: A committed datatype in the source will be copied to the destination as a committed datatype. If a dataset in the source uses a committed datatype or an object in the source has an attribute of a committed datatype, that committed datatype will be written to the destination as an anonymous committed datatype. If copied in a single H5Ocopy() operation, objects that share a committed datatype in the source will share an anonymous committed datatype in the destination copy. Subsequent H5Ocopy() operations, however, will be unaware of prior anonymous committed datatypes and will create new ones. See the “See Also” section immediately below for functions related to the use of this flag.

See also
  Functions and a callback function used to tune committed datatype copying behavior:
  - H5O_mcdt_search_cb_t
  - H5Padd_merge_committed_dtype_path()
  - H5Pfree_merge_committed_dtype_paths()
  - H5Pget_mcdt_search_cb()
  - H5Pset_copy_object()
  - H5Pset_mcdt_search_cb()
  - Copying Committed Datatypes with H5Ocopy

Version
  1.8.9 H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG added in this release.

Since
  1.8.0

## ◆ H5Pset_mcdt_search_cb()

herr_t H5Pset_mcdt_search_cb | ( | hid_t | plist_id,
|  | H5O_mcdt_search_cb_t | func,
|  | void * | op_data )

Sets the callback function that H5Ocopy() will invoke before searching the entire destination file for a matching committed datatype.

Parameters

  [in] | plist_id | Object copy property list identifier
  [in] | func | User-defined callback function
  [in] | op_data | User-defined input data for the callback function

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

H5Pset_mcdt_search_cb() allows an application to set a callback function, `func`, that will be invoked before searching the destination file for a matching committed datatype. The default, global search process is described in H5Padd_merge_committed_dtype_path().

The callback function must conform to the H5O_mcdt_search_cb_t prototype and will return an instruction for one of the following actions:

- Continue the search for a matching committed datatype in the destination file.
- Discontinue the search for a matching committed datatype. H5Ocopy() will then apply the default behavior of creating an anonymous committed datatype.
- Abort the copy operation and exit H5Ocopy().

Motivation: H5Pset_mcdt_search_cb() provides the means to define a callback function. An application can then use that callback to take an additional action before the default search of all committed datatypes in the destination file or to take an action that replaces the default search. This mechanism is intended to improve performance when the global search might take a long time.

Example Usage: This example defines a callback function in the object copy property list.

    static H5O_mcdt_search_ret_t
    mcdt_search_cb(void *_udata)
    {
        H5O_mcdt_search_ret_t action = *((H5O_mcdt_search_ret_t *)_udata);

         return(action);
     }

     int main(void) {
         hid_t ocpypl_id = H5Pcreate(H5P_OBJECT_COPY);

         H5Pset_copy_object(ocpypl_id, H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG);
         H5Padd_merge_committed_dtype_path(ocpypl_id, "/group/committed_dtypeA");

         action = H5O_MCDT_SEARCH_STOP;
         H5Pset_mcdt_search_cb(ocpypl_id, mcdt_search_cb, &action);
         H5Ocopy(...ocpypl_id...);
         ...
         ...
    }

Note
  H5Pset_mcdt_search_cb() will fail if the object copy property list is invalid.

Warning
  If the callback function return value causes H5Ocopy() to abort, the destination file may be left in an inconsistent or corrupted state.

See also
  - H5Ocopy()
  - H5O_mcdt_search_cb_t
  - H5Padd_merge_committed_dtype_path()
  - H5Pfree_merge_committed_dtype_paths()
  - H5Pget_mcdt_search_cb()
  - H5Pset_copy_object()
  - H5Pset_mcdt_search_cb()
  - Copying Committed Datatypes with H5Ocopy

Since
  1.8.9