7.6.2.17 R6RS File Ports

The facilities described in this section are exported by the (rnrs io ports) module.

Scheme Syntax: buffer-mode buffer-mode-symbol

buffer-mode-symbol must be a symbol whose name is one of none, line, and block. The result is the corresponding symbol, and specifies the associated buffer mode. See Buffering, for a discussion of these different buffer modes. To control the amount of buffering, use setvbuf instead. Note that only the name of buffer-mode-symbol is significant.

See Buffering, for a discussion of port buffering.

Scheme Procedure: buffer-mode? obj

Returns #t if the argument is a valid buffer-mode symbol, and returns #f otherwise.

When opening a file, the various procedures accept a file-options object that encapsulates flags to specify how the file is to be opened. A file-options object is an enum-set (see rnrs enums) over the symbols constituting valid file options.

A file-options parameter name means that the corresponding argument must be a file-options object.

Scheme Syntax: file-options file-options-symbol ...

Each file-options-symbol must be a symbol.

The file-options syntax returns a file-options object that encapsulates the specified options.

When supplied to an operation that opens a file for output, the file-options object returned by (file-options) specifies that the file is created if it does not exist and an exception with condition type &i/o-file-already-exists is raised if it does exist. The following standard options can be included to modify the default behavior.

no-create

If the file does not already exist, it is not created; instead, an exception with condition type &i/o-file-does-not-exist is raised. If the file already exists, the exception with condition type &i/o-file-already-exists is not raised and the file is truncated to zero length.

no-fail

If the file already exists, the exception with condition type &i/o-file-already-exists is not raised, even if no-create is not included, and the file is truncated to zero length.

no-truncate

If the file already exists and the exception with condition type &i/o-file-already-exists has been inhibited by inclusion of no-create or no-fail, the file is not truncated, but the port’s current position is still set to the beginning of the file.

These options have no effect when a file is opened only for input. Symbols other than those listed above may be used as file-options-symbols; they have implementation-specific meaning, if any.

Note: Only the name of file-options-symbol is significant.

Scheme Procedure: open-file-input-port filename

Scheme Procedure: open-file-input-port filename file-options

Scheme Procedure: open-file-input-port filename file-options buffer-mode

Scheme Procedure: open-file-input-port filename file-options buffer-mode maybe-transcoder

maybe-transcoder must be either a transcoder or #f.

The open-file-input-port procedure returns an input port for the named file. The file-options and maybe-transcoder arguments are optional.

The file-options argument, which may determine various aspects of the returned port, defaults to the value of (file-options).

The buffer-mode argument, if supplied, must be one of the symbols that name a buffer mode. The buffer-mode argument defaults to block.

If maybe-transcoder is a transcoder, it becomes the transcoder associated with the returned port.

If maybe-transcoder is #f or absent, the port will be a binary port and will support the port-position and set-port-position! operations. Otherwise the port will be a textual port, and whether it supports the port-position and set-port-position! operations is implementation-dependent (and possibly transcoder-dependent).

Scheme Procedure: open-file-output-port filename

Scheme Procedure: open-file-output-port filename file-options

Scheme Procedure: open-file-output-port filename file-options buffer-mode

Scheme Procedure: open-file-output-port filename file-options buffer-mode maybe-transcoder

maybe-transcoder must be either a transcoder or #f.

The open-file-output-port procedure returns an output port for the named file.

The file-options argument, which may determine various aspects of the returned port, defaults to the value of (file-options).

The buffer-mode argument, if supplied, must be one of the symbols that name a buffer mode. The buffer-mode argument defaults to block.

If maybe-transcoder is a transcoder, it becomes the transcoder associated with the port.

If maybe-transcoder is #f or absent, the port will be a binary port and will support the port-position and set-port-position! operations. Otherwise the port will be a textual port, and whether it supports the port-position and set-port-position! operations is implementation-dependent (and possibly transcoder-dependent).