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

| HDF5 Last Updated on 2026-03-23 The HDF5 Field Guide

Loading...
Searching...
No Matches
H5Dpublic.h File Reference
`#include "H5public.h"`
`#include "H5Ipublic.h"`

## Macros
#define | H5D_CHUNK_BTREE H5D_CHUNK_IDX_BTREE
#define | H5D_CHUNK_CACHE_NBYTES_DEFAULT SIZE_MAX
#define | H5D_CHUNK_CACHE_NSLOTS_DEFAULT SIZE_MAX
#define | H5D_CHUNK_CACHE_W0_DEFAULT (-1.0)
#define | H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS (0x0002u)
#define | H5D_XFER_DIRECT_CHUNK_READ_FILTERS_NAME "direct_chunk_read_filters"
#define | H5D_XFER_DIRECT_CHUNK_READ_FLAG_NAME "direct_chunk_read_flag"
#define | H5D_XFER_DIRECT_CHUNK_READ_OFFSET_NAME "direct_chunk_read_offset"
#define | H5D_XFER_DIRECT_CHUNK_WRITE_DATASIZE_NAME "direct_chunk_datasize"
#define | H5D_XFER_DIRECT_CHUNK_WRITE_FILTERS_NAME "direct_chunk_filters"
#define | H5D_XFER_DIRECT_CHUNK_WRITE_FLAG_NAME "direct_chunk_flag"
#define | H5D_XFER_DIRECT_CHUNK_WRITE_OFFSET_NAME "direct_chunk_offset"

## Typedefs
typedef herr_t(* | H5D_append_cb_t) (hid_t dataset_id, hsize_t *cur_dims, void *op_data)
| Callback for H5Pset_append_flush().
typedef int(* | H5D_chunk_iter_op_t) (const hsize_t *offset, unsigned filter_mask, haddr_t addr, hsize_t size, void *op_data)
| Callback for H5Dchunk_iter().
typedef herr_t(* | H5D_gather_func_t) (const void *dst_buf, size_t dst_buf_bytes_used, void *op_data)
| Callback for H5Dgather().
typedef herr_t(* | H5D_operator_t) (void *elem, hid_t type_id, unsigned ndim, const hsize_t *point, void *operator_data)
| Callback for H5Diterate().
typedef herr_t(* | H5D_scatter_func_t) (const void **src_buf, size_t *src_buf_bytes_used, void *op_data)
| Callback for H5Dscatter().

## Enumerations
enum | H5D_alloc_time_t { H5D_ALLOC_TIME_ERROR = -1 , H5D_ALLOC_TIME_DEFAULT = 0 , H5D_ALLOC_TIME_EARLY = 1 , H5D_ALLOC_TIME_LATE = 2 , H5D_ALLOC_TIME_INCR = 3 }
enum | H5D_chunk_index_t { H5D_CHUNK_IDX_BTREE = 0 , H5D_CHUNK_IDX_SINGLE = 1 , H5D_CHUNK_IDX_NONE , H5D_CHUNK_IDX_FARRAY = 3 , H5D_CHUNK_IDX_EARRAY = 4 , H5D_CHUNK_IDX_BT2 = 5 , H5D_CHUNK_IDX_NTYPES }
enum | H5D_fill_time_t { H5D_FILL_TIME_ERROR = -1 , H5D_FILL_TIME_ALLOC = 0 , H5D_FILL_TIME_NEVER = 1 , H5D_FILL_TIME_IFSET = 2 }
enum | H5D_fill_value_t { H5D_FILL_VALUE_ERROR = -1 , H5D_FILL_VALUE_UNDEFINED = 0 , H5D_FILL_VALUE_DEFAULT = 1 , H5D_FILL_VALUE_USER_DEFINED = 2 }
enum | H5D_layout_t { H5D_LAYOUT_ERROR = -1 , H5D_COMPACT = 0 , H5D_CONTIGUOUS = 1 , H5D_CHUNKED = 2 , H5D_VIRTUAL = 3 , H5D_NLAYOUTS = 4 }
enum | H5D_space_status_t { H5D_SPACE_STATUS_ERROR = -1 , H5D_SPACE_STATUS_NOT_ALLOCATED = 0 , H5D_SPACE_STATUS_PART_ALLOCATED = 1 , H5D_SPACE_STATUS_ALLOCATED = 2 }
enum | H5D_vds_view_t { H5D_VDS_ERROR = -1 , H5D_VDS_FIRST_MISSING = 0 , H5D_VDS_LAST_AVAILABLE = 1 }

## Functions
herr_t | H5Dchunk_iter (hid_t dset_id, hid_t dxpl_id, H5D_chunk_iter_op_t cb, void *op_data)
| Iterate over all chunks of a chunked dataset.
herr_t | H5Dclose (hid_t dset_id)
| Closes the specified dataset.
herr_t | H5Dclose_async (hid_t dset_id, hid_t es_id)
hid_t | H5Dcreate1 (hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t dcpl_id)
| Creates a dataset at the specified location.
hid_t | H5Dcreate2 (hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t lcpl_id, hid_t dcpl_id, hid_t dapl_id)
| Creates a new dataset and links it into the file.
hid_t | H5Dcreate_anon (hid_t loc_id, hid_t type_id, hid_t space_id, hid_t dcpl_id, hid_t dapl_id)
| Creates a dataset in a file without linking it into the file structure.
hid_t | H5Dcreate_async (hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t lcpl_id, hid_t dcpl_id, hid_t dapl_id, hid_t es_id)
herr_t | H5Dextend (hid_t dset_id, const hsize_t size[])
| Extends a dataset.
herr_t | H5Dfill (const void *fill, hid_t fill_type_id, void *buf, hid_t buf_type_id, hid_t space_id)
| Fills dataspace elements with a fill value in a memory buffer.
herr_t | H5Dflush (hid_t dset_id)
| Flushes all buffers associated with a dataset to disk.
herr_t | H5Dgather (hid_t src_space_id, const void *src_buf, hid_t type_id, size_t dst_buf_size, void *dst_buf, H5D_gather_func_t op, void *op_data)
| Gathers data from a selection within a memory buffer raw data chunk in a dataset.
hid_t | H5Dget_access_plist (hid_t dset_id)
| Returns the dataset access property list associated with a dataset.
herr_t | H5Dget_chunk_info (hid_t dset_id, hid_t fspace_id, hsize_t chk_idx, hsize_t *offset, unsigned *filter_mask, haddr_t *addr, hsize_t *size)
| Retrieves information about a chunk specified by its index.
herr_t | H5Dget_chunk_info_by_coord (hid_t dset_id, const hsize_t *offset, unsigned *filter_mask, haddr_t *addr, hsize_t *size)
| Retrieves information about a chunk specified by its coordinates.
herr_t | H5Dget_chunk_storage_size (hid_t dset_id, const hsize_t *offset, hsize_t *chunk_bytes)
| Returns the amount of storage allocated within the file for a raw data chunk in a dataset.
hid_t | H5Dget_create_plist (hid_t dset_id)
| Returns an identifier for a copy of the dataset creation property list for a dataset.
herr_t | H5Dget_num_chunks (hid_t dset_id, hid_t fspace_id, hsize_t *nchunks)
| Retrieves number of chunks that have nonempty intersection with a specified selection.
haddr_t | H5Dget_offset (hid_t dset_id)
| Returns dataset address in file.
hid_t | H5Dget_space (hid_t dset_id)
| Returns an identifier for a copy of the dataspace for a dataset.
hid_t | H5Dget_space_async (hid_t dset_id, hid_t es_id)
herr_t | H5Dget_space_status (hid_t dset_id, H5D_space_status_t *allocation)
| Determines whether space has been allocated for a dataset.
hsize_t | H5Dget_storage_size (hid_t dset_id)
| Returns the amount of storage allocated for a dataset.
hid_t | H5Dget_type (hid_t dset_id)
| Returns an identifier for a copy of the datatype for a dataset.
herr_t | H5Diterate (void *buf, hid_t type_id, hid_t space_id, H5D_operator_t op, void *operator_data)
| Iterates over all selected elements in a dataspace.
hid_t | H5Dopen1 (hid_t loc_id, const char *name)
| Opens an existing dataset.
hid_t | H5Dopen2 (hid_t loc_id, const char *name, hid_t dapl_id)
| Opens an existing dataset.
hid_t | H5Dopen_async (hid_t loc_id, const char *name, hid_t dapl_id, hid_t es_id)
herr_t | H5Dread (hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t dxpl_id, void *buf)
| Reads raw data from a dataset into a provided buffer.
herr_t | H5Dread_async (hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t dxpl_id, void *buf, hid_t es_id)
herr_t | H5Dread_chunk1 (hid_t dset_id, hid_t dxpl_id, const hsize_t *offset, uint32_t *filters, void *buf)
| Reads a raw data chunk directly from a dataset in a file into a buffer.
herr_t | H5Dread_chunk2 (hid_t dset_id, hid_t dxpl_id, const hsize_t *offset, uint32_t *filters, void *buf, size_t *buf_size)
| Reads a raw data chunk directly from a dataset in a file into a buffer.
herr_t | H5Dread_multi (size_t count, hid_t dset_id[], hid_t mem_type_id[], hid_t mem_space_id[], hid_t file_space_id[], hid_t dxpl_id, void *buf[])
| Reads raw data from a set of datasets into the provided buffers.
herr_t | H5Dread_multi_async (size_t count, hid_t dset_id[], hid_t mem_type_id[], hid_t mem_space_id[], hid_t file_space_id[], hid_t dxpl_id, void *buf[], hid_t es_id)
herr_t | H5Drefresh (hid_t dset_id)
| Refreshes all buffers associated with a dataset.
herr_t | H5Dscatter (H5D_scatter_func_t op, void *op_data, hid_t type_id, hid_t dst_space_id, void *dst_buf)
| Scatters data into a selection within a memory buffer.
herr_t | H5Dset_extent (hid_t dset_id, const hsize_t size[])
| Changes the sizes of a dataset's dimensions.
herr_t | H5Dset_extent_async (hid_t dset_id, const hsize_t size[], hid_t es_id)
herr_t | H5Dvlen_get_buf_size (hid_t dset_id, hid_t type_id, hid_t space_id, hsize_t *size)
| Determines the number of bytes required to store variable-length (VL) data.
herr_t | H5Dvlen_reclaim (hid_t type_id, hid_t space_id, hid_t dxpl_id, void *buf)
| Reclaims variable-length (VL) datatype memory buffers.
herr_t | H5Dwrite (hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t dxpl_id, const void *buf)
| Writes raw data from a buffer to a dataset.
herr_t | H5Dwrite_async (hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t dxpl_id, const void *buf, hid_t es_id)
herr_t | H5Dwrite_chunk (hid_t dset_id, hid_t dxpl_id, uint32_t filters, const hsize_t *offset, size_t data_size, const void *buf)
| Writes a raw data chunk from a buffer directly to a dataset in a file.
herr_t | H5Dwrite_multi (size_t count, hid_t dset_id[], hid_t mem_type_id[], hid_t mem_space_id[], hid_t file_space_id[], hid_t dxpl_id, const void *buf[])
| Writes raw data from a set buffers to a set of datasets.
herr_t | H5Dwrite_multi_async (size_t count, hid_t dset_id[], hid_t mem_type_id[], hid_t mem_space_id[], hid_t file_space_id[], hid_t dxpl_id, const void *buf[], hid_t es_id)

## Macro Definition Documentation

## ◆ H5D_CHUNK_BTREE

#define H5D_CHUNK_BTREE H5D_CHUNK_IDX_BTREE

v1 B-tree index

Since
  1.10.0

## ◆ H5D_CHUNK_CACHE_NBYTES_DEFAULT

#define H5D_CHUNK_CACHE_NBYTES_DEFAULT SIZE_MAX

Total size of the raw data chunk cache for this dataset. See H5Pset_chunk_cache for details.

Since
  1.8.3

## ◆ H5D_CHUNK_CACHE_NSLOTS_DEFAULT

#define H5D_CHUNK_CACHE_NSLOTS_DEFAULT SIZE_MAX

Default of chunk slots in the raw data chunk cache for this dataset. See H5Pset_chunk_cache for details.

Since
  1.8.3

## ◆ H5D_CHUNK_CACHE_W0_DEFAULT

#define H5D_CHUNK_CACHE_W0_DEFAULT (-1.0)

Chunk preemption policy for this dataset. See H5Pset_chunk_cache for details.

Since
  1.8.3

## ◆ H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS

#define H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS (0x0002u)

Bit flags for the H5Pset/get_chunk_opts()

Since
  1.10.0

## ◆ H5D_XFER_DIRECT_CHUNK_READ_FILTERS_NAME

#define H5D_XFER_DIRECT_CHUNK_READ_FILTERS_NAME "direct_chunk_read_filters"

Direct chunk read filters flag

Deprecated
  As H5DOread_chunk was deprecated

## ◆ H5D_XFER_DIRECT_CHUNK_READ_FLAG_NAME

#define H5D_XFER_DIRECT_CHUNK_READ_FLAG_NAME "direct_chunk_read_flag"

Direct chunk read flag

Deprecated
  As H5DOread_chunk was deprecated

## ◆ H5D_XFER_DIRECT_CHUNK_READ_OFFSET_NAME

#define H5D_XFER_DIRECT_CHUNK_READ_OFFSET_NAME "direct_chunk_read_offset"

Direct chunk read offset flag

Deprecated
  As H5DOread_chunk was deprecated

## ◆ H5D_XFER_DIRECT_CHUNK_WRITE_DATASIZE_NAME

#define H5D_XFER_DIRECT_CHUNK_WRITE_DATASIZE_NAME "direct_chunk_datasize"

Direct chunk write datasize flag

Deprecated
  As H5DOwrite_chunk was deprecated

## ◆ H5D_XFER_DIRECT_CHUNK_WRITE_FILTERS_NAME

#define H5D_XFER_DIRECT_CHUNK_WRITE_FILTERS_NAME "direct_chunk_filters"

Direct chunk write filters flag

Deprecated
  As H5DOwrite_chunk was deprecated

## ◆ H5D_XFER_DIRECT_CHUNK_WRITE_FLAG_NAME

#define H5D_XFER_DIRECT_CHUNK_WRITE_FLAG_NAME "direct_chunk_flag"

Direct chunk write flag

Deprecated
  As H5DOwrite_chunk was deprecated

## ◆ H5D_XFER_DIRECT_CHUNK_WRITE_OFFSET_NAME

#define H5D_XFER_DIRECT_CHUNK_WRITE_OFFSET_NAME "direct_chunk_offset"

Direct chunk write offset flag

Deprecated
  As H5DOwrite_chunk was deprecated

## Typedef Documentation

## ◆ H5D_append_cb_t

typedef herr_t(* H5D_append_cb_t) (hid_t dataset_id, hsize_t *cur_dims, void *op_data)

Callback for H5Pset_append_flush().

Parameters

  [in] | dataset_id | Dataset identifier
  [in] | cur_dims | The current extent of the dataset's dimensions
  [in,out] | op_data | User context

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

Since
  1.10.0

## ◆ H5D_chunk_iter_op_t

typedef int(* H5D_chunk_iter_op_t) (const hsize_t *offset, unsigned filter_mask, haddr_t addr, hsize_t size, void *op_data)

Callback for H5Dchunk_iter().

Parameters

  [in] | offset | Logical position of the chunk's first element in units of dataset elements
  [in] | filter_mask | Bitmask indicating the filters used when the chunk was written
  [in] | addr | Chunk address in the file, taking the user block (if any) into account
  [in] | size | Chunk size in bytes, 0 if the chunk does not exist
  [in,out] | op_data | Pointer to any user-defined data associated with the operation.

Returns
  - Zero (H5_ITER_CONT) causes the iterator to continue, returning zero when all elements have been processed.
  - A positive value (H5_ITER_STOP) causes the iterator to immediately return that value, indicating short-circuit success.
  - A negative (H5_ITER_ERROR) causes the iterator to immediately return that value, indicating failure.

Attention
  Leaving callback functions:
  The callback function must return normally, even in the case of error. Returning with H5_ITER_ERROR, instead of leaving by means of exceptions, exit() function, etc... will allow the HDF5 library to manage its resources and maintain a consistent state. See C++ Developers using HDF5 C-API functions warning for detail.

Since
  1.14.0

## ◆ H5D_gather_func_t

typedef herr_t(* H5D_gather_func_t) (const void *dst_buf, size_t dst_buf_bytes_used, void *op_data)

Callback for H5Dgather().

Parameters

  [in] | dst_buf | Pointer to the destination buffer which has been filled with the next set of elements gathered. This will always be identical to the `dst_buf` passed to H5Dgather()
  [in] | dst_buf_bytes_used | Pointer to the number of valid bytes in `dst_buf`. This number must be a multiple of the datatype size.
  [in,out] | op_data | User-defined pointer to data required by the callback function; a pass-through of the `op_data` pointer provided with the H5Dgather() function call.

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

The callback function should process, store, or otherwise make use of the data returned in dst_buf before it returns, because the buffer will be overwritten unless it is the last call to the callback. This function will be repeatedly called until all gathered elements have been passed to the callback in dst_buf. The callback function should return zero (0) to indicate success, and a negative value to indicate failure.

Since
  1.10.2

## ◆ H5D_operator_t

typedef herr_t(* H5D_operator_t) (void *elem, hid_t type_id, unsigned ndim, const hsize_t *point, void *operator_data)

Callback for H5Diterate().

Parameters

  [in,out] | elem | Pointer to the memory buffer containing the current dataset element
  [in] | type_id | Datatype identifier of the elements stored in `elem`
  [in] | ndim | Number of dimensions for the `point` array
  [in] | point | Array containing the location of the element within the original dataspace
  [in,out] | operator_data | Pointer to any user-defined data associated with the operation

Returns
  - Zero causes the iterator to continue, returning zero when the iteration is complete.
  - A positive value causes the iterator to immediately return that positive value, indicating short-circuit success.
  - A negative value causes the iterator to immediately return that value, indicating failure.

Since
  1.10.2

## ◆ H5D_scatter_func_t

typedef herr_t(* H5D_scatter_func_t) (const void **src_buf, size_t *src_buf_bytes_used, void *op_data)

Callback for H5Dscatter().

Parameters

  [out] | src_buf | Pointer to the buffer holding the next set of elements to scatter. On entry, the value of where `src_buf` points to is undefined. The callback function should set `src_buf` to point to the next set of elements.
  [out] | src_buf_bytes_used | Pointer to the number of valid bytes in `src_buf`. On entry, the value where `src_buf_bytes_used` points to is undefined. The callback function should set `src_buf_bytes_used` to the of valid bytes in `src_buf`. This number must be a multiple of the datatype size.
  [in,out] | op_data | User-defined pointer to data required by the callback function. A pass-through of the `op_data` pointer provided with the H5Dscatter() function call.

Returns
  herr_t

The callback function should always return at least one element in `src_buf`, and must not return more elements than are remaining to be scattered. This function will be repeatedly called until all elements to be scattered have been returned. The callback function should return zero (0) to indicate success, and a negative value to indicate failure.

Since
  1.10.2

## Enumeration Type Documentation

## ◆ H5D_alloc_time_t

enum H5D_alloc_time_t

Values for the space allocation time property

Enumerator
H5D_ALLOC_TIME_ERROR | Error Since 1.6.0
H5D_ALLOC_TIME_DEFAULT | Default (layout dependent) Since 1.6.0
H5D_ALLOC_TIME_EARLY | Allocate on creation Since 1.6.0
H5D_ALLOC_TIME_LATE | Allocate on first write Since 1.6.0
H5D_ALLOC_TIME_INCR | Allocate incrementally (by chunk) Since 1.6.0

## ◆ H5D_chunk_index_t

enum H5D_chunk_index_t

Types of chunk index data structures

Enumerator
H5D_CHUNK_IDX_BTREE | v1 B-tree index (default) Since 1.10.0
H5D_CHUNK_IDX_SINGLE | Single Chunk index (cur dims[]=max dims[]=chunk dims[]; filtered & non-filtered) Since 1.10.0
H5D_CHUNK_IDX_NONE | Implicit: No Index (H5D_ALLOC_TIME_EARLY, non-filtered, fixed dims) Since 1.10.0
H5D_CHUNK_IDX_FARRAY | Fixed array (for 0 unlimited dims) Since 1.10.0
H5D_CHUNK_IDX_EARRAY | Extensible array (for 1 unlimited dim) Since 1.10.0
H5D_CHUNK_IDX_BT2 | v2 B-tree index (for >1 unlimited dims) Since 1.10.0
H5D_CHUNK_IDX_NTYPES | This one must be last! Since 1.10.0

## ◆ H5D_fill_time_t

enum H5D_fill_time_t

Values for time of writing fill value property

Enumerator
H5D_FILL_TIME_ERROR | Error Since 1.6.0
H5D_FILL_TIME_ALLOC | Fill on allocation Since 1.6.0
H5D_FILL_TIME_NEVER | Never write fill values Since 1.6.0
H5D_FILL_TIME_IFSET | Fill if fill-value was set Since 1.6.0

## ◆ H5D_fill_value_t

enum H5D_fill_value_t

Values for fill value status

Enumerator
H5D_FILL_VALUE_ERROR | Error Since 1.6.0
H5D_FILL_VALUE_UNDEFINED | No fill value defined Since 1.6.0
H5D_FILL_VALUE_DEFAULT | Default fill-value Since 1.6.0
H5D_FILL_VALUE_USER_DEFINED | User-defined fill-value Since 1.6.0

## ◆ H5D_layout_t

enum H5D_layout_t

Values for the H5D_LAYOUT property

Enumerator
H5D_LAYOUT_ERROR | error Since 1.0.0
H5D_COMPACT | raw data is small (< 64KB) Since 1.0.0
H5D_CONTIGUOUS | contiguous layout Since 1.0.0
H5D_CHUNKED | chunked or tiled layout Since 1.0.0
H5D_VIRTUAL | actual data is stored in other datasets Since 1.10.0
H5D_NLAYOUTS | this one must be last! Since 1.0.0

## ◆ H5D_space_status_t

enum H5D_space_status_t

Values for the status of space allocation

Enumerator
H5D_SPACE_STATUS_ERROR | Error Since 1.6.0
H5D_SPACE_STATUS_NOT_ALLOCATED | Space has not been allocated for this dataset. Since 1.6.0
H5D_SPACE_STATUS_PART_ALLOCATED | Space has been partially allocated for this dataset. (Used only for datasets with chunked storage.) Since 1.6.0
H5D_SPACE_STATUS_ALLOCATED | Space has been allocated for this dataset. Since 1.6.0

## ◆ H5D_vds_view_t

enum H5D_vds_view_t

Values for VDS bounds option

Enumerator
H5D_VDS_ERROR | Error Since 1.10.0
H5D_VDS_FIRST_MISSING | Include all data before the first missing mapped data Since 1.10.0
H5D_VDS_LAST_AVAILABLE | Include all available mapped data Since 1.10.0