The following procedures are used to open file ports.
See also open, for an interface
to the Unix open system call.
All file access uses the “LFS” large file support functions when available, so files bigger than 2 gibibytes (2^31 bytes) can be read and written on a 32-bit system.
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 Ports).
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:
Open an existing file for input.
Open a file for output, creating it if it doesn’t already exist or removing its contents if it does.
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 fcntl
The following additional characters can be appended:
Open the underlying file in binary mode, if supported by the system. Also, open the file using the binary-compatible character encoding "ISO-8859-1", ignoring the default port encoding.
Open the port for both input and output. E.g., r+: open
an existing file for both input and output.
Mark the underlying file descriptor as close-on-exec, as per the
O_CLOEXEC flag.
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 Buffering).
Add line-buffering to the port. The port output buffer will be automatically flushed whenever a newline character is written.
Use binary mode, ensuring that each byte in the file will be read as one Scheme character.
To provide this property, the file will be opened with the 8-bit character encoding "ISO-8859-1", ignoring the default port encoding. See Ports, for more information on port encodings.
Note that while it is possible to read and write binary data as characters or strings, it is usually better to treat bytes as octets, and byte sequences as bytevectors. See Binary I/O, for more.
This option had another historical meaning, for DOS compatibility: in
the default (textual) mode, DOS reads a CR-LF sequence as one LF byte.
The b flag prevents this from happening, adding O_BINARY
to the underlying open call. Still, the flag is generally useful
because of its port encoding ramifications.
Unless binary mode is requested, the character encoding of the new port
is determined as follows: First, if guess-encoding is true, the
file-encoding procedure is used to guess the encoding of the file
(see Character Encoding of Source Files). If guess-encoding
is false or if file-encoding fails, encoding is used unless
it is also false. As a last resort, the default port encoding is used.
See Ports, for more information on port encodings. It is an error to
pass a non-false guess-encoding or encoding if binary mode
is requested.
If a file cannot be opened with the access requested, open-file
throws an exception.
Open filename for input. If binary is true, open the port
in binary mode, otherwise use text mode. encoding and
guess-encoding determine the character encoding as described above
for open-file. Equivalent to
(open-file filename
(if binary "rb" "r")
#:guess-encoding guess-encoding
#:encoding encoding)
Open filename for output. If binary is true, open the port
in binary mode, otherwise use text mode. encoding specifies the
character encoding as described above for open-file. Equivalent
to
(open-file filename
(if binary "wb" "w")
#:encoding encoding)
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.
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.
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.
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.
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.