cff.txt

OXCC is a multipass, interpreting C compiler with several language extensions. It generates an Archi

int cffind_dupname(
                  void *handle,
                  DupName *dupname  // points to the desired dupname
                  void *itemptr,    // if FOUND the item is returned
                 )
Returns FOUND, NOTFOUND or ERROR. If FOUND, sets up for sequential access.


int cffind_item(
                void *handle,
                void *keyptr,
                int   keylen,
                void *itemptr
               )
Locates a key-item pair.
Returns FOUND, NOTFOUND or ERROR. If FOUND, sets up for sequential access.


int cffind_mark(
                void *handle,
                void *itemptr
               )
Returns the item for the current mark if the mark is valid (see cfmark()).
The mark can be invalidated if items are inserted or deleted after the
mark is set. This phenomenon happens more often with hashed directories
than with B+ trees.

Returns FOUND, NOTFOUND or ERROR. If FOUND, sets up for sequential access.



DELETE ITEMS

int cfdelete(
              void *handle,
              void *keyptr,
              int   keylen
             )
The first item of the key is deleted along with any data.
Returns OK or ERRORNUM a negative number.


int cfdelete_item(
                  void *handle,
                  void *keyptr,
                  int   keylen,
                  void *itemptr
                 )
If the key-item pair exists it is deleted along with any data.
Returns OK or ERRORNUM a negative number.


int cfdelete_dupnum(
                    void *handle,
                    void *keyptr,
                    int   keylen,
                    long  dupnum      // 0 based
                   )
If the dupnum'th item for the key exists it is deleted along with any data.
Returns OK or ERRORNUM a negative number


int cfdelete_dupname(
                     void *handle,
                     void *keyptr,
                     int   keylen,
                     DupName *dupname
                    )
If the dupname exists, it is deleted along with any data.
If the dupname is deleted, the 'holes' counter is incremented by one.
Each DupName set contains a 48 bit holes counter. (see cfcountdups()).
returns OK or ERRORNUM a negative number.


int cfdelete_lastdupname(
                         void *handle,
                         void *keyptr,
                         int   keylen
                        )
If the last DupName for the key exists, it is deleted along with any data.
The DupName counter is decremented by one.
Returns OK or ERRORNUM a negative number.


int cfdelete_lastdupnum(
                         void *handle,
                         void *keyptr,
                         int   keylen
                        )
If the last dupnum for the key exists, it is deleted along with any data.
WARNING: The last dupnum is probably not the last dup entered. B+ trees
sort all input and hashed directories are reorganized when split/coalesced.
Returns OK or ERRORNUM a negative number.


int cfdelete_alldupnames(
                         void *handle,
                         void *keyptr,
                         int   keylen
                        )
All 'DupName' entries for the key are deleted along with any data.
Returns OK or ERROR


int cfdelete_alldupnums(
                         void *handle,
                         void *keyptr,
                         int   keylen
                        )
All 'dupnum' entries for the key are deleted along with any data.
Returns OK or ERROR

DELETE OBJECTS 

int cfunlink(
              void *something, // path or object handle
              ...              // optional 2'nd arg if arg 1 is a handle
            )

Deletes the object denoted by 'something' and an optional second argument.
If 'something' is a path, then the target of the path is deleted.
if 'something' is a handle, then if the second argument is NULL
the object denoted by the handle is deleted. A non-NULL second argument
must be a character string which names an entry in the object's index.
The second argument must not refer to a sub_object.

Returns OK or ERROR if multiply opened or sub_objects open or not found.

NOTE: When an object is unlinked all of it's sub-objects are unlinked
and all data is returned to parent bitmaps. External files can be unlinked.


STACK OPERATIONS

long cfpush_value(
                 void *handle,	// an open object
                 unsigned long *valptr
                )
Push an unsigned long integer on the objects stack.
Returns current stack depth or ERROR.

long cfpush_item(
                 void *handle,	// an open object
                 void *itemptr
                )
Push the item on the objects stack.
Returns current stack depth or ERROR.

long cfpush_data(
                 void *handle,  // an open object
                 void *datbufptr,
                 int   datbuflen
                )
Pushes data onto the objects stack (max 16MB). 
Returns current stack depth or ERROR.


long cfpop_value(
                void *handle,  // an open object
                unsigned long *valptr
               )
Pops an unsigned long integer from the top of the objects stack.

long cfpop_item(
                void *handle,  // an open object
                void *itemptr
               )
Pops an item from the top of the objects stack.
IF THE ITEM DESCRIBES DATA, THE DATA HAS NOT BEEN DELETED (use cfretspace()).
I have chosen this dangerous method of dealing with the stack because
it can be very useful. i.e. One part of a program can push a lot of data
without regard for where it is going or assigning a key to it, another
part of a program can pop the items which describe the data and save the
items for later keyed retrieval, the data moves once. This method is doubly
dangerous: First, the programmer must ensure that the data can eventually
be deleted and Second, if a hashed object contains PREALLOCATED ENTRIES
then the data should NEVER be deleted because the preallocation mechanism
will want to reuse the space, and indeed will overwrite the data at some
time in the future.
Returns current stack depth or ERROR.


long cfpop_data(
                void *handle,  // an open object
                void *datbufptr,
                int   datbuflen
               )
Pops data (if it exists) from the top of the stack.
If the top of the stack contains an item that does not describe data
the item is lost.
Returns current stack depth or ERROR.


long cfstackdepth(
                  void *handle  // an open object
                 )
Returns current stack depth or ERROR.



SPACE ALLOCATION

void *cfgetspace(
                  void *handle,  // an open object
                  long  amount,  // max 16MB
                  void *itemptr	 // receives an Item which describes the space
                )
Returns 'itemptr' if success or NULL.


int cfretspace(
                void *handle,  // an open object
                void *itemptr  // pointer to an Item which describes space
              )
Returns OK or ERROR
CFF Version 5.9 will abort if the Item does not describe valid space.
I think that this is better than returning an error.


    MEMORY FUNCTIONS
    void *malloc(size_t)
    void *calloc(unsigned, unsigned)
    void *realloc(void *, unsigned)
    void *valloc(unsigned)
    void *memalign(unsigned, unsigned)
    void free(void *)
    unsigned mallocsize(void *)
    void *cfmalloc(unsigned, Item *)
    void cffree(Item *)

    MEMORY BY CATEGORY FUNCTIONS
    void *mallocC(long, unsigned)
    void *callocC(long, unsigned, unsigned)
    void *reallocC(long, unsigned, unsigned)
    void *vallocC(long, unsigned)
    void *memalignC(long, unsigned, unsigned)
    void freeC(long, void *)
    void freecat(long)

CONTROL FUNCTIONS

long cfmodbufs(
                long increment   // positive or negative increment in K bytes
              )
Changes the allowed buffering space by 'increment'.
Returns OK

long cfsetlazy(
               void *handle		// an open object
              )
Changes the writethrough characteristic of the object to LAZY.
Some bookeeping entries are forced out.
Returns OK or ERROR

long cfsetverylazy(
                   void *handle  // an open object
                  )
Changes the writethrough characteristic of the object to VERYLAZY.
No data is forced out.
Returns OK or ERROR

long cfclrlazy(
               void *handle   // an open object
              )
Sets the writethrough characteristic of the object to NORMAL.
Forces out everything.
Returns OK or ERROR

long cfsetkeycmp(
                 void *handle,                          // open object
                 int (*func)(void *, int, void *, int)  // function pointer
                )
Changes the default key comparison routine for an object to a programmer
supplied version.
Returns OK or ERROR

long cfsetitemcmp(
                 void *handle,                // open object
                 int (*func)(void *, void *)  // function pointer
                )
Changes the default item comparison routine for an object to a programmer
supplied version.
Returns OK or ERROR

long cfsetprintfunc(
                 int (*func)(int)  // function pointer
                )
Changes the default system print function to a programmer supplied version.
The function must print one character at a time,
and return 1 for success, -1 for error.
Returns OK

void cfport_settestflags(
                         int flags
                        )
Set flags in the portability module 'cfport.c'. This command is issued
before cfinit(). The only defined flag is 1, which causes the extended
memory driver to enable a 4Meg local buffer for testing purposes.
If the 1 flag is not set, the system will map extended memory to
primary memory unless the programmer has included a 'real' extended
memory driver in cfport.c


COPY OBJECTS, FILESYSTEMS and FILES

void *cfcopy(
             void *something_dst,  // designates the destination
             void *something_src   // designates the source
            )

Copy the source to the destination.
The arguments can be paths or handles.
The source may be an object, a filesystem or an external file.
Ditto for the destination.
Sorted objects (created with F_SORTED) may not be copied to a filesystem.
If the source or destination is an external file, then the file property
of the object is copied.

Returns a handle to the OPENED destination or NULL.
NOTE: If the destination argument was an open handle, then the returned
handle SUPERCEEDS the original. i.e. the open object was deleted and
recreated.


DIRECT ACCESS TO DATA IN THE BUFFERS

void *cflocalize(
                 void *handle,   // an open object
                 void *item      // pointer to an Item which describes space
                )
Returns a pointer to memory or NULL.
This command ties up one buffer header.
Be certain to release the buffer when finished.
The buffers are in the heap and thus are not memory protected.


void cfrelease(
               void *memptr,  // a pointer to memory returned by cflocalize()
               long  relmode  // R_CLEAN, R_DIRTY, R_FLUSH
              )
Release a buffer. 
If the release mode is R_CLEAN, then the buffer may never be written out.
If the release mode is R_DIRTY, then the buffer will eventually be written out.
If the release mode is R_FLUSH, then the buffer is written out immediately if
the object writethrough condition is not VERYLAZY. If the object may be in
VERYLAZY mode, be sure to use (R_DIRTY|R_FLUSH).


NAME TRANSLATION FUNCTIONS

int cfdef(
          char *keyptr,  // the key for the definition string
          char *defptr  // the definition string, entered in local dictionary
         )
Enters the definition string in the local dictionary, under the key.
Local definitions override application and system definitions.
Returns OK or ERROR


int cfundef(
            char *keyptr   // the key to a definition string
           )
Deletes a definition string from the local dictionary.
returns OK or ERROR


int cfsysdef(
              char *keyptr,  // the key for the definition string
              char *defptr  // the definition string, entered in PERMFILE
             )
Enters the definition string in the permanent system dictionary (if it exists).
PERMFILE is enabled if arg 3 of cfinit() mentions a valid '.cff' file.
Returns OK or ERROR


int cfsysundef(
               char *keyptr  // the key to a defined string
               )
Deletes a definition string from the permanent system dictionary.
Returns OK or ERROR

int cfappdef(
              char *keyptr,  // the key for the definition string
              char *defptr  // the definition string, entered in PERMINFO
             )
Enters the definition string in the permanent application dictionary.
Application definitions override system definitions.
PERMINFO is enabled if arg 3 of cfinit() mentions a valid '.cff' file.
Returns OK or ERROR