11 The optional File-Access word set

11.1 Introduction

These words provide access to mass storage in the form of "files" under the following assumptions:

files are provided by a host operating system;
file names are represented as character strings;
the format of file names is determined by the host operating system;
an open file is identified by a single-cell file identifier (fileid);
file-state information (e.g., position, size) is managed by the host operating system;
file contents are accessed as a sequence of characters;
file read operations return an actual transfer count, which can differ from the requested transfer count.

11.2 Additional terms

file-access method:: A permissible means of accessing a file, such as "read/write" or "read only".
file position:: The character offset from the start of the file.
input file:: The file, containing a sequence of lines, that is the input source.

11.3 Additional usage requirements

11.3.1 Data types

Append table 11.1 to table 3.1.

Table 11.1: Data types


Symbol	Data type	Size on stack

fam	file access method	1 cell
fileid	file identifier	1 cell

11.3.1.1 File identifiers

File identifiers are implementation-dependent single-cell values that are passed to file operators to designate specific files. Opening a file assigns a file identifier, which remains valid until closed.

11.3.1.3 File access methods (11.3.1.3)

File access methods are implementation-defined single-cell values.

11.3.1.4 File names

A character string containing the name of the file. The file name may include an implementation-dependent path name. The format of file names is implementation defined.

11.3.2 Blocks in files

Blocks may, but need not, reside in files. When they do:

Block numbers may be mapped to one or more files by implementation-defined means. An ambiguous condition exists if a requested block number is not currently mapped;
An UPDATEd block that came from a file shall be transferred back to the same file.

11.3.3 Input source

The File-Access word set creates another input source for the text interpreter. When the input source is a text file, BLK shall contain zero, SOURCE-ID shall contain the fileid of that text file, and the input buffer shall contain one line of the text file. During text interpretation from a text file, the value returned by FILE-POSITION for the fileid returned by SOURCE-ID is undefined. A standard program shall not call REPOSITION-FILE on the fileid returned by SOURCE-ID.

Input with INCLUDED, INCLUDE-FILE, LOAD and EVALUATE shall be nestable in any order to at least eight levels.

A program that uses more than eight levels of input-file nesting has an environmental dependency. See: 3.3.3.5 Input buffers, 9 The optional Exception word set.

11.3.4 Other transient regions

The system provides transient buffers for S" and S\" strings. These buffers shall be no less than 80 characters in length, and there shall be at least two buffers. The system should be able to store two strings defined by sequential use of S" or S\". RAM-limited systems may have environmental restrictions on the number of buffers and their lifetimes.

11.3.5 Parsing

When parsing from a text file using a space delimiter, control characters shall be treated the same as the space character.

Lines of at least 128 characters shall be supported. A program that requires lines of more than 128 characters has an environmental dependency.

A program may reposition the parse area within the input buffer by manipulating the contents of >IN. More extensive repositioning can be accomplished using SAVE-INPUT and RESTORE-INPUT.

See: 3.4.1 Parsing.

11.4 Additional documentation requirements

11.4.1 System documentation

11.4.1.1 Implementation-defined options

file access methods used by 11.6.1.0765 BIN, 11.6.1.1010 CREATE-FILE,
11.6.1.1970 OPEN-FILE, 11.6.1.2054 R/O, 11.6.1.2056 R/W and 11.6.1.2425 W/O;
file exceptions;
file line terminator (11.6.1.2090 READ-LINE);
file name format (11.3.1.4 File names);
information returned by 11.6.2.1524 FILE-STATUS;
input file state after an exception (11.6.1.1717 INCLUDE-FILE, 11.6.1.1718 INCLUDED);
maximum depth of file input nesting (11.3.3 Input source);
maximum size of input line (11.3.5 Parsing);
methods for mapping block ranges to files (11.3.2 Blocks in files);
number of string buffers provided (11.3.4 Other transient regions);
size of string buffer used by 11.3.4 Other transient regions.

11.4.1.2 Ambiguous conditions

attempting to position a file outside its boundaries (11.6.1.2142 REPOSITION-FILE);
attempting to read from file positions not yet written (11.6.1.2080 READ-FILE,
11.6.1.2090 READ-LINE);
fileid is invalid (11.6.1.1717 INCLUDE-FILE);
I/O exception reading or closing fileid (11.6.1.1717 INCLUDE-FILE, 11.6.1.1718 INCLUDED);
named file cannot be opened (11.6.1.1718 INCLUDED);
requesting an unmapped block number (11.3.2 Blocks in files);
using 11.6.1.2218 SOURCE-ID when 7.6.1.0790 BLK is not zero;
a file is required while it is being REQUIRED (11.6.2.2144.50) or INCLUDED (11.6.1.1718);
a marker is defined outside and executed inside a file or vice versa, and the file is REQUIRED (11.6.2.2144.50) again;
the same file is required twice using different names (e.g., through symbolic links), or different files with the same name are provided to 11.6.2.2144.50 REQUIRED (by doing some renaming between the invocations of REQUIRED);
the stack effect of including with 11.6.2.2144.50 REQUIRED the file is not ( i * x -- i * x ).

11.4.1.3 Other system documentation

no additional requirements.

11.4.2 Program documentation

11.4.2.1 Environmental dependencies

requiring lines longer than 128 characters (11.3.5 Parsing);
using more than eight levels of input-file nesting (11.3.3 Input source).

11.4.2.2 Other program documentation

no additional requirements.

11.5 Compliance and labeling

11.5.1 Forth-2012 systems

The phrase "Providing the File Access word set" shall be appended to the label of any Standard System that provides all of the File Access word set.

The phrase "Providing name(s) from the File Access Extensions word set" shall be appended to the label of any Standard System that provides portions of the File Access Extensions word set.

The phrase "Providing the File Access Extensions word set" shall be appended to the label of any Standard System that provides all of the File Access and File Access Extensions word sets.

11.5.2 Forth-2012 programs

The phrase "Requiring the File Access word set" shall be appended to the label of Standard Programs that require the system to provide the File Access word set.

The phrase "Requiring name(s) from the File Access Extensions word set" shall be appended to the label of Standard Programs that require the system to provide portions of the File Access Extensions word set.

The phrase "Requiring the File Access Extensions word set" shall be appended to the label of Standard Programs that require the system to provide all of the File Access and File Access Extensions word sets.