- Created by Mike McGreevy, last modified by Barbara Jones on Jul 28, 2020
H5_ALLOCATE_MEMORY
Allocates memory that will later be freed internally by the HDF5 library
Procedure:
H5_ALLOCATE_MEMORY(size, clear)
Signature:
void *H5allocate_memory
(
size_t size,
hbool_t clear
)
Parameters:
size_t
size | IN: Specifies the size in bytes of the buffer to be allocated |
hbool_t clear | IN: Specifies whether the new buffer is to be initialized to 0 (zero) |
Description:
H5_ALLOCATE_MEMORY allocates a memory buffer of size bytes that will later be freed internally by the HDF5 library.
The boolean clear parameter specifies whether the buffer should be initialized. If clear is TRUE, all bits in the buffer are to be set to 0 (zero); if clear is FALSE, the buffer will not be initialized.
This function is intended to have the semantics of malloc() and calloc(). However, unlike malloc() and calloc() which allow for a “special” pointer to be returned instead of NULL, this function always returns NULL on failure or when size is set to 0 (zero).
At this time, the only intended use for this function is to allocate memory that will be returned to the library as a data buffer from a third-party filter.
To avoid heap corruption, allocated memory should be freed using the same library that initially allocated it. In most cases, the HDF5 API uses resources that are allocated and freed either entirely by the user or entirely by the library, so this is not a problem. In rare cases, however, HDF5 API calls will free memory that the user allocated. This function allows the user to safely allocate this memory.
It is particularly important to use this function to allocate memory in Microsoft Windows environments. In Windows, the C standard library is implemented in dynamic link libraries (DLLs) known as the C run-time (CRT). Each version of Visual Studio comes with multiple versions of the CRT DLLs (debug, release, et cetera) and allocating and freeing memory across DLL boundaries can cause resource leaks and subtle bugs due to heap corruption.
Even when using this function, it is best where possible to ensure that all components of a C application are built with the same version of Visual Studio and configuration (Debug or Release), and thus linked against the same CRT.
Use this function only to allocate memory inside third-party HDF5 filters. It will generally not be safe to use this function to allocate memory for any other purpose.
Returns:
On success, returns pointer to newly allocated buffer or returns NULL if size is 0 (zero).
Returns NULL on failure.
Example:
Coming soon!
See Also:
-
Page:H5_FREE_MEMORY — Frees memory allocated by the HDF5 library
-
Page:H5_RESIZE_MEMORY — Resizes and, if required, re-allocates memory that will later be freed internally by the HDF5 library
History:
| Release | Change |
|---|---|
| 1.8.15 | C function introduced with this release. |
--- Last Modified: July 28, 2020 | 10:12 AM