A stream is an object that can be used with an input or output function to identify an appropriate source or sink of characters or bytes for that operation. A character stream is a source or sink of characters. A binary stream is a source or sink of bytes.
Some operations may be performed on any kind of stream; the next figure provides a list of standardized operations that are potentially useful with any kind of stream.
|
Figure 21.1: Some General-Purpose Stream Operations
Other operations are only meaningful on certain stream types.
For example, read-char
is only defined for character streams
and read-byte
is only defined for binary streams.
A stream, whether a character stream or a binary stream,
can be an input stream (source of data),
an output stream (sink for data),
both,
or (e.g., when “:direction :probe
” is given to open
) neither.
The next figure shows operators relating to input streams.
|
Figure 21.2: Operators relating to Input Streams.
The next figure shows operators relating to output streams.
|
Figure 21.3: Operators relating to Output Streams.
A stream that is both an input stream and an output stream
is called a bidirectional stream.
See the functions input-stream-p and output-stream-p
.
Any of the operators listed in Figure 21.2 or Figure 21.3 can be used with bidirectional streams. In addition, the next figure shows a list of operators that relate specificaly to bidirectional streams.
Streams are either open or closed.
Except as explicitly specified otherwise, operations that create and return streams return open streams.
The action of closing a stream marks the end of its use as a source or sink of data, permitting the implementation to reclaim its internal data structures, and to free any external resources which might have been locked by the stream when it was opened.
Except as explicitly specified otherwise, the consequences are undefined when a closed stream is used where a stream is called for.
Coercion of streams to pathnames is permissible for closed streams; in some situations, such as for a truename computation, the result might be different for an open stream and for that same stream once it has been closed.
An interactive stream is one on which it makes sense to perform interactive querying.
The precise meaning of an interactive stream is implementation-defined, and may depend on the underlying operating system. Some examples of the things that an implementation might choose to use as identifying characteristics of an interactive stream include:
read-char
might wait for the user to type something before returning
instead of immediately returning a character or end-of-file.
The general intent of having some streams be classified as interactive streams is to allow them to be distinguished from streams containing batch (or background or command-file) input. Output to batch streams is typically discarded or saved for later viewing, so interactive queries to such streams might not have the expected effect.
Terminal I/O might or might not be an interactive stream.
Some streams, called
file streams, provide access to files.
An object of class file-stream
is used to represent a file stream.
The basic operation for opening a file is open
,
which typically returns a file stream
(see its dictionary entry for details).
The basic operation for closing a stream is close
.
The macro with-open-file
is useful
to express the common idiom of opening a file
for the duration of a given body of code,
and assuring that the resulting stream is closed upon exit from that body.
The class stream
has a number of subclasses defined
by this specification. The next figure shows some information
about these subclasses.
|
Figure 21.5: Defined Names related to Specialized Streams