The File Access word set provides an interface to the filing system of the host operating system. Below follows a general introduction and some guidelines for the usage of the File Access word set.
Some words take a string as input to describe a filename. The string is decribed by the address of the string, c-addr, and its length, u. The string must be null-terminated, ie. the byte at address ( c-addr + u ) must be zero. This is automatically done, when using the word S" in interpretation mode.
A File identifier (fid) is a file handle allocated by the operating system.
An I/O result code (ior) is the result of a file operation. If it is zero it means that the operation was succesful, otherwise it was unsuccessful, signifying an error occurred. Reaching the end of a file (eof) is considered a successful operation, and thus returns a zero ior. The ior code is actually a pointer to a standard RISCOS error block and can be THROWn, if so desired (see the file 'Docs.Semantics.Error' for a thorough explanation of errors and error handling).
A file access method is any of read-only, write-only and read/write. These are used when opening and creating files.
All reading from and writing to a file results in the file's file position to be advanced by the number of characters actually read or written.
The word WRITE-LINE writes the line terminator as ASCII 10. When reading a line from a file, either by READ-LINE, INCLUDED or INCLUDE-FILE, the ASCII characters 0, 10 and 13 are all recognized as line terminators.
See the 'Examples' directory for examples of the File Access words.
File Access Word Set __________________________________________________________
SOURCE-FILE File
( -- 0 ) or ( -- -1 ) or ( -- fid )
Identifies the source of non-block input stream, ie. when contents of BLK is zero.
In the Archimedes implementation this code is the same as R/W, as RISC-OS does not support write-only file access.
CREATE-FILE File
( c-addr u w1 -- fid ior )
Create a file with the name described by c-addr and u and open it with the file access method w1, ie. either R/O, R/W or W/O. If a file of the same name already exists then recreate it as an empty file.
If ior is zero the file was successfully created and opened and the file has been positioned to the start of the file. If ior is non-zero, fid is an unspecified value.
OPEN-FILE File
( c-addr u w1 -- w2 ior )
Open the file with the name described by c-addr and u and file access method w1.
If ior is zero the file was successfully created and opened and the file has been positioned to the start of the file. If ior is non-zero, fid is an unspecified value.
CLOSE-FILE File
( fid -- ior )
Close the file identified by fid. The I/O result code, ior, is zero if the file was succesfully closed, otherwise it is non-zero.
INCLUDE-FILE File
( i*w fid -- j*w )
Interpret the file identified by fid. Each line of the file is read and interpreted seperately. When the end of file is reached the file is closed. If an error occurs, the file may not be closed.
AForth restricts the line length to 128 characters including the line terminator. This corresponds to the minimum required to comply with the ANS standard.
RISC-OS supports (in release 2.0) 256 open files at one time. AForth imposes a limit of 127 files being open and interpreted by INCLUDE-FILE or INCLUDED (This should though be of no concern! :-)
AForth release 0.70 and above features a special Aforth Fast Include Format (AFIF) which enables very fast loading and dynamic linking of files containing Forth definitions. See the file 'Docs.Internals' for explanation on how to create your own fast-loading libraries.
INCLUDED File
( i*w c-addr u -- j*w )
This is similar to INCLUDE-FILE, though this takes a file name described by c-addr and u as input. The file identified by name c-addr u is opened and interpreting commences in the way described under INCLUDE-FILE.
READ-FILE File
( c-addr u1 fid -- u2 ior )
Read u1 characters (bytes) to the address c-addr from the file identified by fid. The read is initiated at the current file position of the file. u2 is the number of characters actually read and ior is the I/O result code.
If the end of file is reached before all u1 characters have been read, ior is zero and u2 is the number of characters actually read. Also, when the the operation is initiated when end-of-file has already been reached, u2=0 and ior=0. Thus when u2<u1 and ior=0, end-of-file has been reached successfully.
If an error occurs, ior is non-zero and u2 is the number of characters read before the error occurred.
WRITE-FILE File
( c-addr u fid -- ior )
Write u characters (bytes) from the address c-addr to the file identified by fid. The write is initiated at the current file position of the file. ior is zero if the write completed successfully.
READ-LINE File
( c-addr u1 fid -- u2 flag ior )
Read the next line from the file identified by fid to the address c-addr. At most u1 characters are read. The line-terminator, if any, is not put at the end of the line at c-addr. The buffer pointed by c-addr should be at least u1+2 characters long.
If the operation succeeded, flag is true and ior is zero. u2 is the number of characters actually read, exclusive the line terminator. That is, if u1=u2, the line terminator has yet to be reached.
If the read was initiated when the file position was at the end of file, flag is false, u2=0 and ior=0, ie. flag acts as an end of file indicator, being false when end-of-file has been reached (ior=0 on reaching the end of a file because this is considered a successful completion).
If ior is always non-zero an error occurred during the read.
WRITE-LINE File
( c-addr u fid -- ior )
Write u characters (bytes) at address c-addr followed by a line terminator to the file identified by fid. The line terminator is written as ASCII 10.
FILE-POSITION File
( fid -- ud ior )
Return the double number file position of the file identified by fid.
FILE-SIZE File
( fid -- ud ior )
Return the double number file size of the file identified by fid.
REPOSITION-FILE File
( ud fid -- ior )
Reposition the file identified by fid to the file position described by
the double number ud.
RESIZE-FILE File
( ud fid -- ior )
Resize the file identified by fid to the file size described by the double
number ud.
DELETE-FILE File
( c-addr u -- ior )
Delete the file with the name described by c-addr u.
BLOCK-FID File
( -- a-addr )
This word is used in the defininition of some words of the Block word set when this is built upon the File Access word set. Even though the ANS standard requires the Block word set to be present if the File Access word set is, it has not been included and thus the word BLOCK-FID has become obsolescent.
File Access Extensions Word Set _______________________________________________
The following words belong to the File Access Extensions and have not been implemented in the current implementation.
FILE-BLOCK ( u fid -- a-addr ) FileExt
FILE-BUFFER ( u fid -- a-addr ) FileExt
FLUSH-FILE ( fid -- ior ) FileExt
LOAD-FILE ( i*w u fid -- j*w ) FileExt
FILE-STATUS ( c-addr u -- w ior ) FileExt
RENAME-FILE ( c-addr u1 c-addr2 u2 -- ior ) FileExt
