Please, help us to better serve our user community by answering the following short survey: https://www.hdfgroup.org/website-survey/
HDF5 1.14.5
API Reference
Loading...
Searching...
No Matches
Datasets (H5D)

Detailed Description

Use the functions in this module to manage HDF5 datasets, including the transfer of data between memory and disk and the description of dataset properties. Datasets are used by other HDF5 APIs and referenced either by name or by a handle. Such handles can be obtained by either creating or opening the dataset.

Typical stages in the HDF5 dataset life cycle are shown below in introductory examples.

CreateRead
94 {
95 __label__ fail_lcpl, fail_dset, fail_file;
96 hid_t file, lcpl, fspace, dset;
97
98 unsigned mode = H5F_ACC_TRUNC;
99 char file_name[] = "d1.h5";
100 // link names can be arbitrary Unicode strings
101 char dset_name[] = "σύνολο/δεδομένων";
102
103 if ((file = H5Fcreate(file_name, mode, H5P_DEFAULT, H5P_DEFAULT)) == H5I_INVALID_HID) {
104 ret_val = EXIT_FAILURE;
105 goto fail_file;
106 }
107 if ((lcpl = H5Pcreate(H5P_LINK_CREATE)) == H5I_INVALID_HID) {
108 ret_val = EXIT_FAILURE;
109 goto fail_lcpl;
110 }
111 // use UTF-8 encoding for link names
112 if (H5Pset_char_encoding(lcpl, H5T_CSET_UTF8) < 0) {
113 ret_val = EXIT_FAILURE;
114 goto fail_fspace;
115 }
116 // create intermediate groups as needed
117 if (H5Pset_create_intermediate_group(lcpl, 1) < 0) {
118 ret_val = EXIT_FAILURE;
119 goto fail_fspace;
120 }
121 // create a 1D dataspace
122 if ((fspace = H5Screate_simple(1, (hsize_t[]){10}, NULL)) == H5I_INVALID_HID) {
123 ret_val = EXIT_FAILURE;
124 goto fail_fspace;
125 }
126 // create a 32-bit integer dataset
127 if ((dset = H5Dcreate2(file, dset_name, H5T_STD_I32LE, fspace, lcpl, H5P_DEFAULT, H5P_DEFAULT)) ==
129 ret_val = EXIT_FAILURE;
130 goto fail_dset;
131 }
132
133 H5Dclose(dset);
134fail_dset:
135 H5Sclose(fspace);
136fail_fspace:
137 H5Pclose(lcpl);
138fail_lcpl:
139 H5Fclose(file);
140fail_file:;
141 }
#define H5F_ACC_TRUNC
Definition H5Fpublic.h:50
int64_t hid_t
Definition H5Ipublic.h:60
#define H5I_INVALID_HID
Definition H5Ipublic.h:75
#define H5P_LINK_CREATE
Definition H5Ppublic.h:124
#define H5P_DEFAULT
Definition H5Ppublic.h:228
@ H5T_CSET_UTF8
Definition H5Tpublic.h:96
uint64_t hsize_t
Definition H5public.h:301
herr_t H5Pset_char_encoding(hid_t plist_id, H5T_cset_t encoding)
Sets the character encoding used to encode link and attribute names.
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.
herr_t H5Dclose(hid_t dset_id)
Closes the specified dataset.
herr_t H5Fclose(hid_t file_id)
Terminates access to an HDF5 file.
hid_t H5Fcreate(const char *filename, unsigned flags, hid_t fcpl_id, hid_t fapl_id)
Creates an HDF5 file.
herr_t H5Sclose(hid_t space_id)
Releases and terminates access to a dataspace.
hid_t H5Screate_simple(int rank, const hsize_t dims[], const hsize_t maxdims[])
Creates a new simple dataspace and opens it for access.
herr_t H5Pset_create_intermediate_group(hid_t plist_id, unsigned crt_intmd)
Specifies in property list whether to create missing intermediate groups.
#define H5T_STD_I32LE
Definition H5Tpublic.h:323
herr_t H5Pclose(hid_t plist_id)
Terminates access to a property list.
hid_t H5Pcreate(hid_t cls_id)
Creates a new property list as an instance of a property list class.
145 {
146 __label__ fail_dset, fail_file;
147 hid_t file, dset;
148
149 unsigned mode = H5F_ACC_RDONLY;
150 char file_name[] = "d1.h5";
151 // assume a priori knowledge of dataset name and size
152 char dset_name[] = "σύνολο/δεδομένων";
153 int elts[10];
154
155 if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) {
156 ret_val = EXIT_FAILURE;
157 goto fail_file;
158 }
159 if ((dset = H5Dopen2(file, dset_name, H5P_DEFAULT)) == H5I_INVALID_HID) {
160 ret_val = EXIT_FAILURE;
161 goto fail_dset;
162 }
163 // read all dataset elements
164 if (H5Dread(dset, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, elts) < 0)
165 ret_val = EXIT_FAILURE;
166
167 // do something w/ the dataset elements
168
169 H5Dclose(dset);
170fail_dset:
171 H5Fclose(file);
172fail_file:;
173 }
#define H5F_ACC_RDONLY
Definition H5Fpublic.h:48
#define H5S_ALL
Definition H5Spublic.h:32
hid_t H5Dopen2(hid_t loc_id, const char *name, hid_t dapl_id)
Opens an existing dataset.
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.
hid_t H5Fopen(const char *filename, unsigned flags, hid_t fapl_id)
Opens an existing HDF5 file.
#define H5T_NATIVE_INT
Definition H5Tpublic.h:780
UpdateDelete
177 {
178 __label__ fail_update, fail_fspace, fail_dset, fail_file;
179 hid_t file, dset, fspace;
180
181 unsigned mode = H5F_ACC_RDWR;
182 char file_name[] = "d1.h5";
183 char dset_name[] = "σύνολο/δεδομένων";
184 int new_elts[6][2] = {{-1, 1}, {-2, 2}, {-3, 3}, {-4, 4}, {-5, 5}, {-6, 6}};
185
186 if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) {
187 ret_val = EXIT_FAILURE;
188 goto fail_file;
189 }
190 if ((dset = H5Dopen2(file, dset_name, H5P_DEFAULT)) == H5I_INVALID_HID) {
191 ret_val = EXIT_FAILURE;
192 goto fail_dset;
193 }
194 // get the dataset's dataspace
195 if ((fspace = H5Dget_space(dset)) == H5I_INVALID_HID) {
196 ret_val = EXIT_FAILURE;
197 goto fail_fspace;
198 }
199 // select the first 5 elements in odd positions
200 if (H5Sselect_hyperslab(fspace, H5S_SELECT_SET, (hsize_t[]){1}, (hsize_t[]){2}, (hsize_t[]){5},
201 NULL) < 0) {
202 ret_val = EXIT_FAILURE;
203 goto fail_update;
204 }
205
206 // (implicitly) select and write the first 5 elements of the second column of NEW_ELTS
207 if (H5Dwrite(dset, H5T_NATIVE_INT, H5S_ALL, fspace, H5P_DEFAULT, new_elts) < 0)
208 ret_val = EXIT_FAILURE;
209
210fail_update:
211 H5Sclose(fspace);
212fail_fspace:
213 H5Dclose(dset);
214fail_dset:
215 H5Fclose(file);
216fail_file:;
217 }
#define H5F_ACC_RDWR
Definition H5Fpublic.h:49
@ H5S_SELECT_SET
Definition H5Spublic.h:87
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.
hid_t H5Dget_space(hid_t dset_id)
Returns an identifier for a copy of the dataspace for a dataset.
herr_t H5Sselect_hyperslab(hid_t space_id, H5S_seloper_t op, const hsize_t start[], const hsize_t stride[], const hsize_t count[], const hsize_t block[])
Selects a hyperslab region to add to the current selected region.
221 {
222 __label__ fail_delete, fail_file;
223 hid_t file;
224
225 unsigned mode = H5F_ACC_RDWR;
226 char file_name[] = "d1.h5";
227 char group_name[] = "σύνολο";
228 char dset_name[] = "σύνολο/δεδομένων";
229
230 if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) {
231 ret_val = EXIT_FAILURE;
232 goto fail_file;
233 }
234 // delete (unlink) the dataset
235 if (H5Ldelete(file, dset_name, H5P_DEFAULT) < 0) {
236 ret_val = EXIT_FAILURE;
237 goto fail_delete;
238 }
239 // the previous call deletes (unlinks) only the dataset
240 if (H5Ldelete(file, group_name, H5P_DEFAULT) < 0) {
241 ret_val = EXIT_FAILURE;
242 goto fail_delete;
243 }
244
245fail_delete:
246 H5Fclose(file);
247fail_file:;
248 }
herr_t H5Ldelete(hid_t loc_id, const char *name, hid_t lapl_id)
Removes a link from a group.

Macros

#define H5Dcreate   H5Dcreate2
 

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_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 H5Dget_space (hid_t dset_id)
 Returns an identifier for a copy of the dataspace for a dataset.
 
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 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_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 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.
 
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

◆ H5Dcreate

#define H5Dcreate   H5Dcreate2

H5Dcreate() is a macro that is mapped to either H5Dcreate1() or H5Dcreate2().

See also
API Compatibility Macros

Function Documentation

◆ H5Dchunk_iter()

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.


Parameters
[in]dset_idDataset identifier
[in]dxpl_idIdentifier of a transfer property list
[in]cbUser callback function, called for every chunk.
[in]op_dataUser-defined pointer to data required by op
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Dchunk_iter iterates over all chunks in the dataset, calling the user supplied callback with the details of the chunk and the supplied context op_data.

Note
Prior to HDF5 1.14.4, the address passed to the callback did not take the user block into account.
Example
For each chunk, print the allocated chunk size (0 for unallocated chunks).
int
chunk_cb(const hsize_t *offset, unsigned filter_mask, haddr_t addr, hsize_t size, void *op_data)
{
// only print the allocated chunk size only
printf("%" PRIuHSIZE "\n", size);
return EXIT_SUCCESS;
}
uint64_t haddr_t
Definition H5public.h:329
#define PRIuHSIZE
Definition H5public.h:317
Iterate over all chunked datasets and chunks in a file.
H5Ovisit_cb(hid_t obj, const char *name, const H5O_info2_t *info, void *op_data)
{
herr_t retval = 0;
char *base_path = (char *)op_data;
if (info->type == H5O_TYPE_DATASET) // current object is a dataset
{
hid_t dset, dcpl;
if ((dset = H5Dopen(obj, name, H5P_DEFAULT)) == H5I_INVALID_HID) {
retval = -1;
goto func_leave;
}
if ((dcpl = H5Dget_create_plist(dset)) == H5I_INVALID_HID) {
retval = -1;
goto fail_dcpl;
}
if (H5Pget_layout(dcpl) == H5D_CHUNKED) // dataset is chunked
{
__label__ fail_dtype, fail_dspace, fail_shape;
hid_t dspace, dtype;
size_t size, i;
int rank;
// get resources
if ((dtype = H5Dget_type(dset)) < 0) {
retval = -1;
goto fail_dtype;
}
if ((dspace = H5Dget_space(dset)) < 0) {
retval = -1;
goto fail_dspace;
}
// get the shape
if ((size = H5Tget_size(dtype)) == 0 || (rank = H5Sget_simple_extent_ndims(dspace)) < 0 ||
H5Pget_chunk(dcpl, H5S_MAX_RANK, cdims) < 0) {
retval = -1;
goto fail_shape;
}
// calculate the nominal chunk size
size = 1;
for (i = 0; i < (size_t)rank; ++i)
size *= cdims[i];
// print dataset info
printf("%s%s : nominal chunk size %lu [B] \n", base_path, name, size);
// get the allocated chunk sizes
if (H5Dchunk_iter(dset, H5P_DEFAULT, &chunk_cb, NULL) < 0) {
retval = -1;
goto fail_fig;
}
fail_fig:
fail_shape:
H5Sclose(dspace);
fail_dspace:
H5Tclose(dtype);
fail_dtype:;
}
H5Pclose(dcpl);
fail_dcpl:
H5Dclose(dset);
}
func_leave:
return retval;
}
@ H5D_CHUNKED
Definition H5Dpublic.h:48
@ H5O_TYPE_DATASET
Definition H5Opublic.h:110
#define H5S_MAX_RANK
Definition H5Spublic.h:53
int herr_t
Definition H5public.h:239
#define H5Dopen
Definition H5version.h:727
int H5Pget_chunk(hid_t plist_id, int max_ndims, hsize_t dim[])
Retrieves the size of chunks for the raw data of a chunked layout dataset.
H5D_layout_t H5Pget_layout(hid_t plist_id)
Returns the layout of the raw data 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.
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.
int H5Sget_simple_extent_ndims(hid_t space_id)
Determines the dimensionality of a dataspace.
size_t H5Tget_size(hid_t type_id)
Returns the size of a datatype.
herr_t H5Tclose(hid_t type_id)
Releases a datatype.
Definition H5Opublic.h:145
H5O_type_t type
Definition H5Opublic.h:149
Since
1.14.0

◆ H5Dclose()

herr_t H5Dclose ( hid_t  dset_id)

Closes the specified dataset.


Parameters
[in]dset_idDataset identifier
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Dclose() terminates access to a dataset via the identifier dset_id and releases the underlying resources.

Example
{
__label__ fail_dset, fail_file;
hid_t file, dset;
unsigned mode = H5F_ACC_RDONLY;
char file_name[] = "d1.h5";
// assume a priori knowledge of dataset name and size
char dset_name[] = "σύνολο/δεδομένων";
int elts[10];
if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_file;
}
if ((dset = H5Dopen2(file, dset_name, H5P_DEFAULT)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_dset;
}
// read all dataset elements
ret_val = EXIT_FAILURE;
// do something w/ the dataset elements
H5Dclose(dset);
fail_dset:
H5Fclose(file);
fail_file:;
}
Since
1.0.0
See also
H5Dcreate2(), H5Dopen2()

◆ H5Dcreate1()

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.


Parameters
[in]loc_idLocation identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]nameName of the dataset to create
[in]type_idDatatype identifier
[in]space_idDataspace identifier
[in]dcpl_idDataset creation property list identifier
Returns
Returns a dataset identifier if successful; otherwise returns H5I_INVALID_HID.
Deprecated:
Superseded by H5Dcreate2() or the macro H5Dcreate().

H5Dcreate1() creates a data set with a name, name, in the location specified by the identifier loc_id. loc_id may be a file, group, dataset, named datatype or attribute. If an attribute, dataset, or named datatype is specified for loc_id then the dataset will be created at the location where the attribute, dataset, or named datatype is attached.

name can be a relative path based at loc_id or an absolute path from the root of the file. Use of this function requires that any intermediate groups specified in the path already exist.

The dataset's datatype and dataspace are specified by type_id and space_id, respectively. These are the datatype and dataspace of the dataset as it will exist in the file, which may differ from the datatype and dataspace in application memory.

Names within a group are unique: H5Dcreate1() will return an error if a link with the name specified in name already exists at the location specified in loc_id.

As is the case for any object in a group, the length of a dataset name is not limited.

dcpl_id is an H5P_DATASET_CREATE property list created with H5reate1() and initialized with various property list functions described in Property List Interface.

H5Dcreate() and H5Dcreate_anon() return an error if the dataset's datatype includes a variable-length (VL) datatype and the fill value is undefined, i.e., set to NULL in the dataset creation property list. Such a VL datatype may be directly included, indirectly included as part of a compound or array datatype, or indirectly included as part of a nested compound or array datatype.

H5Dcreate() and H5Dcreate_anon() return a dataset identifier for success or a negative value for failure. The dataset identifier should eventually be closed by calling H5Dclose() to release the resources it uses.

See H5Dcreate_anon() for a discussion of the differences between H5Dcreate() and H5Dcreate_anon().

The HDF5 library provides flexible means of specifying a fill value, of specifying when space will be allocated for a dataset, and of specifying when fill values will be written to a dataset.

Version
1.8.0 Function H5Dcreate() renamed to H5Dcreate1() and deprecated in this release.
Since
1.0.0
See also
H5Dopen2(), H5Dclose(), H5Tset_size()

◆ H5Dcreate2()

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.


Parameters
[in]loc_idLocation identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]nameName of the dataset to create
[in]type_idDatatype identifier
[in]space_idDataspace identifier
[in]lcpl_idLink creation property list identifier
[in]dcpl_idDataset creation property list identifier
[in]dapl_idDataset access property list identifier
Returns
Returns a dataset identifier if successful; otherwise returns H5I_INVALID_HID.

H5Dcreate2() creates a new dataset named name at the location specified by loc_id, and associates constant and initial persistent properties with that dataset, including the datatype dtype_id, the dataspace space_id, and other properties as specified by the dataset creation property list dcpl_id and the access property list dapl_id, respectively. Once created, the dataset is opened for access.

loc_id may specify a file, group, dataset, named datatype, or attribute. If an attribute, dataset, or named datatype is specified, then the dataset will be created at the location where the attribute, dataset, or named datatype is attached.

name may be either an absolute path in the file or a relative path from loc_id naming the dataset.

If dtype_id is a committed datatype, and if the file location associated with the committed datatype is different from the file location where the dataset will be created, the datatype is copied and converted to a transient type.

The link creation property list, lcpl_id, governs the creation of the link(s) by which the new dataset is accessed and the creation of any intermediate groups that may be missing.

The datatype and dataspace properties and the dataset creation and access property lists are attached to the dataset, so the caller may derive new datatypes, dataspaces, and creation and access properties from the old ones and reuse them in calls to create additional datasets. Once created, the dataset can be read from or written to. Reading data from a dataset that was not previously written, the HDF5 library will return default or user-defined fill values.

Example
{
__label__ fail_lcpl, fail_dset, fail_file;
hid_t file, lcpl, fspace, dset;
unsigned mode = H5F_ACC_TRUNC;
char file_name[] = "d1.h5";
// link names can be arbitrary Unicode strings
char dset_name[] = "σύνολο/δεδομένων";
if ((file = H5Fcreate(file_name, mode, H5P_DEFAULT, H5P_DEFAULT)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_file;
}
ret_val = EXIT_FAILURE;
goto fail_lcpl;
}
// use UTF-8 encoding for link names
ret_val = EXIT_FAILURE;
goto fail_fspace;
}
// create intermediate groups as needed
ret_val = EXIT_FAILURE;
goto fail_fspace;
}
// create a 1D dataspace
if ((fspace = H5Screate_simple(1, (hsize_t[]){10}, NULL)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_fspace;
}
// create a 32-bit integer dataset
if ((dset = H5Dcreate2(file, dset_name, H5T_STD_I32LE, fspace, lcpl, H5P_DEFAULT, H5P_DEFAULT)) ==
ret_val = EXIT_FAILURE;
goto fail_dset;
}
H5Dclose(dset);
fail_dset:
H5Sclose(fspace);
fail_fspace:
H5Pclose(lcpl);
fail_lcpl:
H5Fclose(file);
fail_file:;
}
Since
1.8.0
See also
H5Dopen2(), H5Dclose(), H5Tset_size()

◆ H5Dcreate_anon()

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.


Parameters
[in]loc_idLocation identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]type_idDatatype identifier
[in]space_idDataspace identifier
[in]dcpl_idDataset creation property list identifier
[in]dapl_idDataset access property list identifier
Returns
Returns a dataset identifier if successful; otherwise returns H5I_INVALID_HID.

H5Dcreate_anon() creates a dataset in the file specified by loc_id.

loc_id may specify a file, group, dataset, named datatype, or attribute. If an attribute, dataset, or named datatype is specified, then the dataset will be created at the location where the attribute, dataset, or named datatype is attached.

The dataset's datatype and dataspace are specified by type_id and space_id, respectively. These are the datatype and dataspace of the dataset as they will exist in the file, which may differ from the datatype and dataspace in application memory.

H5Dcreate_anon() returns a new dataset identifier. Using this identifier, the new dataset must be linked into the HDF5 file structure with H5Olink() or it will be deleted when the file is closed.

Since
1.8.0
See also
H5Olink(), H5Dcreate()

◆ H5Dextend()

herr_t H5Dextend ( hid_t  dset_id,
const hsize_t  size[] 
)

Extends a dataset.


Parameters
[in]dset_idDataset identifier
[in]sizeArray containing the new size of each dimension
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.
Deprecated:
Superseded by H5Dset_extent().

H5Dextend() verifies that the dataset is at least of size size, extending it if necessary. The length of size is the same as that of the dataspace of the dataset being changed.

This function can be applied to the following datasets:

  • Any dataset with unlimited dimensions
  • A dataset with fixed dimensions if the current dimension sizes are less than the maximum sizes set with maxdims (see H5Screate_simple())

Space on disk is immediately allocated for the new dataset extent if the dataset's space allocation time is set to H5D_ALLOC_TIME_EARLY. Fill values will be written to the dataset if the dataset's fill time is set to H5D_FILL_TIME_IFSET or H5D_FILL_TIME_ALLOC. (See H5Pset_fill_time() and H5Pset_alloc_time().)

This function ensures that the dataset dimensions are of at least the sizes specified in size. The function H5Dset_extent() must be used if the dataset dimension sizes are to be reduced.

Version
1.8.0 Function deprecated in this release. Parameter size syntax changed to const hsize_t size[] in this release.
Since
1.0.0

◆ H5Dfill()

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.


Parameters
[in]fillPointer to the fill value to be used
[in]fill_type_idFill value datatype identifier
[in,out]bufPointer to the memory buffer containing the selection to be filled
[in]buf_type_idDatatype of dataspace elements to be filled
[in]space_idDataspace identifier
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Dfill() fills the dataspace selection, space_id, in memory with the fill value specified in fill. If fill is NULL, a fill value of 0 (zero) is used.

fill_type_id specifies the datatype of the fill value. buf specifies the buffer in which the fill elements will be written. buf_type_id specifies the datatype of those data elements.

Note
Note that if the fill value datatype differs from the memory buffer datatype, the fill value will be converted to the memory buffer datatype before filling the selection.
Applications sometimes write data only to portions of an allocated dataset. It is often useful in such cases to fill the unused space with a known fill value.
See also
H5Pset_fill_value(), H5Pget_fill_value(), H5Pfill_value_defined(), H5Pset_fill_time(), H5Pget_fill_time(), H5Pcreate(), H5Dcreate_anon()
Since
1.6.0

◆ H5Dflush()

herr_t H5Dflush ( hid_t  dset_id)

Flushes all buffers associated with a dataset to disk.


Parameters
[in]dset_idDataset identifier
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Dflush() causes all buffers associated with a dataset to be immediately flushed to disk without removing the data from the cache.

Note
HDF5 does not possess full control over buffering. H5Dflush() flushes the internal HDF5 buffers and then asks the operating system (the OS) to flush the system buffers for the open files. After that, the OS is responsible for ensuring that the data is actually flushed to disk.
Since
1.10.0

◆ H5Dgather()

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.


Parameters
[in]src_space_idDataspace identifier for the source buffer
[in]src_bufSource buffer which the data will be gathered from
[in]type_idDatatype identifier for the source
[in]dst_buf_sizeSize in bytes of dst_buf
[out]dst_bufDestination buffer for the gathered data
[in]opCallback function which handles the gathered data
[in]op_dataUser-defined pointer to data required by op
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Dgather() retrieves data from a selection within the supplied buffer src_buf and passes it to the supplied callback function op in a contiguous form.

The dataspace src_space_id describes both the dimensions of the source buffer and the selection within the source buffer to gather data from.

src_buf must be at least the size of the gathered data, that is, the number of elements in the extent of src_space_id times the size in bytes of type_id.

The datatype type_id describes the data in both the source and destination buffers. This information is used to calculate the element size.

The data is gathered into dst_buf, which needs to be large enough to hold all the data if the callback function op is not provided.

op is a callback function that handles the gathered data. It is optional if dst_buf is large enough to hold all of the gathered data; required otherwise.

If no callback function is provided, H5Dgather() simply gathers the data into dst_buf and returns. If a callback function is provided, H5Dgather() repeatedly gathers up to dst_buf_size bytes to process the serialized data.

The callback function op 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

◆ H5Dget_access_plist()

hid_t H5Dget_access_plist ( hid_t  dset_id)

Returns the dataset access property list associated with a dataset.


Parameters
[in]dset_idDataset identifier
Returns
Returns a dataset access property list identifier if successful; otherwise returns H5I_INVALID_HID.

H5Dget_access_plist() returns a copy of the dataset access property list used to open the specified dataset, dset_id. Modifications to the returned property list will have no effect on the dataset it was retrieved from.

The chunk cache parameters in the returned property lists will be those used by the dataset. If the properties in the file access property list were used to determine the dataset's chunk cache configuration, then those properties will be present in the returned dataset access property list. If the dataset does not use a chunked layout, then the chunk cache properties will be set to the default. The chunk cache properties in the returned list are considered to be “set”, and any use of this list will override the corresponding properties in the file's file access property list.

All link access properties in the returned list will be set to the default values.

Since
1.8.3

◆ H5Dget_chunk_info()

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.


Parameters
[in]dset_idDataset identifier
[in]fspace_idFile dataspace selection identifier (See Note below)
[in]chk_idxIndex of the chunk
[out]offsetLogical position of the chunk's first element in units of dataset elements
[out]filter_maskBitmask indicating the filters used when the chunk was written
[out]addrChunk address in the file, taking the user block (if any) into account
[out]sizeChunk size in bytes, 0 if the chunk does not exist
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Dget_chunk_info() retrieves the offset coordinates, offset, filter mask, filter_mask, size, size, and address addr for the dataset specified by the identifier dset_id and the chunk specified by the index index. The chunk belongs to a set of chunks in the selection specified by fspace_id. If the queried chunk does not exist in the file, the size will be set to 0 and address to HADDR_UNDEF. The value pointed to by filter_mask will not be modified. NULL can be passed in for any out parameters.

Note
Prior to HDF5 1.14.4, the reported address did not take the user block into account.

chk_idx is the chunk index in the selection. The index value may have a value of 0 up to the number of chunks stored in the file that has a nonempty intersection with the file dataspace selection.

Note
As of 1.10.5, the dataspace intersection is not yet supported. Hence, the index is of all the written chunks.

fspace_id specifies the file dataspace selection. It is intended to take H5S_ALL to specify the current selection.

Note
Please be aware that this function currently does not support non-trivial selections; thus fspace_id has no effect. Also, the implementation does not handle the H5S_ALL macro correctly. As a workaround, an application can get the dataspace for the dataset using H5Dget_space() and pass that in for fspace_id. This will be fixed in a future release.
Since
1.10.5

◆ H5Dget_chunk_info_by_coord()

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.


Parameters
[in]dset_idDataset identifier
[in]offsetLogical position of the chunk's first element in units of dataset elements
[out]filter_maskBitmask indicating the filters used when the chunk was written
[out]addrChunk address in the file, taking the user block (if any) into account
[out]sizeChunk size in bytes, 0 if the chunk does not exist
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Dget_chunk_info_by_coord() retrieves the filter_mask, size, and addr for a chunk in the dataset specified by dset_id, using the coordinates specified by offset.

If the queried chunk does not exist in the file, size will be set to 0, addr to HADDR_UNDEF, and the buffer filter_mask will not be modified.

offset is a pointer to a one-dimensional array with a size equal to the dataset's rank. Each element is the logical position of the chunk's first element in a dimension.

Note
Prior to HDF5 1.14.4, the reported address did not take the user block into account.
Since
1.10.5

◆ H5Dget_chunk_storage_size()

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.


Parameters
[in]dset_idDataset identifier
[in]offsetLogical offset in the dataset for the chunk to query
[out]chunk_bytesThe size in bytes for the chunk
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Dget_chunk_storage_size() returns the size in bytes allocated in the file for a raw data chunk as specified by its logical offset in the dataset dset_id. The size is returned in chunk_nbytes. It is the size of the compressed data if the chunk is filtered and the size may be zero if no storage is allocated yet for the dataset.

Since
1.10.2

◆ H5Dget_create_plist()

hid_t H5Dget_create_plist ( hid_t  dset_id)

Returns an identifier for a copy of the dataset creation property list for a dataset.


Parameters
[in]dset_idDataset identifier
Returns
Returns a dataset creation property list identifier if successful; otherwise returns H5I_INVALID_HID.

H5Dget_create_plist() returns an identifier for a copy of the dataset creation property list associated with the dataset specified by dset_id.

The creation property list identifier should be released with H5Pclose() to prevent resource leaks.

Since
1.0.0

◆ H5Dget_num_chunks()

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.


Parameters
[in]dset_idDataset identifier
[in]fspace_idFile dataspace selection identifier
[out]nchunksNumber of chunks in the selection
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Dget_num_chunks() retrieves the number of chunks nchunks in a set of selected elements specified by fspace_id for a dataset specified by the identifier dset_id. If fspace_id is H5S_ALL, the function will retrieve the total number of chunks stored for the dataset.

fspace_id specifies the file dataspace selection. It is intended to take H5S_ALL for specifying the current selection.

Note
Please be aware that this function currently does not support non-trivial selections, thus fspace_id has no effect. Also, the implementation does not handle the H5S_ALL macro correctly. As a workaround, application can get the dataspace for the dataset using H5Dget_space() and pass that in for fspace_id. This will be fixed in a future release.
Since
1.10.5

◆ H5Dget_offset()

haddr_t H5Dget_offset ( hid_t  dset_id)

Returns dataset address in file.


Parameters
[in]dset_idDataset identifier
Returns
Returns the offset in bytes; otherwise, returns HADDR_UNDEF, a negative value.

H5Dget_offset() returns the address in the file of the dataset, dset_id. That address is expressed as the offset in bytes from the beginning of the file.

Since
1.6.0

◆ H5Dget_space()

hid_t H5Dget_space ( hid_t  dset_id)

Returns an identifier for a copy of the dataspace for a dataset.


Parameters
[in]dset_idDataset identifier
Returns
Returns a dataspace identifier if successful; otherwise returns H5I_INVALID_HID.

H5Dget_space() makes a copy of the dataspace of the dataset specified by dset_id. The function returns an identifier for the new copy of the dataspace.

A dataspace identifier returned from this function should be released with H5Sclose() when the identifier is no longer needed so that resource leaks will not occur.

Since
1.0.0
Example
{
__label__ fail_update, fail_fspace, fail_dset, fail_file;
hid_t file, dset, fspace;
unsigned mode = H5F_ACC_RDWR;
char file_name[] = "d1.h5";
char dset_name[] = "σύνολο/δεδομένων";
int new_elts[6][2] = {{-1, 1}, {-2, 2}, {-3, 3}, {-4, 4}, {-5, 5}, {-6, 6}};
if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_file;
}
if ((dset = H5Dopen2(file, dset_name, H5P_DEFAULT)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_dset;
}
// get the dataset's dataspace
if ((fspace = H5Dget_space(dset)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_fspace;
}
// select the first 5 elements in odd positions
if (H5Sselect_hyperslab(fspace, H5S_SELECT_SET, (hsize_t[]){1}, (hsize_t[]){2}, (hsize_t[]){5},
NULL) < 0) {
ret_val = EXIT_FAILURE;
goto fail_update;
}
// (implicitly) select and write the first 5 elements of the second column of NEW_ELTS
if (H5Dwrite(dset, H5T_NATIVE_INT, H5S_ALL, fspace, H5P_DEFAULT, new_elts) < 0)
ret_val = EXIT_FAILURE;
fail_update:
H5Sclose(fspace);
fail_fspace:
H5Dclose(dset);
fail_dset:
H5Fclose(file);
fail_file:;
}
See also
H5Sclose()

◆ H5Dget_space_status()

herr_t H5Dget_space_status ( hid_t  dset_id,
H5D_space_status_t allocation 
)

Determines whether space has been allocated for a dataset.


Parameters
[in]dset_idDataset identifier
[out]allocationSpace allocation status
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Dget_space_status() determines whether space has been allocated for the dataset dset_id.

Note
BUG: Prior to the HDF5 1.14.0, 1.12.2 and 1.10.9 releases, H5Dget_space_status() may return incorrect space allocation status values for datasets with filters applied to them. H5Dget_space_status() calculated the space allocation status by comparing the sum of the sizes of all the allocated chunks in the dataset against the total data size of the dataset, as calculated by the number of elements in the dataset's dataspace multiplied by the dataset's datatype size. If the dataset had any compression filters applied to it and the dataset chunks were successfully compressed, the sum of the sizes of the allocated dataset chunks would generally always be less than the total data size of the dataset, and H5Dget_space_status() wouldn't ever return H5D_SPACE_STATUS_ALLOCATED.
Since
1.6.0

◆ H5Dget_storage_size()

hsize_t H5Dget_storage_size ( hid_t  dset_id)

Returns the amount of storage allocated for a dataset.


Parameters
[in]dset_idDataset identifier
Returns
Returns the amount of storage space, in bytes, or 0 (zero).

H5Dget_storage_size() returns the amount of storage, in bytes, that is allocated in the file for the raw data of the dataset specified by dset_id. H5Dget_storage_size() reports only the space required to store the dataset elements, excluding any metadata.

  • For contiguous datasets, the returned size equals the current allocated size of the raw data.
  • For unfiltered chunked datasets, the returned size is the number of allocated chunks times the chunk size.
  • For filtered chunked datasets, the returned size is the space required to store the filtered data. For example, if a compression filter is in use, H5Dget_storage_size() will return the total space required to store the compressed chunks.
Note
Note that H5Dget_storage_size() is not generally an appropriate function to use when determining the amount of memory required to work with a dataset. In such circumstances, you must determine the number of data points in a dataset and the size of an individual dataset element. H5Sget_simple_extent_npoints() and H5Tget_size() can be used to calculate that amount.
Warning
H5Dget_storage_size() does not differentiate between 0 (zero), the value returned for the storage size of a dataset with no stored values, and 0 (zero), the value returned to indicate an error.
Since
1.2.0

◆ H5Dget_type()

hid_t H5Dget_type ( hid_t  dset_id)

Returns an identifier for a copy of the datatype for a dataset.


Parameters
[in]dset_idDataset identifier
Returns
Returns a datatype identifier if successful; otherwise returns H5I_INVALID_HID.

H5Dget_type() returns an identifier of a copy of the datatype for a dataset.

If a dataset has a named datatype, then an identifier to the opened datatype is returned. Otherwise, the returned datatype is read-only.

Since
1.0.0

◆ H5Diterate()

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.


Parameters
[in,out]bufBuffer containing the elements to iterate over
[in]type_idDatatype identifier
[in]space_idDataspace identifier
[in]opFunction pointer
[in,out]operator_dataUser-defined data
Returns
Success: The return value of the first operator that returns non-zero, or zero if all members were processed with no operator returning non-zero.
Failure: Negative if an error occurs in the library, or the negative value returned by one of the operators.

H5Diterate() iterates over all the data elements in the memory buffer buf, executing the callback function op once for each such data element.

Attention
Unlike other HDF5 iterators, this iteration operation cannot be restarted at the point of exit; a second H5Diterate() call will always restart at the beginning.
Warning
Modifying the selection of space_id during iteration will lead to undefined behavior.
Since
1.10.2

◆ H5Dopen1()

hid_t H5Dopen1 ( hid_t  loc_id,
const char *  name 
)

Opens an existing dataset.


Parameters
[in]loc_idLocation identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]nameName of the dataset to access
Returns
Returns a dataset identifier if successful; otherwise returns H5I_INVALID_HID.
Deprecated:
Superseded by H5Dopen2() or the macro H5Dopen().

H5Dopen1() opens an existing dataset for access at the location specified by loc_id. loc_id may be a file, group, dataset, named datatype or attribute. If an attribute, dataset, or named datatype is specified for loc_id then the dataset will be opened at the location where the attribute, dataset, or named datatype is attached. name is a dataset name and is used to identify the dataset in the file.

A dataset opened with this function should be closed with H5Dclose() when the dataset is no longer needed so that resource leaks will not develop.

Version
1.8.0 Function H5Dopen() renamed to H5Dopen1() and deprecated in this release.
Since
1.0.0

◆ H5Dopen2()

hid_t H5Dopen2 ( hid_t  loc_id,
const char *  name,
hid_t  dapl_id 
)

Opens an existing dataset.


Parameters
[in]loc_idLocation identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]nameName of the dataset to open
[in]dapl_idDataset access property list identifier
Returns
Returns a dataset identifier if successful; otherwise returns H5I_INVALID_HID.

H5Dopen2() opens the existing dataset specified by a location identifier and name, loc_id and name, respectively.

loc_id may specify a file, group, dataset, named datatype, or attribute. If an attribute, dataset, or named datatype is specified then the dataset will be opened at the location where the attribute, dataset, or named datatype is attached.

Since
1.8.0
See also
H5Dcreate2(), H5Dclose()

◆ H5Dread()

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.


Parameters
[in]dset_idDataset identifier Identifier of the dataset to read from
[in]mem_type_idIdentifier of the memory datatype
[in]mem_space_idIdentifier of the memory dataspace
[in]file_space_idIdentifier of the dataset's dataspace in the file
[in]dxpl_idIdentifier of a transfer property list
[out]bufBuffer to receive data read from file
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Dread() reads a dataset, specified by its identifier dset_id, from the file into an application memory buffer buf. Data transfer properties are defined by the argument dxpl_id. The memory datatype of the (partial) dataset is identified by the identifier mem_type_id. The part of the dataset to read is defined by mem_space_id and file_space_id.

file_space_id is used to specify only the selection within the file dataset's dataspace. Any dataspace specified in file_space_id is ignored by the library and the dataset's dataspace is always used. file_space_id can be the constant H5S_ALL, which indicates that the entire file dataspace, as defined by the current dimensions of the dataset, is to be selected.

mem_space_id is used to specify both the memory dataspace and the selection within that dataspace. mem_space_id can be the constant H5S_ALL, in which case the file dataspace is used for the memory dataspace and the selection defined with file_space_id is used for the selection within that dataspace.

The number of elements selected in the memory dataspace must be equal to the number of elements selected in the file dataspace.

The behavior of the library for the various combinations of valid dataspace identifiers and H5S_ALL for the mem_space_id and the file_space_id parameters is described below:

mem_space_id file_space_id Behavior
valid dataspace ID valid dataspace ID mem_space_id specifies the memory dataspace and the selection within it. file_space_id specifies the selection within the file dataset's dataspace.
H5S_ALL valid dataspace ID The file dataset's dataspace is used for the memory dataspace and the selection specified with file_space_id specifies the selection within it. The combination of the file dataset's dataspace and the selection from file_space_id is used for memory also.
valid dataspace ID H5S_ALL mem_space_id specifies the memory dataspace and the selection within it. The selection within the file dataset's dataspace is set to the "all" selection.
H5S_ALL H5S_ALL The file dataset's dataspace is used for the memory dataspace and the selection within the memory dataspace is set to the "all" selection. The selection within the file dataset's dataspace is set to the "all" selection.
Note
If no storage space was allocated for the dataset and a fill value is defined, the returned buffer buf is filled with the fill value.
Example
{
__label__ fail_dset, fail_file;
hid_t file, dset;
unsigned mode = H5F_ACC_RDONLY;
char file_name[] = "d1.h5";
// assume a priori knowledge of dataset name and size
char dset_name[] = "σύνολο/δεδομένων";
int elts[10];
if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_file;
}
if ((dset = H5Dopen2(file, dset_name, H5P_DEFAULT)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_dset;
}
// read all dataset elements
ret_val = EXIT_FAILURE;
// do something w/ the dataset elements
H5Dclose(dset);
fail_dset:
H5Fclose(file);
fail_file:;
}
Since
1.0.0

◆ H5Dread_chunk()

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.


Parameters
[in]dset_idDataset identifier
[in]dxpl_idDataset transfer property list identifier
[in]offsetLogical position of the chunk's first element in the dataspace
[in,out]filtersMask for identifying the filters in use
[out]bufBuffer containing data to be read from the chunk
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Dread_chunk() reads a raw data chunk as specified by its logical offset offset in a chunked dataset dset_id from the dataset in the file into the application memory buffer buf. The data in buf is read directly from the file bypassing the library's internal data transfer pipeline, including filters.

offset is an array specifying the logical position of the first element of the chunk in the dataset's dataspace. The length of the offset array must equal the number of dimensions, or rank, of the dataspace. The values in offset must not exceed the dimension limits and must specify a point that falls on a dataset chunk boundary.

The mask filters indicates which filters were used when the chunk was written. A zero value (all bits 0) indicates that all enabled filters are applied on the chunk. A filter is skipped if the bit corresponding to the filter's position in the pipeline (0 ≤ position < 32) is turned on.

buf is the memory buffer containing the chunk read from the dataset in the file.

Attention
Exercise caution when using H5Dread_chunk() and H5Dwrite_chunk(), as they read and write data chunks directly in a file. H5Dwrite_chunk() bypasses hyperslab selection, the conversion of data from one datatype to another, and the filter pipeline to write the chunk. Developers should have experience with these processes before using this function. Please see Using the Direct Chunk Write Function for more information.
Note
H5Dread_chunk() and H5Dwrite_chunk() are currently not supported with parallel HDF5 and do not support variable-length datatypes.
Since
1.10.2

◆ H5Dread_multi()

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.


Parameters
[in]countNumber of datasets to read from
[in]dset_idIdentifiers of the datasets to read from
[in]mem_type_idIdentifiers of the memory datatypes
[in]mem_space_idIdentifiers of the memory dataspaces
[in]file_space_idIdentifiers of the datasets' dataspaces in the file
[in]dxpl_idIdentifier of a transfer property list
[out]bufBuffers to receive data read from file
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Dread_multi() reads data from count datasets, whose identifiers are listed in the dset_id array, from the file into multiple application memory buffers listed in the buf array. Data transfer properties are defined by the argument dxpl_id. The memory datatypes of each dataset are listed by identifier in the mem_type_id array. The parts of each dataset to read are listed by identifier in the file_space_id array, and the parts of each application memory buffer to read to are listed by identifier in the mem_space_id array. All array parameters have length count.

This function will produce the same results as count calls to H5Dread(). Information listed in that function about the specifics of its behavior also applies to H5Dread_multi(). By calling H5Dread_multi() instead of multiple calls to H5Dread(), however, the library can in some cases pass information about the entire I/O operation to the file driver, which can improve performance.

All datasets must be in the same HDF5 file, and each unique dataset may only be listed once. If this function is called collectively in parallel, each rank must pass exactly the same list of datasets in dset_id , though the other parameters may differ.

Since
1.14.0
See also
H5Dread()

◆ H5Drefresh()

herr_t H5Drefresh ( hid_t  dset_id)

Refreshes all buffers associated with a dataset.


Parameters
[in]dset_idDataset identifier
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Drefresh() causes all buffers associated with a dataset to be cleared and immediately re-loaded with updated contents from disk.

This function essentially closes the dataset, evicts all metadata associated with it from the cache, and then re-opens the dataset. The reopened dataset is automatically re-registered with the same identifier.

Since
1.10.2

◆ H5Dscatter()

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.


Parameters
[in]opCallback function which provides data to be scattered
[in]op_dataUser-defined pointer to data required by op
[in]type_idIdentifier for the datatype describing the data in both the source and destination buffers
[in]dst_space_idIdentifier for the dataspace for destination
[out]dst_bufDestination buffer which the data will be scattered to
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Dscatter() retrieves data from the supplied callback op and scatters it to the supplied buffer dst_buf in a manner similar to data being written to a dataset.

dst_space_id is a dataspace that defines the extent of dst_buf and the selection within it to scatter the data to.

type_id is the datatype of the data to be scattered in both the source and destination buffers.

dst_buf must be at least as large as the number of elements in the extent of dst_space_id times the size in bytes of type_id.

To retrieve the data to be scattered, H5Dscatter() repeatedly calls op, which should return a valid source buffer, until enough data to fill the selection has been retrieved.

Since
1.10.2

◆ H5Dset_extent()

herr_t H5Dset_extent ( hid_t  dset_id,
const hsize_t  size[] 
)

Changes the sizes of a dataset's dimensions.


Parameters
[in]dset_idDataset identifier
[in]size[]Array containing the new magnitude of each dimension of the dataset
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Dset_extent() sets the current dimensions of the chunked dataset dset_id to the sizes specified in size.

size is a 1-dimensional array with n elements, where n is the rank of the dataset's current dataspace.

This function can be applied to the following datasets:

  • A chunked dataset with unlimited dimensions
  • A chunked dataset with fixed dimensions if the new dimension sizes are less than the maximum sizes set with maxdims (see H5Screate_simple())
  • An external dataset with unlimited dimensions
  • An external dataset with fixed dimensions if the new dimension sizes are less than the maximum sizes set with maxdims

Note that external datasets are always contiguous and can be extended only along the first dimension.

Space on disk is immediately allocated for the new dataset extent if the dataset's space allocation time is set to H5D_ALLOC_TIME_EARLY.

Fill values will be written to the dataset in either of the following situations, but not otherwise:

Note
If the sizes specified in size array are smaller than the dataset's current dimension sizes, H5Dset_extent() will reduce the dataset's dimension sizes to the specified values. It is the user application's responsibility to ensure that valuable data is not lost as H5Dset_extent() does not check.
Except for external datasets, H5Dset_extent() is for use with chunked datasets only, not contiguous datasets.
A call to H5Dset_extent() affects the dataspace of a dataset. If a dataspace handle was opened for a dataset prior to a call to H5Dset_extent() then that dataspace handle will no longer reflect the correct dataspace extent of the dataset. H5Dget_space() must be called (after closing the previous handle) to obtain the current dataspace extent.
Since
1.8.0

◆ H5Dvlen_get_buf_size()

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.


Parameters
[in]dset_idDataset identifier
[in]type_idDatatype identifier
[in]space_idDataspace identifier
[out]sizeSize in bytes of the memory buffer required to store the VL data
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Dvlen_get_buf_size() determines the number of bytes required to store the VL data from the dataset, using space_id for the selection in the dataset on disk and the type_id for the memory representation of the VL data in memory. size is returned with the number of bytes required to store the VL data in memory.

Since
1.10.2

◆ H5Dvlen_reclaim()

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.


Parameters
[in]type_idDatatype identifier
[in]space_idDataspace identifier
[in]dxpl_idDataset transfer property list identifier
[in]bufPointer to the buffer to be reclaimed
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.
Deprecated:
Superseded by H5Treclaim().

H5Dvlen_reclaim() reclaims memory buffers created to store VL datatypes.

The type_id must be the datatype stored in the buffer. The space_id describes the selection for the memory buffer to free the VL datatypes within. The dxpl_id is the dataset transfer property list that was used for the I/O transfer to create the buffer. And buf is the pointer to the buffer to be reclaimed.

The VL structures (hvl_t) in the user's buffer are modified to zero out the VL information after the memory has been reclaimed.

If nested VL datatypes were used to create the buffer, this routine frees them from the bottom up, releasing all the memory without creating memory leaks.

Version
1.12.0 Function was deprecated
Since
1.2.0

◆ H5Dwrite()

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.


Parameters
[in]dset_idIdentifier of the dataset to read from
[in]mem_type_idIdentifier of the memory datatype
[in]mem_space_idIdentifier of the memory dataspace
[in]file_space_idIdentifier of the dataset's dataspace in the file
[in]dxpl_idDataset transfer property list identifier
[out]bufBuffer with data to be written to the file
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Dwrite() writes a (partial) dataset, specified by its identifier dset_id, from the application memory buffer buf into the file. Data transfer properties are defined by the argument dxpl_id. The memory datatype of the (partial) dataset is identified by the identifier mem_type_id. The part of the dataset to write is defined by mem_space_id and file_space_id.

If mem_type_id is either a fixed-length or variable-length string, it is important to set the string length when defining the datatype. String datatypes are derived from H5T_C_S1 (or H5T_FORTRAN_S1 for Fortran codes), which defaults to 1 character in size. See H5Tset_size() and Creating variable-length string datatypes.

file_space_id is used to specify only the selection within the file dataset's dataspace. Any dataspace specified in file_space_id is ignored by the library and the dataset's dataspace is always used. file_space_id can be the constant H5S_ALL, which indicates that the entire file dataspace, as defined by the current dimensions of the dataset, is to be selected.

mem_space_id is used to specify both the memory dataspace and the selection within that dataspace. mem_space_id can be the constant H5S_ALL, in which case the file dataspace is used for the memory dataspace and the selection defined with file_space_id is used for the selection within that dataspace.

The behavior of the library for the various combinations of valid dataspace IDs and H5S_ALL for the mem_space_id and thefile_space_id parameters is described below:

mem_space_id file_space_id Behavior
valid dataspace ID valid dataspace ID mem_space_id specifies the memory dataspace and the selection within it. file_space_id specifies the selection within the file dataset's dataspace.
H5S_ALL valid dataspace ID The file dataset's dataspace is used for the memory dataspace and the selection specified with file_space_id specifies the selection within it. The combination of the file dataset's dataspace and the selection from file_space_id is used for memory also. valid dataspace ID
valid dataspace ID H5S_ALL mem_space_id specifies the memory dataspace and the selection within it. The selection within the file dataset's dataspace is set to "all" selection.
H5S_ALL H5S_ALL The file dataset's dataspace is used for the memory dataspace and the selection within the memory dataspace is set to the "all" selection. The selection within the file dataset's dataspace is set to the "all" selection.

Setting an "all" selection indicates that the entire dataspace, as defined by the current dimensions of a dataspace, will be selected. The number of elements selected in the memory dataspace must match the number of elements selected in the file dataspace.

dxpl_id can be the constant H5P_DEFAULT, in which case the default data transfer properties are used.

Writing to a dataset will fail if the HDF5 file was not opened with write access permissions.

If the dataset's space allocation time is set to H5D_ALLOC_TIME_LATE or H5D_ALLOC_TIME_INCR and the space for the dataset has not yet been allocated, that space is allocated when the first raw data is written to the dataset. Unused space in the dataset will be written with fill values at the same time if the dataset's fill time is set to H5D_FILL_TIME_IFSET or H5D_FILL_TIME_ALLOC.

Attention
If you are planning to use compression with parallel HDF5, ensure that calls to H5Dwrite() occur in collective mode. In other words, all MPI ranks (in the relevant communicator) call H5Dwrite() and pass a dataset transfer property list with the MPI-IO collective option property set to H5FD_MPIO_COLLECTIVE_IO.
Note that data transformations are currently not supported when writing to datasets in parallel and with compression enabled.
If a dataset's storage layout is 'compact', care must be taken when writing data to the dataset in parallel. A compact dataset's raw data is cached in memory and may be flushed to the file from any of the parallel processes, so parallel applications should always attempt to write identical data to the dataset from all processes.
Example
{
__label__ fail_update, fail_fspace, fail_dset, fail_file;
hid_t file, dset, fspace;
unsigned mode = H5F_ACC_RDWR;
char file_name[] = "d1.h5";
char dset_name[] = "σύνολο/δεδομένων";
int new_elts[6][2] = {{-1, 1}, {-2, 2}, {-3, 3}, {-4, 4}, {-5, 5}, {-6, 6}};
if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_file;
}
if ((dset = H5Dopen2(file, dset_name, H5P_DEFAULT)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_dset;
}
// get the dataset's dataspace
if ((fspace = H5Dget_space(dset)) == H5I_INVALID_HID) {
ret_val = EXIT_FAILURE;
goto fail_fspace;
}
// select the first 5 elements in odd positions
if (H5Sselect_hyperslab(fspace, H5S_SELECT_SET, (hsize_t[]){1}, (hsize_t[]){2}, (hsize_t[]){5},
NULL) < 0) {
ret_val = EXIT_FAILURE;
goto fail_update;
}
// (implicitly) select and write the first 5 elements of the second column of NEW_ELTS
if (H5Dwrite(dset, H5T_NATIVE_INT, H5S_ALL, fspace, H5P_DEFAULT, new_elts) < 0)
ret_val = EXIT_FAILURE;
fail_update:
H5Sclose(fspace);
fail_fspace:
H5Dclose(dset);
fail_dset:
H5Fclose(file);
fail_file:;
}
Since
1.0.0
See also
H5Pset_fill_time(), H5Pset_alloc_time()

◆ H5Dwrite_chunk()

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.


Parameters
[in]dset_idDataset identifier
[in]dxpl_idDataset transfer property list identifier
[in]filtersMask for identifying the filters in use
[in]offsetLogical position of the chunk's first element in the dataspace
[in]data_sizeSize of the actual data to be written in bytes
[in]bufBuffer containing data to be written to the chunk
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Dwrite_chunk() writes a raw data chunk as specified by its logical offset offset in a chunked dataset dset_id from the application memory buffer buf to the dataset in the file. Typically, the data in buf is preprocessed in memory by a custom transformation, such as compression. The chunk will bypass the library's internal data transfer pipeline, including filters, and will be written directly to the file. Only one chunk can be written with this function.

filters is a mask providing a record of which filters are used with the chunk. The default value of the mask is zero (0), indicating that all enabled filters are applied. A filter is skipped if the bit corresponding to the filter's position in the pipeline (0 ≤ position < 32) is turned on. This mask is saved with the chunk in the file.

offset is an array specifying the logical position of the first element of the chunk in the dataset's dataspace. The length of the offset array must equal the number of dimensions, or rank, of the dataspace. The values in offset must not exceed the dimension limits and must specify a point that falls on a dataset chunk boundary.

data_size is the size in bytes of the chunk, representing the number of bytes to be read from the buffer buf. If the data chunk has been precompressed, data_size should be the size of the compressed data.

buf is the memory buffer containing data to be written to the chunk in the file.

Attention
Exercise caution when using H5Dread_chunk() and H5Dwrite_chunk(), as they read and write data chunks directly in a file. H5Dwrite_chunk() bypasses hyperslab selection, the conversion of data from one datatype to another, and the filter pipeline to write the chunk. Developers should have experience with these processes before using this function.
Note
H5Dread_chunk() and H5Dwrite_chunk() are currently not supported with parallel HDF5 and do not support variable-length types.
Since
1.10.2

◆ H5Dwrite_multi()

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.


Parameters
[in]countNumber of datasets to write to
[in]dset_idIdentifiers of the datasets to write to
[in]mem_type_idIdentifiers of the memory datatypes
[in]mem_space_idIdentifiers of the memory dataspaces
[in]file_space_idIdentifiers of the datasets' dataspaces in the file
[in]dxpl_idIdentifier of a transfer property list
[in]bufBuffers with data to be written to the file
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Dwrite_multi() writes data to count datasets, whose identifiers are listed in the dset_id array, from multiple application memory buffers listed in the buf array. Data transfer properties are defined by the argument dxpl_id. The memory datatypes of each dataset are listed by identifier in the mem_type_id array. The parts of each dataset to write are listed by identifier in the file_space_id array, and the parts of each application memory buffer to write from are listed by identifier in the mem_space_id array. All array parameters have length count.

This function will produce the same results as count calls to H5Dwrite(). Information listed in that function's documentation about the specifics of its behaviour also apply to H5Dwrite_multi(). By calling H5Dwrite_multi() instead of multiple calls to H5Dwrite(), however, the library can in some cases pass information about the entire I/O operation to the file driver, which can improve performance.

All datasets must be in the same HDF5 file, and each unique dataset may only be listed once. If this function is called collectively in parallel, each rank must pass exactly the same list of datasets in dset_id , though the other parameters may differ.

Since
1.14.0
See also
H5Dwrite()