read-octets

Function

Package: excl

Arguments: stream buffer start end blocking

Reads as many octets from the stream as possible. The input handle is examined, and if it is a stream (i.e. encapsulated), the stream is read from in a manner similar to read-vector, except that no further checking of arguments is done; it is assumed that the caller has done whatever checking that is necessary. Otherwise, if the handle is an operating-system-defined handle, the system read function is called.

Return values:

A number greater than or equal to 0: the number of bytes actually read. 0 bytes are only ever transferred when blocking is nil.
-1: EOF is returned.
-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 valur of 9, which is EBADF (bad file number) on most systems.

Note: device-read implementations may use the return value of read-octets directly, but if an EOF is not "latching" (i.e. there may be more data read after an EOF condition), then the -1 value should be converted into a -2 value (soft EOF) before returning from the device-read method.

See streams.htm for information on the simple-streams implementation in Allegro CL.

The documentation is described in introduction.htm and the index is in index.htm.

Created 2000.10.5.