read-octets

Arguments: stream buffer start end blocking

Reads as many octets from the argument stream's handle as possible. The input handle is examined, and if it is a stream (i.e. encapsulated), then that input handle 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.

buffer is any specialized simple-array of one dimension (it will be treated as if it were a simple vector of octets). Buffer can also be a fixnum, in which case it is treated as an aligned pointer and the "vector" is the memory implied by the aligned pointer. (See Aligned pointers in ftype.htm.)

If buffer is nil, then the standard buffer slot will be supplied.

The blocking controls what happens if not even one octet can be read. If it is true, the function will block if the first character cannot be read; if it is nil, the function does not block. See Blocking behavior in simple-streams in streams.htm.

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 value 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.

This function is intended for implementing device-level functionality and should not be used except for that purpose. See Simple-stream Description in streams.htm for a description of the device-level.

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

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.