STREAM-ELEMENT-TYPE
EXT:MAKE-STREAM
FILE-POSITION
EXT:ELASTIC-NEWLINE
OPEN
CLOSE
OPEN-STREAM-P
BROADCAST-STREAM
STREAM-ELEMENT-TYPE
STREAM-ELEMENT-TYPE
is SETF
able. The STREAM-ELEMENT-TYPE
of
STREAM
s created by the functions OPEN
, EXT:MAKE-PIPE-INPUT-STREAM
EXT:MAKE-PIPE-OUTPUT-STREAM
, EXT:MAKE-PIPE-IO-STREAM
, SOCKET:SOCKET-ACCEPT
, SOCKET:SOCKET-CONNECT
can be modified, if the old and the new STREAM-ELEMENT-TYPE
s are either
CHARACTER
or
(UNSIGNED-BYTE
8)
or (SIGNED-BYTE
8)
; or(UNSIGNED-BYTE
n
)
or (SIGNED-BYTE
n
)
, with the
same n
.Functions STREAM-ELEMENT-TYPE
and (
are SETF
STREAM-ELEMENT-TYPE
)GENERIC-FUNCTION
s, see
Chapter 30, Gray streams.
*STANDARD-INPUT*
Note that you cannot change STREAM-ELEMENT-TYPE
for some
built-in streams, such as terminal streams,
which is normally the value of *TERMINAL-IO*
.
Since *STANDARD-INPUT*
normally is a SYNONYM-STREAM
pointing
to *TERMINAL-IO*
, you cannot use READ-BYTE
on it.
Since CGI
(Common Gateway Interface) provides the form data for
METHOD="POST" on the stdin
,
and the server will not send you an end-of-stream
on the end of the data,
you will need to use
(
to determine how much data you should read from EXT:GETENV
"CONTENT_LENGTH"
)stdin
.
CLISP will detect that stdin
is not a terminal and create a regular
FILE-STREAM
which can be passed to (
.
To test this functionality interactively,
you will need to open the standard input in the binary mode:
SETF
STREAM-ELEMENT-TYPE
)
(let ((buf (MAKE-ARRAY
(PARSE-INTEGER
(EXT:GETENV
"CONTENT_LENGTH")) :element-type '(
))) (UNSIGNED-BYTE
8)WITH-OPEN-STREAM
(in (EXT:MAKE-STREAM
:INPUT
:ELEMENT-TYPE
'(
)) (UNSIGNED-BYTE
8)READ-SEQUENCE
buf in)) buf)
EXT:MAKE-STREAM
Function EXT:MAKE-STREAM
creates a Lisp stream out of an OS file descriptor:
(
EXT:MAKE-STREAM
object
&KEY
:DIRECTION
:ELEMENT-TYPE
:EXTERNAL-FORMAT
:BUFFERED
)
object
designates an OS handle (a file descriptor),
and should be one of the following:
:INPUT
*STANDARD-INPUT*
:OUTPUT
*STANDARD-OUTPUT*
:ERROR
*ERROR-OUTPUT*
STREAM
FILE-STREAM
or a SOCKET:SOCKET-STREAM
When there are several Lisp STREAM
s backed by the same OS
file descriptor, the behavior may be highly confusing when some of the
Lisp streams are :BUFFERED
. Use FORCE-OUTPUT
for output STREAM
s,
and bulk input for input STREAM
s.
The handle is duplicated (with dup
),
so it is safe to CLOSE
a STREAM
returned by EXT:MAKE-STREAM
.
FILE-POSITION
FILE-POSITION
works on any FILE-STREAM
.
EXT:ELASTIC-NEWLINE
The function (
is like
EXT:ELASTIC-NEWLINE
[stream
])FRESH-LINE
but the other way around: It outputs a conditional newline
on stream
, which is canceled if the next
output on stream
happens to be a newline. More precisely, it
causes a newline to be output right before the next character is
written on stream
, if this character is not a newline.
The newline is also output if the next operation on the stream is
FRESH-LINE
, FINISH-OUTPUT
, FORCE-OUTPUT
or CLOSE
.
The functionality of EXT:ELASTIC-NEWLINE
is also available through
the FORMAT
directive ~.
.
A technique for avoiding unnecessary blank lines in output is to
begin each chunk of output with a call to FRESH-LINE
and to terminate it
with a call to EXT:ELASTIC-NEWLINE
.
See also Section 21.6, “Newline Convention”.
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
)(
; if the stream is to be
unSIGNED-BYTE
n
):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 (
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.
UNSIGNED-BYTE
3)
:EXTERNAL-FORMAT
EXT:ENCODING
s, (constant) SYMBOL
s in the
“CHARSET” package, STRING
s (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.
: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.
SOCKET:SOCKET-STREAM
s and
pipes, :DEFAULT
is equivalent to
T
on the input side and to NIL
on the output side; it you are
transmitting a lot of data then using buffering
will significantly speed up your i/o;: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, a continuable ERROR
is
SIGNAL
ed, unless both the existing and the new STREAM
s are read-only
(i.e., :DIRECTION
is :INPUT
or :INPUT-IMMUTABLE
).
CLOSE
Function CLOSE
is a GENERIC-FUNCTION
, see
Chapter 30, Gray streams.
When the :ABORT
argument is non-NIL
, CLOSE
will not
SIGNAL
s an ERROR
even when the underlying OS call fails.
GET-OUTPUT-STREAM-STRING
returns the same value after
CLOSE
as it would before it.
CLOSE
on an already closed STREAM
does nothing and returns
T
.
If you do not CLOSE
your STREAM
explicitly, it will be
closed at garbage-collection time automatically.
This is not recommended though because garbage-collection is not deterministic.
Please use WITH-OPEN-STREAM
etc.
OPEN-STREAM-P
Function OPEN-STREAM-P
is a GENERIC-FUNCTION
, see
Chapter 30, Gray streams.
BROADCAST-STREAM
INPUT-STREAM-P
and INTERACTIVE-STREAM-P
return false for
BROADCAST-STREAM
s.
(EXT:MAKE-BUFFERED-OUTPUT-STREAM
. Returns a buffered output function
)STREAM
.
function
is a FUNCTION
expecting one argument, a SIMPLE-STRING
.
WRITE-CHAR
collects the CHARACTER
s in a STRING
, until a
newline character is written or FORCE-OUTPUT
/FINISH-OUTPUT
is called.
Then function
is called with a SIMPLE-STRING
as argument,
that contains the characters collected so far.
CLEAR-OUTPUT
discards the characters collected so far.
(EXT:MAKE-BUFFERED-INPUT-STREAM
. Returns a buffered input function
mode
)STREAM
.
function
is a FUNCTION
of 0 arguments that returns
either NIL
(stands for end-of-stream
) or up to three values
string
, start
, end
.
READ-CHAR
returns the CHARACTER
s of the current string
one
after another, as delimited by start
and end
, which default to
0
and NIL
, respectively.
When the string
is consumed, function
is called again.
The string
returned by function
should not be changed by the user.
function
should copy the string
with COPY-SEQ
or SUBSEQ
before
returning if the original string
is to be modified.
mode
determines the behavior of LISTEN
when the current string
buffer is empty:
NIL
FILE-STREAM
,
i.e. function
is calledT
end-of-stream
, i.e. one can assume that further characters will always
arrive, without calling function
FUNCTION
FUNCTION
tells, upon call, if further
non-empty string
s are to be expected.
CLEAR-INPUT
discards the rest of the current string
,
so function
will be called upon the next READ-CHAR
operation.
These notes document CLISP version 2.45 | Last modified: 2008-04-15 |