Common Lisp the Language, 2nd Edition

23.2. Opening and Closing Files

When a file is opened, a stream object is constructed to serve as the file system's ambassador to the Lisp environment; operations on the stream are reflected by operations on the file in the file system. The act of closing the file (actually, the stream) ends the association; the transaction with the file system is terminated, and input/output may no longer be performed on the stream. The stream function close may be used to close a file; the functions described below may be used to open them. The basic operation is open, but with-open-file is usually more convenient for most applications.

[Function]
open filename &key :direction :element-type :if-exists :if-does-not-exist :external-format

X3J13 voted in June 1989 (MORE-CHARACTER-PROPOSAL)   to add to the function open a new keyword argument :external-format. This argument did not appear in the preceding argument description in the first edition.

This returns a stream that is connected to the file specified by filename. The filename is the name of the file to be opened; it may be a string, a pathname, or a stream. (If the filename is a stream, then it is not closed first or otherwise affected; it is used merely to provide a file name for the opening of a new stream.)

X3J13 voted in January 1989 (STREAM-ACCESS)   to specify that the result of open, if it is a stream, is always a stream of type file-stream.

X3J13 voted in March 1988 (PATHNAME-STREAM)   to specify exactly which streams may be used as pathnames. See section 23.1.6.

X3J13 voted in January 1989 (CLOSED-STREAM-OPERATIONS)   to specify that open is unaffected by whether the first argument, if a stream, is open or closed. If the first argument is a stream, open behaves as if the function pathname were applied to the stream and the resulting pathname used instead.

X3J13 voted in June 1989 (PATHNAME-WILD)   to clarify that open accepts only non-wild pathnames; an error is signaled if wild-pathname-p would be true of filename.

X3J13 voted in June 1989 (PATHNAME-LOGICAL)   to require open to accept logical pathnames (see section 23.1.5).

The keyword arguments specify what kind of stream to produce and how to handle errors:

:direction

This argument specifies whether the stream should handle input, output, or both.

:input

The result will be an input stream. This is the default.

:output

The result will be an output stream.

:io

The result will be a bidirectional stream.

:probe

The result will be a no-directional stream (in effect, the stream is created and then closed). This is useful for determining whether a file exists without actually setting up a complete stream.

:element-type

This argument specifies the type of the unit of transaction for the stream. Anything that can be recognized as being a finite subtype of character or integer is acceptable. In particular, the following types are recognized:

string-char

The unit of transaction is a string-character. The functions read-char and/or write-char may be used on the stream. This is the default.

character

The unit of transaction is any character, not just a string-character. The functions read-char and/or write-char may be used on the stream.

X3J13 voted in June 1989 (MORE-CHARACTER-PROPOSAL)   to eliminate the type string-char, add the type base-character, and redefine open to use the type character as the default :element-type.

The preceding two possibilities should therefore be replaced by the following.

character

The unit of transaction is any character, not just a string-character. The functions read-char and write-char (depending on the value of the :direction argument) may be used on the stream. This is the default.

base-character

The unit of transaction is a base character. The functions read-char and write-char (depending on the value of the :direction argument) may be used on the stream.

(unsigned-byte n)

The unit of transaction is an unsigned byte (a non-negative integer) of size n. The functions read-byte and/or write-byte may be used on the stream.

unsigned-byte

The unit of transaction is an unsigned byte (a non-negative integer); the size of the byte is determined by the file system. The functions read-byte and/or write-byte may be used on the stream.

(signed-byte n)

The unit of transaction is a signed byte of size n. The functions read-byte and/or write-byte may be used on the stream.

signed-byte

The unit of transaction is a signed byte; the size of the byte is determined by the file system. The functions read-byte and/or write-byte may be used on the stream.

bit

The unit of transaction is a bit (values 0 and 1). The functions read-byte and/or write-byte may be used on the stream.

(mod n)

The unit of transaction is a non-negative integer less than n. The functions read-byte and/or write-byte may be used on the stream.

:default

The unit of transaction is to be determined by the file system, based on the file it finds. The type can be determined by using the function stream-element-type.

:if-exists

This argument specifies the action to be taken if the :direction is :output or :io and a file of the specified name already exists. If the direction is :input or :probe, this argument is ignored.

:error

Signals an error. This is the default when the version component of the filename is not :newest.

:new-version

Creates a new file with the same file name but with a larger version number. This is the default when the version component of the filename is :newest.

:rename

Renames the existing file to some other name and then creates a new file with the specified name.

:rename-and-delete

Renames the existing file to some other name and then deletes it (but does not expunge it, on those systems that distinguish deletion from expunging). Then create a new file with the specified name.

:overwrite

Uses the existing file. Output operations on the stream will destructively modify the file. If the :direction is :io, the file is opened in a bidirectional mode that allows both reading and writing. The file pointer is initially positioned at the beginning of the file; however, the file is not truncated back to length zero when it is opened. This mode is most useful when the file-position function can be used on the stream.

:append

Uses the existing file. Output operations on the stream will destructively modify the file. The file pointer is initially positioned at the end of the file. If the :direction is :io, the file is opened in a bidirectional mode that allows both reading and writing.

:supersede

Supersedes the existing file. If possible, the implementation should arrange not to destroy the old file until the new stream is closed, against the possibility that the stream will be closed in ``abort'' mode (see close). This differs from :new-version in that :supersede creates a new file with the same name as the old one, rather than a file name with a higher version number.

nil

Does not create a file or even a stream, but instead simply returns nil to indicate failure.

If the :direction is :output or :io and the value of :if-exists is :new-version, then the version of the (newly created) file that is opened will be a version greater than that of any other file in the file system whose other pathname components are the same as those of filename.

If the :direction is :input or :probe or the value of :if-exists is not :new-version, and the version component of the filename is :newest, then the file opened is that file already existing in the file system that has a version greater than that of any other file in the file system whose other pathname components are the same as those of filename.

Some file systems permit yet other actions to be taken when a file already exists; therefore, some implementations provide implementation-specific :if-exist options.

As an example, suppose that a file system does not support distinct file versions and does not distinguish the notions of deletion and expunging (in some file systems file deletion is reversible until an expunge operation is performed). Then :new-version might be treated the same as :rename or :supersede, and :rename-and-delete might be treated the same as :supersede.

If it is utterly impossible for an implementation to handle some option in a manner close to what is specified here, it may simply signal an error. The opening of files is an area where complete portability is too much to hope for; the intent here is simply to make things as portable as possible by providing specific names for a range of commonly supportable options.

:if-does-not-exist

This argument specifies the action to be taken if a file of the specified name does not already exist.

:error

Signals an error. This is the default if the :direction is :input, or if the :if-exists argument is :overwrite or :append.

:create

Creates an empty file with the specified name and then proceeds as if it had already existed (but do not perform any processing directed by the :if-exists argument). This is the default if the :direction is :output or :io, and the :if-exists argument is anything but :overwrite or :append.

nil

Does not create a file or even a stream, but instead simply returns nil to indicate failure. This is the default if the :direction is :probe.

X3J13 voted in June 1989 (MORE-CHARACTER-PROPOSAL)   to add to the function open a new keyword argument :external-format.

:external-format

This argument specifies an implementation-recognized scheme for representing characters in files. The default value is :default and is implementation-defined but must support the base characters. An error is signaled if the implementation does recognize the specified format.

This argument may be specified if the :direction argument is :input, :output, or :io. It is an error to write a character to the resulting stream that cannot be represented by the specified file format. (However, the #\Newline character cannot produce such an error; implementations must provide appropriate line division behavior for all character streams.)

See stream-external-format.

When the caller is finished with the stream, it should close the file by using the close function. The with-open-file form does this automatically, and so is preferred for most purposes. open should be used only when the control structure of the program necessitates opening and closing of a file in some way more complex than provided by with-open-file. It is suggested that any program that uses open directly should use the special form unwind-protect to close the file if an abnormal exit occurs.

[Macro]

with-open-file (stream filename {options}*)
       {declaration}* {form}*

with-open-file evaluates the forms of the body (an implicit progn) with the variable stream bound to a stream that reads or writes the file named by the value of filename. The options are evaluated and are used as keyword arguments to the function open.

When control leaves the body, either normally or abnormally (such as by use of throw), the file is automatically closed. If a new output file is being written, and control leaves abnormally, the file is aborted and the file system is left, so far as possible, as if the file had never been opened. Because with-open-file always closes the file, even when an error exit is taken, it is preferred over open for most applications.

filename is the name of the file to be opened; it may be a string, a pathname, or a stream.

X3J13 voted in March 1988 (PATHNAME-STREAM)   to specify exactly which streams may be used as pathnames. See section 23.1.6.

X3J13 voted in June 1989 (PATHNAME-WILD)   to clarify that with-open-file accepts only non-wild pathnames; an error is signaled if wild-pathname-p would be true of the filename argument.

X3J13 voted in June 1989 (PATHNAME-LOGICAL)   to require with-open-file to accept logical pathnames (see section 23.1.5).

For example:

(with-open-file (ifile name 
                 :direction :input) 
  (with-open-file (ofile (merge-pathname-defaults ifile 
                                                  nil 
                                                  "out") 
                         :direction :output 
                         :if-exists :supersede) 
    (transduce-file ifile ofile)))

X3J13 voted in June 1989 (WITH-OPEN-FILE-DOES-NOT-EXIST)   to specify that the variable stream is not always bound to a stream; rather it is bound to whatever would be returned by a call to open. For example, if the options include :if-does-not-exist nil, stream will be bound to nil if the file does not exist. In this case the value of stream should be tested within the body of the with-open-file form before it is used as a stream. For example:

(with-open-file (ifile name 
                 :direction :input 
                 :if-does-not-exist nil) 
  ;; Process the file only if it actually exists. 
  (when (streamp name)
    (compile-cobol-program ifile)))