$title

| programmer's documentation

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages

# BFT

The "Base Functions and Types" library is intended to simplify and enhance portability, memory and I/O use for scientific codes. It contains a number of system library wrappers for common services such as file I/O or memory management, ensuring portability of the calling code.

## Portability

Using lower-level services in C or C++ often requires the definition of preprocessor symbols such as `_POSIX_SOURCE` (or `OSF_SOURCE`, or `HPUX_SOURCE`, ...). On certain systems, largefile support also requires additionnal preprocessor symbols such as `_FILE_OFFSET_BITS` or `_LARGEFILE_SOURCE`, and `fseek/ftell` replaced with `fseeko/ftello`.

Authors of scientific code seeking portability should not have to worry about these issues unless they deliberately choose to use low-level functions. BFT tries to hide such portability issues while maintaining an API similar to that of the standard `libc` where applicable.

## Return codes and error handling

In most scientific codes destined to run in a batch environment, errors are usually fatal, especially when dealing with file access and memory allocation. The functions provided by the BFT library always check for return codes, and call the appropriate error handler when applicable. The default is to terminate the running program after printing the appropriate message, but the user may define and set other error handlers with different behavior.

Error handling may also be modified by writing a specific error handler (see bft_error_handler_example).

## Added functionnality

BFT functions similar to `libc` functions add functionnality such as optional byte-swapping for conversion from internal to external data repressentation (or vice-versa), or optional memory-allocation logging and tracking of non-freed pointers.

## Goals and Limitations

The BFT library tries to provide a set of utilitarian functions for common use, but does not seek to define a framework. As a general rule, functions provided by BFT should provide added portability or functionnality when compared to their `libc` or Posix counterparts (when such counterparts exist), as simple wrapping with no added functionnality only makes code less readable to an experienced developer and is to be avoided.

Subsets of BFT may be used independently if desired, and are orthogonal, except as regards error handlers. With non-default error handlers, they can be made fully orthogonal. Only certain subsets may be used if preferred.

The BFT library provides memory-usage measurement functions, whose implementations are system-dependent. If it has not yet been ported to a given type of environment, these functions should return 0. The user should thus check for the return values of such functions, but the API is guaranteed.