NAME

blmode − terminal block mode library interface

SYNOPSIS

#include <sys/blmodeio.h>

int bfdes;

bfdes = blopen(fildes)
int fildes;

int blclose (bfdes)
int bfdes;

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

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

int blset (bfdes, arg)
int bfdes;
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(2) interface.

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)) will continue to determine echo and character processing.

There are two parts of the block mode protocol, the block mode handshake and the 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, 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 will send an alert character to the system to notify it that the terminal has a block of data to send. 
 
The system may then send user-definable cursor positioning or other data sequences, such as for home cursor or lock keyboard, to the terminal.
 
The system will then send a second trigger character to the terminal.  The terminal will then transmit 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 will transmit 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 will be block mode transfers.  When CB_BMTRANS is not set, character mode transmissions will be processed as described in termio(7). In this case, if an alert character is received anywhere in the input data, the transmission mode will be switched to block mode automatically for a single transmission.  Any data received before the alert will be discarded.  The alert character may 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 this flow control.)

Read requests

Read requests that receive data from block mode transmissions will 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 will be discarded until the transmission is complete.  The read will wait until a terminator character is seen, or 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 will be 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 will return the requested number of bytes and the remaining bytes will be 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 will complete a read request when the alert character is received.  No data will be discarded before the alert, and the alert will be returned in the data read.  The alert character may be escaped with a backslash ("\") character.  The second trigger will be sent when the application issues the next read. 

Blmode control calls

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

int bfdes; bfdes = blopen (fildes)
int fildes;

A call to blopen must be made before any block mode access is allowed on the specified file descriptor.  Blopen will initialize 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 (bfdes)
int bfdes;

A call to blclose must be issued before the standard close(2) to ensure proper closure of the device.  Otherwise unpredictable results may occur. The argument bfdes is the file descriptor returned from a previous blopen system call. 

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

The blread routine has the same parameters as the read(2) sytem call.  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 will be processed according to termio(7). If CB_BMTRANS is set, or if a non-escaped cb_alertc character is received, echo will be turned off for the duration of the transfer, and no further special character processing will be 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 (bfdes, arg)
int bfdes;
struct blmodeio *arg;

A call to blget will return 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 (bfdes, arg)
int bfdes;
struct blmodeio *arg;

A call to blset will set 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>:

};

The cb_flags field controls the basic block mode protocol:

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 may still be invoked by receipt of an alert character as the first character seen.  A blread issued with the CB_BMTRANS bit set will cause 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 will be flushed and the block mode handshake will be invoked.  The system will then send the cb_trig2c character to the terminal, and a block mode transfer will follow.  The alert character can be escaped by preceding it with a backslash ("\"). 

If CB_OWNTERM is set, reads will be 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 will cause 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 may be undefined by setting its value to 0377. 

cb_trig1c is the initial trigger character sent to the terminal at the beginning of a read request. 

cb_trig2c is the secondary trigger character sent to the terminal after the alert character has been seen. 

cb_alertc 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 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 will not be 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 may 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 will return a value of -1 and errno will be set to indicate the error.  If no error is detected, blread will return the number of characters read.  All other calls will 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 will not be complete.  The following errors may be returned by various library calls described in this document. 

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 will be implementation dependent. 

[EINTR] A signal was caught during the read system call. 

[EIO] An I/O error occured 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

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(2), dup(2), dup2(2), fcntl(2), ioctl(2), read(2), or select(2) until a blclose is called with the same file descriptor as its parameter.  Additionally, scanf(libc), fscanf(libc), getc(libc), getchar(libc), fgetc(libc) and fgetw(libc) 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(2) and calling these routines will result in unpredictable behavior.

AUTHOR

Blmode was developed by HP. 

SEE ALSO

termio(7). 

Hewlett-Packard Company  —  HP-UX Release 7.0: Sept 1989