HDF5 Naming Scheme for

• FILES
• PACKAGES
• PUBLIC vs PRIVATE
• INTEGRAL TYPES
• OTHER TYPES
• GLOBAL VARIABLES
• MACROS, PREPROCESSOR CONSTANTS, AND ENUM MEMEBERs

FILES
• 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.

  For Example:

  H5.c -- "Generic" library functions
  
  H5B.c -- B-link tree functions

  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.

  For Example:

  H5F.c -- the file for this package
  

  H5Fstdio.c -- stdio functions (just an example)
  

  H5Ffcntl.c -- fcntl functions (just an example)

  Each package file has a header file of API stuff (unless there is no API component to the package)

  For Example:

  H5F.h -- things an application would see.

  and a header file of private stuff

  H5Fprivate.h -- things an application wouldn't see. The private header includes the public header.

  and a header for private prototypes

  H5Fproto.h -- prototypes for internal functions.

  By splitting the prototypes into separate include files we don't have to recompile everything when just one function prototype changes.

  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.

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

  Header files should include everything they need and nothing more.

PACKAGES

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.

H5 -- library functions

H5A -- atoms

H5AC -- cache

H5B -- B-link trees

H5D -- datasets

H5E -- error handling

H5F -- files

H5G -- groups

H5M -- meta data

H5MM -- core memory management

H5MF -- file memory management

H5O -- object headers

H5P -- Property Lists

H5S -- dataspaces

H5R -- relationships

H5T -- datatype

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

H5F_t -- HDF5 file type

H5B_t -- B-link tree data type

Not all packages implement a data type (H5, H5MF) and some packages provide access to a preexisting data type (H5MM, H5S).

PUBLIC vs PRIVATE

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.

H5Fopen -- an API function.

H5B_find -- an internal function.

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().

Data types like H5B_t carry no information about whether the type is public or private since it doesn't matter.

INTEGRAL TYPES

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.

	hbool_t     -- boolean values (BTRUE, BFALSE, BFAIL)


	int8		-- signed 8-bit integers


	uint8       -- unsigned 8-bit integers


	int16       -- signed 16-bit integers


	uint16      -- unsigned 16-bit integers


	int32       -- signed 32-bit integers


	uint32      -- unsigned 32-bit integers


	int64       -- signed 64-bit integers


	uint64      -- unsigned 64-bit integers


	intn		-- "native" integers


	uintn		-- "native" unsigned integers

OTHER TYPES

Other data types are always followed by `_t'.

	H5B_key_t-- additional data type used by H5B package.

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

	typedef H5E_err_t herr_t;

GLOBAL VARIABLES

Global variables include the package name and end with `_g'.

	H5AC_methods_g	-- global variable in the H5AC package.

MACROS, PREPROCESSOR CONSTANTS, AND ENUM MEMBERS

Same rules as other symbols except the name is all upper case. There are a few exceptions:


• Constants and macros defined on a system that is deficient:

   
  		MIN(x,y), MAX(x,y) and their relatives
          

• Platform constants :

  No naming scheme; determined by OS and compiler.
  These appear only in one header file anyway.

• Feature test constants (?)
  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.

This file /hdf3/web/hdf/internal/HDF_standard/HDF5.coding_standard.html is maintained by Elena Pourmal [email protected] .

Last modified August 5, 1997