device-write

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

First, an attempt is made to transfer data from the buffer to the device specified by stream from start to end. The number of octets (8-bit bytes) actually written is returned, or else an error or other exceptional situation encode in the following way:

• 0: No data could be written. It is likely that the stream has become clogged with data, and is rejecting further attempts to write.
• -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 can be written, and a -3 value means data could have been written.
• (- -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 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 and returns the number of bytes written.

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.

Defined methods

• On classes: 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.
• On classes: null-simple-stream: nothing is called, and the entire request (- end start) is returned.
• On classes: 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-2002, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 6.2. This page was not revised from the 6.1 page.
Created 2002.2.26.