blmode(3C)

NAME

blopen(), blclose(), blread(), blget(), blset() — terminal block-mode library interface

SYNOPSIS

#include <sys/blmodeio.h>

int blopen(int fildes);

int blclose(int bfdes);

int blread(int bfdes, char *buf, size_t nbyte);

int blget(int bfdes, struct blmodeio *arg);

int blset(int bfdes, const struct blmodeio *arg);

DESCRIPTION

This terminal library interface allows support of block-mode transfers with HP terminals. Block mode only affects input processing. Therefore, data is written with the standard write() interface (see write(2)).

In character mode, the terminal sends each character to the system as it is typed. However, in block mode, data is buffered and possibly edited locally in the terminal memory as it is typed, then sent as a block of data when the [Enter] key is pressed on the terminal. During block-mode data transmissions, the incoming data is not echoed by the interface and no special character processing is performed, other than recognizing a data block terminator character. For subsequent character mode transmissions, the existing termio state (see termio(7)) continues to determine echo and character processing.

Block-mode protocol has two component parts: block-mode handshake and block-mode transmission.

Block-Mode Handshake

At the beginning of a read, a trigger character is sent to the terminal to notify it that the system wants a block of data (the trigger character, if defined, is sent at the beginning of all reads, whether in character- or block-mode. It is necessary for block-mode reads to work correctly).

After receiving the trigger character, and when the user has typed all the data into the terminal's memory and pressed the [Enter] key, the terminal sends an alert character to the system to notify it that the terminal has a block of data to send.

The system might then send user-definable cursor-positioning or other data sequences to the terminal, such as for cursor-home or lock-keyboard.

The system then sends a second trigger character to the terminal. In response, the terminal transmits the data block as described in the Block-Mode Transmission section.

Block-Mode Transmission

The second part of the block-mode protocol is the block-mode transmission. After the block-mode handshake has successfully completed, the terminal transmits the data block to the system. During this transmission of data, the incoming data is not echoed by the system and no special character processing is performed, other than recognizing the data block termination character. It is possible to bypass the block-mode handshake and have the block-mode transmission occur after only the first trigger character is sent, see CB_BMTRANS below.

It is possible to intermix both character-mode and block-mode data transmissions. If CB_BMTRANS (see below) is set, all transfers are block-mode transfers. When CB_BMTRANS is not set, character mode transmissions are processed as described in termio(7). In this case, if an alert character is received anywhere in the input data, the transmission mode is automatically switched to block mode for a single transmission. Any data received before the alert is discarded. The alert character can be escaped with a backslash (\) character.

XON/XOFF Flow Control

To prevent data loss, XON/XOFF flow control should be used between the system and the terminal. The IXOFF bit (see termio(7)) should be set and the terminal strapped appropriately. If flow control is not used, it is possible for incoming data to overflow and be lost. (Note: some older terminals do not support XON/XOFF flow control.)

Read Requests

Read requests that receive data from block-mode transmissions do not return until the transmission is complete (the terminal has transmitted all characters). If the read is satisfied by byte count or if a data transmission error occurs, all subsequent data is discarded until the transmission is complete. The read waits until a terminator character is seen, or until a time interval specified by the system has passed that is longer than necessary for the number of characters specified.

The data-block-terminator character is included in the data returned to the user, and is included in the byte count. If the number of bytes transferred by the terminal in a block-mode transfer exceeds the number of bytes requested by the user, the read returns the requested number of bytes and the remaining bytes are discarded. The user can determine if data was discarded by checking the last character of the returned data. If the last character is not the terminator character, then more data was received than was requested and data was discarded.

The EIO error can be caused by several events, including errors in transmission, framing, parity, break, and overrun, or if the internal timer expires. The internal timer starts when the second trigger character is sent by the computer, and ends when the terminating character is received by the computer. The length of this timer is determined by the number of bytes requested in the read and the current baud rate, plus an additional ten seconds.

User Control of Handshaking

If desired, the application program can provide its own handshake mechanism in response to the alert character by selecting the OWNTERM mode (see CB_OWNTERM below). With this mode selected, the driver completes a read request when the alert character is received. No data is discarded before the alert, and the alert is returned in the data read. The alert character may be escaped with a backslash (\) character. The second trigger is sent when the application issues the next read.

blmode Control Calls

First, the standard open() call to a tty device must be made to obtain a file descriptor for the subsequent block-mode control calls (an open() is done automatically by the system for stdin on the terminal).

int bfdes;
bfdes = blopen (int fildes): A call to blopen() must be made before any block-mode access is allowed on the specified file descriptor. blopen() initializes the block-mode parameters as described below. The return value from blopen() is a block-mode file descriptor that must be passed to all subsequent block-mode control calls.
int blclose (int bfdes): A call to blclose() must be issued before the standard close() to ensure proper closure of the device (see close(2)). Otherwise unpredictable results can occur. The argument bfdes is the file descriptor returned from a previous blopen() system call.
int blread (int bfdes, char *buf, size_t nbyte): The blread() routine has the same parameters as the read() sytem call (see read(2)). At the beginning of a read, the cb_trig1c character (if defined) is sent to the device. If CB_BMTRANS is not set, and no cb_alertc character is received, the read data is processed according to termio(7). If CB_BMTRANS is set, or if a non-escaped cb_alertc character is received, echo is turned off for the duration of the transfer, and no further special character processing is done other than that required for the termination character. The argument bfdes is the file descriptor returned from a previous blopen() system call.
int blget (int bfdes, struct blmodeio *arg): A call to blget() returns the current values of the blmodeio structure (see below). The argument bfdes is the file descriptor returned from a previous blopen() system call.
int blset (int bfdes, const struct blmodeio *arg): A call to blset() sets the block-mode values from the structure whose address is arg. The argument bfdes is the file descriptor returned from a previous blopen() system call.

blmode Structure

The two block-mode control calls, blget() and blset(), use the following structure, defined in <sys/blmodeio.h>:

#define    NBREPLY    64 
struct     blmodeio     { 
    unsigned long     cb_flags;           /* Modes */ 
    unsigned char     cb_trig1c;          /* First trigger */ 
    unsigned char     cb_trig2c;          /* Second trigger */ 
    unsigned char     cb_alertc;          /* Alert character */ 
    unsigned char     cb_termc;           /* Terminating char */ 
    unsigned char     cb_replen;          /* cb_reply length */ 
    char              cb_reply[NBREPLY];  /* optional reply */ 
}; 

The cb_flags field controls the basic block-mode protocol:

CB_BMTRANS     0000001    Enable mandatory block-mode transmission.
CB_OWNTERM     0000002    Enable user control of handshake.

If CB_BMTRANS is set, all transmissions are processed as block-mode transmissions. The block-mode handshake is not required and data read is processed as block-mode transfer data. The block-mode handshake can still be invoked by receipt of an alert character as the first character seen. A blread() issued with the CB_BMTRANS bit set causes any existing input buffer data to be flushed.

If CB_BMTRANS is not set, and if the alert character is defined and is detected anywhere in the input stream, the input buffer is flushed and the block-mode handshake is invoked. The system then sends the cb_trig2c character to the terminal, and a block-mode transfer follows. The alert character can be escaped by preceding it with a backslash (\).

If CB_OWNTERM is set, reads are terminated upon receipt of a non-escaped alert character. No input buffer flushing is performed, and the alert character is returned in the data read. This allows application code to perform its own block-mode handshaking. If the bit is clear, a non-escaped alert character causes normal block-mode handshaking to be used.

The initial cb_flags value is all-bits-cleared.

There are several special characters (both input and output) that are used with block mode. These characters and the initial values for these characters are described below. Any of these characters can be undefined by setting its value to 0377.

cb_trig1c: (default DC1) is the initial trigger character sent to the terminal at the beginning of a read request.
cb_trig2c: (default DC1) is the secondary trigger character sent to the terminal after the alert character has been seen.
cb_alertc: (default DC2) is the alert character sent by the terminal in response to the first trigger character. It signifies that the terminal is ready to send the data block. The alert character can be escaped by preceding it with a backslash ("\").
cb_termc: (default RS) is sent by the terminal after the block-mode transfer has completed. It signifies the end of the data block to the computer.

The cb_replen field specifies the length in bytes of the cb_reply field. If set to zero, the cb_reply string is not used. The cb_replen field is initially set to zero.

The cb_reply array contains a string to be sent out after receipt of the alert character, but before the second trigger character is sent by the computer. Any character can be included in the reply string. The number of characters sent is specified by cb_replen. The initial value of all characters in the cb_reply array is NULL.

RETURNS

If an error occurs, all calls return a value of -1 and errno is set to indicate the error. If no error is detected, blread() returns the number of characters read. All other calls return 0 upon successful completion.

During a read, it is possible for the user's buffer to be altered, even if an error value is returned. The data in the user's buffer should be ignored as it is not complete. The following errors can be returned by the library calls indicated:

blopen()

[ENOTTY]: The file descriptor specified is not related to a terminal device.

blclose()

[ENOTTY]: No previous blopen has been issued for the specified file descriptor.

blread()

[EDEADLK]: A resource deadlock would occur as a result of this operation (see lockf(2)).
[EFAULT]: buf points outside the allocated address space. The reliable detection of this error is implementation dependent.
[EINTR]: A signal was caught during the read system call.
[EIO]: An I/O error occurred during block-mode data transmissions.
[ENOTTY]: No previous blopen has been issued for the specified file descriptor.

blget()

[ENOTTY]: No previous blopen has been issued for the specified file descriptor.

blset()

[EINVAL]: An illegal value was specified in the structure passed to the system.
[ENOTTY]: No previous blopen has been issued for the specified file descriptor.

WARNINGS

blopen(), blclose(), blread(), blget() and blset() are not thread-safe.

Once blopen has been called with a file descriptor and returned successfully, that file descriptor should not subsequently be used as a parameter to the following system calls: close(), dup(), dup2(), fcntl(), ioctl(), read(), or select() until a blclose is called with the same file descriptor as its parameter. Additionally, scanf(), fscanf(), getc(), getchar(), fgetc(), and fgetw() should not be called for a stream associated with a file descriptor that has been used in a blopen() call but has not been used in a blclose() call. These functions call read(), and calling these routines results in unpredictable behavior.

AUTHOR

blopen(), blclose(), blread(), blget(), and blset() were developed by HP.