open
open filespec &key direction element-type if-exists if-does-not-exist external-format → stream
filespec—a pathname designator.
direction—one of :input, :output, :io, or :probe. The default is :input.
23.2.0 9
23.2.0 10
23.2.0 11
23.2.0 12
23.2.0 13
23.2.0 14
23.2.0 15
23.2.0 16
23.2.0 17
23.2.0 18
23.2.0 19element-type—a type specifier for recognizable subtype of character; or a type specifier for a finite recognizable subtype of integer; or one of the symbols signed-byte, unsigned-byte, or :default. The default is character.
23.2.0 21
23.2.0 22
23.2.0 23
23.2.0 24
23.2.0 25
23.2.0 26
23.2.0 27
23.2.0 28if-exists—one of :error, :new-version, :rename, :rename-and-delete, :overwrite, :append, :supersede, or nil. The default is :new-version if the version component of filespec is :newest, or :error otherwise.
23.2.0 35
23.2.0 36if-does-not-exist—one of :error, :create, or nil. The default is :error if direction is :input or if-exists is :overwrite or :append; :create if direction is :output or :io, and if-exists is neither :overwrite nor :append; or nil when direction is :probe.
external-format—an external file format designator. The default is :default.
stream—a file stream or nil.
23.2.0 2
23.2.0 3open creates, opens, and returns a file stream that is connected to the file specified by filespec. Filespec is the name of the file to be opened. Moon: Mostly redundant.
\issue{CLOSED-STREAM-FUNCTIONS:ALLOW-INQUIRY}
If \param{filespec} is a \term{stream},
\param{filespec} effectively
becomes {\tt (pathname \param{filespec})}. \funref{open}
can be used on either an open or a closed \term{stream},
\endissue{CLOSED-STREAM-FUNCTIONS:ALLOW-INQUIRY}
and the \term{stream} is not
closed first or otherwise affected.
\issue{PATHNAME-STREAM}
Also, if \param{filespec} is a \term{stream},
that \term{stream}
can only have been originally opened by
\funref{open} or \macref{with-open-file},
or is a \term{synonym stream} whose \term{symbol} is bound
to a \term{stream} originally opened by
\funref{open} or \macref{with-open-file}.
If \param{filespec} is a \term{pathname} (as returned by \funref{pathname})
it represents the name used to open the file. This might be, but is
not required to be, the actual name of the file.
\issue{PATHNAME-LOGICAL:ADD}
If \param{filespec} is a \term{logical pathname}, it is translated
into a physical pathname as if by calling \funref{translate-logical-pathname}.
\endissue{PATHNAME-LOGICAL:ADD}
Salvaged from the above. -kmp 16-Feb-92If the filespec designator is a stream, that stream is not closed first or otherwise affected.
The keyword arguments to open specify the characteristics of the file stream that is returned, and how to handle errors.
23.2.0 30If direction is :input Barrett: defaults
, not supplied,or :probe, or if if-exists is not :new-version and the version component of the filespec 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 filespec.
23.2.0 31
23.2.0 32An implementation is required to recognize all of the open keyword options and to do something reasonable in the context of the host operating system. For example, if a file system does not support distinct file versions and does not distinguish the notions of deletion and expunging, :new-version might be treated the same as :rename or :supersede, and :rename-and-delete might be treated the same as :supersede.
:direction
These are the possible values for direction, and how they affect the nature of the stream that is created:
:input
Causes the creation of an input file stream.
:output
Causes the creation of an output file stream.
:io
Causes the creation of a bidirectional file stream.
:probe
Causes the creation of a “no-directional” file stream; in effect, the file stream is created and then closed prior to being returned by open.
:element-type
The element-type specifies the unit of transaction for the file stream. This is the only salvaged info from the next block of commented out stuff. -kmp 14-Feb-92If it is :default, the unit is determined by file system, possibly based on the file.
:if-exists
if-exists specifies the action to be taken if direction is :output or :io and a file of the name filespec already exists. If direction is :input, not supplied, or :probe, if-exists is ignored. These are the results of open as modified by if-exists: 23.2.0 29
23.2.0 20
:error
An error of type file-error is signaled.
:new-version
A new file is created with a larger version number.
:rename
The existing file is renamed to some other name and then a new file is created.
:rename-and-delete
The existing file is renamed to some other name, then it is deleted but not expunged, and then a new file is created.
:overwrite
Output operations on the stream destructively modify the existing file. If 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.
:append
Output operations on the stream destructively modify the existing file. The file pointer is initially positioned at the end of the file.
If direction is :io, the file is opened in a bidirectional mode that allows both reading and writing.
:supersede
The existing file is superseded; that is, a new file with the same name as the old one is created. If possible, the implementation should not destroy the old file until the new stream is closed.
nil
No file or stream is created; instead, nil is returned to indicate failure.
:if-does-not-exist
23.2.0 34if-does-not-exist specifies the action to be taken if a file of name filespec does not already exist. These are the results of open as modified by if-does-not-exist:
23.2.0 37
:error
An error of type file-error is signaled.
:create
An empty file is created. Processing continues as if the file had already existed but no processing as directed by if-exists is performed.
nil
No file or stream is created; instead, nil is returned to indicate failure.
:external-format
This option selects an external file format for the file: There are no conforming
\term{values} for \param{external-format} other than the default \term{value},
\kwd{default}, which selects a format that can accomodate at least the
\term{base characters}. \term{Implementations} are permitted to define
additional external file formats.The only standardized value for this option is :default, although implementations are permitted to define additional external file formats and implementation-dependent values returned by stream-external-format can also be used by conforming programs.
The \param{external-format} is meaningful for \term{input}, \term{output}, and \term{bidirectional} \term{streams}. Rewritten by KMP based on discussions with RWK:The external-format is meaningful for any kind of file stream whose element type is a subtype of character. This option is ignored for streams for which it is not meaningful; however, implementations may define other element types for which it is meaningful. End of rewrite.The consequences are unspecified if a character is written that cannot be represented by the given external file format.
23.2.0 1When a file is opened, a file stream is constructed to serve as the file system's ambassador to the Lisp environment; operations on the file stream are reflected by operations on the file in the file system.
A file can be deleted, renamed, or destructively modified by open.
For information about opening relative pathnames, see Section 19.2.3 (Merging Pathnames).
(open filespec :direction :probe) → #<Closed Probe File Stream...>
(setq q (merge-pathnames (user-homedir-pathname) "test"))
→ #<PATHNAME :HOST NIL :DEVICE device-name :DIRECTORY directory-name
:NAME "test" :TYPE NIL :VERSION :NEWEST>
(open filespec :if-does-not-exist :create) → #<Input File Stream...>
(setq s (open filespec :direction :probe)) → #<Closed Probe File Stream...>
(truename s) → #<PATHNAME :HOST NIL :DEVICE device-name :DIRECTORY
directory-name :NAME filespec :TYPE extension :VERSION 1>
(open s :direction :output :if-exists nil) → NIL
The nature and state of the host computer's file system.
If if-exists is :error, (subject to the constraints on the meaning of if-exists listed above), an error of type file-error is signaled.
If if-does-not-exist is :error (subject to the constraints on the meaning of if-does-not-exist listed above), an error of type file-error is signaled.
23.2.0 33If it is impossible for an implementation to handle some option in a manner close to what is specified here, an error of type error might be signaled.
!!! Moon: I would have assumed type-error rather than file-error for this one.
I have no strong opinion, though.An error of type file-error is signaled if (wild-pathname-p filespec) returns true.
An error of type error is signaled if the external-format is not understood by the implementation.
Refer to minutes of Dec-91 meeting (issue STREAM-ELEMENT-TYPE-UPGRADING) for an explanation of where this came from. -kmp 12-Feb-92The various file systems in existence today have widely differing capabilities, and some aspects of the file system are beyond the scope of this specification to define. A given implementation might not be able to support all of these options in exactly the manner stated. An implementation is required to recognize all of these option keywords and to try to do something “reasonable” in the context of the host file system. Where necessary to accomodate the file system, an implementation deviate slightly from the semantics specified here without being disqualified for consideration as a conforming implementation. If it is utterly impossible for an implementation to handle some option in a manner similar to what is specified here, it may simply signal an error.
With regard to the :element-type option, if a type is requested that is not supported by the file system, a substitution of types such as that which goes on in upgrading is permissible. As a minimum requirement, it should be the case that opening an output stream to a file in a given element type and later opening an input stream to the same file in the same element type should work compatibly.
with-open-file, close, pathname, logical-pathname, Section 19.2.3 (Merging Pathnames), Section 19.1.2 (Pathnames as Filenames)
\issue{PATHNAME-LOGICAL:ADD} Whether or not \funref{open} recognizes \term{logical pathname} \term{namestrings} is \term{implementation-defined}. \endissue{PATHNAME-LOGICAL:ADD}
23.2.0 38open does not automatically close the file when an abnormal exit occurs.
When element-type is a subtype of character, read-char and/or write-char can be used on the resulting file stream.
When element-type is a subtype of integer, read-byte and/or write-byte can be used on the resulting file stream.
When \param{element-type} is \typeref{unsigned-byte}, {\tt (unsigned-byte \i{n})}, \typeref{signed-byte}, {\tt (signed-byte \i{n})}, \typeref{bit}, or {\tt (mod \i{n})}, \funref{read-byte} and/or \funref{write-byte} can be used on the resulting \term{file stream}.
When element-type is :default, the type can be determined by using stream-element-type.