6.18.2 General files

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-1.0 “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.