| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |
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.
If read-octets is used to
implement device-read, and
if buffer is passed as nil
, then read-octets will automatically provide the
buffer.
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 bytes read. See Blocking behavior in
simple-streams in streams.htm.
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 (if not nil
) must be a
specialized simple-array of one dimension. It can be of any size and
specialized element-type (its upgraded-element-type must not be
t
). 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 (unsigned-byte 32)
on a
little-endian machine, a read of the four bytes
#x12
, #x34
,
#x56
, and #x78
with
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 #x12345678
.
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.
single-channel-simple-stream
and 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.
Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.
| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |