DEFINITION MODULE Files;

	(********************************************************)
	(*							*)
	(*		    File operations.			*)
	(*							*)
	(*  Programmer:		P. Moylan			*)
	(*  Last edited:	16 September 1991		*)
	(*  Status:		Working				*)
	(*							*)
	(*	IMPORTANT NOTE: The file system starts with	*)
	(*	no pre-conceived idea of what devices are	*)
	(*	present; it's up to the device drivers		*)
	(*	themselves to "install" themselves at program	*)
	(*	initialisation time.  To make this work, the	*)
	(*	user of this module should import whatever	*)
	(*	device drivers are needed.  Furthermore, this	*)
	(*	IMPORT declaration must come before the		*)
	(*	IMPORT of module Files, to ensure that device	*)
	(*	driver initialisation is complete before the	*)
	(*	file system starts its own initialisation.	*)
	(*							*)
	(********************************************************)

FROM SYSTEM IMPORT
    (* type *)	BYTE, ADDRESS;

FROM IOErrorCodes IMPORT
    (* type *)	ErrorCode;

TYPE
    File;	(* is private *)

PROCEDURE OpenFile (VAR (*OUT*) f: File;  name: ARRAY OF CHAR;
					newfile: BOOLEAN): ErrorCode;

    (* Opens the file named by the given character string, and returns	*)
    (* f as the identification to be used when specifying this file in	*)
    (* future.  The caller must specify newfile = TRUE to create a new	*)
    (* file, or newfile = FALSE if the intention is to open an existing	*)
    (* file.  It is illegal to open a new file with the same name as an	*)
    (* existing file; this is to protect against accidental deletions.	*)
    (* The value returned is an error code (OK if no error).		*)

PROCEDURE CloseFile (VAR (*INOUT*) f: File);

    (* Closes file f.	*)

PROCEDURE EOF (f: File): BOOLEAN;

    (* Returns TRUE iff we are currently at the end of file f.	*)

PROCEDURE ReadByte (f: File): BYTE;

    (* Returns the next byte from the file.	*)

PROCEDURE ReadRecord (f: File;  buffaddr: ADDRESS;  desired: CARDINAL;
				VAR (*OUT*) actual: CARDINAL): ErrorCode;

    (* Reads up to "desired" bytes from file f to memory location	*)
    (* "buffaddr".  On return, "actual" gives the number of bytes read.	*)

PROCEDURE WriteByte (f: File;  value: BYTE): ErrorCode;

    (* Writes one byte to the file.	*)

PROCEDURE WriteRecord (f: File;  buffaddr: ADDRESS;
					count: CARDINAL): ErrorCode;

    (* Writes count bytes from memory location buffaddr.	*)

PROCEDURE SetPosition (f: File;  position: LONGCARD): ErrorCode;

    (* Ensures that the next read or write on this file will be at	*)
    (* byte number position in the file.  (The first byte in the file	*)
    (* is byte number 0.)  If a position greater than the file size	*)
    (* is specified, the length of the file will increase.		*)

PROCEDURE SavePosition (f: File): LONGCARD;

    (* Returns the current byte number in file f.	*)

PROCEDURE FileSize (f: File): LONGCARD;

    (* Returns the length of the file in bytes.	*)

END Files.