 |
HDF5
1.12.1
|
|
|
HDF5
1.12.1
|
|
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.
| Create | Read |
|---|---|
{
__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[] = "σύνολο/δεδομένων";
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
if (H5Pset_create_intermediate_group(lcpl, 1) < 0) {
ret_val = EXIT_FAILURE;
goto fail_fspace;
}
// create a 1D dataspace
ret_val = EXIT_FAILURE;
goto fail_fspace;
}
// create a 32-bit integer dataset
ret_val = EXIT_FAILURE;
goto fail_dset;
}
H5Dclose(dset);
fail_dset:
H5Sclose(fspace);
fail_fspace:
H5Pclose(lcpl);
fail_lcpl:
H5Fclose(file);
fail_file:;
}
| {
__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];
ret_val = EXIT_FAILURE;
goto fail_file;
}
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:;
}
|
| Update | Delete |
{
__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}};
ret_val = EXIT_FAILURE;
goto fail_file;
}
ret_val = EXIT_FAILURE;
goto fail_dset;
}
// get the dataset's dataspace
ret_val = EXIT_FAILURE;
goto fail_fspace;
}
// select the first 5 elements in odd positions
NULL) < 0) {
ret_val = EXIT_FAILURE;
goto fail_update;
}
// (implicitly) select and write the first 5 elements of the second column of NEW_ELTS
ret_val = EXIT_FAILURE;
fail_update:
H5Sclose(fspace);
fail_fspace:
H5Dclose(dset);
fail_dset:
H5Fclose(file);
fail_file:;
}
| {
__label__ fail_delete, fail_file;
hid_t file;
unsigned mode = H5F_ACC_RDWR;
char file_name[] = "d1.h5";
char group_name[] = "σύνολο";
char dset_name[] = "σύνολο/δεδομένων";
ret_val = EXIT_FAILURE;
goto fail_file;
}
// delete (unlink) the dataset
ret_val = EXIT_FAILURE;
goto fail_delete;
}
// the previous call deletes (unlinks) only the dataset
ret_val = EXIT_FAILURE;
goto fail_delete;
}
fail_delete:
H5Fclose(file);
fail_file:;
}
|
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. More... | |
| 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. More... | |
| hid_t | H5Dopen2 (hid_t loc_id, const char *name, hid_t dapl_id) |
| Creates a new dataset and links it into the file. More... | |
| hid_t | H5Dget_space (hid_t dset_id) |
| Returns an identifier for a copy of the dataspace for a dataset. More... | |
| herr_t | H5Dget_space_status (hid_t dset_id, H5D_space_status_t *allocation) |
| hid_t | H5Dget_type (hid_t dset_id) |
| Returns an identifier for a copy of the datatype for a dataset. More... | |
| hid_t | H5Dget_create_plist (hid_t dset_id) |
| Returns an identifier for a copy of the dataset creation property list for a dataset. More... | |
| hid_t | H5Dget_access_plist (hid_t dset_id) |
| Returns the dataset access property list associated with a dataset. More... | |
| hsize_t | H5Dget_storage_size (hid_t dset_id) |
| Returns the amount of storage allocated for a dataset. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| haddr_t | H5Dget_offset (hid_t dset_id) |
| Returns dataset address in file. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| herr_t | H5Dset_extent (hid_t dset_id, const hsize_t size[]) |
| Changes the sizes of a dataset’s dimensions. More... | |
| herr_t | H5Dflush (hid_t dset_id) |
| Flushes all buffers associated with a dataset to disk. More... | |
| herr_t | H5Drefresh (hid_t dset_id) |
| Refreshes all buffers associated with a dataset. More... | |
| 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. More... | |
| 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. More... | |
| herr_t | H5Dclose (hid_t dset_id) |
| Closes the specified dataset. More... | |
| 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. More... | |
| hid_t | H5Dopen1 (hid_t loc_id, const char *name) |
| Opens an existing dataset. More... | |
| herr_t | H5Dextend (hid_t dset_id, const hsize_t size[]) |
| Extends a dataset. More... | |
| 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. More... | |
Closes the specified dataset.
| [in] | dset_id | Dataset identifier |
H5Dclose() ends access to a dataset specified by dset_id and releases resources used by it.
Creates a dataset at the specified location.
| [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute. |
| [in] | name | Name of the dataset to create |
| [in] | type_id | Datatype identifier |
| [in] | space_id | Dataspace identifier |
| [in] | dcpl_id | Dataset creation property list identifier |
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 resources it uses.
See H5Dcreate_anon() for 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.
| 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.
| [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute. |
| [in] | name | Name of the dataset to create |
| [in] | type_id | Datatype identifier |
| [in] | space_id | Dataspace identifier |
| [in] | lcpl_id | Link creation property list identifier |
| [in] | dcpl_id | Dataset creation property list identifier |
| [in] | dapl_id | Dataset access property list identifier |
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.
dtype_id specifies the datatype of each data element as stored in the file. If dtype_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.
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 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 datatset that was not previously written, the HDF5 library will return default or user-defined fill values.
To conserve and release resources, the dataset should be closed when access is no longer required.
Creates a dataset in a file without linking it into the file structure.
| [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute. |
| [in] | type_id | Datatype identifier |
| [in] | space_id | Dataspace identifier |
| [in] | dcpl_id | Dataset creation property list identifier |
| [in] | dapl_id | Dataset access property list identifier |
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 it will exist in the file, which may differ from the datatype and dataspace in application memory.
Dataset creation property list and dataset access creation property list are specified by dcpl_id and dapl_id.
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 from the file when the file is closed.
See H5Dcreate2() for further details and considerations on the use of H5Dcreate2() and H5Dcreate_anon().
The differences between this function and H5Dcreate2() are as follows:
A dataset created with this function should be closed with H5Dclose() when the dataset is no longer needed so that resource leaks will not develop.
Extends a dataset.
| [in] | dset_id | Dataset identifier |
| [in] | size | Array containing the new size of each dimension |
H5Dextend() verifies that the dataset is at least of size size, extending it if necessary. The dimensionality of size is the same as that of the dataspace of the dataset being changed.
This function can be applied to the following datasets:
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 are to be reduced.
const hsize_t size[] in this release. | 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.
| [in] | fill | Pointer to the fill value to be used |
| [in] | fill_type_id | Fill value datatype identifier |
| [in,out] | buf | Pointer to the memory buffer containing the selection to be filled |
| [in] | buf_type_id | Datatype of dataspace elements to be filled |
| [in] | space_id | Dataspace identifier |
H5Dfill() fills the dataspace selection in memory, space_id, 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 dataspace elements will be written. buf_type_id specifies the datatype of those data elements.
Flushes all buffers associated with a dataset to disk.
| [in] | dset_id | Dataset identifier |
H5Dflush() causes all buffers associated with a dataset to be immediately flushed to disk without removing the data from the cache.
| 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.
| [in] | src_space_id | Dataspace identifier for the source buffer |
| [in] | src_buf | Source buffer which the data will be gathered from |
| [in] | type_id | Datatype identifier for the source |
| [in] | dst_buf_size | Size in bytes of dst_buf |
| [out] | dst_buf | Destination buffer for the gathered data |
| [in] | op | Callback function which handles the gathered data |
| [in] | op_data | User-defined pointer to data required by op |
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 which 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 prototype of the callback function op is as follows (as defined in the source code file H5Dpublic.h):
The parameters of this callback function are described in the table below.
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(). |
dst_buf_bytes_used | Pointer to the number of valid bytes in dst_buf. This number must be a multiple of the datatype size. |
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. |
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.
Returns the dataset access property list associated with a dataset.
| [in] | dset_id | Dataset identifier |
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.
The access property list identifier should be released with H5Pclose() when the identifier is no longer needed so that resource leaks will not develop.
| 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.
| [in] | dset_id | Dataset identifier |
| [in] | fspace_id | File dataspace selection identifier (See Note below) |
| [in] | chk_idx | Index of the chunk |
| [out] | offset | Logical position of the chunk’s first element |
| [out] | filter_mask | Indicating filters used with the chunk when written |
| [out] | addr | Chunk address in the file |
| [out] | size | Chunk size in bytes, 0 if chunk doesn’t exist |
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.
chk_idx is the chunk index in the selection. Index value may have a value of 0 up to the number of chunks stored in the file that have a nonempty intersection with the file dataspace selection
fspace_id specifies the file dataspace selection. It is intended to take H5S_ALL for specifying the current selection.
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 coming releases.| 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.
| [in] | dset_id | Dataset identifier |
| [in] | offset | Logical position of the chunk’s first element |
| [out] | filter_mask | Indicating filters used with the chunk when written |
| [out] | addr | Chunk address in the file |
| [out] | size | Chunk size in bytes, 0 if chunk doesn’t exist |
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.
Returns the amount of storage allocated within the file for a raw data chunk in a dataset.
| [in] | dset_id | Dataset identifier |
| [in] | offset | Logical offset in the dataset for the chunk to query |
| [out] | chunk_bytes | The size in bytes for the chunk |
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.
Returns an identifier for a copy of the dataset creation property list for a dataset.
| [in] | dset_id | Dataset identifier |
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.
Retrieves number of chunks that have nonempty intersection with a specified selection.
| [in] | dset_id | Dataset identifier |
| [in] | fspace_id | File dataspace selection identifier |
| [out] | nchunks | Number of chunks in the selection |
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.
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 coming releases.| haddr_t H5Dget_offset | ( | hid_t | dset_id | ) |
Returns dataset address in file.
| [in] | dset_id | Dataset identifier |
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.
Returns an identifier for a copy of the dataspace for a dataset.
| [in] | dset_id | Dataset identifier |
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.
| herr_t H5Dget_space_status | ( | hid_t | dset_id, |
| H5D_space_status_t * | allocation | ||
| ) |
| hsize_t H5Dget_storage_size | ( | hid_t | dset_id | ) |
Returns the amount of storage allocated for a dataset.
| [in] | dset_id | Dataset identifier |
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 data, not including that of any metadata.
Returns an identifier for a copy of the datatype for a dataset.
| [in] | dset_id | Dataset identifier |
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. If atomization of the datatype fails, then the datatype is closed.
A datatype identifier returned from this function should be released with H5Tclose() when the identifier is no longer needed to prevent resource leaks.
Please note that the datatype identifier is actually an object
identifier or a handle returned from opening the datatype. It
is not persistent and its value can be different from one HDF5
session to the next.
H5Tequal() can be used to compare datatypes.
HDF5 High Level APIs that may also be of interest are:
H5LTdtype_to_text() creates a text description of a
datatype. H5LTtext_to_dtype() creates an HDF5 datatype
given a text description.
| 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.
| [in,out] | buf | Buffer containing the elements to iterate over |
| [in] | type_id | Datatype identifier |
| [in] | space_id | Dataspace identifier |
| [in] | op | Function pointer |
| [in,out] | operator_data | User-defined data |
H5Diterate() iterates over all the data elements in the memory buffer buf, executing the callback function op once for each such data element.
The prototype of the callback function op is as follows (as defined in the source code file H5Lpublic.h):
The parameters of this callback function are:
elem | [in,out] | Pointer to the memory buffer containing the current data element |
type_id | [in] | Datatype identifier of the elements stored in elem |
ndim | [in] | Number of dimensions for the point array |
point | [in] | Array containing the location of the element within the original dataspace |
operator_data | [in,out] | Pointer to any user-defined data associated with the operation |
The possible return values from the callback function, and the effect ofeach,are as follows:
The operator_data parameter is a user-defined pointer to the data required to process dataset elements in the course of the iteration. If operator needs to pass data back to the application, such data can be returned in this same buffer. This pointer is passed back to each step of the iteration in the operator callback function’s operator_data parameter.
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.
Opens an existing dataset.
| [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute. |
| [in] | name | Name of the dataset to access |
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.
Creates a new dataset and links it into the file.
| [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute. |
| [in] | name | Name of the dataset to open |
| [in] | dapl_id | Dataset access property list identifier |
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.
The dataset access property list, dapl_id, provides information regarding access to the dataset.
To conserve and release resources, the dataset should be closed when access is no longer required.
| 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.
| [in] | dset_id | Dataset identifier Identifier of the dataset to read from |
| [in] | mem_type_id | Identifier of the memory datatype |
| [in] | mem_space_id | Identifier of the memory dataspace |
| [in] | file_space_id | Identifier of the dataset's dataspace in the file |
| [in] | dxpl_id | Identifier of a transfer property list |
| [out] | buf | Buffer to receive data read from file |
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.
If raw data storage space has not been allocated for the dataset and a fill value has been defined, the returned buffer buf is filled with the fill value.
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. |
Setting an H5S_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.
| 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.
| [in] | dset_id | Dataset identifier |
| [in] | dxpl_id | Dataset transfer property list identifier |
| [in] | offset | Logical position of the chunk’s first element in the dataspace |
| [in,out] | filters | Mask for identifying the filters in use |
| [out] | buf | Buffer containing data to be written to the chunk |
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 are used with the chunk when written. A zero value 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.
Refreshes all buffers associated with a dataset.
| [in] | dset_id | Dataset identifier |
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.
| 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.
| [in] | op | Callback function which provides data to be scattered |
| [in] | op_data | User-defined pointer to data required by op |
| [in] | type_id | Identifier for the datatype describing the data in both the source and destination buffers |
| [in] | dst_space_id | Identifier for the dataspace for destination |
| [out] | dst_buf | Destination buffer which the data will be scattered to |
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 which 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. The prototype of the callback function op is as follows (as defined in the source code file H5Dpublic.h):
The parameters of this callback function are described below:
src_buf | [out] | 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. |
src_buf_bytes_used | [out] | 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. |
op_data | [in,out] | User-defined pointer to data required by the callback function. A pass-through of the op_data pointer provided with the H5Dscatter() function call. |
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.
Changes the sizes of a dataset’s dimensions.
| [in] | dset_id | Dataset identifier |
| [in] | size[] | Array containing the new magnitude of each dimension of the dataset |
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:
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:
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.Determines the number of bytes required to store variable-length (VL) data.
| [in] | dset_id | Dataset identifier |
| [in] | type_id | Datatype identifier |
| [in] | space_id | Dataspace identifier |
| [out] | size | Size in bytes of the memory buffer required to store the VL data |
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.
Reclaims variable-length (VL) datatype memory buffers.
| [in] | type_id | Datatype identifier |
| [in] | space_id | Dataspace identifier |
| [in] | dxpl_id | Dataset transfer property list identifier |
| [in] | buf | Pointer to the buffer to be reclaimed |
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 which 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.
| 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.
| [in] | dset_id | Identifier of the dataset to read from |
| [in] | mem_type_id | Identifier of the memory datatype |
| [in] | mem_space_id | Identifier of the memory dataspace |
| [in] | file_space_id | Identifier of the dataset's dataspace in the file |
| [in] | dxpl_id | Dataset transfer property list identifier |
| [out] | buf | Buffer with data to be written to the file |
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.
| 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.
| [in] | dset_id | Dataset identifier |
| [in] | dxpl_id | Dataset transfer property list identifier |
| [in] | filters | Mask for identifying the filters in use |
| [in] | offset | Logical position of the chunk’s first element in the dataspace |
| [in] | data_size | Size of the actual data to be written in bytes |
| [in] | buf | Buffer containing data to be written to the chunk |
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.
H5Dwrite_chunk() replaces the now deprecated H5DOwrite_chunk() function, which was located in the high level optimization library. The parameters and behavior are identical to the original.
filters is a mask providing a record of which filters are used with the 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.
1.8.17