C02/doc/file.txt

File System Input/Output Functions for C02 Programs

This library contains functions for file handling. These functions
are included here instead of in stdio.h because not all 6502 systems 
support file based input/output. Functions that are not part of the
standard C libraries begin with the letters "fs".

At the beginning of the program use the directives

  #include <stdio.h02>
  #include <file.h02>
                      
The following functions are defined:

  fsinit();           Initialize file system.
  
                      This function should be called before calling
                      before any other file functions.
                      
                      Note: Closes any open files and initializes
                      the library's internal file table.

  f = fsptr();        Find an available file pointer.
                      
                      Returns 0 if no more file pointers are available.
                      
                      Note: This is called by the fopen() function, which
                      does the actual file allocation and is of limited 
                      use in application programming.

  r = fschk(f);       Check to see if f is a valid file pointer.

                      Returns 0 if valid, otherwise 255. 

                      Note: Called by the fclose(), feof(), fgetc(), 
                      fgets(), fputc(), fputs(), fread(), and fwrite()
                      functions.

  r = fstat(f);       Get status of file table entry or last file error. 
                      
                      If f is 0, returns a system dependent value 
                      corresponding to the last filesystem I/O error.
                      
                      If f is a potentially valid file pointer. returns a 
                      value representing the state of the corresponding 
                      entry in the file table. If the file table entry is
                      unused, then a 0 is returned. Otherwise, a system
                      dependent system dependent value is returned.

                      If f does not point to a valid file table entry,
                      then 255 is returned.
                      
                      Note: On CBM machines, fstat(0) returns the result
                      of READST directly after the last error. Valid file
                      pointer values are between 1 and FOMAX, inclusive
                      and return a value with bits 0 through 3 containing
                      the Kernal device number, and bit 7 set if an End of
                      File or other error was encountered.

  f = fopen(d, &n);   Open file specified from null-terminated string n 
                      on device d, returning a pointer to the file.
                      
                      Return 0 if the file could not be opened.
                      
                      Note: On CBM machines, d is the device number and
                      f is a logical file nunber as used in a Basic Open
                      statement. Up to 7 files may be opened at a time.                      

  r = fclose(f);      Close file pointed to by f, returning 0 if 
                      successful or 255 if there was an error.

                      Note: Returns 255 if f is not a valid file pointer.

  c = fgetc(f);       Read character from file opened to by filepointer f. 
                      
                      Returns character read from file.
                      
                      Note: Returns 255 if f is not a valid file pointer.
                      
                      Returns a system dependent garbage character if end
                      of file has been reached or any other I/O error. Use
                      feof(f) and fstat(0) to check for these conditions.

  fputc(f, c);        Write character c to file opened to filepointer f.
                      
                      Use feof(f) and fstat(0) to check for errors after
                      write.
                      
-----------------------------------------------------------------
                                           

  r = getstr(&s);     Reads a maximum of 128 characters from keyboard 
                      until the Return/Enter key is pressed, storing the 
                      entered characters as null-terminated string s.
                      
                      Allows corrections using Backspace/Delete. 
                      
                      Pressing the Escape/Abort key terminates entry,
                      leaving the string in an undefined state.
                      
                      Returns number of characters entered, or 255
                      if entry was aborted.

                      Note: Calls getchr() in a loop and uses constants 
                      DELKEY, RTNKEY, and ESCKEY from the system library.


  r = putstr(&s):     Writes up to 128 characters of null-terminated 
                      string s to the screen and advances the cursor to 
                      the beginning of the next line.
                    
                      Returns number of characters printed.
                    
                      Note: Calls outstr(&s) followed by newlin().

Note: This library expects the following functions to be defined:

  setdst(&s);         Set destination string pointer
  setsrc(&s);         Set source string pointer and initialize index

along with the zero page variable pairs
  
  dstlo,dsthi:        Destination string pointer
  srclo,srchi:        Source string pointer

the static array 

  ftbl[FOMAX]
    
and the assembler constant
  
  FOMAX               The maximum number of files that can be opened
                      at one time.

as well as the data structure

  FTBL                A system dependent table of bytes containing data
                      related to files opened by the fopen() function.
                      See function fstat() for more information.