| Allegro CL version 10.0 Unrevised from 9.0 to 10.0. 9.0 version | ||||||||||
Arguments: stream buffer start end blocking
device-write is called to transfer data to the device or to do a no-hang query on the device.
If start and end are not eql, then an attempt is made to transfer data from the buffer (from start to end) to the device specified by stream.
If buffer is nil, then
the appropriate buffer slot must be used as the buffer to write from.
Any manipulation of buffers, including replacement of the buffer slot
with a new one of the same size, can be done before returning.
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 write of the value
#x12345678 will result in the byte stream
#x78, #x56,
#x34, #x12, whereas on a
big-endian machine the resulting byte stream will be
#x12, #x34,
#x56, #x78.
Note that no checking is done to match byte-counts to element-widths. 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 sent as expected.
The output-handle slot of stream can either be an operating-system file descriptor/handle, or another stream. If it is another stream, then device-write performs the equivalent of a write-vector on that stream, instead of getting the data from the operating system. Arguments and return values are adjusted to agree with the interfaces between device-write and write-vector.
The blocking argument allows asynchronous writes. If blocking is true, then the write waits until the first element of the buffer is written (or, if the scheduler is running, the thread waits until output can be continued, allowing other threads to continue meanwhile). Because device-write is a B/NB (blocking/non-blocking) function, when blocking blocking is true, the function blocks on the first element only, and does not block thereafter. See Blocking behavior in simple-streams in streams.htm.
If blocking is nil, then the write transfers as much as it can
immediately.
The number of octets (8-bit bytes) actually written is returned (so a positive return value indicates success). Errors and other exceptional situation are encoded as specified in the 'Return values' section below.
If the start and end arguments are eql and if blocking is nil, then the caller is requesting a no-hang query on the device. device-write should return 0 if no data can be written, and a -3 if data could have been written.
single-channel-simple-stream and dual-channel-simple-stream: for
both methods, after checking for null buffer, write-octets is called
directly and the resulting values returned.
null-simple-stream: nothing is called, and the
entire request (- end start) is returned.
socket-base-simple-stream:
chunking is supported.
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-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 9.0 page.
Created 2015.5.21.
| Allegro CL version 10.0 Unrevised from 9.0 to 10.0. 9.0 version | ||||||||||