[svn-r2208] Big.html --> BigDataSmMach.html
Coding.html --> NamingScheme.html CodeReview.html ExternalFiles.html compat.html --> H4-H5Compat.html heap.txt --> HeapMgmt.html IOPipe.html Lib_Maint.html --> LibMaint.html MemoryManagement.html move.html --> MoveDStruct.html ObjectHeader.txt storage.html --> RawDStorage.html symtab --> SymbolTables.html Version.html Above files moved from doc/html/ to doc/html/TechNotes/ for into new "HDF5 Technical Notes" document. Filenames changed as indicated.
This commit is contained in:
Frank Baker
300
doc/html/TechNotes/NamingScheme.html
Normal file
300
doc/html/TechNotes/NamingScheme.html
Normal file
@@ -0,0 +1,300 @@
|
||||
<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>
|
||||
|
||||
Reference in New Issue
Block a user