Generic Function | Package: excl | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 10.1 Unrevised from 10.0 to 10.1. 10.0 version

## device-write

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.

### Data Transfer

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.

### No-hand query

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.

### Return values

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

### 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-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.

|  | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 10.1 Unrevised from 10.0 to 10.1. 10.0 version