Scieneer Common Lisp 1.3.9 online documentation

ext:make-character-conversion-stream stream &key input output external-format close-stream-p buffering in-buffer-size out-buffer-size finalizep pathname input-error-value output-error-value[Function]

Create a character conversion stream that reads and/or writes the given binary stream.

The functions file-position and file-length are fully supported on all character conversion streams when the character encoded width is a fixed size and the encapsulated binary stream also supports these functions, and are also supported when the character conversion stream is a file input stream. However when the character encoded width is variable and the character conversion stream is not a file input stream then file-length is not support and file-position has only limited support for positioning to the start or end of the file. The position and length of character streams are measured in units of characters, and determining the position within a file with a variable character encoding size requires reading the file to count the number of characters. So if the file-length is needed or the file-position is being changed on an output file using a variable width character encoding then the file must also be opened for input. Overwriting a file with a variable character encoding size is permitted but may change the file length or leave the file corrupted.

The default action upon an encoding or decoding error is to signal an appropriate condition, however it is possible to substitute a character or ignore errors if possible. Note that ignoring input or output errors affects the file-length and file-position.

:input
If true, allow input operations. This is the default if neither :input or :output is specified.
:output
If true, allow output operations.
:external-format
The external character format to use. The default value is :default for which the value of ext:*default-external-format* is used.
:close-stream-p
If true then the target stream is closed when this stream is closed.
:buffering
Indicates the kind of output buffer flushing to use which may be one of: :none, :line, or the default :full.
:pathname
When true, the returned stream will be a subclass of the class file-stream. This should generally be true if the stream is a file-stream.
:input-error-value
A character or character code to be substituted upon a decoding error. When nil, decoding errors are ignored and an attempt is made to move on to the next character. When the value is the keyword :error, which is the default, an ext:character-decoding-error condition is signaled upon a decoding error.
:output-error-value
A character or character code to be substituted upon an encoding error. When nil, encoding errors are ignored and the character output is skipped. When the value is the keyword :error, which is the default, an ext:character-encoding-error condition is signaled upon an encoding error.