5.6 Reading from and writing to streams

5.6.6 Using file streams

The following operations can be performed on file streams.

close

G.f. method

close file-stream #key abort wait? => ()

: Closes a file stream. If the stream is asynchronous and wait? is false (its default value is #t), then a close request is merely enqueued to be performed after all pending write operations; otherwise the file is closed immediately and all underlying system resources held on behalf of the stream are freed.
: If abort?. is false (the default) all buffered data is written before closing; if abort? false, this data is discarded.
: If synchronize? (default value #f) is true, the file is flushed to the physical disk before closing -- this guarantees that no data is retained in the operating system's write cache. Calling close with synchronize? #t is equivalent to calling force-output with synchronize? true and then calling close.

wait-for-io-completion

Statement macro

wait-for-io-completion file-stream => ()

: If file-stream is asynchronous, waits for all pending write or close operations to complete and signals any queued errors. If file-stream is not asynchronous, returns immediately.

with-open-file

Statement macro

with-open-file (stream-var = filename, #rest keys) body end => values

: This macro provides a safe mechanism for working with file streams. It creates a file stream and binds it to stream-var, evaluates a body of code within the context of this binding, and then closes the stream. The macro calls close upon exiting body.
: The values of the last expression in body are returned.
: The keys are passed to the make method on <file-stream>.
: For example, the following expression yields the contents of file foo.text as a <byte-vector>:

with-open-file (fs = "foo.text", element-type: <byte>)
  read-to-end(fs)
end;

: It is roughly equivalent to:

begin
  let hidden-fs = #f;     // In case the user bashes fs variable
  block ()
    hidden-fs := make(<file-stream>, 
                    locator: "foo.text", element-type: <byte>);
    let fs = hidden-fs;
    read-to-end(fs);
  cleanup
    if (hidden-fs) close(hidden-fs) end;
  end block;
end;