6.14.9.1 File Ports

The following procedures are used to open file ports. See also open, for an interface to the Unix open system call.

Most systems have limits on how many files can be open, so it’s strongly recommended that file ports be closed explicitly when no longer required (see section Ports).

Scheme Procedure: open-file filename mode

C Function: scm_open_file (filename, mode)

Open the file whose name is filename, and return a port representing that file. The attributes of the port are determined by the mode string. The way in which this is interpreted is similar to C stdio. The first character must be one of the following:

‘r’

Open an existing file for input.

‘w’

Open a file for output, creating it if it doesn’t already exist or removing its contents if it does.

‘a’

Open a file for output, creating it if it doesn’t already exist. All writes to the port will go to the end of the file. The "append mode" can be turned off while the port is in use see section fcntl

The following additional characters can be appended:

‘+’

Open the port for both input and output. E.g., r+: open an existing file for both input and output.

‘0’

Create an "unbuffered" port. In this case input and output operations are passed directly to the underlying port implementation without additional buffering. This is likely to slow down I/O operations. The buffering mode can be changed while a port is in use see section setvbuf

‘l’

Add line-buffering to the port. The port output buffer will be automatically flushed whenever a newline character is written.

‘b’

Use binary mode. On DOS systems the default text mode converts CR+LF in the file to newline for the program, whereas binary mode reads and writes all bytes unchanged. On Unix-like systems there is no such distinction, text files already contain just newlines and no conversion is ever made. The b flag is accepted on all systems, but has no effect on Unix-like systems.

(For reference, Guile leaves text versus binary up to the C library, b here just adds O_BINARY to the underlying open call, when that flag is available.)

Also, open the file using the 8-bit character encoding "ISO-8859-1", ignoring any coding declaration or port encoding.

Note that, when reading or writing binary data with ports, the bytevector ports in the (rnrs io ports) module are preferred, as they return vectors, and not strings (see section R6RS I/O Ports).

If a file cannot be opened with the access requested, open-file throws an exception.

When the file is opened, this procedure will scan for a coding declaration (see section Character Encoding of Source Files). If present will use that encoding for interpreting the file. Otherwise, the port’s encoding will be used. To suppress this behavior, open the file in binary mode and then set the port encoding explicitly using set-port-encoding!.

In theory we could create read/write ports which were buffered in one direction only. However this isn’t included in the current interfaces.

Scheme Procedure: open-input-file filename

Open filename for input. Equivalent to

(open-file filename "r")

Scheme Procedure: open-output-file filename

Open filename for output. Equivalent to

(open-file filename "w")

Scheme Procedure: call-with-input-file filename proc

Scheme Procedure: call-with-output-file filename proc

Open filename for input or output, and call (proc port) with the resulting port. Return the value returned by proc. filename is opened as per open-input-file or open-output-file respectively, and an error is signaled if it cannot be opened.

When proc returns, the port is closed. If proc does not return (e.g. if it throws an error), then the port might not be closed automatically, though it will be garbage collected in the usual way if not otherwise referenced.

Scheme Procedure: with-input-from-file filename thunk

Scheme Procedure: with-output-to-file filename thunk

Scheme Procedure: with-error-to-file filename thunk

Open filename and call (thunk) with the new port setup as respectively the current-input-port, current-output-port, or current-error-port. Return the value returned by thunk. filename is opened as per open-input-file or open-output-file respectively, and an error is signaled if it cannot be opened.

When thunk returns, the port is closed and the previous setting of the respective current port is restored.

The current port setting is managed with dynamic-wind, so the previous value is restored no matter how thunk exits (eg. an exception), and if thunk is re-entered (via a captured continuation) then it’s set again to the FILENAME port.

The port is closed when thunk returns normally, but not when exited via an exception or new continuation. This ensures it’s still ready for use if thunk is re-entered by a captured continuation. Of course the port is always garbage collected and closed in the usual way when no longer referenced anywhere.

Scheme Procedure: port-mode port

C Function: scm_port_mode (port)

Return the port modes associated with the open port port. These will not necessarily be identical to the modes used when the port was opened, since modes such as "append" which are used only during port creation are not retained.

Scheme Procedure: port-filename port

C Function: scm_port_filename (port)

Return the filename associated with port, or #f if no filename is associated with the port.

port must be open, port-filename cannot be used once the port is closed.

Scheme Procedure: set-port-filename! port filename

C Function: scm_set_port_filename_x (port, filename)

Change the filename associated with port, using the current input port if none is specified. Note that this does not change the port’s source of data, but only the value that is returned by port-filename and reported in diagnostic output.

Scheme Procedure: file-port? obj

C Function: scm_file_port_p (obj)

Determine whether obj is a port that is related to a file.