H5Dpublic.h File Reference

#include "H5public.h"
#include "H5Ipublic.h"

Macros
#define	H5D_CHUNK_CACHE_NSLOTS_DEFAULT   SIZE_MAX
#define	H5D_CHUNK_CACHE_NBYTES_DEFAULT   SIZE_MAX
#define	H5D_CHUNK_CACHE_W0_DEFAULT   (-1.0)
#define	H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS   (0x0002u)
#define	H5D_CHUNK_BTREE   H5D_CHUNK_IDX_BTREE
#define	H5D_XFER_DIRECT_CHUNK_WRITE_FLAG_NAME   "direct_chunk_flag"
#define	H5D_XFER_DIRECT_CHUNK_WRITE_FILTERS_NAME   "direct_chunk_filters"
#define	H5D_XFER_DIRECT_CHUNK_WRITE_OFFSET_NAME   "direct_chunk_offset"
#define	H5D_XFER_DIRECT_CHUNK_WRITE_DATASIZE_NAME   "direct_chunk_datasize"
#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_READ_FILTERS_NAME   "direct_chunk_read_filters"

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 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()
typedef herr_t(*	H5D_gather_func_t) (const void *dst_buf, size_t dst_buf_bytes_used, void *op_data)
	Callback for H5Dgather()
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()

Enumerations
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_chunk_index_t {   H5D_CHUNK_IDX_BTREE = 0 , H5D_CHUNK_IDX_SINGLE , H5D_CHUNK_IDX_NONE = 2 , H5D_CHUNK_IDX_FARRAY = 3 ,   H5D_CHUNK_IDX_EARRAY = 4 , H5D_CHUNK_IDX_BT2 = 5 , H5D_CHUNK_IDX_NTYPES }
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_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_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_vds_view_t { H5D_VDS_ERROR = -1 , H5D_VDS_FIRST_MISSING = 0 , H5D_VDS_LAST_AVAILABLE = 1 }

Functions
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_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)
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	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)
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.
hid_t	H5Dget_type (hid_t dset_id)
	Returns an identifier for a copy of the datatype for 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.
hid_t	H5Dget_access_plist (hid_t dset_id)
	Returns the dataset access property list associated with a dataset.
hsize_t	H5Dget_storage_size (hid_t dset_id)
	Returns the amount of storage allocated for a dataset.
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.
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.
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	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	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.
haddr_t	H5Dget_offset (hid_t dset_id)
	Returns dataset address in file.
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_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_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_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	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_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_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_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)
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	H5Dread_chunk (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	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.
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	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	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	H5Dflush (hid_t dset_id)
	Flushes all buffers associated with a dataset to disk.
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	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.
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	H5Dopen1 (hid_t loc_id, const char *name)
	Opens an existing dataset.
herr_t	H5Dextend (hid_t dset_id, const hsize_t size[])
	Extends a dataset.
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.

Macro Definition Documentation

H5D_CHUNK_BTREE

#define H5D_CHUNK_BTREE   H5D_CHUNK_IDX_BTREE

H5D_CHUNK_CACHE_NBYTES_DEFAULT

#define H5D_CHUNK_CACHE_NBYTES_DEFAULT   SIZE_MAX

H5D_CHUNK_CACHE_NSLOTS_DEFAULT

#define H5D_CHUNK_CACHE_NSLOTS_DEFAULT   SIZE_MAX

H5D_CHUNK_CACHE_W0_DEFAULT

#define H5D_CHUNK_CACHE_W0_DEFAULT   (-1.0)

H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS

#define H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS   (0x0002u)

Bit flags for the H5Pset_chunk_opts() and H5Pget_chunk_opts()

H5D_XFER_DIRECT_CHUNK_READ_FILTERS_NAME

#define H5D_XFER_DIRECT_CHUNK_READ_FILTERS_NAME   "direct_chunk_read_filters"

H5D_XFER_DIRECT_CHUNK_READ_FLAG_NAME

#define H5D_XFER_DIRECT_CHUNK_READ_FLAG_NAME   "direct_chunk_read_flag"

H5D_XFER_DIRECT_CHUNK_READ_OFFSET_NAME

#define H5D_XFER_DIRECT_CHUNK_READ_OFFSET_NAME   "direct_chunk_read_offset"

H5D_XFER_DIRECT_CHUNK_WRITE_DATASIZE_NAME

#define H5D_XFER_DIRECT_CHUNK_WRITE_DATASIZE_NAME   "direct_chunk_datasize"

H5D_XFER_DIRECT_CHUNK_WRITE_FILTERS_NAME

#define H5D_XFER_DIRECT_CHUNK_WRITE_FILTERS_NAME   "direct_chunk_filters"

H5D_XFER_DIRECT_CHUNK_WRITE_FLAG_NAME

#define H5D_XFER_DIRECT_CHUNK_WRITE_FLAG_NAME   "direct_chunk_flag"

H5D_XFER_DIRECT_CHUNK_WRITE_OFFSET_NAME

#define H5D_XFER_DIRECT_CHUNK_WRITE_OFFSET_NAME   "direct_chunk_offset"

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
H5D_ALLOC_TIME_DEFAULT	Default (layout dependent)
H5D_ALLOC_TIME_EARLY	Allocate on creation
H5D_ALLOC_TIME_LATE	Allocate on first write
H5D_ALLOC_TIME_INCR	Allocate incrementally (by chunk)

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

H5D_fill_time_t

enum H5D_fill_time_t

Values for time of writing fill value property

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

H5D_fill_value_t

enum H5D_fill_value_t

Values for fill value status

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

H5D_layout_t

enum H5D_layout_t

Values for the H5D_LAYOUT property

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

H5D_space_status_t

enum H5D_space_status_t

Values for the status of space allocation

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

H5D_vds_view_t

enum H5D_vds_view_t

Values for VDS bounds option

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