History:
|
Release |
Change |
| 1.8.13 |
C function introduced with this release. |
Last modified: 25 October 2011
- Name: H5garbage_collect
- Signature:
- herr_t
H5garbage_collect(void)
- Purpose:
- Garbage collects on all free-lists of all types.
- Description:
H5garbage_collect walks through all the garbage
collection routines of the library, freeing any unused memory.
It is not required that H5garbage_collect be called
at any particular time; it is only necessary in certain situations
where the application has performed actions that cause the library
to allocate many objects. The application should call
H5garbage_collect if it eventually releases those
objects and wants to reduce the memory used by the library from
the peak usage required.
The library automatically garbage collects all the free lists
when the application ends.
- Parameters:
-
None.
- Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Fortran90 Interface: h5garbage_collect_f
-
Signature:
SUBROUTINE h5garbage_collect_f(error)
INTEGER, INTENT(OUT) :: error
Outputs:
error - Returns 0 if successful and -1 if fails
- History:
|
Release |
Fortran90 |
| 1.4.5 |
Function introduced in this release. |
| 1.8.8 |
Fortran subroutine updated in this release. |
Last modified: 25 October 2011
- Name: H5get_libversion
- Signature:
- herr_t
H5get_libversion(
unsigned *majnum,
unsigned *minnum,
unsigned *relnum
)
- Purpose:
- Returns the HDF library release number.
- Description:
H5get_libversion retrieves the major, minor, and release
numbers of the version of the HDF library which is linked to
the application.
- Parameters:
unsigned *majnum |
OUT: The major version of the library. |
unsigned *minnum |
OUT: The minor version of the library. |
unsigned *relnum |
OUT: The release number of the library. |
- Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Fortran90 Interface: h5get_libversion_f
-
Signature:
SUBROUTINE h5get_libversion_f(majnum, minnum, relnum, error)
INTEGER, INTENT(OUT) :: majnum, minnum, relnum, error
Outputs:
majnum - major version of the library
minum - minor version of the library
relnum - release version of the library
error - Returns 0 if successful and -1 if fails
- History:
|
Release |
Change |
| 1.4.5 |
Fortran subroutine introduced in this release. |
| 1.8.8 |
Fortran subroutine updated in this release. |
Last modified: 29 September 2015
- Name:
H5is_library_threadsafe
- Signature:
herr_t H5is_library_threadsafe(/*OUT*/
hbool_t* is_ts)
- Purpose:
- Determine whether the HDF5 Library was built with the thread-safety
feature enabled.
- Description:
- The HDF5 Library, although not internally multithreaded, can
optionally be built with a thread-safety feature enabled that
protects internal data structures with a mutex. In certain
circumstances, it may be useful to determine, at run-time, whether
the linked HDF5 Library was built with this thread-safety feature
enabled.
- Parameters:
hbool_t* is_ts |
OUT: Boolean value indicating
whether the library was built with thread-safety enabled. |
- Returns:
- Returns a non-negative value if successful. Otherwise, returns
a negative value.
- Fortran Interface:
- None
- History:
-
|
Release |
Change |
| 1.8.16 |
C function introduced with this release. |
Last modified: 25 October 2011
- Name: H5open
- Signature:
- herr_t
H5open(void)
- Purpose:
- Initializes the HDF5 library.
- Description:
H5open initialize the library.
When the HDF5 Library is employed in a C application,
this function is normally called automatically, but if you
find that an HDF5 library function is failing inexplicably,
try calling this function first.
If you wish to elimnate this possibility, it is safe to
routinely call H5open before an application
starts working with the library as there are no damaging
side-effects in calling it more than once.
When the HDF5 Library is employed in a Fortran90 application,
h5open_f initializes global variables
(for example, predefined types) and performs other tasks required
to initialize the HDF5 Fortran Library.
h5open_f and h5close_f are
required calls in HDF5 Fortran applications.
- Parameters:
- None.
- Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Fortran90 Interface: h5open_f
-
Signature:
SUBROUTINE h5open_f(error)
INTEGER, INTENT(OUT) :: error
Outputs:
error - Returns 0 if successful and -1 if fails
- History:
|
Release |
Change |
| 1.8.8 |
Fortran subroutine updated in this release. |
Last modified: 1 May 2015
- Name: H5resize_memory
- Signature:
void * H5resize_memory(
void *mem,
size_t size
)
- Purpose:
- Resizes and possibly re-allocates memory
that will later be freed internally by the HDF5 Library.
- Description:
H5resize_memory takes a pointer to an existing buffer
and resizes the buffer to match the value in size.
If necessary, the buffer is reallocated.
If size is 0, the buffer is released.
The input buffer must either be NULL
or have been allocated by H5allocate_memory
since the input buffer may be freed by the library.
For certain behaviors, the pointer mem
may be passed in as NULL.
This function is intended to have the semantics of
realloc():
|
H5resize_memory(buffer, size)
|
Resizes buffer.
Returns pointer to resized buffer. |
|
H5resize_memory(NULL, size) |
Allocates memory using HDF5 Library allocator.
Returns pointer to new buffer |
|
H5resize_memory(buffer, 0) |
Frees memory using HDF5 Library allocator.
Returns NULL. |
|
H5resize_memory(NULL, 0) |
Returns NULL (undefined in C standard). |
Unlike realloc(), which allows for a
“special” pointer to be returned instead of
NULL, this function always returns NULL
on failure or when size is 0 (zero).
At this time, the only intended use for this function
is to resize or reallocate memory that will be returned
to the library (and eventually to the user) as a data buffer
from a third-party HDF5 filter.
- Notes:
- 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 resize memory
on Microsoft Windows systems. 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 still best to ensure
that all components of a C application are built with the
same version of Visual Studio and the same configuration
(Debug or Release), and thus linked against the same CRT.
Only use this function to resize memory inside third-party
HDF5 filters. It will generally not be safe to use this function
to resize memory for any other purpose.
- Parameters:
void *mem |
|
IN: Pointer to a buffer to be resized.
May be NULL. |
size_t size |
|
IN: New size of the buffer, in bytes |
- Returns:
- On success, returns pointer to resized or reallocated buffer or
returns
NULL if size is 0
(zero).
Returns NULL on failure.
- Fortran Interface:
- None
- See Also:
- History:
-
|
Release |
Change |
| 1.8.15 |
C function introduced with this release. |
Last modified: 6 May 2010
- Name: H5set_free_list_limits
- Signature:
- herr_t
H5set_free_list_limits(
int reg_global_lim,
int reg_list_lim,
int arr_global_lim,
int arr_list_lim,
int blk_global_lim,
int blk_list_lim
)
- Purpose:
- Sets free-list size limits.
- Description:
H5set_free_list_limits sets size limits
on all types of free lists.
The HDF5 library uses free lists internally to manage memory.
The types of free lists used are as follows:
- Regular
free lists manage memory for single internal data structures.
- Array
free lists manage memory for arrays of internal data structures.
- Block
free lists manage memory for arbitrarily-sized blocks of bytes.
- Factory
free lists manage memory for fixed-size blocks of bytes.
The parameters specify global and per-list limits; for example,
reg_global_limit and reg_list_limit limit the
accumulated size of all regular free lists and the size of each
individual regular free list, respectively. Therefore, if an application
sets a 1Mb limit on each of the global lists, up to 4Mb of total storage
might be allocated, 1Mb for each of the regular, array, block, and
factory type lists.
The settings specified for block free lists are duplicated for
factory free lists. Therefore, increasing the global limit on block
free lists by x bytes will increase the potential free list
memory usage by 2x bytes.
Using a value of -1 for a limit means that
no limit is set for the specified type of free list.
- Parameters:
int reg_global_lim |
IN: The cumulative limit, in bytes,
on memory used for all regular free lists
(Default: 1MB) |
int reg_list_lim |
IN: The limit, in bytes,
on memory used for each regular free list
(Default: 64KB) |
int arr_global_lim |
IN: The cumulative limit, in bytes,
on memory used for all array free lists
(Default: 4MB) |
int arr_list_lim |
IN: The limit, in bytes,
on memory used for each array free list
(Default: 256KB) |
int blk_global_lim |
IN: The cumulative limit, in bytes,
on memory used for all block free lists and, separately,
for all factory free lists
(Default: 16MB) |
int blk_list_lim |
IN: The limit, in bytes,
on memory used for each block or factory free list
(Default: 1MB) |
- Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Fortran90 Interface:
- None.
- History:
|
Release |
C |
| 1.6.0 |
Function introduced in this release. |
| 1.8.3 |
Function changed in this release to set factory free list memory
limits. |
Last modified: 22 April 2011
- Name: H5_VERSION_GE
- Signature:
H5_VERSION_GE(
int maj,
int min,
int rel
)
- Purpose:
- Determines whether the version of the library being used is
greater than or equal to the specified version.
- Motivation:
- The
H5_VERSION_GE
and H5_VERSION_LE
macros are used at compile time to conditionally include or exclude
code based on the version of the HDF5 library against which
an application will be linked.
- Description:
- The
H5_VERSION_GE macro compares the version of
the HDF5 library being used against the version number specified
in the parameters.
For more information, see “HDF5 Software Updates” at
www.hdfgroup.org/HDF5/doc/TechNotes/Version.html.
- Parameters:
int maj |
IN: Major version number
A non-negative integer value |
int min |
IN: Minor version number
A non-negative integer value |
int rel |
IN: Release number
A non-negative integer value |
- Returns:
TRUE |
If the library version is
greater than or equal to the version number specified |
FALSE |
If the library version is
less than the version number specified |
A library version is greater than the specified version number if its
major version is larger than the specified major version number.
If the major version numbers are the same, it is greater than the
specified version number if its minor version is larger than the
specified minor version number. If the minor version numbers are
the same, then a library version would be greater than the specified
version number if its release number is larger than the specified
release number.
- Fortran Interface:
- None
- Example Usage:
- Suppose an application wants to call different functions based
on the version of the HDF5 library to which an application will be
linked.
For example, the link functions,
H5Lxxx,
are new in the 1.8 versions of HDF5,
and some group functions, H5Gxxx,
are deprecated in the 1.8 versions.
The following code uses H5Ldelete if the library version
is 1.8.0 or greater or uses H5Gunlink if the
library version is not greater than 1.8.0.
Similarly, the code calls H5Lexists or
H5Gopen to make sure the group has been deleted.
#if H5_VERSION_GE(1,8,0)
ret = H5Ldelete(file, "Group", H5P_DEFAULT);
CHECK(ret, FAIL, "H5Lunlink");
status = H5Lexists(file, "Group", H5P_DEFAULT);
VERIFY(status, FALSE, "H5Lexists");
#else
ret = H5Gunlink(file, "Group");
CHECK(ret, FAIL, "H5Gunlink");
H5E_BEGIN_TRY {
grp = H5Gopen(file, "Group");
} H5E_END_TRY;
VERIFY(grp, FAIL, "H5Gopen");
#endif
- History:
Release |
Change |
| 1.8.7 |
C macro introduced in this release. |
Last modified: 22 April 2011
- Name: H5_VERSION_LE
- Signature:
H5_VERSION_LE(
int maj,
int min,
int rel
)
- Purpose:
- Determines whether the version of the library being used is
less than or equal to the specified version.
- Motivation:
- The
H5_VERSION_GE
and H5_VERSION_LE
macros are used at compile time to conditionally include or exclude
code based on the version of the HDF5 library against which
an application will be linked.
- Description:
- The
H5_VERSION_LE macro compares the version of
the HDF5 library being used against the version number specified
in the parameters.
For more information, see “HDF5 Software Updates” at
www.hdfgroup.org/HDF5/doc/TechNotes/Version.html.
- Parameters:
int maj |
IN: Major version number
A non-negative integer value |
int min |
IN: Minor version number
A non-negative integer value |
int rel |
IN: Release number
A non-negative integer value |
- Returns:
TRUE |
If the library version is
less than or equal to the version number specified |
FALSE |
If the library version is greater than the
version number specified |
A library version is less than the specified version number if its
major version is smaller than the specified major version number.
If the major version numbers are the same, it is less than the
specified version number if its minor version is smaller than the
specified minor version number. If the minor version numbers are
the same, then a library version would be less than the specified
version number if its release number is smaller than the specified
release number.
- Fortran Interface:
- None
- Example Usage:
-
Suppose an application wants to call different functions based
on the version of the HDF5 library to which an application will be
linked. For example, the link functions,
H5Lxxx,
are new in the 1.8 versions of HDF5, and some group functions,
H5Gxxx, are deprecated in the 1.8 versions.
The following code uses H5Gunlink if the
library version is 1.6.10 or earlier or uses H5Ldelete
if the library version is not 1.6.10 or earlier. Similarly, the code
calls H5Gopen or H5Lexists
to make sure the group has been deleted.
#if H5_VERSION_LE(1,6,10)
ret = H5Gunlink(file, "Group");
CHECK(ret, FAIL, "H5Gunlink");
H5E_BEGIN_TRY {
grp = H5Gopen(file, "Group");
} H5E_END_TRY;
VERIFY(grp, FAIL, "H5Gopen");
#else
ret = H5Ldelete(file, "Group", H5P_DEFAULT);
CHECK(ret, FAIL, "H5Lunlink");
status = H5Lexists(file, "Group", H5P_DEFAULT);
VERIFY(status, FALSE, "H5Lexists");
#endif
- History:
Release |
Change |
| 1.8.7 |
C macro introduced in this release. |
The HDF Group Help Desk: 
Describes HDF5 Release 1.8.20, November 2017.
| |
Copyright by
The HDF Group
and the Board of Trustees of the University of Illinois
|
Last modified: 29 September 2015
|