TERMIO(M) UNIX System V
Name
termio - general terminal interface
Description
All asynchronous communications ports use the same general
interface, no matter what hardware is involved. The
remainder of this section discusses the common features of
this interface.
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 getty(M) and become a user's standard input,
output, and error files. The very first terminal file
opened by the process group leader of a terminal file not
already associated with a process group becomes the 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(S). A process can break this association by changing
its process group using setpgrp(S).
A terminal associated with one of these files ordinarily
operates in full-duplex mode. Characters can be entered 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, 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 attempting to read
will be suspended until an entire line has been entered.
Also, no matter how many characters are requested in the
read call, one line will be returned at most. 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.
Erase and kill processing is normally done during input. By
default, a Ctrl-H or BACKSPACE erases the last character
typed, except that it will not erase beyond the beginning of
the line. By default, a Ctrl-U kills (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. Both 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 (see stty(C)).
Certain characters have special functions on input. These
functions and their default character values are summarized
as follows:
INTR (Rubout or ASCII DEL) Generates an interrupt signal
which is sent to all processes with the associated
control 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 signal(S).
QUIT (Ctrl-\ or ASCII FS) Generates a quit signal. 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.
SWTCH (ASCII NUL) Is used by the job control facility,
shl(C), to change the current layer to the control
layer.
ERASE (Ctrl-H) Erases the preceding character. It will
not erase beyond the start of a line, as delimited
by a NL, EOF, or EOL character.
KILL (Ctrl-U) Deletes the entire line, as delimited by a
NL, EOF, or EOL character.
EOF (Ctrl-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 newline, 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 cannot
be changed or escaped.
EOL (ASCII NUL) Is an additional line delimiter, like
NL. It is not normally used.
STOP (Ctrl-S or ASCII DC3) Temporarily suspends 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 (Ctrl-Q or ASCII DC1) Resumes 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 cannot be changed
or escaped.
The character values for INTR, QUIT, SWTCH, ERASE, KILL,
EOF, and EOL may be changed to suit individual tastes. The
ERASE, KILL, and EOF characters may be escaped by a
preceding backslash (\) character, in which case no special
function is carried out.
When the carrier signal from the dataset drops, a signal is
sent to all processes that have this terminal as the control
terminal. Unless other arrangements have been made, this
signal causes the processes to terminate. If the hangup
signal is ignored, any subsequent read returns with an end-
of-file indication. Thus, programs that read a terminal and
test for an 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 the previously typed
characters have been entered. 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 a
given limit. When the queue has drained down to the given
threshold, the program is resumed.
Several ioctl(S) system calls apply to terminal files. The
primary calls use the following structure, defined in the
file <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
c_cc. The relative positions and initial values for each
function are as follows:
0 VINTR DEL
1 VQUIT FS
2 VERASE Ctrl-H
3 VKILL Ctrl-U
4 VEOF/VMIN EOT
5 VEOL/VTIME NUL
6 VEOL2 EOL
7 VSWTCH NUL
The c_iflag field describes the basic terminal input
control:
IGNBRK 0000001 Ignores break condition
BRKINT 0000002 Signals interrupt on break
IGNPAR 0000004 Ignores characters with parity errors
PARMRK 0000010 Marks parity errors
INPCK 0000020 Enables input parity check
ISTRIP 0000040 Strips character
INLCR 0000100 Maps NL to CR on input
IGNCR 0000200 Ignores CR
ICRNL 0000400 Maps CR to NL on input
IUCLC 0001000 Maps uppercase to lowercase on input
IXON 0002000 Enables start/stop output control
IXANY 0004000 Enables any character to restart output
IXOFF 0010000 Enables 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 3-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 CR character. If IGNCR is set, a received CR character is
ignored (not read). Otherwise, if ICRNL is set, a received
CR character is translated into a NL character.
If IUCLC is set, a received uppercase alphabetic character
is translated into the corresponding lowercase 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 characters
when the input queue is nearly empty and STOP characters
when nearly full.
If CTSFLOW or RTSFLOW are set,
IXON and
IXANY should not be set (or vice versa) so that these two
types of flow control do not interfere with each other.
The RTS and CTS lines for the RS-232 (i.e. serial) interface
were originally intended as handshaking signals between a
Data Terminal Equipment (DTE) device (computer, printer,
etc,) and a Data Communications Equipment (DCE) device
(almost always a modem). The RTS (Ready To Send) line is
asserted by the DTE when it is ready to send data to the
DCE. The DCE asserts the CTS (Clear To Send) line when it
was ready to receive data. If the CTS line goes low, then
the DTE should stop sending data until CTS goes high again.
UNIX systems also use the RTS line for handshaking in the
other direction. If the system sees that its input buffer
is nearly full, it will lower the RTS line. The serial
device should then stop sending, and wait for the system to
catch up. The system will raise the RTS line when it is
ready for more data.
The initial input control value is all bits clear.
The c_oflag field specifies the system treatment of output:
OPOST 0000001 Postprocesses output
OLCUC 0000002 Maps lowercase to uppercase on output
ONLCR 0000004 Maps NL to CR-NL on output
OCRNL 0000010 Maps CR to NL on output
ONOCR 0000020 No CR output at column 0
ONLRET 0000040 NL performs CR function
OFILL 0000100 Uses fill characters for delay
OFDEL 0000200 Fills is DEL, else NUL
NLDLY 0000400 Selects newline delays:
NL0 0
NL1 0000400
CRDLY 0003000 Selects carriage return delays:
CR0 0
CR1 0001000
CR2 0002000
CR3 0003000
TABDLY 0014000 Selects horizontal tab delays:
TAB0 0
TAB1 0004000
TAB2 0010000
TAB3 0014000 Expands tabs to spaces
BSDLY 0020000 Selects backspace delays:
BS0 0
BS1 0020000
VTDLY 0040000 Selects vertical tab delays:
VT0 0
VT1 0040000
FFDLY 0100000 Selects 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 lowercase alphabetic character is
transmitted as the corresponding uppercase 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 perform the
carriage return function and the column pointer is set to 0
and the delays specified for CR will be used. Otherwise,
the NL character is assumed to perform the linefeed
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.
Newline 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, 2 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
2 fill characters, and type 2 transmits 4 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, 2 fill characters will be transmitted for any
delay.
Backspace delay lasts about 0.05 seconds. If OFILL is set,
1 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 c_cflag field describes the hardware control of the
terminal:
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 Sends two stop bits, else one
CREAD 0000200 Enables receiver
PARENB 0000400 Parity enable
PARODD 0001000 Odd parity, else even
HUPCL 0002000 Hangs up on last close
CLOCAL 0004000 Local line, else dial-up
LOBLK 0010000 Block layer output
CTSFLOW 0020000 Enables CTS protocol for a modem line
RTSFLOW 0040000 Enables RTS signaling for a modem line
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.
Without this signal, the line is disconnected if it is
connected through a modem. 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, 2 stop bits are used,
otherwise 1 stop bit. For example, at 110 baud, 2 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
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. The data-terminal-ready
and request-to-send signals are asserted, but incoming modem
signals are ignored. If CLOCAL is not set, modem control is
assumed. This means the data-terminal-ready and request-to-
send signals are asserted. Also, the carrier-detect signal
must be returned before communications can proceed.
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 B9600, CS8,
CREAD, HUPCL.
The c_lflag 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 Enables echo
ECHOE 0000020 Echoes erase character as BS-SP-BS
ECHOK 0000040 Echoes NL after kill character
ECHONL 0000100 Echoes NL
NOFLSH 0000200 Disables flush after interrupt or quit
XCLUDE 0100000 Exclusive use of the line
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 VMIN characters have been received or the
timeout value VTIME has expired and at least one character
has been input. This allows fast bursts of input to be read
efficiently while still allowing single character input.
(See the discussion of VMIN and VTIME below.)
The VMIN and VTIME values are stored in the position for the
EOF and EOL characters respectively. VMIN and VTIME are
interpreted as EOF and EOL if ICANON is set. Default VMIN
and VTIME values are stored in the /usr/include/sys/termio.h
file. To change these values, set ICANON to off and use
stty(C) to change the VMIN and VTIME values as represented
by EOF and EOL. The TIME value represents tenths of
seconds.
If XCASE and ICANON are set, an uppercase 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:
` \'
| \!
~ \^
{ \(
} \)
\ \\
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 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 and interrupt characters
will not be done.
If XCLUDE is set, any subsequent attempt to open the TTY
device using open(S) will fail for all users except the
super-user. If the call fails, it returns EBUSY in errno.
XCLUDE is useful for programs which must have exclusive use
of a communications line. It is not intended for the line
to the program's controlling terminal. XCLUDE must be
cleared before the setting program terminates, otherwise
subsequent attempts to open the device will fail.
VMIN represents the minimum number of characters that should
be received when the read is satisfied (i.e., the characters
are returned to the user). VTIME is a timer of 0.10 second
granularity used to time-out bursty and short-term data
transmissions. The four possible values for VMIN and VTIME
and their interactions are:
VMIN > 0, VTIME > 0
In this case, VTIME serves as an inter-character timer
activated after the first character is received, and reset
upon receipt of each character. VMIN and VTIME interact as
follows:
As soon as one character is received the inter-
character timer is started.
If VMIN characters are received before the inter-
character timer expires the read is satisfied.
If the timer expires before VMIN characters are
received the characters received to that point are
returned to the user.
A read(S) operation will sleep until the VMIN and VTIME
mechanisms are activated by the receipt of the first
character; thus, at least one character must be
returned.
VMIN > 0, VTIME = 0
In this case, because VTIME = 0, the timer plays no role and
only VMIN is significant. A read(S) operation is not
satisfied until VMIN characters are received.
VMIN = 0, VTIME > 0
In this case, because VMIN = 0, VTIME no longer serves as an
inter-character timer, but now serves as a read timer that
is activated as soon as the read(S) operation is processed.
A read(S) operation is satisfied as soon as a single
character is received or the timer expires, in which case,
the read(S) operation will not return any characters.
VMIN = 0, VTIME = 0
In this case, return is immediate. If characters are
present, they will be returned to the user.
The initial line-discipline control value is all bits clear.
The primary ioctl(S) system calls have the form:
ioctl (fildes, command, arg)
struct termio *arg;
The commands using this form are:
TCGETA Gets the parameters associated with the
terminal and stores them in the termio
structure referenced by arg.
TCSETA Sets the parameters associated with the
terminal from the structure referenced by
arg. The change is immediate.
TCSETAW Waits for the output to drain before setting
the new parameters. This form should be used
when changing parameters that will affect
output.
TCSETAF Waits for the output to drain, then flushes
the input queue and sets the new parameters.
Additional ioctl(S) calls have the form:
ioctl (fildes, command, arg)
int arg;
The commands using this form are:
TCSBRK Waits for the output to drain. If arg is 0,
then sends a break (zero bits for 0.25
seconds).
TCXONC Starts/stops control. If arg is 0, suspends
output; if 1, restarts suspended output.
TCFLSH If arg is 0, flushes the input queue; if 1,
flushes the output queue; if 2, flushes both
the input and output queues.
Files
/dev/tty
/dev/tty*
/dev/console
See Also
fork(S), ioctl(S), mapchan(F), mapchan(M), read(S),
setgprp(S), signal(S), stty(C), tty(M), termios(M)
Standards Conformance
termio is conformant with:
AT&T SVID Issue 2, Select Code 307-127;
and The X/Open Portability Guide II of January 1987.
(printed 2/15/90) TERMIO(M)