H5public.h

00001 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
00002  * Copyright by The HDF Group.                                               *
00003  * Copyright by the Board of Trustees of the University of Illinois.         *
00004  * All rights reserved.                                                      *
00005  *                                                                           *
00006  * This file is part of HDF5.  The full HDF5 copyright notice, including     *
00007  * terms governing use, modification, and redistribution, is contained in    *
00008  * the files COPYING and Copyright.html.  COPYING can be found at the root   *
00009  * of the source code distribution tree; Copyright.html can be found at the  *
00010  * root level of an installed copy of the electronic HDF5 document set and   *
00011  * is linked from the top-level documents page.  It can also be found at     *
00012  * http://hdfgroup.org/HDF5/doc/Copyright.html.  If you do not have          *
00013  * access to either file, you may request a copy from help@hdfgroup.org.     *
00014  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
00015 
00016 /*
00017  * This file contains public declarations for the HDF5 module.
00018  */
00019 #ifndef _H5public_H
00020 #define _H5public_H
00021 
00022 /* Include files for public use... */
00023 /*
00024  * Since H5pubconf.h is a generated header file, it is messy to try
00025  * to put a #ifndef _H5pubconf_H ... #endif guard in it.
00026  * HDF5 has set an internal rule that it is being included here.
00027  * Source files should NOT include H5pubconf.h directly but include
00028  * it via H5public.h.  The #ifndef _H5public_H guard above would
00029  * prevent repeated include.
00030  */
00031 #include "H5pubconf.h"          /*from configure                             */
00032 
00033 /* API Version macro wrapper definitions */
00034 #include "H5version.h"
00035 
00036 #ifdef H5_HAVE_FEATURES_H
00037 #include <features.h>           /*for setting POSIX, BSD, etc. compatibility */
00038 #endif
00039 #ifdef H5_HAVE_SYS_TYPES_H
00040 #include <sys/types.h>
00041 #endif
00042 #ifdef H5_STDC_HEADERS
00043 #   include <limits.h>          /*for H5T_NATIVE_CHAR defn in H5Tpublic.h    */
00044 #endif
00045 #ifndef __cplusplus
00046 #ifdef H5_HAVE_STDINT_H
00047 #   include <stdint.h>          /*for C9x types                              */
00048 #endif
00049 #endif
00050 #ifdef H5_HAVE_INTTYPES_H
00051 #   include <inttypes.h>        /* For uint64_t on some platforms            */
00052 #endif
00053 #ifdef H5_HAVE_STDDEF_H
00054 #   include <stddef.h>
00055 #endif
00056 #ifdef H5_HAVE_PARALLEL
00057 #   include <mpi.h>
00058 #ifndef MPI_FILE_NULL           /*MPIO may be defined in mpi.h already       */
00059 #   include <mpio.h>
00060 #endif
00061 #endif
00062 
00063 
00064 /* Include the Windows API adapter header early */
00065 #include "H5api_adpt.h"
00066 
00067 #ifdef __cplusplus
00068 extern "C" {
00069 #endif
00070 
00071 /* Version numbers */
00072 #define H5_VERS_MAJOR   1       /* For major interface/format changes        */
00073 #define H5_VERS_MINOR   8       /* For minor interface/format changes        */
00074 #define H5_VERS_RELEASE 4       /* For tweaks, bug-fixes, or development     */
00075 #define H5_VERS_SUBRELEASE "snap17"     /* For pre-releases like snap0       */
00076                                 /* Empty string for real releases.           */
00077 #define H5_VERS_INFO    "HDF5 library version: 1.8.4-snap17"      /* Full version string */
00078 
00079 #define H5check()       H5check_version(H5_VERS_MAJOR,H5_VERS_MINOR,          \
00080                                         H5_VERS_RELEASE)
00081 
00082 /*
00083  * Status return values.  Failed integer functions in HDF5 result almost
00084  * always in a negative value (unsigned failing functions sometimes return
00085  * zero for failure) while successfull return is non-negative (often zero).
00086  * The negative failure value is most commonly -1, but don't bet on it.  The
00087  * proper way to detect failure is something like:
00088  *
00089  *      if((dset = H5Dopen2(file, name)) < 0)
00090  *          fprintf(stderr, "unable to open the requested dataset\n");
00091  */
00092 typedef int herr_t;
00093 
00094 
00095 /*
00096  * Boolean type.  Successful return values are zero (false) or positive
00097  * (true). The typical true value is 1 but don't bet on it.  Boolean
00098  * functions cannot fail.  Functions that return `htri_t' however return zero
00099  * (false), positive (true), or negative (failure). The proper way to test
00100  * for truth from a htri_t function is:
00101  *
00102  *      if ((retval = H5Tcommitted(type))>0) {
00103  *          printf("data type is committed\n");
00104  *      } else if (!retval) {
00105  *          printf("data type is not committed\n");
00106  *      } else {
00107  *          printf("error determining whether data type is committed\n");
00108  *      }
00109  */
00110 typedef unsigned int hbool_t;
00111 typedef int htri_t;
00112 
00113 /* Define the ssize_t type if it not is defined */
00114 #if H5_SIZEOF_SSIZE_T==0
00115 /* Undefine this size, we will re-define it in one of the sections below */
00116 #undef H5_SIZEOF_SSIZE_T
00117 #if H5_SIZEOF_SIZE_T==H5_SIZEOF_INT
00118 typedef int ssize_t;
00119 #       define H5_SIZEOF_SSIZE_T H5_SIZEOF_INT
00120 #elif H5_SIZEOF_SIZE_T==H5_SIZEOF_LONG
00121 typedef long ssize_t;
00122 #       define H5_SIZEOF_SSIZE_T H5_SIZEOF_LONG
00123 #elif H5_SIZEOF_SIZE_T==H5_SIZEOF_LONG_LONG
00124 typedef long long ssize_t;
00125 #       define H5_SIZEOF_SSIZE_T H5_SIZEOF_LONG_LONG
00126 #else /* Can't find matching type for ssize_t */
00127 #   error "nothing appropriate for ssize_t"
00128 #endif
00129 #endif
00130 
00131 /*
00132  * The sizes of file objects have their own types defined here, use a 64-bit
00133  * type.
00134  */
00135 #if H5_SIZEOF_LONG_LONG >= 8
00136 typedef unsigned long long      hsize_t;
00137 typedef signed long long        hssize_t;
00138 #       define H5_SIZEOF_HSIZE_T H5_SIZEOF_LONG_LONG
00139 #       define H5_SIZEOF_HSSIZE_T H5_SIZEOF_LONG_LONG
00140 #else
00141 #   error "nothing appropriate for hsize_t"
00142 #endif
00143 
00144 /*
00145  * File addresses have their own types.
00146  */
00147 #if H5_SIZEOF_INT64_T>=8
00148     typedef uint64_t                haddr_t;
00149 #   define HADDR_UNDEF              ((haddr_t)(int64_t)(-1))
00150 #   define H5_SIZEOF_HADDR_T        H5_SIZEOF_INT64_T
00151 #   ifdef H5_HAVE_PARALLEL
00152 #       define HADDR_AS_MPI_TYPE    MPI_LONG_LONG_INT
00153 #   endif  /* H5_HAVE_PARALLEL */
00154 #elif H5_SIZEOF_INT>=8
00155     typedef unsigned                haddr_t;
00156 #   define HADDR_UNDEF              ((haddr_t)(-1))
00157 #   define H5_SIZEOF_HADDR_T        H5_SIZEOF_INT
00158 #   ifdef H5_HAVE_PARALLEL
00159 #       define HADDR_AS_MPI_TYPE    MPI_UNSIGNED
00160 #   endif  /* H5_HAVE_PARALLEL */
00161 #elif H5_SIZEOF_LONG>=8
00162     typedef unsigned long           haddr_t;
00163 #   define HADDR_UNDEF              ((haddr_t)(long)(-1))
00164 #   define H5_SIZEOF_HADDR_T        H5_SIZEOF_LONG
00165 #   ifdef H5_HAVE_PARALLEL
00166 #       define HADDR_AS_MPI_TYPE    MPI_UNSIGNED_LONG
00167 #   endif  /* H5_HAVE_PARALLEL */
00168 #elif H5_SIZEOF_LONG_LONG>=8
00169     typedef unsigned long long      haddr_t;
00170 #   define HADDR_UNDEF              ((haddr_t)(long long)(-1))
00171 #   define H5_SIZEOF_HADDR_T        H5_SIZEOF_LONG_LONG
00172 #   ifdef H5_HAVE_PARALLEL
00173 #       define HADDR_AS_MPI_TYPE    MPI_LONG_LONG_INT
00174 #   endif  /* H5_HAVE_PARALLEL */
00175 #else
00176 #   error "nothing appropriate for haddr_t"
00177 #endif
00178 #if H5_SIZEOF_HADDR_T ==H5_SIZEOF_INT
00179 #   define H5_PRINTF_HADDR_FMT  "%u"
00180 #elif H5_SIZEOF_HADDR_T ==H5_SIZEOF_LONG
00181 #   define H5_PRINTF_HADDR_FMT  "%lu"
00182 #elif H5_SIZEOF_HADDR_T ==H5_SIZEOF_LONG_LONG
00183 #   define H5_PRINTF_HADDR_FMT  "%"H5_PRINTF_LL_WIDTH"u"
00184 #else
00185 #   error "nothing appropriate for H5_PRINTF_HADDR_FMT"
00186 #endif
00187 #define HADDR_MAX               (HADDR_UNDEF-1)
00188 
00189 /* uint32_t type is used for creation order field for messages.  It may be
00190  * defined in Posix.1g, otherwise it is defined here.
00191  */
00192 #if H5_SIZEOF_UINT32_T>=4
00193 #elif H5_SIZEOF_SHORT>=4
00194     typedef short uint32_t;
00195 #   undef H5_SIZEOF_UINT32_T
00196 #   define H5_SIZEOF_UINT32_T H5_SIZEOF_SHORT
00197 #elif H5_SIZEOF_INT>=4
00198     typedef unsigned int uint32_t;
00199 #   undef H5_SIZEOF_UINT32_T
00200 #   define H5_SIZEOF_UINT32_T H5_SIZEOF_INT
00201 #elif H5_SIZEOF_LONG>=4
00202     typedef unsigned long uint32_t;
00203 #   undef H5_SIZEOF_UINT32_T
00204 #   define H5_SIZEOF_UINT32_T H5_SIZEOF_LONG
00205 #else
00206 #   error "nothing appropriate for uint32_t"
00207 #endif
00208 
00209 /* int64_t type is used for creation order field for links.  It may be
00210  * defined in Posix.1g, otherwise it is defined here.
00211  */
00212 #if H5_SIZEOF_INT64_T>=8
00213 #elif H5_SIZEOF_INT>=8
00214     typedef int int64_t;
00215 #   undef H5_SIZEOF_INT64_T
00216 #   define H5_SIZEOF_INT64_T H5_SIZEOF_INT
00217 #elif H5_SIZEOF_LONG>=8
00218     typedef long int64_t;
00219 #   undef H5_SIZEOF_INT64_T
00220 #   define H5_SIZEOF_INT64_T H5_SIZEOF_LONG
00221 #elif H5_SIZEOF_LONG_LONG>=8
00222     typedef long long int64_t;
00223 #   undef H5_SIZEOF_INT64_T
00224 #   define H5_SIZEOF_INT64_T H5_SIZEOF_LONG_LONG
00225 #else
00226 #   error "nothing appropriate for int64_t"
00227 #endif
00228 
00229 /* uint64_t type is used for fields for H5O_info_t.  It may be
00230  * defined in Posix.1g, otherwise it is defined here.
00231  */
00232 #if H5_SIZEOF_UINT64_T>=8
00233 #elif H5_SIZEOF_INT>=8
00234     typedef unsigned uint64_t;
00235 #   undef H5_SIZEOF_UINT64_T
00236 #   define H5_SIZEOF_UINT64_T H5_SIZEOF_INT
00237 #elif H5_SIZEOF_LONG>=8
00238     typedef unsigned long uint64_t;
00239 #   undef H5_SIZEOF_UINT64_T
00240 #   define H5_SIZEOF_UINT64_T H5_SIZEOF_LONG
00241 #elif H5_SIZEOF_LONG_LONG>=8
00242     typedef unsigned long long uint64_t;
00243 #   undef H5_SIZEOF_UINT64_T
00244 #   define H5_SIZEOF_UINT64_T H5_SIZEOF_LONG_LONG
00245 #else
00246 #   error "nothing appropriate for uint64_t"
00247 #endif
00248 
00249 /* Default value for all property list classes */
00250 #define H5P_DEFAULT     0
00251 
00252 /* Common iteration orders */
00253 typedef enum {
00254     H5_ITER_UNKNOWN = -1,       /* Unknown order */
00255     H5_ITER_INC,                /* Increasing order */
00256     H5_ITER_DEC,                /* Decreasing order */
00257     H5_ITER_NATIVE,             /* No particular order, whatever is fastest */
00258     H5_ITER_N                   /* Number of iteration orders */
00259 } H5_iter_order_t;
00260 
00261 /* Iteration callback values */
00262 /* (Actually, any postive value will cause the iterator to stop and pass back
00263  *      that positive value to the function that called the iterator)
00264  */
00265 #define H5_ITER_ERROR   (-1)
00266 #define H5_ITER_CONT    (0)
00267 #define H5_ITER_STOP    (1)
00268 
00269 /*
00270  * The types of indices on links in groups/attributes on objects.
00271  * Primarily used for "<do> <foo> by index" routines and for iterating over
00272  * links in groups/attributes on objects.
00273  */
00274 typedef enum H5_index_t {
00275     H5_INDEX_UNKNOWN = -1,      /* Unknown index type                   */
00276     H5_INDEX_NAME,              /* Index on names                       */
00277     H5_INDEX_CRT_ORDER,         /* Index on creation order              */
00278     H5_INDEX_N                  /* Number of indices defined            */
00279 } H5_index_t;
00280 
00281 /*
00282  * Storage info struct used by H5O_info_t and H5F_info_t
00283  */
00284 typedef struct H5_ih_info_t {
00285     hsize_t     index_size;     /* btree and/or list */
00286     hsize_t     heap_size;
00287 } H5_ih_info_t;
00288 
00289 /* Functions in H5.c */
00290 H5_DLL herr_t H5open(void);
00291 H5_DLL herr_t H5close(void);
00292 H5_DLL herr_t H5dont_atexit(void);
00293 H5_DLL herr_t H5garbage_collect(void);
00294 H5_DLL herr_t H5set_free_list_limits (int reg_global_lim, int reg_list_lim,
00295                 int arr_global_lim, int arr_list_lim, int blk_global_lim,
00296                 int blk_list_lim);
00297 H5_DLL herr_t H5get_libversion(unsigned *majnum, unsigned *minnum,
00298                                 unsigned *relnum);
00299 H5_DLL herr_t H5check_version(unsigned majnum, unsigned minnum,
00300                                unsigned relnum);
00301 
00302 #ifdef __cplusplus
00303 }
00304 #endif
00305 #endif
00306