tty(7) Miscellaneous Information Manual tty(7)
NAME
tty - General terminal interface
SYNOPSIS
#include <sys/termios.h>
DESCRIPTION
This section describes both a particular special file /dev/tty and the terminal drivers used for conversational computing. Much of the
terminal interface performance is governed by the settings of a terminal's termios structure. This structure provides definitions for ter-
minal input and output processing, control and local modes, and so on. These definitions are found in the termios.h header file.
Line Disciplines
The operating system supports STREAMS-based and clist-based line disciplines, which allows for both STREAMS- and clist-based terminal driv-
ers. Both line disciplines are POSIX compliant.
The STREAMS-based line discipline is implemented as the STREAMS module ldterm. This line discipline performs most of the functions defined
by the termios interface for session management and character processing but not some low level device control. In order to determine if a
terminal device is implemented as a STREAMS device, use the libc function isastream on the open file descriptor. See the isastream(3) ref-
erence page.
Users can switch line disciplines by using the command strchg or the I_POP or I_PUSH STREAMS ioctls. The ldterm line discipline is the
only STREAMS-based line discipline provided by the base operating system for use with terminals. However, additional STREAMS modules to
support features needed in countries other than the United States can be pushed above and below the ldterm module.
The operating system supports several clist-based line disciplines for controlling communication lines. By default, the Standard line dis-
cipline, which supports full POSIX terminal semantics, is the only line discipline available for terminals. However, after the installation
of worldwide portability subsets, two additional line disciplines are available for processing the multibyte and single-byte coded charac-
ter sets used for Asian languages. The atty(7) and ttty(7) reference pages, which are also available after the worldwide portability sub-
sets are installed, describe these additional line disciplines.
Line discipline switching is done with the TIOCSETD ioctl for clist-based terminal drivers. The following example illustrates how to
switch line disciplines:
int ldisc = LDISC;
ioctl(fd,TIOCSETD,&ldisc);
In this example, LDISC is the index into the linesw table. (See the /sys/bsd/tty_conf.c file.)
Other clist disciplines exist for special purposes, such as communication lines for network devices. The current line discipline can be
obtained with the TIOCGETD ioctl for clist-based terminal drivers. Pending output is discarded when the line discipline is changed. When
the Standard line discipline is used, NTTYDISC (value 2) is returned by default for BSD compatibility. TTYDISC (value 0) is returned only
when you compile the application with the -D_USE_NEW_TTY switch. When the atty or ttty line discipline is used, ASYDISC (value 9) or TSB-
DISC (value 10) is returned, respectively.
The Controlling Terminal
The operating system supports the concept of a controlling terminal. Any process in the system can have a controlling terminal associated
with it. Certain events, such as the delivery of keyboard generated signals (for example, interrupt, quit, suspend), affect all the pro-
cesses in the process group associated with the controlling terminal. The controlling terminal also determines the physical device that is
accessed when the indirect device /dev/tty is opened.
In earlier versions of UNIX systems, a controlling terminal was implicitly assigned to a process if, at the time an open was done on the
terminal, the terminal was not the controlling terminal for any process, and if the process doing the open did not have a controlling ter-
minal. In this version of UNIX, in accordance with POSIX 1003.1, a process must be a session leader to allocate a controlling terminal.
In addition, the allocation is now done explicitly with a call to ioctl(). (This implies that the O_NOCTTY flag to the open() function is
ignored.) The following example illustrates the correct sequence for obtaining a controlling tty (no error checking is shown). This code
fragment calls the setsid() function to make the current process the group and session leader, and to remove any controlling tty that the
process may already have. It then opens the console device and attaches it to the current session as the controlling terminal. Note that
the process must not already be a session or process group leader, and the console must not already be the controlling tty of any other
session. (void)setsid(); /* become session leader and */
/* lose controlling tty */ fd = open("/dev/console", O_RDWR); (void)ioctl(fd,TIOCSCTTY,0);
A process can remove the association it has with its controlling terminal by opening the /dev/tty file and issuing the following call:
ioctl(fd, TIOCNOTTY, 0);
For example: fd = open("/dev/tty", O_RDWR); if (fd > = 0) { ioctl(fd,TIOCNOTTY,0); close(fd); }
If the calling process is not the session leader, the process group of the calling process is set to 0.
When a control terminal file is closed, pending input is removed, and pending output is sent to the receiving device.
When a terminal file is opened, the process blocks until a carrier signal is detected. If the open() function is called with the O_NON-
BLOCK flag set, however, the process does not wait. Instead, the first read() or write() call will wait for carrier to be established. If
the CLOCAL mode is set in the termios structure, the driver assumes that modem control is not in effect, and open(), read(), and write()
therefore proceed without waiting for a carrier signal to be established.
Process Groups
Each process belongs to a process group with a specific process group ID. Each process belongs to the process group of its creating
process. This enables related processes to be signaled. Process group IDs are unique identifiers that cannot be used for other system
process groups until the original process group is disbanded. Each process group also has a group leader process. A process group leader
has the same process ID as its process group.
Each process group belongs to a session. Each process in the process group also belongs to the process group's session. A process which
is not the process group leader can create its own session and process group with a call to the setsid() function. That calling process
then becomes the session leader of the new session and of the new process group. The new session has no controlling terminal until the
session leader assigns one to it. The calling process's ID is assigned to the new process group. With the setpgid() function, other pro-
cesses can be added to a process group.
A controlling terminal can have a distinguished process group associated with it known as the foreground process group. The terminal's
foreground process group is the one that receives signals generated by the INTR, QUIT, and SUSP special control characters. Certain opera-
tions on the terminal are also restricted to processes in the terminal's foreground process group (see "Terminal Access Control"). A ter-
minal's foreground process group may be changed by calling the tcsetpgrp() function. A terminal's current foreground process group may be
obtained by calling the tcgetpgrp() function.
Input Processing Modes
The terminal drivers have two major modes, characterized by the kind of processing that takes place on the input characters: If a terminal
is in canonical mode, input is collected and processed one line at a time. Lines are terminated by a newline (
), End-of-File (EOF), or
End-of-Line (EOL) character. A read request is not returned until the line has been terminated, or a signal has been received. The maxi-
mum number of bytes of unread input allowed on an input terminal is MAX_INPUT bytes. If the maximum number of unread bytes exceeds
MAX_INPUT bytes, the behavior of the driver depends on the setting of the IMAXBEL input flag (see "Input Editing").
Erase and kill processing is performed on input that has not been terminated by one of the line termination characters. Erase processing
removes the last character in the line, kill processing removes the whole line. This mode eliminates erase and kill processing, making
input characters available to the user program as they are typed. Input is not processed into lines. The received bytes are processed
according to the values at the VMIN and VTIME indexes of the c_cc array in the termios structure. MIN is the minimum number of bytes the
terminal can receive in noncanonical mode before a read is considered successful. TIME, measured in 0.1 second granularity, times out spo-
radic input.
These cases are summarized as follows: In this case, TIME is an interbyte timer that is activated after the first byte of the input line is
received, and reset after each byte is received. The read operation is a success if MIN bytes are read before TIME runs out. If TIME runs
out before MIN bytes have been received, the characters that were received are returned. In this case, only MIN is used. A queued read()
waits until MIN bytes are received, or a signal is received. In this case, TIME is used as a read timer that starts when a read() call is
made. The read() call is finished when one byte is read, or when TIME runs out. In this case, either the number of requested bytes or the
number of currently available bytes is returned, depending on which is the lesser number. The read() function returns a zero if no data
was read.
Canonical mode is entered by setting the ICANON flag of the c_lflag field in the in the terminal's termios structure. Other input process-
ing is performed according to the other flags set in the c_iflag and c_lflag fields.
Input Editing
A terminal ordinarily operates in full-duplex mode. Characters may be typed at any time, even while output is occurring. Characters are
only lost when: The system's character input buffers become completely choked, which is rare. The user has accumulated the maximum allowed
number of input characters (MAX_INPUT) that have not yet been read by some program. The MAX_INPUT limit is 512 characters. When this
limit is reached, the terminal driver refuses to accept any further input and rings the terminal bell if IMAXBEL is set in the c_iflag
field, or throws away all input and output without notice if this flag is not set.
Input characters are normally accepted in either even or odd parity with the parity bit being stripped off before the character is given to
the program. The ISTRIP mask of the c_iflag field controls whether the parity bit is stripped (ISTRIP set) or not stripped (ISTRIP not
set). By setting the PARENB flag in the c_cflag field, and either setting (not setting) the PARODD flag, it is possible to have input
characters with EVEN (ODD) parity discarded or marked (see "Input Modes").
In all of the line disciplines, it is possible to simulate terminal input using the TIOCSTI ioctl, which takes, as its third argument, the
address of a character. The system pretends that this character was typed on the argument terminal, which must be the control terminal for
the process, unless the process has superuser privileges.
Input characters are normally echoed by putting them in an output queue as they arrive. This may be disabled by clearing the ECHO bit in
the c_lflag word using the tcsetattr() call or the TIOCSETA, TIOCSETAW, or TIOCSETAF ioctls.
In canonical mode, terminal input is processed in units of lines. A program attempting to read will normally be suspended until an entire
line has been received (but see the description of SIGTTIN in "Terminal Access Control"). No matter how many characters are requested in
the read call, at most one line will be returned. It is not, however, necessary to read a whole line at once; any number of characters may
be requested in a read, even one, without losing information. In read() requests, the O_NONBLOCK flag affects the read() operation behav-
ior.
If O_NONBLOCK is not set, a read() request is blocked until data or a signal has been received. If the O_NONBLOCK flag is set, the read()
request is not blocked, and one of the following situations holds: Some data may have been typed, but there may or may not be enough data
to satisfy the entire read request. In either case, the read() function returns the data available, returning the number of bytes of data
it read. If there is no data for the read operation, the read() returns a -1 with an error of EAGAIN.
During input, line editing is normally done with the erase special control character (VERASE) logically erasing the last character typed
and the kill special control character (VKILL) logically erasing the entire current input line. These characters never erase beyond the
beginning of the current input line or an EOF (End-of-File). These characters, along with the other special control characters, may be
entered literally by preceding them with the literal-next character (VLNEXT -- default ^V).
The drivers normally treat either a newline character (`
'), End-of-File character (EOF), or End-of-Line character (EOL) as terminating an
input line, echoing a return and a line feed. If the ICRNL character bit is set in the c_iflag word then carriage returns are translated
to newline characters on input, and are normally echoed as carriage return-linefeed sequences. If ICRNL is not set, this processing for
carriage return is disabled, and it is simply echoed as a return, and does not terminate cooked mode input.
The POSIX terminal driver also provides two other editing characters in normal mode. The word-erase character, normally <Ctrl-W>, is a
c_cc structure special control character VWERASE. This character erases the preceding word, but not any spaces before it. For the pur-
poses of <Ctrl-W>, a word is defined as a sequence of nonblank characters, with tabs counted as blanks. However, if the ALTWERASE flag is
set in the c_lflag word, then a word is considered to be any sequence of alphanumerics or underscores bounded by characters that are not
alphanumerics or underscores. Finally, the reprint character, normally <Ctrl-R>, is a c_cc structure special control character VREPRINT.
This character retypes the pending input beginning on a new line. Retyping occurs automatically in canonical mode if characters which
would normally be erased from the screen are fouled by program output.
Input Modes
The termios structure has an input mode field c_iflag, which controls basic terminal input characteristics. These characteristics are
masks that can be bitwise inclusive ORed. The masks include: An interrupt is signaled on a break condition. All carriage returns are
mapped to newline characters when input. Break conditions are ignored. Carriage returns are ignored. Characters with parity errors are
ignored. Newline characters are mapped to carriage returns when input. Parity checks are enabled on input. The eighth bit (parity bit)
is stripped on input characters. Stop/start characters are sent for input flow control enabled. Stop/start characters are recognized for
output flow control. Any char will restart output after stop. Map upper case to lower case on input. Parity errors are marked with a
three character sequence. The bell is rung when the input queue fills.
The input mode mask bits can be combined for the following results:
The setting of IGNBRK causes input break conditions to be ignored. If IGNBRK is not set, but BRKINT is set, the break condition has the
same effect as if the VINTR control character had been typed. If neither IGNBRK nor BRKINT are set, then the break condition is input as a
single character '