mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-11-27 02:10:55 +08:00
301 lines
7.5 KiB
HTML
301 lines
7.5 KiB
HTML
|
<HTML>
|
||
|
|
<HEAD><TITLE>
|
||
|
|
HDF5 Naming Scheme
|
||
|
|
</TITLE> </HEAD>
|
||
|
|
|
||
|
|
<BODY bgcolor="#ffffff">
|
||
|
|
|
||
|
|
|
||
|
|
<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: <A HREF = "mailto:koziol@ncsa.uiuc.edu">
|
||
|
|
<I>Quincey Koziol</I> </A> and
|
||
|
|
<A HREF = "mailto:matzke@llnl.gov">
|
||
|
|
<I> Robb Matzke </I> </A>
|
||
|
|
|
||
|
|
</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>
|
||
|
|
<H6>
|
||
|
|
<center>
|
||
|
|
This file /hdf3/web/hdf/internal/HDF_standard/HDF5.coding_standard.html is
|
||
|
|
maintained by Elena Pourmal <A HREF = "mailto:epourmal@ncsa.uiuc.edu">
|
||
|
|
<I>epourmal@ncsa.uiuc.edu</I> </A>.
|
||
|
|
</center>
|
||
|
|
<p>
|
||
|
|
<center>
|
||
|
|
Last modified August 5, 1997
|
||
|
|
</center>
|
||
|
|
|
||
|
|
</H6>
|
||
|
|
</BODY>
|
||
|
|
<HTML>
|
||
|
|
|