* | \c mem_space_id |
* \c file_space_id |
* Behavior |
|---|
* | valid dataspace ID |
* valid dataspace ID |
* \p mem_space_id specifies the memory dataspace and the
* selection within it. \p 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 \p file_space_id
* specifies the selection within it. The combination of the
* file dataset's dataspace and the selection from \p
* file_space_id is used for memory also. valid dataspace
* ID |
* | valid dataspace ID |
* #H5S_ALL |
* \p 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.
*
* \p 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.
*
* \par_compr_note
*
* \attention 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.
*
* \par Example
* \snippet H5D_examples.c update
*
* \see H5Pset_fill_time(), H5Pset_alloc_time()
*
*/
H5_DLL 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);
/**
* --------------------------------------------------------------------------
* \ingroup ASYNC
* \async_variant_of{H5Dwrite}
*/
H5_DLL herr_t H5Dwrite_async(const char *app_file, const char *app_func, unsigned app_line, hid_t dset_id,
hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t dxpl_id,
const void *buf, hid_t es_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Writes a raw data chunk from a buffer directly to a dataset in a file
*
* \dset_id
* \dxpl_id
* \param[in] filters Mask for identifying the filters in use
* \param[in] offset Logical position of the chunk’s first element in the
* dataspace
* \param[in] data_size Size of the actual data to be written in bytes
* \param[in] buf Buffer containing data to be written to the chunk
*
* \return \herr_t
*
* \details H5Dwrite_chunk() writes a raw data chunk as specified
* by its logical offset \p offset in a chunked dataset \p dset_id
* from the application memory buffer \p buf to the dataset in
* the file. Typically, the data in \p 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.
*
* \p 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.
*
* \p 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.
*
* \p data_size is the size in bytes of the chunk, representing
* the number of bytes to be read from the buffer \p buf. If the
* data chunk has been precompressed, \p data_size should be the
* size of the compressed data.
*
* \p 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
*
*/
H5_DLL 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);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Reads a raw data chunk directly from a dataset in a file into
* a buffer
*
* \dset_id
* \dxpl_id
* \param[in] offset Logical position of the chunk’s first element in the
* dataspace
* \param[in,out] filters Mask for identifying the filters in use
* \param[out] buf Buffer containing data to be written to the chunk
*
* \return \herr_t
*
* \details H5Dread_chunk() reads a raw data chunk as specified by
* its logical offset \p offset in a chunked dataset \p dset_id
* from the dataset in the file into the application memory
* buffer \p buf. The data in \p buf is read directly from the
* file bypassing the library’s internal data transfer pipeline,
* including filters.
*
* \p offset is an array specifying the logical position of the
* first element of the chunk in the dataset’s dataspace. The
* length of the \p offset array must equal the number of dimensions,
* or rank, of the dataspace. The values in \p offset must not exceed
* the dimension limits and must specify a point that falls on
* a dataset chunk boundary.
*
* The mask \p 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.
*
* \p 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
*
*/
H5_DLL herr_t H5Dread_chunk(hid_t dset_id, hid_t dxpl_id, const hsize_t *offset, uint32_t *filters,
void *buf);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Iterates over all selected elements in a dataspace
*
* \param[in,out] buf Buffer containing the elements to iterate over
* \type_id
* \space_id
* \param[in] op Function pointer
* \param[in,out] operator_data User-defined data
*
* \return \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.}
* \return \failure{Negative if an error occurs in the library, or the negative
* value returned by one of the operators.}
*
* \details H5Diterate() iterates over all the data elements
* in the memory buffer \p buf, executing the callback function
* \p 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.
*
*
* \since 1.10.2
*
*/
H5_DLL herr_t H5Diterate(void *buf, hid_t type_id, hid_t space_id, H5D_operator_t op, void *operator_data);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Determines the number of bytes required to store variable-length
* (VL) data
*
* \dset_id
* \type_id
* \space_id
* \param[out] size Size in bytes of the memory buffer required to store
* the VL data
*
* \return \herr_t
*
* \details H5Dvlen_get_buf_size() determines the number of bytes
* required to store the VL data from the dataset, using \p
* space_id for the selection in the dataset on disk and the \p
* type_id for the memory representation of the VL data in memory.
* \p size is returned with the number of bytes required to store
* the VL data in memory.
*
* \since 1.10.2
*
*/
H5_DLL herr_t H5Dvlen_get_buf_size(hid_t dset_id, hid_t type_id, hid_t space_id, hsize_t *size);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Fills dataspace elements with a fill value in a memory buffer
*
* \param[in] fill Pointer to the fill value to be used
* \param[in] fill_type_id Fill value datatype identifier
* \param[in,out] buf Pointer to the memory buffer containing the
* selection to be filled
* \param[in] buf_type_id Datatype of dataspace elements to be filled
* \space_id
*
* \return \herr_t
*
* \details H5Dfill() fills the dataspace selection, \p space_id, in memory
* with the fill value specified in \p fill. If \p fill is NULL,
* a fill value of 0 (zero) is used.
*
* \p fill_type_id specifies the datatype of the fill value.
* \p buf specifies the buffer in which the fill elements
* will be written. \p 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.
*
* \note 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 H5Pset_fill_value(), H5Pget_fill_value(), H5Pfill_value_defined(),
* H5Pset_fill_time(), H5Pget_fill_time(), H5Pcreate(), H5Dcreate_anon()
*
*/
H5_DLL herr_t H5Dfill(const void *fill, hid_t fill_type_id, void *buf, hid_t buf_type_id, hid_t space_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Changes the sizes of a dataset’s dimensions
*
* \dset_id
* \param[in] size[] Array containing the new magnitude of each dimension
* of the dataset
*
* \return \herr_t
*
* \details H5Dset_extent() sets the current dimensions of the
* chunked dataset \p dset_id to the sizes specified in size.
*
* \p size is a 1-dimensional array with n elements, where \p 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 \p 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:
*
* - If the dataset’s fill time is set to #H5D_FILL_TIME_IFSET and a
* fill value is defined (see H5Pset_fill_time() and
* H5Pset_fill_value())
* - If the dataset’s fill time is set to #H5D_FILL_TIME_ALLOC
* (see H5Pset_alloc_time())
*
* \note If the sizes specified in \p 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.
*
* \note Except for external datasets, H5Dset_extent() is for use with
* chunked datasets only, not contiguous datasets.
*
* \note 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
*
*/
H5_DLL herr_t H5Dset_extent(hid_t dset_id, const hsize_t size[]);
/**
* --------------------------------------------------------------------------
* \ingroup ASYNC
* \async_variant_of{H5Dset_extent}
*/
H5_DLL herr_t H5Dset_extent_async(const char *app_file, const char *app_func, unsigned app_line,
hid_t dset_id, const hsize_t size[], hid_t es_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Flushes all buffers associated with a dataset to disk
*
* \dset_id
*
* \return \herr_t
*
* \details 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
*
*/
H5_DLL herr_t H5Dflush(hid_t dset_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Refreshes all buffers associated with a dataset
*
* \dset_id
*
* \return \herr_t
*
* \details 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
*
*/
H5_DLL herr_t H5Drefresh(hid_t dset_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Scatters data into a selection within a memory buffer
*
* \param[in] op Callback function which provides data to be scattered
* \param[in] op_data User-defined pointer to data required by op
* \param[in] type_id Identifier for the datatype describing the data in
* both the source and destination buffers
* \param[in] dst_space_id Identifier for the dataspace for destination
* \param[out] dst_buf Destination buffer which the data will be scattered to
*
* \return \herr_t
*
* \details H5Dscatter() retrieves data from the supplied callback
* \p op and scatters it to the supplied buffer \p dst_buf in a
* manner similar to data being written to a dataset.
*
* \p dst_space_id is a dataspace which defines the extent of \p
* dst_buf and the selection within it to scatter the data to.
*
* \p type_id is the datatype of the data to be scattered in both
* the source and destination buffers.
*
* \p dst_buf must be at least as large as the number of elements
* in the extent of \p dst_space_id times the size in bytes of
* \p type_id.
*
* To retrieve the data to be scattered, H5Dscatter() repeatedly
* calls \p op, which should return a valid source buffer, until
* enough data to fill the selection has been retrieved.
*
* \since 1.10.2
*
*/
H5_DLL herr_t H5Dscatter(H5D_scatter_func_t op, void *op_data, hid_t type_id, hid_t dst_space_id,
void *dst_buf);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Gathers data from a selection within a memory buffer
* raw data chunk in a dataset
*
* \param[in] src_space_id Dataspace identifier for the source buffer
* \param[in] src_buf Source buffer which the data will be gathered from
* \param[in] type_id Datatype identifier for the source
* \param[in] dst_buf_size Size in bytes of \p dst_buf
* \param[out] dst_buf Destination buffer for the gathered data
* \param[in] op Callback function which handles the gathered data
* \param[in] op_data User-defined pointer to data required by \p op
*
* \return \herr_t
*
* \details H5Dgather() retrieves data from a selection within the supplied
* buffer src_buf and passes it to the supplied callback function
* \p op in a contiguous form.
*
* The dataspace \p src_space_id describes both the dimensions of
* the source buffer and the selection within the source buffer
* to gather data from.
*
* \p src_buf must be at least the size of the gathered data, that
* is, the number of elements in the extent of \p src_space_id
* times the size in bytes of \p type_id.
*
* The datatype \p 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 \p dst_buf, which needs to be large
* enough to hold all the data if the callback function \p op is
* not provided.
*
* \p op is a callback function which handles the gathered data.
* It is optional if \p 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 \p dst_buf and returns. If a callback function is
* provided, H5Dgather() repeatedly gathers up to \p dst_buf_size
* bytes to process the serialized data.
*
* The callback function \p op should process, store, or otherwise,
* make use of the data returned in \p 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 \p dst_buf. The callback function should return zero (0)
* to indicate success, and a negative value to indicate failure.
*
* \since 1.10.2
*
*/
H5_DLL 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);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Closes the specified dataset
*
* \dset_id
*
* \return \herr_t
*
* \details H5Dclose() terminates access to a dataset via the identifier
* \p dset_id and releases the underlying resources.
*
* \par Example
* \snippet H5D_examples.c read
*
* \since 1.8.0
*
* \see H5Dcreate2(), H5Dopen2()
*
*/
H5_DLL herr_t H5Dclose(hid_t dset_id);
/**
* --------------------------------------------------------------------------
* \ingroup ASYNC
* \async_variant_of{H5Dclose}
*/
H5_DLL herr_t H5Dclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t dset_id,
hid_t es_id);
/// \cond DEV
/* Internal API routines */
H5_DLL herr_t H5Ddebug(hid_t dset_id);
H5_DLL herr_t H5Dformat_convert(hid_t dset_id);
H5_DLL herr_t H5Dget_chunk_index_type(hid_t did, H5D_chunk_index_t *idx_type);
/// \endcond
/// \cond DEV
/* API Wrappers for async routines */
/* (Must be defined _after_ the function prototype) */
/* (And must only defined when included in application code, not the library) */
#ifndef H5D_MODULE
#define H5Dcreate_async(...) H5Dcreate_async(__FILE__, __func__, __LINE__, __VA_ARGS__)
#define H5Dopen_async(...) H5Dopen_async(__FILE__, __func__, __LINE__, __VA_ARGS__)
#define H5Dget_space_async(...) H5Dget_space_async(__FILE__, __func__, __LINE__, __VA_ARGS__)
#define H5Dread_async(...) H5Dread_async(__FILE__, __func__, __LINE__, __VA_ARGS__)
#define H5Dwrite_async(...) H5Dwrite_async(__FILE__, __func__, __LINE__, __VA_ARGS__)
#define H5Dset_extent_async(...) H5Dset_extent_async(__FILE__, __func__, __LINE__, __VA_ARGS__)
#define H5Dclose_async(...) H5Dclose_async(__FILE__, __func__, __LINE__, __VA_ARGS__)
/* Define "wrapper" versions of function calls, to allow compile-time values to
* be passed in by language wrapper or library layer on top of HDF5.
*/
#define H5Dcreate_async_wrap H5_NO_EXPAND(H5Dcreate_async)
#define H5Dopen_async_wrap H5_NO_EXPAND(H5Dopen_async)
#define H5Dget_space_async_wrap H5_NO_EXPAND(H5Dget_space_async)
#define H5Dread_async_wrap H5_NO_EXPAND(H5Dread_async)
#define H5Dwrite_async_wrap H5_NO_EXPAND(H5Dwrite_async)
#define H5Dset_extent_async_wrap H5_NO_EXPAND(H5Dset_extent_async)
#define H5Dclose_async_wrap H5_NO_EXPAND(H5Dclose_async)
#endif /* H5D_MODULE */
/// \endcond
/* Symbols defined for compatibility with previous versions of the HDF5 API.
*
* Use of these symbols is deprecated.
*/
#ifndef H5_NO_DEPRECATED_SYMBOLS
/* Macros */
#define H5D_CHUNK_BTREE H5D_CHUNK_IDX_BTREE
/* Formerly used to support the H5DOread/write_chunk() API calls.
* These symbols are no longer used in the library.
*/
/* Property names for H5DOwrite_chunk */
#define H5D_XFER_DIRECT_CHUNK_WRITE_FLAG_NAME "direct_chunk_flag"
#define H5D_XFER_DIRECT_CHUNK_WRITE_FILTERS_NAME "direct_chunk_filters"
#define H5D_XFER_DIRECT_CHUNK_WRITE_OFFSET_NAME "direct_chunk_offset"
#define H5D_XFER_DIRECT_CHUNK_WRITE_DATASIZE_NAME "direct_chunk_datasize"
/* Property names for H5DOread_chunk */
#define H5D_XFER_DIRECT_CHUNK_READ_FLAG_NAME "direct_chunk_read_flag"
#define H5D_XFER_DIRECT_CHUNK_READ_OFFSET_NAME "direct_chunk_read_offset"
#define H5D_XFER_DIRECT_CHUNK_READ_FILTERS_NAME "direct_chunk_read_filters"
/* Typedefs */
/* Function prototypes */
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Creates a dataset at the specified location
*
* \fgdta_loc_id
* \param[in] name Name of the dataset to create
* \type_id
* \space_id
* \dcpl_id
*
* \return \hid_t{dataset}
*
* \deprecation_note{H5Dcreate2() or the macro H5Dcreate()}
*
* \details H5Dcreate1() creates a data set with a name, \p name, in the
* location specified by the identifier \p loc_id. \p loc_id may be a
* file, group, dataset, named datatype or attribute. If an attribute,
* dataset, or named datatype is specified for \p loc_id then the
* dataset will be created at the location where the attribute,
* dataset, or named datatype is attached.
*
* \p name can be a relative path based at \p 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 \p type_id and
* \p 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 \p loc_id.
*
* As is the case for any object in a group, the length of a dataset
* name is not limited.
*
* \p dcpl_id is an #H5P_DATASET_CREATE property list created with \p
* 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 \c 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.
*
* \version 1.8.0 Function H5Dcreate() renamed to H5Dcreate1() and deprecated in this release.
* \since 1.0.0
*
* \see H5Dopen2(), H5Dclose(), H5Tset_size()
*
*/
H5_DLL hid_t H5Dcreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t dcpl_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Opens an existing dataset
*
* \fgdta_loc_id
* \param[in] name Name of the dataset to access
*
* \return \hid_t{dataset}
*
* \deprecation_note{H5Dopen2() or the macro H5Dopen()}
*
* \details H5Dopen1() opens an existing dataset for access at the location
* specified by \p loc_id. \p 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
*
*/
H5_DLL hid_t H5Dopen1(hid_t loc_id, const char *name);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Extends a dataset
*
* \dset_id
* \param[in] size Array containing the new size of each dimension
*
* \return \herr_t
*
* \deprecation_note{H5Dset_extent()}
*
* \details H5Dextend() verifies that the dataset is at least of size \p size,
* extending it if necessary. The length of \p size is the same as
* that of the dataspace of the dataset being changed.
*
* This function can be applied to the following datasets:
* \li Any dataset with unlimited dimensions
* \li A dataset with fixed dimensions if the current dimension sizes
* are less than the maximum sizes set with \c 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.
*
* \version 1.8.0 Function deprecated in this release. Parameter size
* syntax changed to \Code{const hsize_t size[]} in this release.
*
*/
H5_DLL herr_t H5Dextend(hid_t dset_id, const hsize_t size[]);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Reclaims variable-length (VL) datatype memory buffers
*
* \type_id
* \space_id
* \dxpl_id
* \param[in] buf Pointer to the buffer to be reclaimed
*
* \return \herr_t
*
* \deprecation_note{H5Treclaim()}
*
* \details H5Dvlen_reclaim() reclaims memory buffers created to store VL
* datatypes.
*
* The \p type_id must be the datatype stored in the buffer. The \p
* space_id describes the selection for the memory buffer to free the
* VL datatypes within. The \p dxpl_id is the dataset transfer property
* list which was used for the I/O transfer to create the buffer. And
* \p buf is the pointer to the buffer to be reclaimed.
*
* The VL structures (\ref 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
*
*/
H5_DLL herr_t H5Dvlen_reclaim(hid_t type_id, hid_t space_id, hid_t dxpl_id, void *buf);
#endif /* H5_NO_DEPRECATED_SYMBOLS */
#ifdef __cplusplus
}
#endif
#endif /* H5Dpublic_H */