H5public.h File Reference

#include "H5pubconf.h"
#include "H5version.h"
#include <features.h>
#include <sys/types.h>
#include <limits.h>
#include <stdarg.h>
#include <stdint.h>
#include <inttypes.h>
#include <stddef.h>
#include <mpi.h>
#include <mpio.h>
#include "H5api_adpt.h"

Data Structures
struct	H5_ih_info_t

Macros
#define	MPICH_SKIP_MPICXX   1
#define	OMPI_SKIP_MPICXX   1
#define	H5_GCC_DIAG_OFF(x)
#define	H5_GCC_DIAG_ON(x)
#define	H5_VERS_MAJOR   1
#define	H5_VERS_MINOR   8
#define	H5_VERS_RELEASE   23
#define	H5_VERS_SUBRELEASE   ""
#define	H5_VERS_INFO   "HDF5 library version: 1.8.23"
#define	H5check()   H5check_version(H5_VERS_MAJOR, H5_VERS_MINOR, H5_VERS_RELEASE)
#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. More...
#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. More...
#define	UINT64_MAX   ((uint64_t)-1)
#define	PRIdHSIZE   H5_PRINTF_LL_WIDTH "d"
#define	PRIiHSIZE   H5_PRINTF_LL_WIDTH "i"
#define	PRIoHSIZE   H5_PRINTF_LL_WIDTH "o"
#define	PRIuHSIZE   H5_PRINTF_LL_WIDTH "u"
#define	PRIxHSIZE   H5_PRINTF_LL_WIDTH "x"
#define	PRIXHSIZE   H5_PRINTF_LL_WIDTH "X"
#define	H5_SIZEOF_HSIZE_T   H5_SIZEOF_LONG_LONG
#define	H5_SIZEOF_HSSIZE_T   H5_SIZEOF_LONG_LONG
#define	HSIZE_UNDEF   ULLONG_MAX
#define	HADDR_UNDEF   ULONG_MAX
#define	H5_SIZEOF_HADDR_T   H5_SIZEOF_LONG
#define	HADDR_AS_MPI_TYPE   MPI_UNSIGNED_LONG
#define	PRIdHADDR   "ld"
#define	PRIoHADDR   "lo"
#define	PRIuHADDR   "lu"
#define	PRIxHADDR   "lx"
#define	PRIXHADDR   "lX"
#define	H5_PRINTF_HADDR_FMT   "%" PRIuHADDR
#define	HADDR_MAX   (HADDR_UNDEF - 1)
#define	H5_ITER_ERROR   (-1)
#define	H5_ITER_CONT   (0)
#define	H5_ITER_STOP   (1)

Typedefs
typedef int	herr_t
typedef unsigned int	hbool_t
typedef int	htri_t
typedef unsigned long long	hsize_t
typedef signed long long	hssize_t
typedef unsigned long	haddr_t

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

Functions
herr_t	H5open (void)
	Initializes the HDF5 library. More...
herr_t	H5close (void)
	Flushes all data to disk, closes all open objects, and releases memory. More...
herr_t	H5dont_atexit (void)
	Instructs library not to install atexit() cleanup routine. More...
herr_t	H5garbage_collect (void)
	Garbage collects on all free-lists of all types. More...
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. More...
herr_t	H5get_libversion (unsigned *majnum, unsigned *minnum, unsigned *relnum)
	Returns the HDF library release number. More...
herr_t	H5check_version (unsigned majnum, unsigned minnum, unsigned relnum)
	Verifies that HDF5 library versions are consistent. More...
herr_t	H5is_library_threadsafe (hbool_t *is_ts)
	Determines whether the HDF5 library was built with the thread-safety feature enabled. More...
herr_t	H5free_memory (void *mem)
	Frees memory allocated by the HDF5 library. More...
void *	H5allocate_memory (size_t size, hbool_t clear)
	Frees memory allocated by the HDF5 library. More...
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. More...

Macro Definition Documentation

H5_GCC_DIAG_OFF

#define H5_GCC_DIAG_OFF

(

x

)

H5_GCC_DIAG_ON

#define H5_GCC_DIAG_ON

(

x

)

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_PRINTF_HADDR_FMT

#define H5_PRINTF_HADDR_FMT   "%" PRIuHADDR

H5_SIZEOF_HADDR_T

#define H5_SIZEOF_HADDR_T   H5_SIZEOF_LONG

H5_SIZEOF_HSIZE_T

#define H5_SIZEOF_HSIZE_T   H5_SIZEOF_LONG_LONG

H5_SIZEOF_HSSIZE_T

#define H5_SIZEOF_HSSIZE_T   H5_SIZEOF_LONG_LONG

H5_VERS_INFO

#define H5_VERS_INFO   "HDF5 library version: 1.8.23"

Full version string

H5_VERS_MAJOR

#define H5_VERS_MAJOR   1

For major interface/format changes

H5_VERS_MINOR

#define H5_VERS_MINOR   8

For minor interface/format changes

H5_VERS_RELEASE

#define H5_VERS_RELEASE   23

For tweaks, bug-fixes, or development

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))

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

(

)

H5check_version(H5_VERS_MAJOR, H5_VERS_MINOR, H5_VERS_RELEASE)

HADDR_AS_MPI_TYPE

#define HADDR_AS_MPI_TYPE   MPI_UNSIGNED_LONG

HADDR_MAX

#define HADDR_MAX   (HADDR_UNDEF - 1)

HADDR_UNDEF

#define HADDR_UNDEF   ULONG_MAX

HSIZE_UNDEF

#define HSIZE_UNDEF   ULLONG_MAX

MPICH_SKIP_MPICXX

#define MPICH_SKIP_MPICXX   1

OMPI_SKIP_MPICXX

#define OMPI_SKIP_MPICXX   1

PRIdHADDR

#define PRIdHADDR   "ld"

PRIdHSIZE

#define PRIdHSIZE   H5_PRINTF_LL_WIDTH "d"

PRIiHSIZE

#define PRIiHSIZE   H5_PRINTF_LL_WIDTH "i"

PRIoHADDR

#define PRIoHADDR   "lo"

PRIoHSIZE

#define PRIoHSIZE   H5_PRINTF_LL_WIDTH "o"

PRIuHADDR

#define PRIuHADDR   "lu"

PRIuHSIZE

#define PRIuHSIZE   H5_PRINTF_LL_WIDTH "u"

PRIxHADDR

#define PRIxHADDR   "lx"

PRIXHADDR

#define PRIXHADDR   "lX"

PRIxHSIZE

#define PRIxHSIZE   H5_PRINTF_LL_WIDTH "x"

PRIXHSIZE

#define PRIXHSIZE   H5_PRINTF_LL_WIDTH "X"

UINT64_MAX

#define UINT64_MAX   ((uint64_t)-1)

The size of file objects.

Typedef Documentation

haddr_t

typedef unsigned long haddr_t

The address of an object in the file.

hbool_t

typedef unsigned int hbool_t

Boolean type. Successful return values are zero (false) or positive (true). The typical true value is 1 but don't bet on it. Boolean functions cannot fail. 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");
}

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");

hsize_t

typedef unsigned long long hsize_t

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

hssize_t

typedef signed long long hssize_t

htri_t

typedef int htri_t

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