LAZY WRITING

The writethrough properties of an object can be set with the commands
cfsetlazy(handle) and cfsetverylazy(handle). The command cfclrlazy(handle)
causes the object and all underlying buffers, including the OS, to be flushed.
The default writethrough property of an object causes it to be up to date
at the user API level. By this I mean that the CFF buffers are written to
the OS buffers. In order to ensure that the OS buffers are flushed, the
programmer should issue cfflush(handle) and cfsync() commands when appropriate.


BITMAPS

The term 'bitmaps' is misleading. CFF uses extent maps which are 512 bytes
in size and contain 49 sorted entries per map. Each bitmap set has an
in-core sorted index. The root directory of each filesystem has a bitmap
set by default. Individual objects can be created with a bitmap which
will control space allocation for the object and it's subobjects. If an
object has a bitmap it can be deleted very quickly, the system merely returns
all the space defined by the maps to the parent maps. Without a bitmap the
deletion of a complex object can take a while. Nevertheless, DO NOT USE
BITMAPS unless you know what you are doing. This is because they lead to
fragmentation in any environment that involves active insertions and deletions.
Preferably you would pre-allocate all the anticipated space to the bitmap
when you create the object, but this usually means that you allocate a lot
more than is really needed. To find out more about bitmaps, issue the command
cfprintbitmaps(something). Hashed objects which have preallocated data and
entries do not return space to the controlling bitmaps when something
is deleted, this is good. To shrink a sparsely populated preallocated hashed 
object, copy it.

CFF maintains two caches for each set of bitmaps, the KEYCACHE is used
for storage of hashed keys and tends to segregate long keys from the data,
this is good; the CACHE is used to dispense space for data, and nodes.
Bitmaps are stored in the space that they map; often as the first 512
bytes.


GARBAGE COLLECTION

The system actively returns space to the underlying bitmaps and
also coalesces the bitmaps in a timely manner. The system currently does not
compress an object or filesystem in place, i.e. rearrange the placement
of things so that the end of a bitmap contains a nice chunk of space that
can be returned to it's parent. cfcopy() is the rich man's substitute.


ERROR REPORTING

Version 5.9 has very uninformative error reporting.


ACCESS CONTROL and SECURITY

Version 5.9 has no access control or security.


FILE AND RECORD LOCKING

Version 5.9 has no locks.


DATA COMPRESSION

An adaptation of lz77 is used to achieve automatic data compression of
permanent categories. Two calls, cfzip() and cfunzip() are provided
for the programmer.


STDIO STYLE I/O

A set of 'stream' calls is included. These calls work with objects, data 
chunks, values, external files and raw devices. There are several additional
opening modes: unique,temp,string,stat,text,binary.


INFORMATIONAL PRINTING

The programmer can set the system print function with the command
cfsetprintfunc(int (*funcptr)(int));

The print function prints one character at a time and returns 1 if OK
and -1 if a device error.

The default print function calls PORTPRINT in cfport.c which writes
one character to file descriptor 1. Unbuffered printing gets you all
there is to see even when the system aborts.

CFF contains a built in printf 'cfeprintf' which is reentrant and
prints one character at a time.


cfprintbitmaps(void *something);
Prints the bitmaps of something (a path or handle) and it's parents.


cfprintentries(void *something);
Prints the contents of the storage maps of something (a path or handle).


cfpflags(char *label, void *handle)
Prints the flags for an open object and its parents, 
adds a programmer supplied label string.



THE COMMAND SET

NOTATION:
void *something     Denotes a path or handle (use either one). 
                    If a path, the object need not be open.
void *handle        Denotes a handle for an open object or data chunk.



INITIALIZATION AND EXIT

void cfinit(
              char *appname,    // the name of the application
              int bufferspace,  // size of buffer area in KB
              char *permfile    // path of file containing permanent objs
           )
Initialize, load permanent malloc categories from permfile,
load application and system string definitions from permfile,
define PERMFILE, PERMCAT and PERMINFO to refer to the appropriate
objects in permfile, add 'cfexit()' to the atexit list.


void cfexit(
            void
           )
Save permanent malloc categories, save current application and system string
definitions, close all open objects.


OPEN CLOSE READ WRITE etc.

typedef struct opninfo {
    long initial_entries;  // if hashed object, preallocates buckets
    unsigned long bitmap_prealloc;  // if object has bitmap, initial space
    long data_prealloc;    // if hashed object, data space per initial entry
} OPNINFO;

/* OPEN MODE BITS */

#define F_RDONLY    0x0001     // The object is readonly, the parents are rdwr
#define F_WRONLY    0x0002     // I don't think this works
#define F_RDWR      0x0003
#define F_CREAT     0x0004     // create if non-existant
#define F_TEMP      0x0008     // delete on close
#define F_UNIQ      0x0010     // create a unique name and append to path
#define F_EXCL      0x0020     // non shared open
#define F_BITMAP    0x0040     // attach a bitmap
#define F_TRUNC     0x0080     // truncate on open
#define F_APPEND    0x0100     // only append when writing to file
#define F_FILEONLY  0x0400     // 512 byte nodes
#define F_BIGDIR    0x0800     // 4096 byte nodes
#define F_HUGEDIR   0x1000     // 8192 byte nodes
#define F_SORTED    0x8000     // B+ tree
#define F_UNTAGGED  0x10000    // items are untagged if B+ tree
#define F_STAT      0x20000    // The object and parents are readonly

void *cfopen(
                char *path,		// pathname of object
                long mode,		// open mode bits
                void *info		// pointer to OPNINFO struct or NULL
            )
Returns an opaque handle or NULL, check errno.
Will also open a chunk or value for read/write
(the path must contain only legal chars).


void *cfsubopen(
                void *handle,	// handle of open object
                void *name,		// name of subobject
                long mode,		// open mode bits
                void *info		// pointer to OPNINFO struct or NULL
               )				
Pastes the path, this is a convenience for the programmer.
If name is NULL or name[0] == 0, then reopens handle.
Returns an opaque handle or NULL, check errno.
Will also open a chunk or value for read/write
(the name must contain only legal chars).


void *cfopen_chunk(
                   void *handle,	// handle of open object
                   void *item		// pointer to an Item describing a chunk
                  )
Permits read/write access to a fixed length chunk of data.  
Use cfclose() when finished.
Returns an opaque handle or NULL, check errno.


void *cfmake_chunk(
					void *handle,	// handle of open object
					void *key,		// pointer to key
					int keylen,		// length of key
					int chunksize	// size of chunk, 16Meg max
					)

Creates a chunk in the open object, providing that the open object
is not a chunk and is not an external file. Chunks are fixed length
and can be read/written but not extended.
Returns an opaque handle which can be used with cfread, cfwrite, cfclose,
cfdup, cfreopen, cfdopen etc.


void* cfdup(
			void *handle	// handle of open object.
			)

Same as dup() in unix, shared filepointer.
Use cfclose() when finished.
Returns an opaque handle or NULL, check errno.


void* cfreopen(
			void *handle	// handle of open object.
			)

The reopened handle has an independant filepointer which is set to the
position of the original, NOTE this reopen is UNCONDITIONAL, unlike cfsubopen()
with a NULL name.
Use cfclose() when finished.
Returns an opaque handle or NULL, check errno.


void cfclose(
             void *handle
             )
Closes and flushes whatever is referenced by the handle.
If an object or file has been created with F_TEMP, it is deleted on close.


void cfflush(
             void *handle
             )
Ensures that all information pertaining
to the object or external file is written out.

void cfsync()
Ensures that all information pertaining
to all open objects and external files is written out.
NOTE -- this may not work, depends upon the supporting OS.


long cfread(
            void *handle,
            void *userbuffer,
            long amount
            )
Reads from a file or a chunk.
Returns amount read or ERROR, check errno.

long cfwrite(
             void *handle,
             void *userbuffer,
             long amount
            )
Writes to a file or a chunk.
Returns amount written or ERROR, check errno.

long cfseek(
            void *handle,
            unsigned long amount,
            int mode
           )
Seeks within a file or a chunk.
It is legal to seek past the end of a file.
CFF Version 5.9 files do not have holes.
Returns position or ERROR

/* Seek modes */
#define S_SET 0
#define S_CUR 1
#define S_END 2

int cftruncate(
               void *something,
               unsigned long size
              )
Truncates the file property to 'size', returns OK or ERROR



SEQUENTIAL DIRECTORY ACCESS -- JUST LIKE POSIX almost

typedef struct cfdirent {
    int d_namlen;
    char *d_name;
    unsigned long d_bytesalloc;
    unsigned long d_bytesused;
    unsigned long d_mode;
    unsigned long d_entrycnt;
    void *d_fpt;
} CFDIRENT;

void *cfopendir(
                void *something,   // path or handle
               )
Opens the directory and dictionary aspects of a path or handle.
Works for external files.
Returns opaque handle, or NULL, check errno.


void cfclosedir(
                void *openhandle
               )
Close using the handle produced by cfopendir.


CFDIRENT *cfreaddir(
                    void *openhandle
                   )
Returns a pointer to a CFDIRENT struct, or NULL if EOD.
The nodes (sub-directories) are returned.

CFDIRENT *cfreadfulldir(
                    void *openhandle
                   )
Returns a pointer to a CFDIRENT struct, or NULL if EOD.
Nodes, values and chunks are returned.

void cfrewinddir(
                 void *openhandle
                )
Reset to beginning of directory.


void cftelldir(
               void *openhandle,
			   STOR *curentry
              )
Returns a pointer to the current directory entry.


void cfseekdir(
               void *openhandle,
               STOR *curentry
              )
Sets the directory search to the spot returned by cftelldir.


SEQUENTIAL INDEX ACCESS

long cfhead(
            void *handle,
            Item *itemptr
           )
Goto beginning of entries, get current item.
Returns OK or ERROR, 

long cfhead_dupnum(
                   void *handle
                   void *keyptr,
                   int   keylen,
                   void *itemptr
                  )
Goto beginning of normal duplicate entries for the key, get current item.
Returns OK or ERROR

long cfhead_dupname(
                   void *handle
                   void *keyptr,
                   int   keylen,
                   void *itemptr
                  )
Goto beginning of DupName duplicate entries for the key, get current item.
Returns OK or ERROR

long cftail(
            void *handle,
            Item *itemptr
           )
Goto end of entries, get current item.
Returns OK or ERROR, 

long cftail_dupnum(
                   void *handle
                   void *keyptr,
                   int   keylen,
                   void *itemptr
                  )
Goto end of normal duplicate entries for the key, get current item.
Returns OK or ERROR