11.6.1.2080
READ-FILE
 
FILE
 
( c-addr u1 fileid -- u2 ior )

Read u1 consecutive characters to c-addr from the current position of the file identified by fileid.

If u1 characters are read without an exception, ior is zero and u2 is equal to u1.

If the end of the file is reached before u1 characters are read, ior is zero and u2 is the number of characters actually read.

If the operation is initiated when the value returned by FILE-POSITION is equal to the value returned by FILE-SIZE for the file identified by fileid, ior is zero and u2 is zero.

If an exception occurs, ior is the implementation-defined I/O result code, and u2 is the number of characters transferred to c-addr without an exception.

An ambiguous condition exists if the operation is initiated when the value returned by FILE-POSITION is greater than the value returned by FILE-SIZE for the file identified by fileid, or if the requested operation attempts to read portions of the file not written.

At the conclusion of the operation, FILE-POSITION returns the next file position after the last character read.

See:
A.11.6.1.2080 READ-FILE.

Rationale:
A typical sequential file-processing algorithm might look like:
BEGIN                        ( )
    ... READ-FILE THROW      ( length )
?DUP WHILE                   ( length )
    ...                      ( )
REPEAT                       ( )
In this example, THROW is used to handle exception conditions, which are reported as non-zero values of the ior return value from READ-FILE. End-of-file is reported as a zero value of the "length" return value.