21.12. Function OPEN

OPEN accepts an additional keyword :BUFFERED.

The acceptable values for the arguments to the file/pipe/socket STREAM functions

:ELEMENT-TYPE

types equivalent to CHARACTER or (UNSIGNED-BYTE n), (SIGNED-BYTE n); if the stream is to be un:BUFFERED, n must be a multiple of 8.

If n is not a multiple of 8, CLISP will use the specified number of bits for i/o, and write the file length (as a number of n-bit bytes) in the preamble.

This is done to ensure the input/output consistency: suppose you open a file with :ELEMENT-TYPE of (UNSIGNED-BYTE 3) and write 7 bytes (i.e., 21 bit) there. The underlying OS can do input/output only in whole 8-bit bytes. Thus the OS will report the size of the file as 3 (8-bit) bytes. Without the preamble CLISP will have no way to know how many 3-bit bytes to read from this file - 6, 7 or 8.

See also Section 21.8, “Function STREAM-ELEMENT-TYPE.

:EXTERNAL-FORMAT

EXT:ENCODINGs, (constant) SYMBOLs in the CHARSET package, STRINGs (denoting iconv-based encodings), the symbol :DEFAULT, and the line terminator keywords :UNIX, :MAC, :DOS. The default encoding is CUSTOM:*DEFAULT-FILE-ENCODING*. This argument determines how the lisp CHARACTER data is converted to/from the 8-bit bytes that the underlying OS uses.

See also Section 21.7, “Function STREAM-EXTERNAL-FORMAT.

:BUFFERED

NIL, T, or :DEFAULT. Have CLISP manage an internal buffer for input or output (in addition to the buffering that might be used by the underlying OS). Buffering is a known general technique to significantly speed up i/o.

  • for functions that create SOCKET:SOCKET-STREAMs and pipes, :DEFAULT is equivalent to T on the input side and to NIL on the output side; if you are transmitting a lot of data then using buffering will significantly speed up your i/o;
  • for functions that open files, :DEFAULT means that buffered file streams will be returned for regular files and (on UNIX) block-devices, and unbuffered file streams for special files.

Note that some files, notably those on the /proc filesystem (on UNIX systems), are actually, despite their innocuous appearance, special files, so you might need to supply an explicit :BUFFERED NIL argument for them. Actually, CLISP detects that the file is a /proc file, so that one is covered, but there are probably more strange beasts out there!

When an already opened file is opened again, and not both the existing and the new STREAMs are read-only (i.e., :DIRECTION is :INPUT or :INPUT-IMMUTABLE), the streams can mess up each other and produce unexpected results. The user variable CUSTOM:*REOPEN-OPEN-FILE* controls how CLISP handles the situation and can take 4 values:

NIL
do nothing: do not even check that there are other STREAMs pointing to the same file
WARN
SIGNAL a WARNING and proceed
CLOSE
CLOSE the other STREAMs and proceed (this could be dangerous and is not generally recommended)
ERROR (default)
SIGNAL a continuable ERROR

These notes document CLISP version 2.49.93+Last modified: 2018-02-19