BFILE library

The BFILE library provides buffered access to open files or other objects which have similar semantics to files. It provides functionality similar to the fread() and fwrite() functions in the standard stdio library. Its main differences are:

The buffering can be applied to any object as the library provides a way to specify how it accesses the underlying object.
It does not use errno. The use of global variables is inappropriate for communication with libraries since it is inefficient (especially for multi-threaded programs).
It does not split the specification of the buffer into arbitrary 'size' and 'number of elements', which the library has to multiply together, preventing compile-time optimisation, and leading to ambiguous return status if an item was partially read or written.
The end-of-file condition is less likely to be confused with error conditions.
Errors are sticky ensuring that they are handled. Every function which operates on a BFILE object returns zero to indicate success, or an errno value if an error occurs. Errors are also 'sticky', so a BFILE object which has experienced an error will keep returning the error code for all operations attempted until bferror() is called. This avoids the need to continually check for errors when performing a sequence of small reads, writes, and seeks.

Functions provided

The library can be regarded as implementing a class for general buffered access and two subclasses implementing buffered access for files specified by filename and for Windows HANDLEs.

Core functions in bfile.c:

Supplementary functions:

bfopenhandle() - buffered file setup for Windows HANDLEs in bfhandle.c
bfopen() - buffered file setup for files by filename in bfopen.c

The BFILE library is distributed with Prosody which uses it in some of its high level libraries.