/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * * terms governing use, modification, and redistribution, is contained in * * the COPYING file, which can be found at the root of the source code * * distribution tree, or in https://support.hdfgroup.org/ftp/HDF5/releases. * * If you do not have access to either file, you may request a copy from * * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* * This file contains public declarations for the HDF5 module. */ #ifndef _H5public_H #define _H5public_H /* Include files for public use... */ /* * Since H5pubconf.h is a generated header file, it is messy to try * to put a #ifndef _H5pubconf_H ... #endif guard in it. * HDF5 has set an internal rule that it is being included here. * Source files should NOT include H5pubconf.h directly but include * it via H5public.h. The #ifndef _H5public_H guard above would * prevent repeated include. */ #include "H5pubconf.h" /* From configure */ /* API Version macro wrapper definitions */ #include "H5version.h" #ifdef H5_HAVE_FEATURES_H #include /* For setting POSIX, BSD, etc. compatibility */ #endif #ifdef H5_HAVE_SYS_TYPES_H #include #endif #ifdef H5_STDC_HEADERS #include /* For H5T_NATIVE_CHAR defn in H5Tpublic.h */ #include /* For variadic functions in H5VLpublic.h */ #endif #ifndef __cplusplus #ifdef H5_HAVE_STDINT_H #include /* For C9x types */ #endif #else #ifdef H5_HAVE_STDINT_H_CXX #include /* For C9x types (when included from C++) */ #endif #endif #ifdef H5_HAVE_INTTYPES_H #include /* C99/POSIX.1 header for uint64_t, PRIu64 */ #endif #ifdef H5_HAVE_STDDEF_H #include #endif #ifdef H5_HAVE_PARALLEL /* Don't link against MPI C++ bindings */ #define MPICH_SKIP_MPICXX 1 #define OMPI_SKIP_MPICXX 1 #include #ifndef MPI_FILE_NULL /* MPIO may be defined in mpi.h already */ #include #endif #endif /* Include the Windows API adapter header early */ #include "H5api_adpt.h" #ifdef __cplusplus extern "C" { #endif /* Macros for enabling/disabling particular GCC warnings */ /* (see the following web-sites for more info: * http://www.dbp-consulting.com/tutorials/SuppressingGCCWarnings.html * http://gcc.gnu.org/onlinedocs/gcc/Diagnostic-Pragmas.html#Diagnostic-Pragmas */ /* These pragmas are only implemented usefully in gcc 4.6+ */ #if ((__GNUC__ * 100) + __GNUC_MINOR__) >= 406 #define H5_GCC_DIAG_JOINSTR(x, y) x y #define H5_GCC_DIAG_DO_PRAGMA(x) _Pragma(#x) #define H5_GCC_DIAG_PRAGMA(x) H5_GCC_DIAG_DO_PRAGMA(GCC diagnostic x) #define H5_GCC_DIAG_OFF(x) H5_GCC_DIAG_PRAGMA(push) H5_GCC_DIAG_PRAGMA(ignored H5_GCC_DIAG_JOINSTR("-W", x)) #define H5_GCC_DIAG_ON(x) H5_GCC_DIAG_PRAGMA(pop) #else #define H5_GCC_DIAG_OFF(x) #define H5_GCC_DIAG_ON(x) #endif /* Version numbers */ #define H5_VERS_MAJOR 1 /* For major interface/format changes */ #define H5_VERS_MINOR 13 /* For minor interface/format changes */ #define H5_VERS_RELEASE 0 /* For tweaks, bug-fixes, or development */ #define H5_VERS_SUBRELEASE "" /* For pre-releases like snap0 */ /* Empty string for real releases. */ #define H5_VERS_INFO "HDF5 library version: 1.13.0" /* Full version string */ #define H5check() H5check_version(H5_VERS_MAJOR, H5_VERS_MINOR, H5_VERS_RELEASE) /* macros for comparing the version */ #define H5_VERSION_GE(Maj, Min, Rel) \ (((H5_VERS_MAJOR == Maj) && (H5_VERS_MINOR == Min) && (H5_VERS_RELEASE >= Rel)) || \ ((H5_VERS_MAJOR == Maj) && (H5_VERS_MINOR > Min)) || (H5_VERS_MAJOR > Maj)) #define H5_VERSION_LE(Maj, Min, Rel) \ (((H5_VERS_MAJOR == Maj) && (H5_VERS_MINOR == Min) && (H5_VERS_RELEASE <= Rel)) || \ ((H5_VERS_MAJOR == Maj) && (H5_VERS_MINOR < Min)) || (H5_VERS_MAJOR < Maj)) /* * 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"); */ typedef int herr_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"); * } */ #ifdef H5_HAVE_STDBOOL_H #include #else /* H5_HAVE_STDBOOL_H */ #ifndef __cplusplus #if defined(H5_SIZEOF_BOOL) && (H5_SIZEOF_BOOL != 0) #define bool _Bool #else #define bool unsigned int #endif #define true 1 #define false 0 #endif /* __cplusplus */ #endif /* H5_HAVE_STDBOOL_H */ typedef bool hbool_t; typedef int htri_t; /* Define the ssize_t type if it not is defined */ #if H5_SIZEOF_SSIZE_T == 0 /* Undefine this size, we will re-define it in one of the sections below */ #undef H5_SIZEOF_SSIZE_T #if H5_SIZEOF_SIZE_T == H5_SIZEOF_INT typedef int ssize_t; #define H5_SIZEOF_SSIZE_T H5_SIZEOF_INT #elif H5_SIZEOF_SIZE_T == H5_SIZEOF_LONG typedef long ssize_t; #define H5_SIZEOF_SSIZE_T H5_SIZEOF_LONG #elif H5_SIZEOF_SIZE_T == H5_SIZEOF_LONG_LONG typedef long long ssize_t; #define H5_SIZEOF_SSIZE_T H5_SIZEOF_LONG_LONG #else /* Can't find matching type for ssize_t */ #error "nothing appropriate for ssize_t" #endif #endif /* int64_t type is used for creation order field for links. It may be * defined in Posix.1g, otherwise it is defined here. */ #if H5_SIZEOF_INT64_T >= 8 #elif H5_SIZEOF_INT >= 8 typedef int int64_t; #undef H5_SIZEOF_INT64_T #define H5_SIZEOF_INT64_T H5_SIZEOF_INT #elif H5_SIZEOF_LONG >= 8 typedef long int64_t; #undef H5_SIZEOF_INT64_T #define H5_SIZEOF_INT64_T H5_SIZEOF_LONG #elif H5_SIZEOF_LONG_LONG >= 8 typedef long long int64_t; #undef H5_SIZEOF_INT64_T #define H5_SIZEOF_INT64_T H5_SIZEOF_LONG_LONG #else #error "nothing appropriate for int64_t" #endif /* uint64_t type is used for fields for H5O_info_t. It may be * defined in Posix.1g, otherwise it is defined here. */ #if H5_SIZEOF_UINT64_T >= 8 #ifndef UINT64_MAX #define UINT64_MAX ((uint64_t)-1) #endif #elif H5_SIZEOF_INT >= 8 typedef unsigned uint64_t; #define UINT64_MAX UINT_MAX #undef H5_SIZEOF_UINT64_T #define H5_SIZEOF_UINT64_T H5_SIZEOF_INT #elif H5_SIZEOF_LONG >= 8 typedef unsigned long uint64_t; #define UINT64_MAX ULONG_MAX #undef H5_SIZEOF_UINT64_T #define H5_SIZEOF_UINT64_T H5_SIZEOF_LONG #elif H5_SIZEOF_LONG_LONG >= 8 typedef unsigned long long uint64_t; #define UINT64_MAX ULLONG_MAX #undef H5_SIZEOF_UINT64_T #define H5_SIZEOF_UINT64_T H5_SIZEOF_LONG_LONG #else #error "nothing appropriate for uint64_t" #endif /* * The sizes of file objects have their own types defined here, use a 64-bit * type. */ typedef uint64_t hsize_t; typedef int64_t hssize_t; #define PRIdHSIZE PRId64 #define PRIiHSIZE PRIi64 #define PRIoHSIZE PRIo64 #define PRIuHSIZE PRIu64 #define PRIxHSIZE PRIx64 #define PRIXHSIZE PRIX64 #define H5_SIZEOF_HSIZE_T H5_SIZEOF_UINT64_T #define H5_SIZEOF_HSSIZE_T H5_SIZEOF_INT64_T #define HSIZE_UNDEF UINT64_MAX /* * File addresses have their own types. */ #if H5_SIZEOF_INT >= 8 typedef unsigned haddr_t; #define HADDR_UNDEF UINT_MAX #define H5_SIZEOF_HADDR_T H5_SIZEOF_INT #ifdef H5_HAVE_PARALLEL #define HADDR_AS_MPI_TYPE MPI_UNSIGNED #endif /* H5_HAVE_PARALLEL */ #elif H5_SIZEOF_LONG >= 8 typedef unsigned long haddr_t; #define HADDR_UNDEF ULONG_MAX #define H5_SIZEOF_HADDR_T H5_SIZEOF_LONG #ifdef H5_HAVE_PARALLEL #define HADDR_AS_MPI_TYPE MPI_UNSIGNED_LONG #endif /* H5_HAVE_PARALLEL */ #elif H5_SIZEOF_LONG_LONG >= 8 typedef unsigned long long haddr_t; #define HADDR_UNDEF ULLONG_MAX #define H5_SIZEOF_HADDR_T H5_SIZEOF_LONG_LONG #ifdef H5_HAVE_PARALLEL #define HADDR_AS_MPI_TYPE MPI_LONG_LONG_INT #endif /* H5_HAVE_PARALLEL */ #else #error "nothing appropriate for haddr_t" #endif #if H5_SIZEOF_HADDR_T == H5_SIZEOF_INT #define PRIXHADDR "X" #define PRIoHADDR "o" #define PRIuHADDR "u" #define PRIxHADDR "x" #define PRIXHADDR "X" #elif H5_SIZEOF_HADDR_T == H5_SIZEOF_LONG #define PRIXHADDR "lX" #define PRIoHADDR "lo" #define PRIuHADDR "lu" #define PRIxHADDR "lx" #define PRIXHADDR "lX" #elif H5_SIZEOF_HADDR_T == H5_SIZEOF_LONG_LONG #define PRIXHADDR H5_PRINTF_LL_WIDTH "X" #define PRIoHADDR H5_PRINTF_LL_WIDTH "o" #define PRIuHADDR H5_PRINTF_LL_WIDTH "u" #define PRIxHADDR H5_PRINTF_LL_WIDTH "x" #define PRIXHADDR H5_PRINTF_LL_WIDTH "X" #else #error "nothing appropriate for PRI.HADDR" #endif #define H5_PRINTF_HADDR_FMT "%" PRIuHADDR #define HADDR_MAX (HADDR_UNDEF - 1) /* uint32_t type is used for creation order field for messages. It may be * defined in Posix.1g, otherwise it is defined here. */ #if H5_SIZEOF_UINT32_T >= 4 #elif H5_SIZEOF_SHORT >= 4 typedef short uint32_t; #undef H5_SIZEOF_UINT32_T #define H5_SIZEOF_UINT32_T H5_SIZEOF_SHORT #elif H5_SIZEOF_INT >= 4 typedef unsigned int uint32_t; #undef H5_SIZEOF_UINT32_T #define H5_SIZEOF_UINT32_T H5_SIZEOF_INT #elif H5_SIZEOF_LONG >= 4 typedef unsigned long uint32_t; #undef H5_SIZEOF_UINT32_T #define H5_SIZEOF_UINT32_T H5_SIZEOF_LONG #else #error "nothing appropriate for uint32_t" #endif /* Common iteration orders */ typedef enum { H5_ITER_UNKNOWN = -1, /* 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 */ } H5_iter_order_t; /* Iteration callback values */ /* (Actually, any positive value will cause the iterator to stop and pass back * that positive value to the function that called the iterator) */ #define H5_ITER_ERROR (-1) #define H5_ITER_CONT (0) #define H5_ITER_STOP (1) /* * The types of indices on links in groups/attributes on objects. * Primarily used for " by index" routines and for iterating over * links in groups/attributes on objects. */ typedef enum H5_index_t { H5_INDEX_UNKNOWN = -1, /* 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_index_t; /* * Storage info struct used by H5O_info_t and H5F_info_t */ typedef struct H5_ih_info_t { hsize_t index_size; /* btree and/or list */ hsize_t heap_size; } H5_ih_info_t; /* Tokens are unique and permanent identifiers that are * used to reference HDF5 objects in a container. */ /* The maximum size allowed for tokens */ #define H5O_MAX_TOKEN_SIZE (16) /* Allows for 128-bit tokens */ /* Type for object tokens */ /* (Hoisted here, since it's used by both the H5Lpublic.h and H5Opublic.h headers) */ typedef struct H5O_token_t { uint8_t __data[H5O_MAX_TOKEN_SIZE]; } H5O_token_t; /* * Allocation statistics info struct */ typedef struct H5_alloc_stats_t { unsigned long long total_alloc_bytes; /* Running count of total # of bytes allocated */ size_t curr_alloc_bytes; /* Current # of bytes allocated */ size_t peak_alloc_bytes; /* Peak # of bytes allocated */ size_t max_block_size; /* Largest block allocated */ size_t total_alloc_blocks_count; /* Running count of total # of blocks allocated */ size_t curr_alloc_blocks_count; /* Current # of blocks allocated */ size_t peak_alloc_blocks_count; /* Peak # of blocks allocated */ } H5_alloc_stats_t; /* Functions in H5.c */ H5_DLL herr_t H5open(void); H5_DLL herr_t H5close(void); H5_DLL herr_t H5dont_atexit(void); H5_DLL herr_t H5garbage_collect(void); H5_DLL 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); H5_DLL herr_t H5get_free_list_sizes(size_t *reg_size, size_t *arr_size, size_t *blk_size, size_t *fac_size); H5_DLL herr_t H5get_alloc_stats(H5_alloc_stats_t *stats); H5_DLL herr_t H5get_libversion(unsigned *majnum, unsigned *minnum, unsigned *relnum); H5_DLL herr_t H5check_version(unsigned majnum, unsigned minnum, unsigned relnum); H5_DLL herr_t H5is_library_threadsafe(hbool_t *is_ts); H5_DLL herr_t H5free_memory(void *mem); H5_DLL void * H5allocate_memory(size_t size, hbool_t clear); H5_DLL void * H5resize_memory(void *mem, size_t size); #ifdef __cplusplus } #endif #endif /* _H5public_H */