10.1. Low-Level Stream I/O PROCEDURE Conventions

10.1.1. Timeouts

If timeout is omitted or $block is given, the PROCEDURE blocks indefinitely until something can be input/output or an error occurs. If timeout is greater than zero, it specifies a minimum amount of time in milliseconds to wait before returning a timeout failure. If timeout is $poll, the PROCEDURE returns immediately with either a success value or one of the error values described below, as applicable. $poll should always be used in conjunction with the errorOK bit. If the errorOK bit is not set and no I/O is ready, STREAMS PROCEDUREs call errMsg with a fatal error, even if the timeout value is $poll. If the timeout value is $poll and nothing is ready, the STREAMS PROCEDUREs in question return $timedOut.

If the system does not support timeout, i.e., if $systemSupportsTimeout returns FALSE, all timeout values are treated as if they were $block and the PROCEDURE does not return until the I/O is complete or an error occurs.

10.1.2. Success and Failure of I/O Operations

The macros shown in Figure 10–2 are defined to test the return values.

A return of $error indicates a general error. A return of $timedOut indicates that the I/O operation did not occur because the timeout value was exceeded. A return of $eos indicates that no more data are available on input, or that no more data can be accepted by the other end on output.

The character-reading PROCEDURE $cReadStream returns INTEGER instead of LONG INTEGER values but is otherwise similar in this respect.

If an error return of any kind occurs, the field $lastInputError or $lastOutputError of the stream contains a description of the error. If the operation is neither input nor output, $lastInputError is set.

10.1.3. The General Error Return ($error)

10.1.4. The End-of-Stream Return ($eos)

For TTY streams, in the input direction, $eos means that the user typed some system-dependent key combination to signal the end of an exchange (e.g., CTRL-D under BSD UNIX). Repeated $eos errors, however, might mean that no more input is available at all.

For socket streams, in both the input and output directions, $eos means that the process at the other end has “hung up” the connection for some reason.

For some implementations of some stream types, such as standard UNIX V.0 TTY streams, the STREAMS package may not be able to distinguish end-of-stream from a simple lack of data. On such platforms, the $eos return does not occur.

10.1.5. Timeout Return ($timedOut)

10.2. Octets

All physical channels on which stream communication is based transmit information in the form of eight-bit units, so the octet is the quantum of information used by most stream I/O PROCEDUREs.

10.3. Input: $readStream

$readStream reads octets from the stream st into the destination STRING or buffer with maximum size given by bufSize.

The interpretation of the octets read from the stream (how they are packed into memory) depends on the the form of $readStream that is used. The STRING and CHARADR forms read text ($text mode), the CHARADR form with the $octet bit set reads octets, and the ADDRESS form reads octets into complete storage units ($image mode).

It is not necessary to specify the bits $text or $image in ctrlBits because they are implied by the GENERIC instance. However, when reading octets it is necessary to include the $octet bit, since octets are addressed by CHARADRs.

The precise interpretation of the octets in the stream is as follows:

• The text (STRING and CHARADR without the $octet bit set) forms interpret the incoming octets as characters and pack them into memory as STRINGs are normally packed. If necessary, the characters are translated from the PDF character set (see Chapter 26 of the MAINSAIL Language Manual) to the character set of the current machine. By default, each read returns the next group of characters that is received from the stream, including eol characters but not necessarily an integral number of lines. bufSize for the CHARADR form is given in characters.

• The octet form packs the incoming octets into memory as full octets are normally packed. By default, the next group of octets that flow through the stream is read. bufSize is given in octets.

• The storage unit form packs the incoming octets into memory as full storage units. bufSize is given in storage units. By default, the next group of octets corresponding to an integral number of storage units are read.

At most one of the following buffering bits may be set:

• $unbuffered (default): $readStream waits until some octets are available. It returns all the available octets that fit into the supplied buffer, retaining any that do not fit for subsequent reads. In $text mode, the amount of text returned may not be an integral number of lines. End-of-line characters are included in the buffer where they occurred in the input. In $image mode, $readStream always reads octets corresponding to an integral number of storage units.

• $line (for $text only): $readStream waits for a full line of text to become available. It then returns the characters in the line, including the end-of-line or line BREAK character.

• $fillBuffer: $readStream waits until the supplied buffer has been filled completely. For the STRING form, $charsPerPage characters are read.

• $packet: $readStream reads a well-defined packet produced by the other end of the stream. The packet is guaranteed to be read and returned as a unit, rather than possibly arriving piecemeal. This mode is useful for communications between a client and server process, for example. Both the reader and writer must set $packet for the operation to work.

The buffering modes and defaults for each type of object read are summarized in Table 10–4.

If the read is successful, the number of characters or octets actually read is returned. Otherwise, a negative error value is returned.

On streams that buffer output and that are opened for both input and output, the output is flushed with $flushStream (see below) before a read on the stream. This ensures that prompts or requests to a user or another process are sent out to the other side before the read blocks waiting for a response.

The MAINSAIL PROCEDURE ttyRead acts similarly to the following stream calls:

$readStream($tty,tempString,$line);
read(tempString,resultString);

The second call to read removes the eol that $readStream returns as part of the line.

Additional conventions applicable to $readStream are described in Section 10.1.

10.4. Output: $writeStream

$writeStream writes the data contained in the specified buffer to the stream st.

The interpretation of the buffer (how it is converted into octets) depends on the the form of $writeStream that is used. The STRING and CHARADR (without $octet set) forms write text by translating it to the PDF character set (if necessary), the CHARADR form with $octet set in ctrlBits writes octets directly, and the ADDRESS form writes storage units by converting them to octets in the standard way for the host system. The bufSize parameter is in character units for the CHARADR form and storage units for the ADDRESS form.

It is not necessary to specify the bits $text or $image in ctrlBits because they are implied by the GENERIC instance. However, when writing octets it is necessary to include the $octet bit because octets are addressed by CHARADRs.

At most one of the following buffering bits may be set:

• $unbuffered (default): $writestream writes the octets and make them available to the other end of the stream immediately.

• $line ($text mode only): $writeStream writes the text in units of lines, including any eol characters, but (possibly) buffers up characters until an eol has been written before sending characters to the reader at the other end of the stream. The buffering is done if it is required for efficiency. If the stream is talking to a device, eol-like characters are converted to their proper form for the device. For example, bare carriage returns and/or bare linefeeds are typically translated into carriage return-linefeed sequences if the output goes to a TTY and the device requires such a translation.

• $packet: $writeStream writes a well-defined packet to be read as a packet by the other end of the stream. The packet is guaranteed to be preserved as a unit upon arrival, rather than possibly arriving piecemeal. This mode must be used if and only if the reader calls the corresponding $readStream with $packet set. Clearly, this mode must be used as part of an overall communications protocol, e.g., between a server and a client or between two cooperating coroutines.

$writeStream returns a nonnegative LONG INTEGER on a successful write. Otherwise, a negative value is returned.

The system PROCEDURE ttyWrite produces results similar to:

$writeStream($tty,argStr,$line)

Additional conventions applicable to $writeStream are described in Section 10.1.

10.5. Single-Character I/O: $cReadStream and $cWriteStream

The PROCEDUREs $cReadStream and $cWriteStream are similar to $readStream and $writeStream except that they read and write single characters or octets at a time. It is necessary to include the $text or $octet bit to indicate whether characters or octets should be read or written.

The following bits are valid in ctrlBits:

• $text: On input, the next octet from the stream is interpreted as a character and returned in the rightmost $bitsPerChar bits of the result. If $line is set, the first character of a line may (possibly) not be returned until the entire line containing it has been received. On output, interpret the rightmost $bitsPerChar bits of the argument as a character and send it out as an octet. If $line is set, the character may (possibly) not be sent to the other end of the stream until an eol is output.

• $octet: On input, the next octet read from the stream is returned unchanged. On output, the rightmost eight bits of the argument are interpreted as an octet and sent out.

• The only legal buffering modes for $cReadStream and $cWriteStream are $unbuffered (the default) and $line (which affects only $text I/O).

On success, $cReadStream returns the actual octet or character value. On failure it returns one of the standard error codes $error, $eos, or $timedOut, except that the value is converted to an INTEGER instead of a LONG INTEGER (i.e., test for cvi($error), cvi($eos), or cvi($timedOut)). $cReadStream is the only stream I/O PROCEDURE that returns an INTEGER instead of a LONG INTEGER.

On success, $cWriteStream returns an arbitrary nonnegative value; on failure, it returns a negative value.

The buffer PROCEDUREs $readStream and $writeStream are more efficient for reading many characters or octets. However, the character versions of these PROCEDUREs are more convenient when program logic requires reading a single character or octet at a time.

Additional conventions applicable to $cReadStream and $cWriteStream are described in Section 10.1.

10.6. Miscellaneous Operations: $flushStream and $clearStream

$flushStream forces all output done to the stream out so that it is available to the process or device at the other end. This action is of use if the implementation of the stream uses an internal buffer for efficiency. A read on the stream automatically causes the previously buffered output to be sent, but a program might want to ensure that all output has been sent before issuing an error message, for example.

$clearStream discards pending input (if input is set in ctrlBits) and/or output (if output is set in ctrlBits) on st. For example, if an editor reads an invalid command character from the terminal and prints an error message, it would be reasonable to call $clearStream($tty,input) so that all unread characters typed ahead by the user are discarded (since the user is likely to assume that the errant command was performed).

Both $flushStream and $clearStream return TRUE if the operation was successful and FALSE if the operation failed and errorOK was specified in ctrlBits. If errorOK was not set, they issue a fatal error.

10.7. Constants and Macros for Stream I/O

• $optionalFirstEol: A character that sometimes precedes last(eol) in text read from streams, files transferred from other systems, or output from certain programs. The portable way to remove ends-of-lines from such text on all systems is to look for last(eol) and then discard the previous character if it is $optionalFirstEol.

• $error: The general error return value.

• $timedOut: A timeout error.

• $eos: An end-of-stream condition.

• $poll: A special timeout value that indicates immediate return if the operation would otherwise block (normally used in conjunction with the errorOK bit).

• $block: A special timeout value that indicates an indefinite wait for an operation to complete. This is the default timeout for most PROCEDUREs.

Similarly, when two streams write to the same scheduled stream, it is not specified which write occurs first, or whether one stream's write is more likely to succeed after the other stream's write has been performed.