5.5.1 Creating streams

5.5.1.2 Options when creating file streams

When creating file streams, you can supply the following init-keywords to make in addition to those described in Section 5.5.1.1 on page 37:

if-exists:: An action to take if the file already exists.
if-does-not-exist:
: An action to take if the file does not already exist.
element-type:: How the elements of the underlying file are accessed.
asynchronous?:: Allows asynchronous writing of stream data to disk.
share-mode:: How the file can be accessed while the stream is operating on it.

The if-exists: init-keyword allows you to specify an action to take if the file named by filename already exists. The options are:

#f: The file is opened with the stream position at the beginning. This is the default when the stream's direction is #"input" or #"input-output".
#"new-version"
: If the underlying file system supports file versioning, a new version of the file is created. This is the default when the stream's direction is #"output".
: If the file system does not support file versioning, the default is #"replace" when the direction of the stream is #"output".
#"overwrite": Set the stream's position to the beginning of the file, but preserve the current contents of the file. This is useful when the direction is #"input-output" or #"output" and you want to overwrite an existing file.
#"replace": Delete the existing file and create a new file.
#"append": Set the stream's initial position to the end of the existing file so that all new output occurs at the end of the file. This option is only useful if the file is writeable.
#"truncate": If the file exists, it is truncated, setting the size of the file to 0. If the file does not exist, create a new file.
#"signal": Signal a <file-exists-error> condition.

The if-does-not-exist: init-keyword allows you to specify an action to take if the file named by filename does not exist. The options are:

#f: No action.
#"signal": Signal a <file-does-not-exist-error> condition. This is the default when the stream's direction is #"input".
#"create": Create a new zero-length file. This is the default when the stream's direction is #"output" or #"input-output".

Because creating a file stream always involves an attempt to open the underlying file, the aforementioned error conditions will occur during file stream instance initialization.

File permissions are checked when creating and opening file streams, and if the user attempts to open a file for input, and has no read permission, or to open a file for output, and has no write permission, then an <invalid-file-permissions-error> condition is signalled at the time the file stream is created.

The element-type: init-keyword controls how the elements of the underlying file are accessed. This allows file elements to be represented abstractly; for instance, contiguous elements could be treated as a single database record. The three possible element types are:

<byte-character>
: The file is accessed as a sequence of 8-bit characters.
<unicode-character>
: The file is accessed as a sequence of 16-bit Unicode characters.
<byte>: The file is accessed as a sequence of unsigned 8-bit integers.

The asynchronous?: init-keyword allows asynchronous writing of stream data to disk. If #f, whenever the stream has to write a buffer to disk, the thread which triggered the write must wait for the write to complete. If asynchronous? is #t, the write proceeds in parallel with the subsequent actions of the thread.

Note that asynchronous writes complicate error handling a bit. Any write error which occurs most likely occurs after the call which triggered the write. If this happens, the error is stored in a queue, and the next operation on that stream signals the error. If you close the stream with the wait? flag #f, the close happens asynchronously (after all queued writes complete) and errors may occur after close has returned. A method wait-for-io-completion is provided to catch any errors that may occur after close is called.

The share-mode: keyword determines how a file can be accessed by other streams while the stream has it open. The possible values are:

#"share-read": Allow other streams to be opened to the file for reading but not for writing.
#"share-write": Allow other streams to be opened for writing but not for reading.
#"share-read-write"
: Allow other streams to be opened for writing or reading.
#"exclusive": Do not allow other streams to be opened to this file.