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
|
<HTML>
<HEAD><TITLE>
HDF5 Naming Scheme
</TITLE> </HEAD>
<BODY bgcolor="#ffffff">
<!--
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* 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 files COPYING and Copyright.html. COPYING can be found at the root *
* of the source code distribution tree; Copyright.html can be found at the *
* root level of an installed copy of the electronic HDF5 document set and *
* is linked from the top-level documents page. It can also be found at *
* http://hdfgroup.org/HDF5/doc/Copyright.html. If you do not have *
* access to either file, you may request a copy from help@hdfgroup.org. *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
-->
<H1>
<FONT color="#c80028"
<I> <B> <CENTER> HDF5 Naming Scheme for </CENTER> </B> </I> </H1>
</FONT>
<P>
<UL>
<LI> <A HREF = "#01"><I> FILES </I> </A>
<LI> <A HREF = "#02"><I> PACKAGES </I> </A>
<LI> <A HREF = "#03"><I> PUBLIC vs PRIVATE </I> </A>
<LI> <A HREF = "#04"><I> INTEGRAL TYPES </I> </A>
<LI> <A HREF = "#05"><I> OTHER TYPES </I> </A>
<LI> <A HREF = "#06"><I> GLOBAL VARIABLES </I> </A>
<LI> <A HREF = "#07"><I> MACROS, PREPROCESSOR CONSTANTS, AND ENUM MEMEBERs </I> </A>
</UL>
<P>
<center>
Authors:
<I>Quincey Koziol</I> and
<I>Robb Matzke </I>
</center>
<UL>
<FONT color="#c80028"
<LI> <A NAME="01"> <B> <I> FILES </I> </B> </A>
</FONT>
<UL>
<LI> Source files are named according to the package they contain (see
below). All files will begin with `H5' so we can stuff our
object files into someone else's library and not worry about file
name conflicts.
<P>For Example:
<i><b>
<dd> H5.c -- "Generic" library functions
<br>
<dd> H5B.c -- B-link tree functions
</i></b>
<p>
<LI> If a package is in more than one file, then another name is tacked
on. It's all lower case with no underscores or hyphens.
<P>For Example:
<i><b>
<dd> H5F.c -- the file for this package
<br>
<dd> H5Fstdio.c -- stdio functions (just an example)
<br>
<dd> H5Ffcntl.c -- fcntl functions (just an example)
</i></b>
<p>
<LI> Each package file has a header file of API stuff (unless there is
no API component to the package)
<P>For Example:
<i><b>
<dd> H5F.h -- things an application would see. </i> </b>
<P>
and a header file of private stuff
<i><b>
<p>
<dd> H5Fprivate.h -- things an application wouldn't see. The
private header includes the public header.
</i></b>
<p>
and a header for private prototypes
<i><b>
<p>
<dd> H5Fproto.h -- prototypes for internal functions.
</i></b>
<P>
By splitting the prototypes into separate include files we don't
have to recompile everything when just one function prototype
changes.
<LI> The main API header file is `hdf5.h' and it includes each of the
public header files but none of the private header files. Or the
application can include just the public header files it needs.
<LI> There is no main private or prototype header file because it
prevents make from being efficient. Instead, each source file
includes only the private header and prototype files it needs
(first all the private headers, then all the private prototypes).
<LI> Header files should include everything they need and nothing more.
</UL>
<P>
<FONT color="#c80028"
<LI> <A NAME="02"> <B> <I> PACKAGES </I> </B> </A>
</FONT>
<P>
Names exported beyond function scope begin with `H5' followed by zero,
one, or two upper-case letters that describe the class of object.
This prefix is the package name. The implementation of packages
doesn't necessarily have to map 1:1 to the source files.
<P>
<i><b>
<dd> H5 -- library functions
<br>
<dd> H5A -- atoms
<br>
<dd> H5AC -- cache
<br>
<dd> H5B -- B-link trees
<br>
<dd> H5D -- datasets
<br>
<dd> H5E -- error handling
<br>
<dd> H5F -- files
<br>
<dd> H5G -- groups
<br>
<dd> H5M -- meta data
<br>
<dd> H5MM -- core memory management
<br>
<dd> H5MF -- file memory management
<br>
<dd> H5O -- object headers
<br>
<dd> H5P -- Property Lists
<br>
<dd> H5S -- dataspaces
<br>
<dd> H5R -- relationships
<br>
<dd> H5T -- datatype
</i></b>
<p>
Each package implements a single main class of object (e.g., the H5B
package implements B-link trees). The main data type of a package is
the package name followed by `_t'.
<p>
<i><b>
<dd> H5F_t -- HDF5 file type
<br>
<dd> H5B_t -- B-link tree data type
</i></b>
<p>
Not all packages implement a data type (H5, H5MF) and some
packages provide access to a preexisting data type (H5MM, H5S).
<p>
<FONT color="#c80028"
<LI> <A NAME="03"> <B> <I> PUBLIC vs PRIVATE </I> </B> </A>
</FONT>
<p>
If the symbol is for internal use only, then the package name is
followed by an underscore and the rest of the name. Otherwise, the
symbol is part of the API and there is no underscore between the
package name and the rest of the name.
<p>
<i><b>
<dd> H5Fopen -- an API function.
<br>
<dd> H5B_find -- an internal function.
</i></b>
<p>
For functions, this is important because the API functions never pass
pointers around (they use atoms instead for hiding the implementation)
and they perform stringent checks on their arguments. Internal
unctions, on the other hand, check arguments with assert().
<p>
Data types like H5B_t carry no information about whether the type is
public or private since it doesn't matter.
<p>
<FONT color="#c80028"
<LI> <A NAME="04"> <B> <I> INTEGRAL TYPES </I> </B> </A>
</FONT>
<p>
Integral fixed-point type names are an optional `u' followed by `int'
followed by the size in bits (8, 16,
32, or 64). There is no trailing `_t' because these are common
enough and follow their own naming convention.
<p>
<pre><H4>
<dd> hbool_t -- boolean values (BTRUE, BFALSE, BFAIL)
<br>
<dd> int8 -- signed 8-bit integers
<br>
<dd> uint8 -- unsigned 8-bit integers
<br>
<dd> int16 -- signed 16-bit integers
<br>
<dd> uint16 -- unsigned 16-bit integers
<br>
<dd> int32 -- signed 32-bit integers
<br>
<dd> uint32 -- unsigned 32-bit integers
<br>
<dd> int64 -- signed 64-bit integers
<br>
<dd> uint64 -- unsigned 64-bit integers
<br>
<dd> intn -- "native" integers
<br>
<dd> uintn -- "native" unsigned integers
</pre></H4>
<p>
<FONT color="#c80028"
<LI> <A NAME="05"> <B> <I> OTHER TYPES </I> </B> </A>
</FONT>
<p>
Other data types are always followed by `_t'.
<p>
<pre><H4>
<dd> H5B_key_t-- additional data type used by H5B package.
</pre></H4>
<p>
However, if the name is so common that it's used almost everywhere,
then we make an alias for it by removing the package name and leading
underscore and replacing it with an `h' (the main datatype for a
package already has a short enough name, so we don't have aliases for
them).
<P>
<pre><H4>
<dd> typedef H5E_err_t herr_t;
</pre> </H4>
<p>
<FONT color="#c80028"
<LI> <A NAME="06"> <B> <I> GLOBAL VARIABLES </I> </B> </A>
</FONT>
<p>
Global variables include the package name and end with `_g'.
<p>
<pre><H4>
<dd> H5AC_methods_g -- global variable in the H5AC package.
</pre> </H4>
<p>
<FONT color="#c80028"
<LI> <A NAME="07">
<I> <B>
MACROS, PREPROCESSOR CONSTANTS, AND ENUM MEMBERS
</I> </B> </A>
</FONT>
<p>
Same rules as other symbols except the name is all upper case. There
are a few exceptions: <br>
<ul>
<li> Constants and macros defined on a system that is deficient:
<p><pre><H4>
<dd> MIN(x,y), MAX(x,y) and their relatives
</pre></H4>
<li> Platform constants :
<P>
No naming scheme; determined by OS and compiler.<br>
These appear only in one header file anyway.
<p>
<li> Feature test constants (?)<br>
Always start with `HDF5_HAVE_' like HDF5_HAVE_STDARG_H for a
header file, or HDF5_HAVE_DEV_T for a data type, or
HDF5_HAVE_DIV for a function.
</UL>
<p>
</UL>
<p>
<hr>
Last modified: August 5, 1997
<br>
Last modified: March 27, 2007 (Removed out-of-date contact information.)
</BODY>
<HTML>
|
