open Function

Summary

Creates, opens, and returns a file stream that is connected to a specified file.

Package

common-lisp

Signature

open filespec &key direction element-type external-format if-exists if-does-not-exist => stream

Arguments

Values

Description

The function open opens a file.

filespec, direction, if-exists and if-does-not-exist are used as specified by ANSI Common Lisp.

If direction is :probe, external-format is ignored. The element type and external format of the returned stream are undefined.

element-type defaults to the value of *default-character-element-type* (the ANSI standard default is character).

If external-format has a name which is not :default and the parameters include :eol-style, it is used as is.

Otherwise, the system decides which external format to use via guess-external-format. By default, this finds a match based on the filename; or (if that fails), looks in the EMACS-style (-*-) attribute line for an option called encoding or external-format or coding; or (if that fails), chooses from among likely encodings by analyzing the bytes near the start of the file. By default, it then also analyzes the start of the file for byte patterns indicating the end-of-line style, and uses a default end-of-line style if no such pattern is found. This behavior is configurable.

After the external-format has been determined, it is verified using valid-external-format-p; and an error is signaled if this check fails.

See 26.6 External Formats to translate Lisp characters from/to external encodings for more details about external formats.

If open gets :default as its element-type arg, it chooses the type on the basis of the external format. If open gets an element-type other than :default and the direction is :input or :io, the argument must be a supertype of the type of characters produced by the external format; if the direction is :output or :io, it must be a subtype of the type of characters accepted by the external format; if it does not satisfy these requirements, an error is signaled.

Standard stream input and output functions for character and binary data generally work in the obvious way on a file-stream with element-type base-char, (unsigned-byte 8) or (signed-byte 8). For example, read-sequence can be called with a string buffer and a binary file-stream: the character data is constructed from the input as if by code-char. Similarly write-sequence can be called with a string buffer and a binary file-stream: the output is converted from the character data as if by char-code. Also, 8-bit binary data can be read from and written to a base-char file-stream.

All standard stream I/O functions except for write-byte and read-byte have this flexibility.

See also

open in the Common Lisp HyperSpec
*default-character-element-type*
guess-external-format
set-file-dates
valid-external-format-p
26.6 External Formats to translate Lisp characters from/to external encodings