summaryrefslogtreecommitdiffstats
path: root/doc/html/TechNotes/NamingScheme.html
diff options
context:
space:
mode:
authorFrank Baker <fbaker@hdfgroup.org>2000-08-25 17:42:24 (GMT)
committerFrank Baker <fbaker@hdfgroup.org>2000-08-25 17:42:24 (GMT)
commit2e8cd59163cda6b051eae53aac58f54e0a9e9351 (patch)
tree5d9058906b7a9a39b0815476d7daea0229c67eb4 /doc/html/TechNotes/NamingScheme.html
parent3ff571ab58fedf8dbb20ac8e1eea251ffb343f9e (diff)
downloadhdf5-2e8cd59163cda6b051eae53aac58f54e0a9e9351.zip
hdf5-2e8cd59163cda6b051eae53aac58f54e0a9e9351.tar.gz
hdf5-2e8cd59163cda6b051eae53aac58f54e0a9e9351.tar.bz2
[svn-r2482] Bringing "HDF5 Technical Notes" into development branch (from R1.2 branch)
Diffstat (limited to 'doc/html/TechNotes/NamingScheme.html')
-rw-r--r--doc/html/TechNotes/NamingScheme.html300
1 files changed, 300 insertions, 0 deletions
diff --git a/doc/html/TechNotes/NamingScheme.html b/doc/html/TechNotes/NamingScheme.html
new file mode 100644
index 0000000..dbf55bf
--- /dev/null
+++ b/doc/html/TechNotes/NamingScheme.html
@@ -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>
+