Arguments: stream buffer start end blocking
If buffer is nil, and start and end are not eql, then the appropriate buffer slot must be used as the buffer to read into, and the end argument (which will be nil) must be taken as if it were specified the number of octets in the buffer. Any manipulation of buffers, including replacement of the buffer slot with a new one of the same size, can be done before returning.
An attempt is made to fill the buffer from start to end with data coming from the device. The number of octets (8-bit bytes) actually read is returned, or else an error or other exceptional situation encode in the following way:
The blocking argument also allows asynchronous reads. If
blocking is true, then the read waits until at least one
byte can be read (or, if the scheduler is running, the thread waits
until at least one byte can be read, allowing other threads to
continue meanwhile). If blocking is
nil, then the read
transfers as much as it can immediately and returns the number of
Note that there is no device-level listen operation. The higher-level streams API
implements listen as a query
to its buffer possibly followed by a device-read with blocking set to
false. If there is no data on the stream, all is well, and the read
returns with 0 bytes, allowing a listen operation to return with
nil. But if there is data on the stream, then it will
be read into the given buffer and the higher level operation must take
care not to lose this data.
buffer may be a vector of any size and element-type. If the
element-type is not octet (8-bit byte, signed or unsigned) then the
endianness order of bits or bytes is that of the natural order of the
native machine. Thus, with an element-type of
32) on a little-endian machine, a read of the four bytes
start of 0 will be read into the element as the word
#x78563412. The same byte stream read into a
big-endian machine will form the word
Note that no checking is done to match the byte-count to element-widths; if three bytes only are read into a four-byte element, the fourth byte is left alone. It is up to the strategy-level programmer (see the end of section Simple-stream Description) to ensure that endianness is matched against the stream, and that data widths are received as expected.
dual-channel-simple-stream: for both methods, after checking for null buffer and end args, read-octets is called directly and the resulting values returned.
null-simple-stream: nothing is called, and -1 is always returned.
terminal-simple-stream: A return value of -1 (latching eof) is turned into -2 (non-latching eof).
Note that the supplied device-read and device-write functions do not generate errors themselves, but pass them back to the higher level for processing. This allows read-octets and write-octets to pass errors back as well, as the implementation of a higher level (encapsulating) device-read and device-write.
See streams.htm for information on the simple-streams implementation in Allegro CL. The older but still supported Gray streams implementation is described in gray-streams.htm.
The documentation is described in introduction.htm and the index is in index.htm.
Copyright (c) 1998-2000, Franz Inc. Berkeley, CA., USA. All rights reserved.