device-read

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:

• -1: EOF. This condition is latched into the stream until reset by some operation such as file-position.
• >-2 Soft EOF. This value can be returned for a device that might read beyond an eof, such as a terminal (after typing a Control-D). The strategy processes the EOF, but does not leave the stream in that state; the next read will cause another device-read.
• -3: Special return value for a no-hang query. If the start and end arguments are eql and if blocking is nil, then a 0 return means no data will be read, and a -3 value means data would have been read.
• (- -10 errno): the value of the error return from the system operation. For example, -19 represents an errno value of 9, which is EBADF (bad file number) on most systems.

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.

Defined methods

• On classes: 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.
• On classes: null-simple-stream: nothing is called, and -1 is always returned.
• On classes: 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.