### 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.

standard procedure: call-with-input-file filename procedure ¶
standard procedure: call-with-output-file filename procedure ¶

  It is an error if procedure does not accept one argument.

  These procedures obtain a textual port obtained by opening the named file for input or output as if by `open-input-file` or `open-output-file`. The port and procedure are then passed to a procedure equivalent to `call-with-port`.

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

  It is an error if procedure does not accept one argument.

  These procedures obtain a binary port obtained by opening the named file for input or output as if by `open-binary-input-file` or `open-binary-output-file`. The port and procedure are then passed to a procedure equivalent to `call-with-port`.

standard procedure: with-input-from-file filename thunk ¶
standard procedure: with-output-to-file filename thunk ¶

  The file named by filename is opened for input or output as if by `open-input-file` or `open-output-file`, and the new port is made to be the value returned by `current-input-port` or `current-output-port` (as used by `(read)`, `(write obj)`, and so forth). The thunk is then called with no arguments. When the thunk returns, the port is closed and the previous default is restored. It is an error if thunk does not accept zero arguments. Both procedures return the values yielded by thunk. If an escape procedure is used to escape from the continuation of these procedures, they behave exactly as if the current input or output port had been bound dynamically with `parameterize`.

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

  These procedures are deprecated; instead use `parameterize` along with `call-with-binary-input-file` or `call-with-binary-output-file`.

procedure: open-input-file filename ¶
procedure: open-binary-input-file filename ¶

  Takes a filename for an existing file and returns a textual input port or binary input port that is capable of delivering data from the file. If the file does not exist or cannot be opened, an error an error that satisfies `file-error?` is signaled.

standard procedure: open-output-file filename [append?] ¶
standard procedure: open-binary-output-file filename [append?] ¶

  Takes a filename naming an output file to be created and returns a textual output port or binary output port that is capable of writing data to a new file by that name. If a file with the given name already exists, the effect is unspecified. (In that case, MIT/GNU Scheme overwrites an existing file.) If the file cannot be opened, an error that satisfies `file-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 ¶
procedure: open-binary-i/o-file filename ¶

  Takes a filename referring to an existing file and returns an I/O port that is capable of both reading from and writing to the file. If the file cannot be opened, an error that satisfies `file-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: 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.