Next: , Previous: Forth source files, Up: Files

5.17.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”

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-line       c_addr u1 wfileid – u2 flag wior         file       “read-line”

key-file       wfileid – c        gforth       “paren-key-file”

Read one character c 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       “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).

write-file       c-addr u1 wfileid – wior        file       “write-file”

write-line       c-addr u fileid – ior         file       “write-line”

emit-file       c wfileid – wior        gforth       “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       “slurp-file”

c-addr1 u1 is the filename, c-addr2 u2 is the file's contents

slurp-fid       fid – addr u         gforth       “slurp-fid”

addr u is the content of the file fid

stdin       – wfileid        gforth       “stdin”

The standard input file of the Gforth process.

stdout       – wfileid        gforth       “stdout”

The standard output file of the Gforth process.

stderr       – wfileid        gforth       “stderr”

The standard error output file of the Gforth process.