summaryrefslogtreecommitdiffstats
path: root/src/H5public.h
blob: 5216906516aa5154b115494ea24ea2b0993d072a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * 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 <features.h>           /* For setting POSIX, BSD, etc. compatibility */
#endif
#ifdef H5_HAVE_SYS_TYPES_H
#include <sys/types.h>
#endif
#ifdef H5_STDC_HEADERS
#   include <limits.h>          /* For H5T_NATIVE_CHAR defn in H5Tpublic.h  */
#   include <stdarg.h>          /* For variadic functions in H5VLpublic.h   */
#endif
#ifndef __cplusplus
# ifdef H5_HAVE_STDINT_H
#   include <stdint.h>          /* For C9x types */
# endif
#else
# ifdef H5_HAVE_STDINT_H_CXX
#   include <stdint.h>          /* For C9x types (when included from C++) */
# endif
#endif
#ifdef H5_HAVE_INTTYPES_H
#   include <inttypes.h>        /* C99/POSIX.1 header for uint64_t, PRIu64 */
#endif
#ifdef H5_HAVE_STDDEF_H
#   include <stddef.h>
#endif
#ifdef H5_HAVE_PARALLEL
/* Don't link against MPI C++ bindings */
#   define MPICH_SKIP_MPICXX 1
#   define OMPI_SKIP_MPICXX 1
#   include <mpi.h>
#ifndef MPI_FILE_NULL           /* MPIO may be defined in mpi.h already */
#   include <mpio.h>
#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 <stdbool.h>
#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 "<do> <foo> 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 */