AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs

Chapter 28. TTY Subsystem

AIX is a multiuser operating system which allows user access from local or remote attached device. The communication layer that supports this function is the tty subsystem.

The communication between terminal devices and the programs that read and write to them is controlled by the tty interface. Examples of tty devices are:

Modems
ASCII terminals
System console
Serial printer
System console
Xterm or aixterm under X-Windows.

This overview provides information about following topics:

TTY Subsystem Objectives

TTY Subsystem Modules

TTY Subsystem Structure

TTY Subsystem Objectives

The tty subsystem is responsible for:

Controlling the physical flow of data on asynchronous lines (including the transmission speed, character size, line availability)
Interpreting the data by recognizing special characters and adapting to national languages
Controlling jobs and terminal accesses by using the concept of controlling terminal.
A controlling terminal manages the input and output operations of a group of processes. The tty special file supports the controlling terminal interface. In practice, user programs seldom open terminal files, such as dev/tty5. These files are opened by a getty or rlogind command and become the user's standard input and output devices.

TTY Subsystem Modules

To perform these tasks, the tty subsystem is composed of modules, or disciplines. A module is a set of processing rules that govern the interface for communication between the computer and an asynchronous device. Modules can be added and removed dynamically for each tty.

The tty subsystem supports three main types of modules:

TTY Drivers

tty drivers, or hardware disciplines, directly control the hardware (tty devices) or pseudo-hardware (pty devices). They perform the actual input and output to the adapter by providing services to the modules above it: flow control and special semantics when a port is being opened.

The following tty drivers are provided:

cxma	128-port asynchronous controller High-function terminal. The tty name is /dev/hft/Y, where Y >= 0.
lft	Low-function terminal. The tty name is /dev/lftY, where Y >= 0.
lion	64-port asynchronous controller
pty	Pseudo-tty (see "pty Special File" in AIX Files Reference)
rs	Native, 8-port, and 16-port asynchronous controller.

TTY Drivers provides more information about tty drivers.

Line Disciplines

Line disciplines provide editing, job control, and special character interpretation. They perform all transformations that occur on the inbound and outbound data stream. Line disciplines also perform most of the error handling and status monitoring for the tty driver.

The following line disciplines are provided:

ldterm	Terminal devices
sptr	Serial printer (splp command)
slip	Serial Line Internet Protocol (slattach command).

Converter Modules

Converter modules, or mapping disciplines, translate, or map, input and output characters.

The following converter modules are provided:

nls	National language support for terminal mapping; this converter translates incoming and outgoing characters on the data stream, based on the input and output maps defined for the port (see the setmaps command)
lc_sjis and uc_sjis	Upper and lower converter used to translate multibyte characters between the Shifted Japanese Industrial Standard (SJIS) and the Advanced Japanese EUC Code (AJEC) handled by the ldterm line discipline.

Converter Modules provides more information about converter modules.

TTY Subsystem Structure

The tty subsystem is based on STREAMS (see "STREAMS" in AIX Communications Programming Concepts) . This STREAMS-based structure provides modularity and flexibility, and enables the following features:

The structure of a tty stream is made up of the following modules:

The stream head, processing the user's requests. The stream head is the same for all tty devices, regardless of what line discipline or tty driver is in use.

An optional upper converter (uc_sjis for example), a converter module pushed above the line discipline to convert upstream and downstream data.
The line discipline.
An optional lower converter (lc_sjis for example), a converter module pushed below the line discipline to convert upstream and downstream data.
An optional character mapping module (nls), a converter module pushed above the tty driver to support input and output terminal mapping.
The stream end: a tty driver.

Unless required, the internationalization modules are not present in the tty stream. The following figure shows the tty stream structure for a terminal.

For a serial printer, the internationalization modules are usually not present on the stream; therefore, the structure, shown in the following figure, is more simple.

Common Services

The /usr/include/sys/ioctl.h and /usr/include/termios.h files describe the interface to the common services provided by the tty subsystem. The ioctl.h file, which is used by all of the modules, includes the winsize structure, as well as several ioctl commands. The termios.h file includes the POSIX compliant subroutines and data types.

The provided services are grouped and discussed here according to their specific functions.

Hardware control services:
- cfgetispeed subroutine
- cfgetospeed subroutine
- cfsetispeed subroutine
- cfsetospeed subroutine
- tcsendbreak subroutine
Flow control services:
- tcdrain subroutine
- tcflow subroutine
- tcflush subroutine
Terminal information and control:
- isatty subroutine
- tcgetattr subroutine
- tcsetattr subroutine
- ttylock subroutine
- ttylocked subroutine
- ttyname subroutine
- ttyunlock subroutine
- ttywait subroutine
Window and terminal size services:
- termdef subroutine
- TIOCGWINSZ ioctl operation
- TIOCSWINSZ ioctl operation
Process group management services:
- tcgetpgrp subroutine
- tcsetpgrp subroutine

Buffer size operations:
- TXSETIHOG ioctl operation
- TXSETOHOG ioctl operation.

Hardware Control Services

The following subroutines are provided for hardware control.

cfgetispeed	Gets input baud rate.
cfgetospeed	Gets output baud rate.
cfsetispeed	Sets input baud rate.
cfsetospeed	Sets output baud rate.
tcsendbreak	Sends a break on an asynchronous serial data line.

Flow Control Services

The following subroutines are provided for flow control.

tcdrain	Waits for output to complete.
tcflow	Performs flow control functions.
tcflush	Discards data from the specified queue.

Terminal Information and Control

The following subroutines are provided for terminal information and control.

isatty	Determines if the device is a terminal.
setcsmap	Reads a code set map file and assigns it to the standard input device.
tcgetattr	Gets terminal state.
tcsetattr	Sets terminal state.
ttylock, ttywait, ttyunlock, or ttylocked	Controls tty locking functions.
ttyname	Gets the name of a terminal.

Window and Terminal Size Services

The kernel stores the winsize structure to provide a consistent interface for the current terminal or window size. The winsize structure contains the following fields:

`ws_row`	Indicates the number of rows (in characters) on the window or terminal.
`ws_col`	Indicates the number of columns (in characters) on the window or terminal.
`ws_xpixel`	Indicates the horizontal size (in pixels) of the window or terminal.
`ws_ypixel`	Indicates the vertical size (in pixels) of the window or terminal.

By convention, a value of 0 in all of the winsize structure fields indicates that the structure has not yet been set up.

termdef	This subroutine queries terminal characteristics.
TIOCGWINSZ	Gets the window size. The argument to this ioctl operation is a pointer to a winsize structure, into which the current terminal or window size is placed.
TIOCSWINSZ	Sets the window size. The argument to this ioctl operation is a pointer to a winsize structure, which is used to set the current terminal or window size information. If the new information differs from the previous, a SIGWINCH signal is sent to the terminal process group.

Process Group Management Services

The following subroutines are provided for process group management:

tcgetpgrp	Gets foreground process group ID.
tcsetpgrp	Sets foreground process group ID.

Buffer Size Operations

The following ioctl operations are used for setting the size of the terminal input and output buffers. The argument to these operations is a pointer to an integer specifying the size of the buffer.

TXSETIHOG

Sets the hog limit for the number of input characters that can be received and stored in the internal tty buffers before the process reads them. The default hog limit is 512 characters. Once the hog limit plus one character is reached, an error is logged in the error log and the input buffer is flushed. The hog number should not be too large, since the buffer is allocated from the system-pinned memory.

TXSETOHOG

Sets the hog limit for the number of output characters buffered to echo input. The default hog limit is 512 characters. Once the hog output limit is reached, input characters are no longer echoed. The hog number should not be too large, since the buffer is allocated from the system-pinned memory.

Synchronization

The tty subsystem takes advantage of the synchronization provided by STREAMS. The tty stream modules are configured with the queue pair level synchronization. This synchronization allows the parallelization of the processing for two different streams.

Related Information

STREAMS Overview

Input and Output Handling Programmer's Overview

National Language Support Overview for Programming

TTY Revision History

Line Discipline Module (ldterm)

Understanding Converter Modules

Understanding TTY Drivers

The lft special file describes the console device driver.

The termios.h file contains the structures used for the POSIX line discipline.

The termiox.h file contains the interface for asynchronous hardware flow control.

The tty special file is a synonym for the controlling terminal.

The pty special file describes the pseudo-terminal device driver.