termio(7) termio(7)
NAME
termio - general terminal interface
DESCRIPTION
This section describes both a particular file and the
terminal interface.
The file /dev/tty is, in each process, the control terminal
associated with the process group of that process. Programs
or shell sequences use it to ensure that their messages
appear on the terminal, no matter how output is redirected.
Also, program programs that demand an output file name will
accept /dev/tty, so you don't have to find out what terminal
they are using.
The asynchronous communications ports use the same general
interface, no matter what their hardware. This section
discusses the common features of this interface.
When a terminal file is opened, it normally makes the
process wait until it establishes a connection. Users'
programs seldom open these files; getty opens them and they
become a user's standard input, output, and error files.
The first terminal file the process group leader opens,
which is not already associated with a process group,
becomes the control terminal for that process group. The
control terminal plays a special role in handling quit and
interrupt signals, as discussed below. The control terminal
is inherited by a child process during a fork(2). A process
breaks this association by changing its process group (using
setpgrp(2)).
Terminals associated with one of these files operate in
full-duplex mode. You may type at any time, even while the
terminal is printing. Characters you type are lost only
when the system's character input buffers are full, which is
rare, or when you have accumulated the maximum number of
input characters that have not been read by some program.
Currently, this limit is 256 characters. When you reach the
input limit, all the saved characters are thrown away
without notice.
Normally, terminal input is processed in units of lines. A
line is delimited by a newline (ASCII LF) character, an
end-of-file (ASCII EOT character, or an end-of-line
character. This means that a program cannot read input
until you have typed an entire line. Also, no matter how
many characters a read call requests, at most one line is
returned. It is not, however, necessary to read a whole
line at once; a read can request any number of characters,
even one, without losing information.
Page 1 (last mod. 1/15/87)
termio(7) termio(7)
Erase and kill processing is normally done duing input. By
default, the character # erases the last character typed,
but it does not erase beyond the beginning of the line. By
default, the character @ deletes the entire input line, and
optionally outputs a newline character. Both these
characters operate on a key-stroke basis, independent of any
backspacing or tabbing that may have been done. You can
escape both the erase and kill characters by preceding them
with the escape character (\). This prints @ or # on your
screen. You can also change the erase and kill characters.
The following characters have special input functions:
INTR (Rubout or CONTROL-c) interrupt signal to all
processes associated with the control terminal.
Normally, it terminates each process, but you can
arrange to have it ignore the signal or to receive a
trap to an agreed-upon location; see signal(2).
SWTCH (CONTROL-z or ASCII SUB) is used by the shell
layering facility, shl, to change the current layer
to the control layer, (except on PDP-11s).
QUIT (CONTROL- or ASCII FS) generates a quit signal. It
is identical to the interrupt signal except that,
unless a receiving process has made other
arrangements, it will also create a core image file
(called core) in the current working directory.
ERASE (#) erases the preceding character. It will not
erase beyond the start of a line, as delimited by a
NL, EOF, or EOL character.
KILL (@) deletes the entire line, as delimited by a NL,
EOF, or EOL character.
EOF (CONTROL-d or ASCII EOT) generates an end-of-file
from a terminal. This passes the characters waiting
to be read to the program, without waiting for a
newline, and discards the EOF. If no characters are
waiting, (if EOF occurred at the beginning of a
line), 0 characters are passed back; this is the
standard end-of-file indication.
NL (ASCII LF) is the normal line delimiter. It cannot
be changed or escaped.
EOL (ASCII NUL) is an additional line delimiter, like
NL. It is not normally used.
STOP (CONTROL-s or ASCII DC3) temporarily suspends
output. It is useful for preventing output from
Page 2 (last mod. 1/15/87)
termio(7) termio(7)
disappearing from CRT terminals before you have read
it. While output is suspended, STOP characters are
ignored and not read.
START (CONTROL-q or ASCII DC1) resumes output 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.
You can change the character values for INTR, QUIT, SWTCH,
ERASE, KILL, EOF, and EOL. You can escape the ERASE, KILL,
and EOF characters by preceding them with a \ character, in
which case no special function is done.
When a data-set drops the carrier signal, a hang-up signal
is sent to all processes that have this terminal as the
control terminal. Unless you have made other arrangements,
this signal terminates the processes. If the hang-up signal
is ignored, subsequent reads return 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.
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 by putting them in the output queue as they arrive.
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.
Several ioctl(2) system calls apply to terminal files. The
primary calls use the following structure, defined in
termio.h:
#define NCC 8
struct termio {
unsigned short c_iflag;/* input modes */
unsigned short c_oflag;/* output modes */
unsigned short c_cflag;/* control modes */
unsigned short c_lflag;/* local modes */
char c_line;/* line discipline */
unsigned char c_cc[NCC];/* control chars */
};
The special control characters are defined by the array
ccc. The relative positions and initial values for each
function are as follows:
0 VINTR DEL
1 VQUIT FS
2 VERASE #
3 VKILL @
Page 3 (last mod. 1/15/87)
termio(7) termio(7)
4 VEOF 1EOT
5 VEOL 1NUL
6 reserved
7 SWTCH NUL
The ciflag field describes the basic terminal input
control:
IGNBRK 0000001 Ignore break condition.
BRKINT 0000002 Signal interrupt on break.
IGNPAR 0000004 Ignore characters with parity errors.
PARMRK 0000010 Mark parity errors.
INPCK 0000020 Enable input parity check.
ISTRIP 0000040 Strip character.
INLCR 0000100 Map NL to CR on input.
IGNCR 0000200 Ignore CR.
ICRNL 0000400 Map CR to NL on input.
IUCLC 0001000 Map upper-case to lower-case on input.
IXON 0002000 Enable start/stop output control.
IXANY 0004000 Enable any character to restart output.
IXOFF 0010000 Enable start/stop input control.
If IGNBRK is set, the break condition (a character framing
error with data all zeros) is ignored, that is, not put on
the input queue and therefore not read by any process.
Otherwise 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.
If PARMRK is set, a character with a framing or parity error
which is not ignored is read as the three-character
sequence: 0377, 0, X, where X is the data of the character
received in error. To avoid ambiguity in this case, if
ISTRIP is not set, a valid character of 0377 is read as
0377, 0377. If PARMRK is not set, a framing or parity error
which is not ignored is read as the character NUL (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 8-bits are processed.
If INLCR is set, a received NL character is translated into
a RETURN character. If IGNCR is set, a received RETURN
character is ignored (not read). Otherwise if ICRNL is set,
a received RETURN character is translated into a NL
character.
If IUCLC is set, a received upper-case alphabetic character
Page 4 (last mod. 1/15/87)
termio(7) termio(7)
is translated into the corresponding lower-case character.
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 ignored and not read. If IXANY is set, any
input character, will restart output which has been
suspended.
If IXOFF is set, the system will transmit START/STOP
characters when the input queue is nearly empty/full.
The initial input control value is all-bits-clear.
The coflag field specifies the system treatment of output:
OPOST 0000001 Postprocess output.
OLCUC 0000002 Map lower case to upper on output.
ONLCR 0000004 Map NL to CR-NL on output.
OCRNL 0000010 Map CR to NL on output.
ONOCR 0000020 No CR output at column 0.
ONLRET 0000040 NL performs CR function.
OFILL 0000100 Use fill characters for delay.
OFDEL 0000200 Fill is DEL, else NNUL.
NLDLY 0000400 Select newline delays:
NL0 0
NL1 0000400
CRDLY 0003000 Select carriage-return delays:
CR0 0
CR1 0001000
CR2 0002000
CR3 0003000
TABDLY 0014000 Select horizontal-tab delays:
TAB0 0
TAB1 0004000
TAB2 0010000
TAB3 0014000 Expand tabs to spaces.
BSDLY 0020000 Select backspace delays:
BS0 0
BS1 0020000
VTDLY 0040000 Select vertical-tab delays:
VT0 0
VT1 0040000
FFDLY 0100000 Select form-feed delays:
FF0 0
FF1 0100000
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
Page 5 (last mod. 1/15/87)
termio(7) termio(7)
transmitted as the corresponding upper-case character. This
function is often used in conjunction with IUCLC.
If ONLCR is set, the NL character is transmitted as the CR-
NL character pair. If OCRNL is set, the CR character is
transmitted as the NL character. If ONOCR is set, no CR
character is transmitted when at column 0 (first position).
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 OFILL is set, fill characters will be
transmitted for delay instead of a timed delay. This is
useful for high baud rate terminals which need only a
minimal delay. If OFDEL is set, the fill character is DEL,
otherwise NUL.
If a form-feed or vertical-tab delay is specified, it lasts
for about 2 seconds.
New-line delay lasts about 0.10 seconds. If ONLRET is set,
the carriage-return delays are used instead of the newline
delays. If OFILL is set, two fill characters will be
transmitted.
Carriage-return delay type 1 is dependent on the current
column position, type 2 is about 0.10 seconds, and type 3 is
about 0.15 seconds. If OFILL is set, delay type 1 transmits
two fill characters, and type 2, four fill characters.
Horizontal-tab delay type 1 is dependent on the current
column position. Type 2 is about 0.10 seconds. Type 3
specifies that tabs are to be expanded into spaces. If
OFILL is set, two fill characters will be transmitted for
any delay.
Backspace delay lasts about 0.05 seconds. If OFILL is set,
one fill character will be transmitted.
The actual delays depend on line speed and system load.
The initial output control value is all bits clear.
The field describes the hardware control of the terminal:
Page 6 (last mod. 1/15/87)
termio(7) termio(7)
CBAUD 0000017 Baud rate:
B0 0 Hang up
B50 0000001 50 baud
B75 0000002 75 baud
B110 0000003 110 baud
B134 0000004 134.5 baud
B150 0000005 150 baud
B200 0000006 200 baud
B300 0000007 300 baud
B600 0000010 600 baud
B1200 0000011 1200 baud
B1800 0000012 1800 baud
B2400 0000013 2400 baud
B4800 0000014 4800 baud
B9600 0000015 9600 baud
EXTA 0000016 External A
EXTB 0000017 External B
CSIZE 0000060 Character size:
CS5 0 5 bits
CS6 0000020 6 bits
CS7 0000040 7 bits
CS8 0000060 8 bits
CSTOPB 0000100 Send two stop bits, else one.
CREAD 0000200 Enable receiver.
PARENB 0000400 Parity enable.
PARODD 0001000 Odd parity, else even.
HUPCL 0002000 Hang up on last close.
CLOCAL 0004000 Local line, else dial-up.
LOBLK 0010000 Block layer output.
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
stops 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.
If CREAD is set, the receiver is enabled. Otherwise no
characters will be received.
If HUPCL is set, the line will be disconnected when the last
process with the line open closes it or terminates. That
Page 7 (last mod. 1/15/87)
termio(7) termio(7)
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.
If LOBLK is set, the output of a job control layer will be
blocked when it is not the current layer. Otherwise the
output generated by that layer will be multiplexed onto the
current layer.
The initial hardware control value after open is B300,CS8,
CREAD, HUPCL.
The clflag field of the argument structure is used by the
line discipline to control terminal functions. The basic
line discipline (0) provides the following:
ISIG 0000001 Enable signals.
ICANON 0000002 Canonical input (erase and kill processing).
XCASE 0000004 Canonical upper/lower presentation.
ECHO 0000010 Enable echo.
ECHOE 0000020 Echo erase character as BS-SP-BS.
ECHOK 0000040 Echo NL after kill character.
ECHONL 0000100 Echo NL.
NOFLSH 0000200 Disable flush after interrupt or quit.
If ISIG is set, each input character is checked against the
special control characters INTR, SWTCH, and QUIT. 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 not be satisfied
until at least MIN characters have been received or the
timeout value TIME has expired between characters. This
allows fast bursts of input to be read efficiently while
still allowing single character input. The MIN and TIME
values are stored in the position for the EOF and EOL
characters, respectively. The time value represents tenths
of seconds.
If XCASE is set, and if ICANON is set, an upper-case letter
is accepted on input by preceding it with a \ character, and
Page 8 (last mod. 1/15/87)
termio(7) termio(7)
is output preceded by a \ character. In this mode, the
following escape sequences are generated on output and
accepted on input:
for: use:
` \'
| \!
~ \^
{ \(
} \)
\ \\
For example, A is input as \a, \n as \\n, and \N as \\\n.
If ECHO is set, characters are echoed as received.
When ICANON is set, the following echo functions are
possible. If ECHO and ECHOE are set, the erase character is
echoed as ASCII BS SP BS, which will clear the last
character from a CRT screen. If ECHOE is set and ECHO is
not set, the erase character is echoed as ASCII SP BS. If
ECHOK is set, the NL character will be 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. If ECHONL is set,
the NL character will be echoed even if ECHO is not set.
This is useful for terminals set to local echo (so-called
half duplex). Unless escaped, the EOF character is not
echoed. Because EOT is the default EOF character, this
prevents terminals that respond to EOT from hanging up.
If NOFLSH is set, the normal flush of the input and output
queues associated with the quit, switch, and interrupt
characters will not be done.
The initial line-discipline control value is all bits clear.
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.
TIOCGPGRP The current terminal process group is placed
into the word at the address contained in
arg.
Page 9 (last mod. 1/15/87)
termio(7) termio(7)
TIOCSPGRP The address pointed to by arg contains a
word, typically a process id, that becomes
the process group for the controlling
terminal.
TCSETA Set the parameters associated with the
terminal from the structure referenced by
arg. The change is immediate.
TCSETAW Wait for the output to drain before setting
the new parameters. This form should be used
when changing parameters that will affect
output.
TCSETAF Wait for the output to drain, then flush the
input queue and set the new parameters.
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).
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.
The following ioctl(2) calls take the form
ioctl(fildes, command, 0)
They are for modem control - not all devices support all or
any them. If any are supported then UIOCTTSTAT is supported.
The default is UIOCNOMODEM/UIOCNOFLOW. All these are
``remembered'' when a device is closed and reopened again.
The following are mutually exclusive (on some systems
DTR/DCD are named in reverse order: here DCD is the input,
DTR the output)
UIOCMODEM modem control (DTR/DCD) is enabled (DCD
is required before a device can be
opened, if it is removed the device is
"hung up", on opening DTR is asserted);
the default is on for /dev/modem and
Page 10 (last mod. 1/15/87)
termio(7) termio(7)
/dev/tty0
UIOCEMODEM ``European style'' modem control. Like
UIOMODEM except that DTR is not asserted
until RI (ring interrupt) is detected.
UIOCNOMODEM no modem control, DTR is still asserted
but DCD is ignored and opens always
complete without waiting
UIOCDTRFLOW the DCD (on some printers this is the
DTR line) is used for flow control. It
must be asserted before characters can
be transmitted; the default is on for
/dev/printer and /dev/tty1
The next two are also mutually exclusive. Again CTS/RTS are
sometimes named in reverse order. Here RTS is the output,
CTS the input
UIOCNOFLOW hardware flow control is disabled. RTS
is asserted before transmitting (or
asserted all the time). CTS is ignored
UIOCFLOW hardware flow control is enabled. RTS is
asserted before transmitting. CTS must
be asserted by the other end before
transmission can start. (this is
required for every character).
UIOCTTSTAT this returns 3 bytes. The first is 1 if
UIOCMODEM is enabled. The second is 1 if
UIOCDTRFLOW is enabled and the third is
1 if UIOCFLOW is enabled.
One last ioctl(2) call has the form
ioctl (fildes, command, pArg)
int *pArg;
The command using this form is:
FIONREAD Return the number of characters currently in a
terminal's input buffer into the integer
pointer *pArg.
FIONBIO If the integer referenced by the pointer pArg
is 1, then turn on non-blocking IO. If it is
0, turn it off. If non-blocking IO is turned
on, then read or write will reuturn without
blocking (and return the error EWOULDBLOCK) if
it is not possible to complete the transfer
Page 11 (last mod. 1/15/87)
termio(7) termio(7)
immediately.
FIOASYNC If the integer referenced byt he pointer pArg
is 1, turn on IO signalling. If it is 0, turn
it off. If IO signalling is turned on then the
signal SIGIO will be sent whenever input is
available to the device. Care should be taken
that all the processes in the tty's process
group can respond (or ignore) this signal if it
is enabled.
Some devices are streams based. In order for them to
respond to the ioctl calls discussed here, the streams
module (line discipline) line must be pushed on the stream.
For most logged in terminals, this is done by /etc/getty as
part of the logging in process. Refer to streams(7) and
linepush(3) for more information about how to do this if it
is required.
4.2 BSD Compatible Features
Local Special Characters
When job control is active, there is a ltchars structure
associated with each terminal. Two fields are used, which
define characters to stop a process. The other fields are
for compatibility with past and future systems.
struct ltchars {
char t_suspc; /* stop process signal */
char t_dsuspc; /* delayed stop process
signal */
char t_rprntc; /* Not used */
char t_flushc; /* Not used */
char t_werase; /* Not used */
char t_lnextc; /* Not used */
};
By default, these characters are disabled (set to -1).
Traditionally CONTROL-Z is used for the suspend character
and CONTROL-Y for the delayed suspend.
TIOCSLTC The arg parameter to the ioctl call (as shown
above) is the address of a ltchars structure
which defines the new local characters.
TIOCGLTC The arg parameter to the ioctl is the address of
a ltchars structure into which the current set
of special characters is placed.
Compatibility Modes
An additional mode word is recognized by the BSD compatible
TTY driver. It is used to set and clear the job control
Page 12 (last mod. 1/15/87)
termio(7) termio(7)
``tostop'' bit. When set, processes running in background
which write on the terminal will be sent a SIGTTOU signal.
When BSD compatible signals are used, background processes
which read from TTY will be sent SIGTTIN.
TOSTOP 0x1 Send SIGTTOU for background
output.
TIOCSCOMPAT
The arg parameter to the ioct call is the address of an
integer containing the new value of the compatibility
mode word.
/dev/tty
/dev/tty*
/dev/console
SEE ALSO
stty(1), fork(2), ioctl(2), setpgrp(2), signal(2),
line_push(3), streams(7).
Page 13 (last mod. 1/15/87)