NAME

termio − general terminal interface

SYNOPSIS

None; included by default. 

DESCRIPTION

This section describes the special file /dev/tty and the terminal drivers used for interactive I/O by devices such as zs(4S), cons(4S), and pty(4).

Opening a Terminal File

When a terminal file is opened, it normally causes the process to wait until a connection is established.  In practice, users’ programs seldom open these files; they are opened by init (8) and become a user’s standard input, output, and error files. 

The Controlling Terminal

A terminal may belong to a process, in which case it is known  as its controlling terminal. This controlling terminal may have a distinguished process group associated with it which plays a special role in handling QUIT and INT (interrupt) signals, as discussed below.  The controlling terminal is inherited by a child process during a fork(2).

If a process that has no controlling terminal opens a terminal file, then the device or pseudo-device associated with that terminal file becomes the controlling terminal for the process; the terminal’s distinguished process group is set to that of the process. 

The file /dev/tty is, for each process, a synonym for its controlling terminal.  This is useful for programs that wish to be sure of writing messages on the terminal directly, no matter how output has been redirected.  It can also be used for programs that demand a filename for output when typed output is desired and it is tiresome to find out which terminal is currently in use. 

Implementation Restrictions

Due to restrictions imposed by the current terminal driver, some features are not fully supported:

1.Certain terminal driver features are always enabled, except when the driver is in “RAW mode”.  If the character size is 8 bits, no parity is specified, no output processing is selected (i.e., either OPOST is on or none of OLCUC, ONLCR, or any of the delays are selected), and no input process is selected (as with BRKINT, IGNPAR, INPCK, ISTRIP, ICRNL, IUCLC, and IXON are all off in the c_iflag word and ISIG, ICANON, and XCASE are all off in the c_lflag word), the driver is in “RAW mode”.  If a terminal port is being used for transferring binary data (such as when uucp(1) or some microcomputer data transfer program like KERMIT is using the port), it is usually in “RAW mode”.  If it is being used to give a user interactive access to the computer, it is usually not in “RAW mode”. 

BRKINT and IGNPAR are disabled only in “RAW mode”; if they are to be disabled, the other modes listed must also be disabled.  The WERASE, REPRINT, DISCARD, and LNEXT characters are also disabled only in raw mode. 

2.IUCLC, OLCUC, and XCASE must either all be on or all be off, and ICRNL and ONLCR must either both be on or both be off. 

3.The MIN and TIME values supported by other implementations can be set, but this has no effect on the terminal driver.  The driver behaves as if MIN were 1 and TIME were 0. 

4.Character sizes CS5 and CS6 may not be selected; size CS7 may only be selected when PARENB is set, and size CS8 may only be selected when PARENB is not set.  Furthermore, if size CS8 is selected, unless OPOST is not set, it only applies to input, not output. 

5.IGNBRK, PARMRK, INLCR, IGNCR, ONOCR, OFILL, OFDEL and ECHONL are treated as if they were always not set.  CREAD and ECHOK are treated as if they were always set. 

6.The TCSETAW call will flush any pending input, just as TCSETAF does.  TCSBRK will also flush any pending input. 

7.The EOF character may not be escaped with a backslash (\) (unless XCASE is set; see below). 

8.If XCASE is set, a backslash (\) followed by any character other than a letter or one of the special characters listed in the description of XCASE will be read as the character; the backslash will not be read.  This includes the special characters ERASE, WERASE, KILL, REPRINT, EOF, NEWLINE (the ASCII NL character), EOL, and DISCARD. 

Reading Characters

A terminal associated with one of these files ordinarily operates in full-duplex mode.  Characters may be typed at any time, even while output is occurring, and are only lost when the system’s character-input buffers become completely full (which is rare), or when the user has accumulated the maximum allowed number of input characters that have not yet been read by some program.  Currently, this limit is 256 characters.  When the input limit is reached, if the terminal port is in “RAW mode”, all the saved characters are thrown away without notice.  Otherwise, any further input is discarded and an ASCII BEL character is echoed. 

Two general kinds of input processing are available, determined by whether the terminal device file is in canonical mode or non-canonical mode (see ICANON in the Local Modes section). 

Canonical Mode Input Processing

In canonical mode, terminal input is processed in units of lines.  A line is delimited by a NL (ASCII LF) character, an end-of-file (ASCII EOT) character, or an end-of-line character.  This means that a program attempting to read will be suspended until an entire line has been typed.  Also, 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 can be requested in a read, even one, without losing information. 

Erase and kill processing is normally done during input.  The ERASE character (by default, the character DEL) erases the last character typed.  The WERASE character (the character ^W) erases the last “word” typed (but not any preceding spaces or tabs).  A “word” is defined as a sequence of nonblank characters, with tabs counted as blanks.  Neither ERASE nor WERASE will erase beyond the beginning of the line.  The KILL character (by default, the character ^U) kills (deletes) the entire input line, and optionally produces a NL character.  These special characters operate on a keystroke basis, independently of any backspacing or tabbing that may have been done. 

The REPRINT character (the character ^R) prints a NL followed by all characters which have not been read.  Reprinting also occurs automatically if characters which would normally be erased from the screen are fouled by program output.  The characters are reprinted as if they were being echoed; as a consequence, if ECHO is not set, they are not printed. 

The ERASE and KILL characters may be entered literally by preceding them with the escape character (\).  In this case the escape character is not read.  The ERASE and KILL characters may be changed by such commands as stty(1), and tset(1).

Noncanonical Mode Input Processing

In non-canonical mode, input characters are not assembled into lines, and erase and kill processing does not occur.  Characters are read as soon as they are typed. 

Writing Characters

When one or more characters are written, they are transmitted to the terminal as soon as previously-written characters have finished typing.  Input characters are echoed as they are typed, if echoing has been enabled.  If a process produces characters more rapidly than they can be typed, it will be suspended when its output queue exceeds some limit.  When the queue has drained down to some threshold, the program is resumed. 

Special Characters

Certain characters have special functions on input and/or output.  These functions and their default character values are summarized as follows:

INTR (Control-C or ASCII ETX) generates a SIGINT signal which is sent to all processes in the distinguished process group associated with the terminal.  Normally, each such process is forced to terminate, but arrangements may be made either to ignore the signal or to receive a trap to an agreed-upon location; see sigvec(2).

QUIT (Control-│ or ASCII FS) generates a SIGQUIT signal which is sent to all processes in the distinguished process group associated with the terminal.  Its treatment is identical to the interrupt signal except that, unless a receiving process has made other arrangements, it will not only be terminated but a core image file (called core) will be created in the current working directory. 

ERASE (Rubout or ASCII DEL) erases the preceding character.  It will not erase beyond the start of a line, as delimited by a NL, EOF, or EOL character. 

WERASE (^W or ASCII ETB) erases the preceding “word”.  It will not erase beyond the start of a line, as delimited by a NL, EOF, or EOL character. 

KILL (^U or ASCII NAK) deletes the entire line, as delimited by a NL, EOF, or EOL character. 

REPRINT (^R or ASCII DC2) reprints all characters which have not been read, preceded by a NL. 

EOF (^D or ASCII EOT) may be used to generate an end-of-file from a terminal.  When received, all the characters waiting to be read are immediately passed to the program, without waiting for a NL, and the EOF is discarded.  Thus, if there are no characters waiting, which is to say the EOF occurred at the beginning of a line, zero characters will be passed back, which is the standard end-of-file indication. 

NL (ASCII LF) is the normal line delimiter.  It can not be changed or escaped. 

EOL (Off by default) is an additional line delimiter, like NL.  It is not normally used. 

SUSP (^Z or ASCII EM) is used by the job control facility to change the current job to return to the controlling job.  It generates a SIGTSTP signal, which stops all processes in the terminal’s process group. 

DSUSP (^Y or ASCII SUB) is used by the job control facility to change the current job to return to the controlling job.  It generates a SIGTSTP signal as SUSP does, but the signal is sent when a program attempts to read the DSUSP character, rather than when it is typed. 

STOP (^S or ASCII DC3) can be used to temporarily suspend output.  It is useful with CRT terminals to prevent output from disappearing before it can be read.  While output is suspended, STOP characters are ignored and not read. 

START (^Q or ASCII DC1) is used to resume output which has been suspended by a STOP character.  While output is not suspended, START characters are ignored and not read.  The start/stop characters can not be changed or escaped. 

DISCARD (^O or ASCII SI) causes subsequent output to be discarded until another DISCARD character is typed, more input arrives, or the condition is cleared by a program. 

LNEXT (^V or ASCII SYN) causes the special meaning of the next character to be ignored; this works for all the special characters mentioned above.  This allows characters to be input that would otherwise get interpreted by the system (such as KILL, or QUIT). 

The character values for INTR, QUIT, ERASE, KILL, EOF, and EOL may be changed to suit individual tastes.  The ERASE and KILL characters may be escaped by a preceding \ character, in which case no special function is done.  Any of the special characters may be preceded by the LNEXT character, in which case no special function is done. 

When in “RAW mode”, none of the special characters perform any special function. 

Modem Disconnect

When the carrier signal from the data-set drops, a SIGHUP signal is sent to all processes in the distinguished process group associated with this terminal.  Unless other arrangements have been made, this signal causes the processes to terminate.  If SIGHUP is ignored or caught, any subsequent read returns with an end-of-file indication.  Thus, programs that read a terminal and test for end-of-file can terminate appropriately when hung up on. 

ioctl Calls

Several ioctl(2) system calls apply to terminal files. The primary calls use the following structure, defined in <termio.h>:

#defineNCC8
structtermio {
unsignedshortc_iflag;/∗ input modes ∗/
unsignedshortc_oflag;/∗ output modes ∗/
unsignedshortc_cflag;/∗ control modes ∗/
unsignedshortc_lflag;/∗ local modes ∗/
charc_line;/∗ line discipline ∗/
unsignedcharc_cc[NCC]; /∗ control chars ∗/
};

The special control characters are defined by the array c_cc. The relative positions and initial values for each function are as follows:

0VINTRETX
1VQUITFS
2VERASEDEL
3VKILLNAK
4VEOFEOT
5VEOL(disabled)
6reserved
7reserved

Input Modes

The c_iflag field describes the basic terminal input control:

BRKINT0000002Signal interrupt on break.
IGNPAR0000004Ignore characters with parity errors.
INPCK0000020Enable input parity check.
ISTRIP0000040Strip character.
ICRNL0000400Map CR to NL on input.
IUCLC0001000Map upper-case to lower-case on input.
IXON0002000Enable start/stop output control.
IXANY0004000Enable any character to restart output.
IXOFF0010000Enable start/stop input control.

If BRKINT is set, the break condition will generate an interrupt signal and flush both the input and output queues.  If IGNPAR is set, characters with other framing and parity errors are ignored.  A framing or parity error which is not ignored is read as the ASCII NUL character (0). 

If INPCK is set, input parity checking is enabled.  If INPCK is not set, input parity checking is disabled.  This allows output parity generation without input parity errors. 

If ISTRIP is set, valid input characters are first stripped to 7-bits, otherwise all eight bits are processed. 

If ICRNL is set, a received CR character is translated into a NL character. 

If IUCLC is set, a received upper-case alphabetic character is translated into the corresponding lower-case character.  Note: if this bit is set, the OLCUC bit in the c_oflag word and the XCASE bit in the c_lflag word must also be set. 

If IXON is set, start/stop output control is enabled.  A received STOP character will suspend output and a received START character will restart output.  All start/stop characters are not read, but merely perform flow control functions.  If IXANY is set, any input character, will restart output which has been suspended. 

If IXOFF is set, the system will transmit a STOP character when the input queue is nearly full, and a START character when enough input has been read that the input queue is nearly empty again. 

The initial input control value is undefined. 

Output Modes

The c_oflag field specifies the system treatment of output:

OPOST0000001Postprocess output.
OLCUC0000002Map lower case to upper on output.
ONLCR0000004Map NL to CR-NL on output.
ONLRET0000040NL performs CR function.
NLDLY0000400Select
NL
 delays:
  NL00
  NL10000400
CRDLY0003000Select carriage-return delays:
  CR00
  CR10001000
  CR20002000
  CR30003000
TABDLY0014000Select horizontal-tab delays
  TAB00         or tab expansion:
  TAB10004000
  TAB20010000
  TAB30014000Expand tabs to spaces.
BSDLY0020000Select backspace delays:
  BS00
  BS10020000
VTDLY0040000Select vertical-tab delays:
  VT00
  VT10040000
FFDLY0100000Select form-feed delays:
  FF00
  FF10100000

If OPOST is set, output characters are post-processed as indicated by the remaining flags, otherwise characters are transmitted without change. 

If OLCUC is set, a lower-case alphabetic character is transmitted as the corresponding upper-case character.  Note: if this bit is set, the IUCLC bit in the c_iflag word and the XCASE bit in the c_lflag word must also be set. 

If ONLCR is set, the NL character is transmitted as the CR-NL character pair.  If ONLRET is set, the NL character is assumed to do the carriage-return function; the column pointer will be set to 0 and the delays specified for CR will be used.  Otherwise the NL character is assumed to do just the line-feed function; the column pointer will remain unchanged.  The column pointer is also set to 0 if the CR character is actually transmitted. 

The delay bits specify how long transmission stops to allow for mechanical or other movement when certain characters are sent to the terminal.  In all cases a value of 0 indicates no delay. 

If a form-feed or vertical-tab delay is specified, it lasts for about 2 seconds. 

NEWLINE
 delay lasts about 0.10 seconds. If ONLRET is set, the carriage-return delays are used instead of the NL
 delays.

Carriage-return delay type 1 is dependent on the current column position, type 2 is about 0.08 seconds, and type 3 is about 0.16 seconds. 

Horizontal-tab delay type 1 is dependent on the current column position.  Type 2 is not supported.  Type 3 specifies that tabs are to be expanded into spaces. 

Backspace delay is not supported. 

The actual delays depend on line speed and system load. 

The initial output control value is undefined. 

Control Modes

The c_cflag field describes the hardware control of the terminal:

CBAUD0000017Baud rate:
  B00Hang up
  B50000000150 baud
  B75000000275 baud
  B1100000003110 baud
  B1340000004134.5 baud
  B1500000005150 baud
  B2000000006200 baud
  B3000000007300 baud
  B6000000010600 baud
  B120000000111200 baud
  B180000000121800 baud
  B240000000132400 baud
  B480000000144800 baud
  B960000000159600 baud
  EXTA000001619200 baud
  EXTB0000017External B
CSIZE0000060Character size:
  CS700000407 bits
  CS800000608 bits
CSTOPB0000100Send two stop bits, else one.
PARENB0000400Parity enable.
PARODD0001000Odd parity, else even.
HUPCL0002000Hang up on last close.
CLOCAL0004000Local line, else dial-up.

The CBAUD bits specify the baud rate.  The zero baud rate, B0, is used to hang up the connection.  If B0 is specified, the data-terminal-ready signal will not be asserted.  Normally, this will disconnect the line.  For any particular hardware, impossible speed changes are ignored. 

The CSIZE bits specify the character size in bits for both transmission and reception.  This size does not include the parity bit, if any.  If CSTOPB is set, two stop bits are used, otherwise one stop bit.  For example, at 110 baud, two stop bits are required. 

If PARENB is set, parity generation and detection is enabled and a parity bit is added to each character.  If parity is enabled, the PARODD flag specifies odd parity if set, otherwise even parity is used.  The only combinations that are supported are CS7 with PARENB and CS8 without PARENB. 

If HUPCL is set, the line will be disconnected when the last process with the line open closes it or terminates.  That is, the data-terminal-ready signal will not be asserted. 

If CLOCAL is set, the line is assumed to be a local, direct connection with no modem control.  Otherwise modem control is assumed. 

The initial hardware control value after open is undefined. 

Local Modes

The c_lflag field of the argument structure is used by the line discipline to control terminal functions.  The basic line discipline provides the following:

ISIG0000001Enable signals.
ICANON0000002Canonical input (erase and kill processing).
XCASE0000004Canonical upper/lower presentation.
ECHO0000010Enable echo.
ECHOE0000020Echo erase character as BS-SP-BS.
NOFLSH0000200Disable flush after interrupt or quit.

If ISIG is set, each input character is checked against the special control characters INTR, QUIT, SUSP, and DSUSP.  If an input character matches one of these control characters, the function associated with that character is performed.  If ISIG is not set, no checking is done.  Thus these special input functions are possible only if ISIG is set.  These functions may be disabled individually by changing the value of the control character to an unlikely or impossible value (e.g., 0377). 

If ICANON is set, canonical processing is enabled.  This enables the erase and kill edit functions, and the assembly of input characters into lines delimited by NL, EOF, and EOL.  If ICANON is not set, read requests are satisfied directly from the input queue.  A read will be satisfied as soon as one character is received; the values of MIN and TIME are ignored. 

If XCASE is set, and if ICANON is set, an upper-case letter is accepted on input by preceding it with a \ character, and is output preceded by a \ character.  In this mode, the following escape sequences are generated on output and accepted on input:

for: use:

` \´

│ \! 

~ \^

{ \(

} \)

Any other character, when preceded on input by \, will be read as itself, and the \ will not be read.  This means a \ must be entered as \\.  For example, A is input as \a, \n as \\n, and \N as \\\n.  Note: if this bit is set, the IUCLC bit in the c_iflag word and the OLCUC bit in the c_oflag word must also be set. 

If ECHO is set, characters are echoed as received.  If ECHO is not set, input characters are not echoed. 

When ICANON is set, the following echo functions are possible.  If ECHO and ECHOE are set, the erase character is echoed as a sequence of ASCII BS SP BS, which will clear the last character from a CRT screen.  If the baud rate is greater than 1200 baud, the kill character is echoed as a sequence of ASCII BS SP BS, which will clear all the characters on the current line from a CRT screen; otherwise, it is echoed as itself (if it is a control character, it will be echoed as described below) followed by an NL character.  If ECHOE is not set, the erase character is echoed by printing the character being erased; erased characters are echoed between a backslash (\) and a slash (/).  The NL character is always echoed after the kill character to emphasize that the line will be deleted.  Note that an escape character preceding the erase or kill character removes any special function. 

Non-printing (control) characters are normally echoed as ^X, where X is the character given by adding 100 octal to the control character’s code (so that the character with octal code 1 is echoed as ^A), and the ASCII DEL character, with code 177 octal, is echoed as ^?.  In “RAW mode”, control characters and DEL are echoed as themselves. 

If NOFLSH is set, the normal flush of the input and output queues associated with the INTR, QUIT, and SUSP characters will not be done. 

The initial line-discipline control value is undefined. 

The primary ioctl(2) system calls have the form:

ioctl (fildes, command, arg)
struct termio ∗arg;

The commands using this form are:

TCGETA Get the parameters associated with the terminal and store in the termio structure referenced by arg.

TCSETA Set the parameters associated with the terminal from the structure referred to by arg. The change is immediate.

TCSETAW

TCSETAF Wait for the output to drain, then flush the input queue and set the new parameters. This form should be used when changing parameters that will affect output. 

Additional ioctl(2) calls have the form:

ioctl (fildes, command, arg)
int arg;

The commands using this form are:

TCSBRK Wait for the output to drain.  If arg is 0, then send a break (zero bits for 0.25 seconds). 

Note: this call will flush any pending input. 

TCXONC Start/stop control.  If arg is 0, suspend output; if 1, restart suspended output. 

TCFLSH If arg is 0, flush the input queue; if 1, flush the output queue; if 2, flush both the input and output queues. 

FILES

/dev/tty∗

SEE ALSO

stty(1V), tset(1), fork(2), ioctl(2), setpgrp(2V), signal(2). 

Sun Release 3.2  —  Last change: