HDF5 Naming Scheme

#
HDF5 Naming Scheme for

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

Authors: Quincey Koziol and Robb Matzke

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.

Last modified: August 5, 1997
Last modified: March 27, 2007 (Removed out-of-date contact information.)