Help us improve by taking our short survey: https://www.hdfgroup.org/website-survey/

| HDF5 Last Updated on 2026-03-23 The HDF5 Field Guide

Loading...
Searching...
No Matches
H5public.h File Reference
`#include "H5pubconf.h"`
`#include "H5version.h"`
`#include <inttypes.h>`
`#include <limits.h>`
`#include <stdarg.h>`
`#include <stdbool.h>`
`#include <stddef.h>`
`#include <stdint.h>`
`#include <sys/types.h>`
`#include <mpi.h>`
`#include <mpio.h>`
`#include "H5api_adpt.h"`

## Data Structures
struct | H5_ih_info_t
struct | H5O_token_t

## Macros
#define | H5_ITER_CONT (0)
#define | H5_ITER_ERROR (-1)
#define | H5_ITER_STOP (1)
#define | H5_LIKELY(expression)
#define | H5_NO_EXPAND(x)
#define | H5_PRINTF_HADDR_FMT "%" PRIuHADDR
#define | H5_SIZEOF_HADDR_T 8
#define | H5_SIZEOF_HSIZE_T 8
#define | H5_SIZEOF_HSSIZE_T 8
#define | H5_UNLIKELY(expression)
#define | H5_VERS_INFO "HDF5 library version: " H5_VERS_STR
#define | H5_VERS_MAJOR 2
#define | H5_VERS_MINOR 1
#define | H5_VERS_RELEASE 1
#define | H5_VERS_STR H5_VERS_STR_CONCAT(H5_VERS_MAJOR, H5_VERS_MINOR, H5_VERS_RELEASE, H5_VERS_SUBRELEASE)
#define | H5_VERS_STR_CONCAT(major, minor, release, sub)
#define | H5_VERS_STR_HELPER(major, minor, release)
#define | H5_VERS_SUBRELEASE ""
#define | H5_VERSION_GE(Maj, Min, Rel)
| Determines whether the version of the library being used is greater than or equal to the specified version.
#define | H5_VERSION_LE(Maj, Min, Rel)
| Determines whether the version of the library being used is less than or equal to the specified version.
#define | H5check()
#define | H5O_MAX_TOKEN_SIZE (16)
#define | H5OPEN (H5_UNLIKELY(!H5_libinit_g && !H5_libterm_g) ? H5open() : 0),
#define | HADDR_AS_MPI_TYPE MPI_UINT64_T
#define | HADDR_MAX (HADDR_UNDEF - 1)
#define | HADDR_UNDEF UINT64_MAX
#define | HDF5_DRIVER "HDF5_DRIVER"
#define | HDF5_DRIVER_CONFIG "HDF5_DRIVER_CONFIG"
#define | HDF5_NOCLEANUP "HDF5_NOCLEANUP"
#define | HDF5_PLUGIN_PATH "HDF5_PLUGIN_PATH"
#define | HDF5_PLUGIN_PRELOAD "HDF5_PLUGIN_PRELOAD"
#define | HDF5_PREFER_WINDOWS_CODE_PAGE "HDF5_PREFER_WINDOWS_CODE_PAGE"
#define | HDF5_USE_FILE_LOCKING "HDF5_USE_FILE_LOCKING"
#define | HDF5_VOL_CONNECTOR "HDF5_VOL_CONNECTOR"
#define | HSIZE_AS_MPI_TYPE MPI_UINT64_T
#define | HSIZE_UNDEF UINT64_MAX
#define | MPICH_SKIP_MPICXX 1
#define | OMPI_SKIP_MPICXX 1
#define | PRIdHADDR PRId64
#define | PRIdHSIZE PRId64
#define | PRIiHSIZE PRIi64
#define | PRIoHADDR PRIo64
#define | PRIoHSIZE PRIo64
#define | PRIuHADDR PRIu64
#define | PRIuHSIZE PRIu64
#define | PRIXHADDR PRIX64
#define | PRIXHSIZE PRIX64

## Typedefs
typedef void(* | H5_atclose_func_t) (void *ctx)
typedef uint64_t | haddr_t
typedef bool | hbool_t
typedef off_t | HDoff_t
typedef int | herr_t
typedef uint64_t | hsize_t
typedef int64_t | hssize_t
typedef int | htri_t

## Enumerations
enum | H5_index_t { H5_INDEX_UNKNOWN = -1 , H5_INDEX_NAME , H5_INDEX_CRT_ORDER , H5_INDEX_N }
enum | H5_iter_order_t { H5_ITER_UNKNOWN = -1 , H5_ITER_INC , H5_ITER_DEC , H5_ITER_NATIVE , H5_ITER_N }

## Functions
void * | H5allocate_memory (size_t size, bool clear)
| Allocates memory that will be freed later internally.
herr_t | H5atclose (H5_atclose_func_t func, void *ctx)
| Registers a callback for the library to invoke when it's closing.
herr_t | H5check_version (unsigned majnum, unsigned minnum, unsigned relnum)
| Verifies that HDF5 library versions are consistent.
herr_t | H5close (void)
| Flushes all data to disk, closes all open objects, and releases memory.
herr_t | H5dont_atexit (void)
| Instructs library not to install atexit() cleanup routine.
herr_t | H5free_memory (void *mem)
| Frees memory allocated by the HDF5 library.
herr_t | H5garbage_collect (void)
| Garbage collects on all free-lists of all types.
herr_t | H5get_free_list_sizes (size_t *reg_size, size_t *arr_size, size_t *blk_size, size_t *fac_size)
| Gets the current size of the free lists used to manage memory.
herr_t | H5get_libversion (unsigned *majnum, unsigned *minnum, unsigned *relnum)
| Returns the HDF library release number.
herr_t | H5is_library_terminating (bool *is_terminating)
| Checks whether the HDF5 library is closing.
herr_t | H5is_library_threadsafe (bool *is_ts)
| Determines whether the HDF5 library was built with the thread-safety feature enabled.
herr_t | H5open (void)
| Initializes the HDF5 library.
void * | H5resize_memory (void *mem, size_t size)
| Resizes and, if required, re-allocates memory that will later be freed internally by the HDF5 library.
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)
| Sets free-list size limits.

## Variables
bool | H5_libterm_g

## Macro Definition Documentation

## ◆ H5_ITER_CONT

#define H5_ITER_CONT (0)

Continue iteration

## ◆ H5_ITER_ERROR

#define H5_ITER_ERROR (-1)

Error, stop iteration

## ◆ H5_ITER_STOP

#define H5_ITER_STOP (1)

Stop iteration, short-circuit success

## ◆ H5_LIKELY

#define H5_LIKELY | ( |  | expression | ) |

Value:
(expression)

## ◆ H5_NO_EXPAND

#define H5_NO_EXPAND | ( |  | x | ) |

Value:
(x)

## ◆ H5_PRINTF_HADDR_FMT

#define H5_PRINTF_HADDR_FMT "%" PRIuHADDR

## ◆ H5_SIZEOF_HADDR_T

#define H5_SIZEOF_HADDR_T 8

## ◆ H5_SIZEOF_HSIZE_T

#define H5_SIZEOF_HSIZE_T 8

## ◆ H5_SIZEOF_HSSIZE_T

#define H5_SIZEOF_HSSIZE_T 8

## ◆ H5_UNLIKELY

#define H5_UNLIKELY | ( |  | expression | ) |

Value:
(expression)

## ◆ H5_VERS_INFO

#define H5_VERS_INFO "HDF5 library version: " H5_VERS_STR

Full version string - automatically derived from H5_VERS_STR

## ◆ H5_VERS_MAJOR

#define H5_VERS_MAJOR 2

For major interface/format changes

## ◆ H5_VERS_MINOR

#define H5_VERS_MINOR 1

For minor interface/format changes

## ◆ H5_VERS_RELEASE

#define H5_VERS_RELEASE 1

For tweaks, bug-fixes, or development

## ◆ H5_VERS_STR

#define H5_VERS_STR H5_VERS_STR_CONCAT(H5_VERS_MAJOR, H5_VERS_MINOR, H5_VERS_RELEASE, H5_VERS_SUBRELEASE)

## ◆ H5_VERS_STR_CONCAT

#define H5_VERS_STR_CONCAT | ( |  | major,
|  |  | minor,
|  |  | release,
|  |  | sub )

Value:
H5_VERS_STR_HELPER(major, minor, release) sub
H5_VERS_STR_HELPER
#define H5_VERS_STR_HELPER(major, minor, release)
Definition H5public.h:94

## ◆ H5_VERS_STR_HELPER

#define H5_VERS_STR_HELPER | ( |  | major,
|  |  | minor,
|  |  | release )

Value:
#major "." #minor "." #release

Short version string - automatically derived from H5_VERS_MAJOR/MINOR/RELEASE/SUBRELEASE

This macro uses C preprocessor string concatenation. The H5_VERS_MAJOR, H5_VERS_MINOR, and H5_VERS_RELEASE values are stringified and concatenated with dots, then concatenated with H5_VERS_SUBRELEASE (which must already be a string literal).

## ◆ H5_VERS_SUBRELEASE

#define H5_VERS_SUBRELEASE ""

For pre-releases like `snap0`. Empty string for official releases.

## ◆ H5_VERSION_GE

#define H5_VERSION_GE | ( |  | Maj,
|  |  | Min,
|  |  | Rel )

Value:
(((H5_VERS_MAJOR == Maj) && (H5_VERS_MINOR == Min) && (H5_VERS_RELEASE >= Rel)) || \
((H5_VERS_MAJOR == Maj) && (H5_VERS_MINOR > Min)) || (H5_VERS_MAJOR > Maj))
H5_VERS_MAJOR
#define H5_VERS_MAJOR
Definition H5public.h:64
H5_VERS_MINOR
#define H5_VERS_MINOR
Definition H5public.h:68
H5_VERS_RELEASE
#define H5_VERS_RELEASE
Definition H5public.h:72

Determines whether the version of the library being used is greater than or equal to the specified version.

Parameters

  [in] | Maj | Major version number - A non-negative integer value
  [in] | Min | Minor version number - A non-negative integer value
  [in] | Rel | Release version number - A non-negative integer value

Returns
  A value of 1 is returned if the library version is greater than or equal to the version number specified.
  A value of 0 is returned 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.

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.

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 about release versioning, see HDF5 Library Release Version Numbers.

Since
  1.8.7

## ◆ H5_VERSION_LE

#define H5_VERSION_LE | ( |  | Maj,
|  |  | Min,
|  |  | Rel )

Value:
(((H5_VERS_MAJOR == Maj) && (H5_VERS_MINOR == Min) && (H5_VERS_RELEASE <= Rel)) || \
((H5_VERS_MAJOR == Maj) && (H5_VERS_MINOR < Min)) || (H5_VERS_MAJOR < Maj))

Determines whether the version of the library being used is less than or equal to the specified version.

Parameters

  [in] | Maj | Major version number - A non-negative integer value
  [in] | Min | Minor version number - A non-negative integer value
  [in] | Rel | Release version number - A non-negative integer value

Returns
  A value of 1 is returned if the library version is less than or equal to the version number specified.
  A value of 0 is returned 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 smaller 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 smaller than the specified version number if its release number is smaller than the specified release number.

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.

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 about release versioning, see HDF5 Library Release Version Numbers.

Since
  1.8.7

## ◆ H5check

#define H5check | ( |  | ) |

Value:
H5check_version(H5_VERS_MAJOR, H5_VERS_MINOR, H5_VERS_RELEASE)
H5check_version
herr_t H5check_version(unsigned majnum, unsigned minnum, unsigned relnum)
Verifies that HDF5 library versions are consistent.

## ◆ H5O_MAX_TOKEN_SIZE

#define H5O_MAX_TOKEN_SIZE (16)

The maximum size allowed for tokens

Tokens are unique and permanent identifiers that are used to reference HDF5 objects in a container. This allows for 128-bit tokens

Since
  1.12.0

## ◆ H5OPEN

#define H5OPEN (H5_UNLIKELY(!H5_libinit_g && !H5_libterm_g) ? H5open() : 0),

## ◆ HADDR_AS_MPI_TYPE

#define HADDR_AS_MPI_TYPE MPI_UINT64_T

## ◆ HADDR_MAX

#define HADDR_MAX (HADDR_UNDEF - 1)

## ◆ HADDR_UNDEF

#define HADDR_UNDEF UINT64_MAX

## ◆ HDF5_DRIVER

#define HDF5_DRIVER "HDF5_DRIVER"

Used to specify the name of an HDF5 Virtual File Driver to use as the default file driver for file access. Setting this environment variable overrides the default file driver for File Access Property Lists.

Since
  1.14.0

## ◆ HDF5_DRIVER_CONFIG

#define HDF5_DRIVER_CONFIG "HDF5_DRIVER_CONFIG"

Used to specify a configuration string for the HDF5 Virtual File Driver being used for file access.

Since
  1.14.0

## ◆ HDF5_NOCLEANUP

#define HDF5_NOCLEANUP "HDF5_NOCLEANUP"

Used to instruct HDF5 not to cleanup files created during testing.

Since
  1.14.0

## ◆ HDF5_PLUGIN_PATH

#define HDF5_PLUGIN_PATH "HDF5_PLUGIN_PATH"

Used to specify a delimiter-separated (currently, ';' for Windows and ':' for other systems) list of paths that HDF5 should search when loading plugins.

Since
  1.14.0

## ◆ HDF5_PLUGIN_PRELOAD

#define HDF5_PLUGIN_PRELOAD "HDF5_PLUGIN_PRELOAD"

Used to control the loading of HDF5 plugins at runtime. If this environment variable is set to the special string "::" (defined in H5PLpublic.h as H5PL_NO_PLUGIN), then dynamic loading of any HDF5 plugins will be disabled. No other values are valid for this environment variable.

Since
  1.14.0

## ◆ HDF5_PREFER_WINDOWS_CODE_PAGE

#define HDF5_PREFER_WINDOWS_CODE_PAGE "HDF5_PREFER_WINDOWS_CODE_PAGE"

Macro for environment variable used to instruct HDF5 to prefer Windows code pages over UTF-8 for functions that accept 'char *' parameters. Valid values for this environment variable are as follows (case-insensitive):

"TRUE" or "1" - Request that Windows code pages be preferred
"FALSE" or "0" - Request that UTF-8 be preferred

Since
  2.0.0

## ◆ HDF5_USE_FILE_LOCKING

#define HDF5_USE_FILE_LOCKING "HDF5_USE_FILE_LOCKING"

Used to control whether HDF5 uses file locking when creating or opening a file. Valid values for this environment variable are as follows:

"TRUE" or "1" - Request that file locks should be used
"FALSE" or "0" - Request that file locks should NOT be used
"BEST_EFFORT" - Request that file locks should be used and that any locking errors caused by file locking being disabled on the system should be ignored

Since
  1.14.0

## ◆ HDF5_VOL_CONNECTOR

#define HDF5_VOL_CONNECTOR "HDF5_VOL_CONNECTOR"

Used to specify the name of an HDF5 Virtual Object Layer Connector to use as the default VOL connector for file access. Setting this environment variable overrides the default VOL connector for File Access Property Lists.

Since
  1.14.0

## ◆ HSIZE_AS_MPI_TYPE

#define HSIZE_AS_MPI_TYPE MPI_UINT64_T

## ◆ HSIZE_UNDEF

#define HSIZE_UNDEF UINT64_MAX

Represents the largest possible value of uint64_t

Since
  1.10.0

## ◆ MPICH_SKIP_MPICXX

#define MPICH_SKIP_MPICXX 1

## ◆ OMPI_SKIP_MPICXX

#define OMPI_SKIP_MPICXX 1

## ◆ PRIdHADDR

#define PRIdHADDR PRId64

d print conversion specifier for unsigned integer type

Since
  1.8.23

## ◆ PRIdHSIZE

#define PRIdHSIZE PRId64

d print conversion specifier for signed integer type

Since
  1.10.8

## ◆ PRIiHSIZE

#define PRIiHSIZE PRIi64

i print conversion specifier for signed integer type

Since
  1.10.8

## ◆ PRIoHADDR

#define PRIoHADDR PRIo64

o print conversion specifier for unsigned integer type

Since
  1.8.23

## ◆ PRIoHSIZE

#define PRIoHSIZE PRIo64

o print conversion specifier for signed integer type

Since
  1.10.8

## ◆ PRIuHADDR

#define PRIuHADDR PRIu64

u print conversion specifier for unsigned integer type

Since
  1.8.23

## ◆ PRIuHSIZE

#define PRIuHSIZE PRIu64

u print conversion specifier for signed integer type

Since
  1.10.8

## ◆ PRIXHADDR

#define PRIXHADDR PRIX64

X print conversion specifier for unsigned integer type

Since
  1.8.23

## ◆ PRIxHADDR

#define PRIxHADDR PRIx64

x print conversion specifier for unsigned integer type

Since
  1.8.23

## ◆ PRIXHSIZE

#define PRIXHSIZE PRIX64

X print conversion specifier for signed integer type

Since
  1.10.8

## ◆ PRIxHSIZE

#define PRIxHSIZE PRIx64

x print conversion specifier for signed integer type

Since
  1.10.8

## Typedef Documentation

## ◆ H5_atclose_func_t

typedef void(* H5_atclose_func_t) (void *ctx)

Library shutdown callback, used by H5atclose().

## ◆ haddr_t

typedef uint64_t haddr_t

The address of an object in the file.

## ◆ hbool_t

typedef bool hbool_t

C99-style Boolean type. Successful return values are zero (false) or positive (true). The typical true value is 1 but don't bet on it.

Deprecated
  Now that we require C99, hbool_t is typedef'd to C99's bool and hbool_t is considered deprecated. Due to its long-standing, widespread use, we have no plans to remove the hbool_t typedef from the public API, though it is otherwise unused in the library.

Attention
  Boolean functions cannot fail.

## ◆ HDoff_t

typedef off_t HDoff_t

Platform-independent offset

## ◆ herr_t

typedef int herr_t

Status return values. Failed integer functions in HDF5 result almost always in a negative value (unsigned failing functions sometimes return zero for failure) while successful return is non-negative (often zero). The negative failure value is most commonly -1, but don't bet on it.

The proper way to detect failure is something like:

if((dset = H5Dopen2(file, name)) < 0)
fprintf(stderr, "unable to open the requested dataset\n");
H5Dopen2
hid_t H5Dopen2(hid_t loc_id, const char *name, hid_t dapl_id)
Opens an existing dataset.

## ◆ hsize_t

typedef uint64_t hsize_t

The size of file objects.

## ◆ hssize_t

typedef int64_t hssize_t

The size of file objects. Used when negative values are needed to indicate errors.

## ◆ htri_t

typedef int htri_t

Three-valued Boolean type. Functions that return htri_t however return zero (false), positive (true), or negative (failure).

The proper way to test for truth from a htri_t function is:

if ((retval = H5Tcommitted(type)) > 0) {
printf("data type is committed\n");
} else if (!retval) {
printf("data type is not committed\n");
} else {
printf("error determining whether data type is committed\n");
}
H5Tcommitted
htri_t H5Tcommitted(hid_t type_id)
Determines whether a datatype is a committed type or a transient type.

## Enumeration Type Documentation

## ◆ H5_index_t

enum H5_index_t

The types of indices on links in groups/attributes on objects. Primarily used for "<do> <foo> by index" routines and for iterating over links in groups/attributes on objects.

Enumerator
H5_INDEX_UNKNOWN | Unknown index type
H5_INDEX_NAME | Index on names
H5_INDEX_CRT_ORDER | Index on creation order
H5_INDEX_N | Number of indices defined

## ◆ H5_iter_order_t

enum H5_iter_order_t

Common iteration orders

Enumerator
H5_ITER_UNKNOWN | Unknown order
H5_ITER_INC | Increasing order
H5_ITER_DEC | Decreasing order
H5_ITER_NATIVE | No particular order, whatever is fastest
H5_ITER_N | Number of iteration orders

## Variable Documentation

## ◆ H5_libterm_g

bool H5_libterm_g
| extern