Proposal of macros for Stdio functions coding
The ISO C library facilities defines many functions used by the HDF5 library. Examples are: fopen, fclose, fseek, etc. These are well defined and HDF5 could have just invoke them by the official name. But in platforms that supports both 32-bits and 64-bits programming models, there are confusions. Most vendors introduce a parallel versions of Stdio library routine. E.g., fseek64 vs. fseek. But some vendors will invoke 64-bits or 32-bits fseek that depends on compiler switch. HDF5 wants to support the larger file size access if available. But the larger file size Stdio function protocols are not standardized yet.
One can code the library with all sorts of #ifdef such as the following:
#ifdef
platformA
fseek64(…,long_long_address)
#elif
platformB
fseek64(…, long_address)
#else
fseek(…)
#endif
This makes the source code hard to follow and hard to maintain.
1. Stdio Macros
Define an HDF5 macro for each
stdio function used. E.g.,
#define HDfopen(n, m) fopen(n, m)
#define
HDfseek(f, off, where) fseek(f, off,
where)
HDF5 will use the corresponding macro name whenever an stdio function is invoked. These class of macros are defined in HDF5 private space such as H5private.h. They should not be available in the public API space.
Platform dependent definition should be coded in the macro definitions. E.g.,
#ifdef
platformA
#define
HDfseek(f, off, where) fseek64(f, off,
where)
#else
#define
HDfseek(f, off, where) fseek64(f, off,
where)
#endif
2. HDF5 file driver examples
The HDF5 stdio file driver (H5FDstdio.c) and Multi file driver (H5Fdmulti.c) are intended to be examples showing how a file driver is coded by using only public API. Thus, they should not use the macros defined in the private space and should not #include any private header files such as H5private.h. In order to make the two driver code compatible to as many platforms as possible, they would have to duplicate the macro definitions inside their own source code files.
3. autoconfigure extension
We plan to add more configure options to detect which stdio or stdio like functions to invoke in order to support larger file size (greater than 32-bit file sizes). This will make the macro definitions to be configurable rather than hard coded. E.g.,
#ifdef
H5_HAVE_FSEEK64
#define
HDfseek(f, off, where) fseek64(f, off,
where)
#else
#define
HDfseek(f, off, where) fseek(f, off,
where)
#endif
One goal is to use configurable macro to maintain the source code as platform independent as possible and to isolate all platforms dependent code in a central location such as header files, instead of all over multiple files. Another goal is to keep the HDF5 stdio and multi file driver source code to use HDF5 public definitions only.
===
Revision: April 9, 2002 by Albert Cheng
Email: acheng@ncsa.uiuc.edu