<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>