Next: , Previous: Ports, Up: Input/Output

14.2 File Ports

Before Scheme can access a file for reading or writing, it is necessary to open a port to the file. This section describes procedures used to open ports to files. Such ports are closed (like any other port) by close-port. File ports are automatically closed if and when they are reclaimed by the garbage collector.

Before opening a file for input or output, by whatever method, the filename argument is converted to canonical form by calling the procedure merge-pathnames with filename as its sole argument. Thus, filename can be either a string or a pathname, and it is merged with the current pathname defaults to produce the pathname that is then opened.

Any file can be opened in one of two modes, normal or binary. Normal mode is for accessing text files, and binary mode is for accessing other files. Unix does not distinguish these modes, but Windows do: in normal mode, their file ports perform newline translation, mapping between the carriage-return/linefeed sequence that terminates text lines in files, and the #\newline that terminates lines in Scheme. In binary mode, such ports do not perform newline translation. Unless otherwise mentioned, the procedures in this section open files in normal mode.

— procedure: open-input-file filename

Takes a filename referring to an existing file and returns an input port capable of delivering characters from the file. If the file cannot be opened, an error of type condition-type:file-operation-error is signalled.

— procedure: open-output-file filename [append?]

Takes a filename referring to an output file to be created and returns an output port capable of writing characters to a new file by that name. If the file cannot be opened, an error of type condition-type:file-operation-error is signalled. The optional argument append? is an MIT/GNU Scheme extension. If append? is given and not #f, the file is opened in append mode. In this mode, the contents of the file are not overwritten; instead any characters written to the file are appended to the end of the existing contents. If the file does not exist, append mode creates the file and writes to it in the normal way.

— procedure: open-i/o-file filename

Takes a filename referring to an existing file and returns an I/O port capable of both reading and writing the file. If the file cannot be opened, an error of type condition-type:file-operation-error is signalled. This procedure is often used to open special files. For example, under unix this procedure can be used to open terminal device files, pty device files, and named pipes.

— procedure: open-binary-input-file filename
— procedure: open-binary-output-file filename [append?]
— procedure: open-binary-i/o-file filename

These procedures open files in binary mode. In all other respects they are identical to open-input-file, open-output-file, and open-i/o-file, respectively.

— procedure: close-all-open-files

This procedure closes all file ports that are open at the time that it is called, and returns an unspecified value.

— procedure: call-with-input-file filename procedure
— procedure: call-with-output-file filename procedure

These procedures call procedure with one argument: the port obtained by opening the named file for input or output, respectively. If the file cannot be opened, an error of type condition-type:file-operation-error is signalled. If procedure returns, then the port is closed automatically and the value yielded by procedure is returned. If procedure does not return, then the port will not be closed automatically unless it is reclaimed by the garbage collector.1

— procedure: call-with-binary-input-file filename procedure
— procedure: call-with-binary-output-file filename procedure

These procedures open files in binary mode. In all other respects they are identical to call-with-input-file and call-with-output-file, respectively.

— procedure: with-input-from-file filename thunk
— procedure: with-output-to-file filename thunk

Thunk must be a procedure of no arguments. The file is opened for input or output, an input or output port connected to it is made the default value returned by current-input-port or current-output-port, and the thunk is called with no arguments. When the thunk returns, the port is closed and the previous default is restored. with-input-from-file and with-output-to-file return the value yielded by thunk. If an escape procedure is used to escape from the continuation of these procedures, their behavior is implementation-dependent; in that situation MIT/GNU Scheme leaves the files open.

— procedure: with-input-from-binary-file filename thunk
— procedure: with-output-to-binary-file filename thunk

These procedures open files in binary mode. In all other respects they are identical to with-input-from-file and with-output-to-file, respectively.

Footnotes

[1] Because Scheme's escape procedures have unlimited extent, it is possible to escape from the current continuation but later to escape back in. If implementations were permitted to close the port on any escape from the current continuation, then it would be impossible to write portable code using both call-with-current-continuation and call-with-input-file or call-with-output-file.