HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
H5public.h
Go to the documentation of this file.
1 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
2  * Copyright by The HDF Group. *
3  * Copyright by the Board of Trustees of the University of Illinois. *
4  * All rights reserved. *
5  * *
6  * This file is part of HDF5. The full HDF5 copyright notice, including *
7  * terms governing use, modification, and redistribution, is contained in *
8  * the files COPYING and Copyright.html. COPYING can be found at the root *
9  * of the source code distribution tree; Copyright.html can be found at the *
10  * root level of an installed copy of the electronic HDF5 document set and *
11  * is linked from the top-level documents page. It can also be found at *
12  * http://hdfgroup.org/HDF5/doc/Copyright.html. If you do not have *
13  * access to either file, you may request a copy from help@hdfgroup.org. *
14  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
15 
16 /*
17  * This file contains public declarations for the HDF5 module.
18  */
19 #ifndef _H5public_H
20 #define _H5public_H
21 
22 /* Include files for public use... */
23 /*
24  * Since H5pubconf.h is a generated header file, it is messy to try
25  * to put a #ifndef _H5pubconf_H ... #endif guard in it.
26  * HDF5 has set an internal rule that it is being included here.
27  * Source files should NOT include H5pubconf.h directly but include
28  * it via H5public.h. The #ifndef _H5public_H guard above would
29  * prevent repeated include.
30  */
31 #include "H5pubconf.h" /*from configure */
32 
33 /* API Version macro wrapper definitions */
34 #include "H5version.h"
35 
36 #ifdef H5_HAVE_FEATURES_H
37 #include <features.h> /*for setting POSIX, BSD, etc. compatibility */
38 #endif
39 #ifdef H5_HAVE_SYS_TYPES_H
40 #include <sys/types.h>
41 #endif
42 #ifdef H5_STDC_HEADERS
43 # include <limits.h> /*for H5T_NATIVE_CHAR defn in H5Tpublic.h */
44 #endif
45 #ifndef __cplusplus
46 # ifdef H5_HAVE_STDINT_H
47 # include <stdint.h> /*for C9x types */
48 # endif
49 #else
50 # ifdef H5_HAVE_STDINT_H_CXX
51 # include <stdint.h> /*for C9x types when include from C++ */
52 # endif
53 #endif
54 #ifdef H5_HAVE_INTTYPES_H
55 # include <inttypes.h> /* For uint64_t on some platforms */
56 #endif
57 #ifdef H5_HAVE_STDDEF_H
58 # include <stddef.h>
59 #endif
60 #ifdef H5_HAVE_PARALLEL
61 # include <mpi.h>
62 #ifndef MPI_FILE_NULL /*MPIO may be defined in mpi.h already */
63 # include <mpio.h>
64 #endif
65 #endif
66 
67 
68 /* Include the Windows API adapter header early */
69 #include "H5api_adpt.h"
70 
71 #ifdef __cplusplus
72 extern "C" {
73 #endif
74 
75 /* Version numbers */
76 #define H5_VERS_MAJOR 1 /* For major interface/format changes */
77 #define H5_VERS_MINOR 8 /* For minor interface/format changes */
78 #define H5_VERS_RELEASE 11 /* For tweaks, bug-fixes, or development */
79 #define H5_VERS_SUBRELEASE "" /* For pre-releases like snap0 */
80  /* Empty string for real releases. */
81 #define H5_VERS_INFO "HDF5 library version: 1.8.11" /* Full version string */
82 
83 #define H5check() H5check_version(H5_VERS_MAJOR,H5_VERS_MINOR, \
84  H5_VERS_RELEASE)
85 
86 /* macros for comparing the version */
87 #define H5_VERSION_GE(Maj,Min,Rel) \
88  (((H5_VERS_MAJOR==Maj) && (H5_VERS_MINOR==Min) && (H5_VERS_RELEASE>=Rel)) || \
89  ((H5_VERS_MAJOR==Maj) && (H5_VERS_MINOR>Min)) || \
90  (H5_VERS_MAJOR>Maj))
91 
92 #define H5_VERSION_LE(Maj,Min,Rel) \
93  (((H5_VERS_MAJOR==Maj) && (H5_VERS_MINOR==Min) && (H5_VERS_RELEASE<=Rel)) || \
94  ((H5_VERS_MAJOR==Maj) && (H5_VERS_MINOR<Min)) || \
95  (H5_VERS_MAJOR<Maj))
96 
97 /*
98  * Status return values. Failed integer functions in HDF5 result almost
99  * always in a negative value (unsigned failing functions sometimes return
100  * zero for failure) while successfull return is non-negative (often zero).
101  * The negative failure value is most commonly -1, but don't bet on it. The
102  * proper way to detect failure is something like:
103  *
104  * if((dset = H5Dopen2(file, name)) < 0)
105  * fprintf(stderr, "unable to open the requested dataset\n");
106  */
107 typedef int herr_t;
108 
109 
110 /*
111  * Boolean type. Successful return values are zero (false) or positive
112  * (true). The typical true value is 1 but don't bet on it. Boolean
113  * functions cannot fail. Functions that return `htri_t' however return zero
114  * (false), positive (true), or negative (failure). The proper way to test
115  * for truth from a htri_t function is:
116  *
117  * if ((retval = H5Tcommitted(type))>0) {
118  * printf("data type is committed\n");
119  * } else if (!retval) {
120  * printf("data type is not committed\n");
121  * } else {
122  * printf("error determining whether data type is committed\n");
123  * }
124  */
125 typedef unsigned int hbool_t;
126 typedef int htri_t;
127 
128 /* Define the ssize_t type if it not is defined */
129 #if H5_SIZEOF_SSIZE_T==0
130 /* Undefine this size, we will re-define it in one of the sections below */
131 #undef H5_SIZEOF_SSIZE_T
132 #if H5_SIZEOF_SIZE_T==H5_SIZEOF_INT
133 typedef int ssize_t;
134 # define H5_SIZEOF_SSIZE_T H5_SIZEOF_INT
135 #elif H5_SIZEOF_SIZE_T==H5_SIZEOF_LONG
136 typedef long ssize_t;
137 # define H5_SIZEOF_SSIZE_T H5_SIZEOF_LONG
138 #elif H5_SIZEOF_SIZE_T==H5_SIZEOF_LONG_LONG
139 typedef long long ssize_t;
140 # define H5_SIZEOF_SSIZE_T H5_SIZEOF_LONG_LONG
141 #else /* Can't find matching type for ssize_t */
142 # error "nothing appropriate for ssize_t"
143 #endif
144 #endif
145 
146 /*
147  * The sizes of file objects have their own types defined here, use a 64-bit
148  * type.
149  */
150 #if H5_SIZEOF_LONG_LONG >= 8
151 typedef unsigned long long hsize_t;
152 typedef signed long long hssize_t;
153 # define H5_SIZEOF_HSIZE_T H5_SIZEOF_LONG_LONG
154 # define H5_SIZEOF_HSSIZE_T H5_SIZEOF_LONG_LONG
155 #else
156 # error "nothing appropriate for hsize_t"
157 #endif
158 
159 /*
160  * File addresses have their own types.
161  */
162 #if H5_SIZEOF_INT64_T>=8
163  typedef uint64_t haddr_t;
164 # define HADDR_UNDEF ((haddr_t)(int64_t)(-1))
165 # define H5_SIZEOF_HADDR_T H5_SIZEOF_INT64_T
166 # ifdef H5_HAVE_PARALLEL
167 # define HADDR_AS_MPI_TYPE MPI_LONG_LONG_INT
168 # endif /* H5_HAVE_PARALLEL */
169 #elif H5_SIZEOF_INT>=8
170  typedef unsigned haddr_t;
171 # define HADDR_UNDEF ((haddr_t)(-1))
172 # define H5_SIZEOF_HADDR_T H5_SIZEOF_INT
173 # ifdef H5_HAVE_PARALLEL
174 # define HADDR_AS_MPI_TYPE MPI_UNSIGNED
175 # endif /* H5_HAVE_PARALLEL */
176 #elif H5_SIZEOF_LONG>=8
177  typedef unsigned long haddr_t;
178 # define HADDR_UNDEF ((haddr_t)(long)(-1))
179 # define H5_SIZEOF_HADDR_T H5_SIZEOF_LONG
180 # ifdef H5_HAVE_PARALLEL
181 # define HADDR_AS_MPI_TYPE MPI_UNSIGNED_LONG
182 # endif /* H5_HAVE_PARALLEL */
183 #elif H5_SIZEOF_LONG_LONG>=8
184  typedef unsigned long long haddr_t;
185 # define HADDR_UNDEF ((haddr_t)(long long)(-1))
186 # define H5_SIZEOF_HADDR_T H5_SIZEOF_LONG_LONG
187 # ifdef H5_HAVE_PARALLEL
188 # define HADDR_AS_MPI_TYPE MPI_LONG_LONG_INT
189 # endif /* H5_HAVE_PARALLEL */
190 #else
191 # error "nothing appropriate for haddr_t"
192 #endif
193 #if H5_SIZEOF_HADDR_T ==H5_SIZEOF_INT
194 # define H5_PRINTF_HADDR_FMT "%u"
195 #elif H5_SIZEOF_HADDR_T ==H5_SIZEOF_LONG
196 # define H5_PRINTF_HADDR_FMT "%lu"
197 #elif H5_SIZEOF_HADDR_T ==H5_SIZEOF_LONG_LONG
198 # define H5_PRINTF_HADDR_FMT "%" H5_PRINTF_LL_WIDTH "u"
199 #else
200 # error "nothing appropriate for H5_PRINTF_HADDR_FMT"
201 #endif
202 #define HADDR_MAX (HADDR_UNDEF-1)
203 
204 /* uint32_t type is used for creation order field for messages. It may be
205  * defined in Posix.1g, otherwise it is defined here.
206  */
207 #if H5_SIZEOF_UINT32_T>=4
208 #elif H5_SIZEOF_SHORT>=4
209  typedef short uint32_t;
210 # undef H5_SIZEOF_UINT32_T
211 # define H5_SIZEOF_UINT32_T H5_SIZEOF_SHORT
212 #elif H5_SIZEOF_INT>=4
213  typedef unsigned int uint32_t;
214 # undef H5_SIZEOF_UINT32_T
215 # define H5_SIZEOF_UINT32_T H5_SIZEOF_INT
216 #elif H5_SIZEOF_LONG>=4
217  typedef unsigned long uint32_t;
218 # undef H5_SIZEOF_UINT32_T
219 # define H5_SIZEOF_UINT32_T H5_SIZEOF_LONG
220 #else
221 # error "nothing appropriate for uint32_t"
222 #endif
223 
224 /* int64_t type is used for creation order field for links. It may be
225  * defined in Posix.1g, otherwise it is defined here.
226  */
227 #if H5_SIZEOF_INT64_T>=8
228 #elif H5_SIZEOF_INT>=8
229  typedef int int64_t;
230 # undef H5_SIZEOF_INT64_T
231 # define H5_SIZEOF_INT64_T H5_SIZEOF_INT
232 #elif H5_SIZEOF_LONG>=8
233  typedef long int64_t;
234 # undef H5_SIZEOF_INT64_T
235 # define H5_SIZEOF_INT64_T H5_SIZEOF_LONG
236 #elif H5_SIZEOF_LONG_LONG>=8
237  typedef long long int64_t;
238 # undef H5_SIZEOF_INT64_T
239 # define H5_SIZEOF_INT64_T H5_SIZEOF_LONG_LONG
240 #else
241 # error "nothing appropriate for int64_t"
242 #endif
243 
244 /* uint64_t type is used for fields for H5O_info_t. It may be
245  * defined in Posix.1g, otherwise it is defined here.
246  */
247 #if H5_SIZEOF_UINT64_T>=8
248 #elif H5_SIZEOF_INT>=8
249  typedef unsigned uint64_t;
250 # undef H5_SIZEOF_UINT64_T
251 # define H5_SIZEOF_UINT64_T H5_SIZEOF_INT
252 #elif H5_SIZEOF_LONG>=8
253  typedef unsigned long uint64_t;
254 # undef H5_SIZEOF_UINT64_T
255 # define H5_SIZEOF_UINT64_T H5_SIZEOF_LONG
256 #elif H5_SIZEOF_LONG_LONG>=8
257  typedef unsigned long long uint64_t;
258 # undef H5_SIZEOF_UINT64_T
259 # define H5_SIZEOF_UINT64_T H5_SIZEOF_LONG_LONG
260 #else
261 # error "nothing appropriate for uint64_t"
262 #endif
263 
264 /* Default value for all property list classes */
265 #define H5P_DEFAULT 0
266 
267 /* Common iteration orders */
268 typedef enum {
269  H5_ITER_UNKNOWN = -1, /* Unknown order */
270  H5_ITER_INC, /* Increasing order */
271  H5_ITER_DEC, /* Decreasing order */
272  H5_ITER_NATIVE, /* No particular order, whatever is fastest */
273  H5_ITER_N /* Number of iteration orders */
275 
276 /* Iteration callback values */
277 /* (Actually, any postive value will cause the iterator to stop and pass back
278  * that positive value to the function that called the iterator)
279  */
280 #define H5_ITER_ERROR (-1)
281 #define H5_ITER_CONT (0)
282 #define H5_ITER_STOP (1)
283 
284 /*
285  * The types of indices on links in groups/attributes on objects.
286  * Primarily used for "<do> <foo> by index" routines and for iterating over
287  * links in groups/attributes on objects.
288  */
289 typedef enum H5_index_t {
290  H5_INDEX_UNKNOWN = -1, /* Unknown index type */
291  H5_INDEX_NAME, /* Index on names */
292  H5_INDEX_CRT_ORDER, /* Index on creation order */
293  H5_INDEX_N /* Number of indices defined */
294 } H5_index_t;
295 
296 /*
297  * Storage info struct used by H5O_info_t and H5F_info_t
298  */
299 typedef struct H5_ih_info_t {
300  hsize_t index_size; /* btree and/or list */
301  hsize_t heap_size;
302 } H5_ih_info_t;
303 
304 /* Functions in H5.c */
305 H5_DLL herr_t H5open(void);
306 H5_DLL herr_t H5close(void);
307 H5_DLL herr_t H5dont_atexit(void);
308 H5_DLL herr_t H5garbage_collect(void);
309 H5_DLL herr_t H5set_free_list_limits (int reg_global_lim, int reg_list_lim,
310  int arr_global_lim, int arr_list_lim, int blk_global_lim,
311  int blk_list_lim);
312 H5_DLL herr_t H5get_libversion(unsigned *majnum, unsigned *minnum,
313  unsigned *relnum);
314 H5_DLL herr_t H5check_version(unsigned majnum, unsigned minnum,
315  unsigned relnum);
316 
317 #ifdef __cplusplus
318 }
319 #endif
320 #endif
321 
unsigned int hbool_t
Definition: H5public.h:125
H5_index_t
Definition: H5public.h:289
#define H5_DLL
Definition: H5api_adpt.h:406
struct H5_ih_info_t H5_ih_info_t
int herr_t
Definition: H5public.h:107
unsigned long long hsize_t
Definition: H5public.h:151
H5_DLL herr_t H5check_version(unsigned majnum, unsigned minnum, unsigned relnum)
uint64_t haddr_t
Definition: H5public.h:163
H5_DLL herr_t H5get_libversion(unsigned *majnum, unsigned *minnum, unsigned *relnum)
H5_DLL herr_t H5dont_atexit(void)
H5_DLL herr_t H5garbage_collect(void)
hsize_t index_size
Definition: H5public.h:300
H5_iter_order_t
Definition: H5public.h:268
H5_DLL herr_t H5open(void)
signed long long hssize_t
Definition: H5public.h:152
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)
hsize_t heap_size
Definition: H5public.h:301
int htri_t
Definition: H5public.h:126
H5_DLL herr_t H5close(void)