Files are opened/created by name and type. The following file access methods (FAMs) are recognised:
r/o ( – fam ) file “r-o”
r/w ( – fam ) file “r-w”
w/o ( – fam ) file “w-o”
bin ( fam1 – fam2 ) file “bin”
+fmode ( fam1 rwxrwxrwx – fam2 ) gforth “plus-f-mode”
add file access mode to fam - for create-file only
When a file is opened/created, it returns a file identifier, wfileid that is used for all other file commands. All file commands also return a status value, wior, that is 0 for a successful operation and an implementation-defined non-zero value in the case of an error.
open-file ( c-addr u wfam – wfileid wior ) file “open-file”
create-file ( c-addr u wfam – wfileid wior ) file “create-file”
close-file ( wfileid – wior ) file “close-file”
delete-file ( c-addr u – wior ) file “delete-file”
rename-file ( c-addr1 u1 c-addr2 u2 – wior ) file-ext “rename-file”
Rename file c_addr1 u1 to new name c_addr2 u2
read-file ( c-addr u1 wfileid – u2 wior ) file “read-file”
Read u1 characters from file wfileid into the buffer at c_addr. A non-zero wior indicates an error. U2 indicates the length of the read data. End-of-file is not an error and is indicated by u2$<$u1 and wior=0.
read-line ( c_addr u1 wfileid – u2 flag wior ) file “read-line”
Reads a line from wfileid into the buffer at c_addr u1.
Gforth supports all three common line terminators: LF, CR and
CRLF. A non-zero wior indicates an error. A false
flag indicates that read-line has been invoked at
the end of the file. u2 indicates the line length (without
terminator): u2$<$u1 indicates that the line is u2
chars long; u2=u1 indicates that the line is at least
u1 chars long, the u1 chars of the buffer have been
filled with chars from the line, and the next slice of the line
with be read with the next read-line. If the line is
u1 chars long, the first read-line returns
u2=u1 and the next read-line returns u2=0.
key-file ( fd – key ) gforth-0.4 “key-file”
Read one character n from wfileid. This word disables
buffering for wfileid. If you want to read characters from a
terminal in non-canonical (raw) mode, you have to put the terminal
in non-canonical mode yourself (using the C interface); the
exception is stdin: Gforth automatically puts it into
non-canonical mode.
key?-file ( wfileid – f ) gforth-0.4 “key-q-file”
f is true if at least one character can be read from wfileid
without blocking. If you also want to use read-file or
read-line on the file, you have to call key?-file or
key-file first (these two words disable buffering).
file-eof? ( wfileid – flag ) gforth-0.6 “file-eof-query”
Flag is true if the end-of-file indicator for wfileid is set.
write-file ( c-addr u1 wfileid – wior ) file “write-file”
write-line ( c-addr u wfileid – ior ) file “write-line”
emit-file ( c wfileid – wior ) gforth-0.2 “emit-file”
flush-file ( wfileid – wior ) file-ext “flush-file”
file-status ( c-addr u – wfam wior ) file-ext “file-status”
file-position ( wfileid – ud wior ) file “file-position”
reposition-file ( ud wfileid – wior ) file “reposition-file”
file-size ( wfileid – ud wior ) file “file-size”
resize-file ( ud wfileid – wior ) file “resize-file”
slurp-file ( c-addr1 u1 – c-addr2 u2 ) gforth-0.6 “slurp-file”
c-addr1 u1 is the filename, c-addr2 u2 is the file’s contents
slurp-fid ( fid – addr u ) gforth-0.6 “slurp-fid”
addr u is the content of the file fid
stdin ( – wfileid ) gforth-0.4 “stdin”
The standard input file of the Gforth process.
stdout ( – wfileid ) gforth-0.2 “stdout”
The standard output file of the Gforth process.
stderr ( – wfileid ) gforth-0.2 “stderr”
The standard error output file of the Gforth process.