TERMIOS(7) TERMIOS(7)
NAME
termios - general terminal interface
SYNOPSIS
#include <termios.h>
DESCRIPTION
This section describes a general terminal interface for
controlling asynchronous communications ports.
When a terminal file is opened, it normally causes the
process to wait until the connection is established. In
practice, user programs seldom open these files; getty(1M)
opens them and they become a user's standard input, output
and error files.
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, programs that demand an output file name will accept
/dev/tty, so it is not necessary to determine which terminal
is being used.
Opening a terminal device causes the process to block until
the connection is established. If the ONONBLOCK flag is
set, open(2) will return a file descriptor without waiting
for the connection to be established.
A terminal may have a distinguished process group associated
with it. Certain characters have special functions on input
and/or output. The distinguished process group plays a role
in the handling of signal-generating characters.
Shells that support job control can allocate the terminal to
different jobs, or process groups, by placing related
processes in a single process group and associating this
process group with the terminal. A terminal's associated
process group may be set or examined by a process in the
process group using tcsetpgrp(3P) and tcgetpgrp(3P).
Page 1 May 1989
TERMIOS(7) TERMIOS(7)
A terminal may belong to a process as its controlling
terminal. If a process which is a session process group
leader and does not have a controlling terminal, opens a
terminal file not already associated with a process group
and the ONOCTTY flag is not set, the terminal associated
with the terminal file becomes the controlling terminal for
the process and the terminal's distinguished process group
is set to the process group of the process.
The controlling terminal is inherited by a child process
during a fork(2). A process relinquishes its controlling
terminal when it changes its process group using setpgrp(2)
or setsid(3). When a controlling process terminates, the
distinguished process group of its controlling terminal is
set to zero. This allows the terminal to be acquired as a
controlling terminal by a new session process group leader.
A terminal device associated with a terminal device file may
operate in full-duplex mode, so that characters may arrive
even while output is occurring. Each terminal device file
has associated with it an input queue, into which incoming
characters are placed by the system before being read by a
process. The system imposes a limit, {MAX_INPUT}, on the
number of bytes that may be stored in the input queue. If
{MAX_INPUT} is exceeded, the queue is flushed.
A terminal device file may be in canonical mode or non-
canonical mode. The mode of the terminal device file
determines the method of input processing.
In canonical mode input processing, terminal input is
processed in units of lines. A line is delimited by a
newline ('\n') character, and end-of-file (EOF) character or
an end-of-line (EOL) character. This means that a read
request will not be satisfied until an entire line has been
typed or a signal has been received. Also, no matter how
many characters are requested by the read, at most one line
is returned. It is not necessary to read a whole line at
once; any number of characters, even one, may be requested
Page 2 May 1989
TERMIOS(7) TERMIOS(7)
in a read without losing information. {MAX_CANON} is the
limit on the number of bytes in a line. If this limit is
exceeded, the input buffer is flushed. Erase and kill
processing will occur during canonical mode input
processing.
In non-canonical mode input processing, input characters are
not assembled into line, and erase and kill processing does
not occur. The values of the special characters MIN and
TIME are used to determine how to process the characters
received. MIN and TIME are defined in the ccc array of
special control characters.
MIN represents the minimum number of characters that should
be received when the read is satisfied. TIME is a timer of
0.1 second granularity that is used to time-out data
characterized by short bursts and short term data
transmissions. The four possible combinations for MIN and
TIME are as follows:
MIN > 0, TIME > 0:
In this case TIME serves as an intercharacter timer and
is activated after the first character is received.
Since it is an intercharacter timer, it is reset after a
character is received. When the first character is
received, the intercharacter timer is started. If MIN
characters are received before the timer expires, the
read is satisfied. If the timer expires before MIN
characters are received, the characters received to that
point are returned to the user. Note that if TIME
expires, at least one character is returned because the
timer is not started unless a character has been
received. In this case, the read blocks until the MIN
and TIME mechanisms are activated by the receipt of a
character.
MIN > 0, TIME = 0:
When the value of TIME is zero, the timer plays no role
and only MIN is significant. A pending read is not
satisfied until MIN characters are received. A program
Page 3 May 1989
TERMIOS(7) TERMIOS(7)
that sets TIME to zero when reading record-based
terminal I/O may block indefinitely on a read operation.
MIN = 0, TIME > 0:
When MIN is zero, TIME no longer represents an
intercharacter timer. TIME now serves as a read timer
that is activated as soon as the read() is processed. A
read is satisfied as soon as a single character is
received or the read timer expires. Note that if the
timer expires, no character will be returned. If the
timer does not expire, the only way the read can be
satisfied is if a character is received. In this case,
reads will not block indefinitely waiting for a
character; if no character is received within TIME*0.1
seconds after the read is initiated the read will return
zero characters.
MIN = 0, TIME = 0:
The minimum of either the number of characters requested
or the number of characters currently available will be
returned without waiting for more characters to be
input.
Reads are also dependent on the whether the ONONBLOCK flag
is set by the open(2) or fcntl(2) call. If the ONONBLOCK
flag is not set, then a read request will block until data
is available or a signal is received. If the ONONBLOCK
flag is set, then reads will complete without blocking in
one of three ways:
1.If there is enough data available to satisfy the entire
request, the read will complete successfully, having read
all the requested data, and return the number of bytes
read.
2.If there is not enough data available to satisfy the
entire request, the read will complete successfully,
having read as much data as possible, and return the
number of bytes it was able to read.
Page 4 May 1989
TERMIOS(7) TERMIOS(7)
3.If there is no data available, the read will return -1 and
errno will be set to EAGAIN.
Routines that control terminal characteristics do so by
modifying the termios structure for the device. This
structure is defined in <termios.h> as follows:
struct termios {
tcflagt ciflag;
tcflagt coflag;
tcflagt ccflag;
tcflagt clflag;
char cline;
unsigned char ccc[NCCS];
};
The c_iflag 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.
IXON 0002000 Enable start/stop output control.
IXOFF 0010000 Enable start/stop input control.
IUCLC 0001000 Map uppercase to lowercase on input.
IXANY 0004000 Enable any character to restart output.
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 neither IGNBRK or BRKINT is set, the
break condition is read as NUL (0). If IGNPAR is set,
Page 5 May 1989
TERMIOS(7) TERMIOS(7)
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). If ICRNL is set, a
received RETURN character is translated in an 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/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.
Page 6 May 1989
TERMIOS(7) TERMIOS(7)
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 003000 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 postprocessed 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
Page 7 May 1989
TERMIOS(7) TERMIOS(7)
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.
Page 8 May 1989
TERMIOS(7) TERMIOS(7)
The actual delays depend on line speed and system load.
The initial output control value is all bits clear.
The ccflag 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
B19200 0000016 19200 baud
B38400 0000017 38400 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.
Page 9 May 1989
TERMIOS(7) TERMIOS(7)
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
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).
ECHO 0000010 Enable echo.
ECHOE 0000020 Echo erase character as BS-SP-BS.
Page 10 May 1989
TERMIOS(7) TERMIOS(7)
ECHOK 0000040 Echo NL after kill character.
ECHONL 0000100 Echo NL.
NOFLSH 0000200 Disable flush after interrupt or quit.
TOSTOP 0000400 Send SIGTTOU for background output.
XCAS 0000004 Canonical upper/lower presentation.
If ISIG is set, each input character is checked against the
special control characters INTR, SUSP, 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 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:
Page 11 May 1989
TERMIOS(7) TERMIOS(7)
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, suspend, switch and
interrupt characters will not be done.
The initial line-discipline control value is all bits clear.
The special characters, their default values and functions
are as follows:
INTR Control-c. If the ISIG flag is enabled, generates a
SIGINT signal which is sent to all processes in the
distinguished process group associated with the
Page 12 May 1989
TERMIOS(7) TERMIOS(7)
terminal.
QUIT ASCII FS. If the ISIG flag is enabled, generates a
SIGQUIT signal which is sent to all process in the
distinguished process group associated with the
terminal.
ERASE DELETE. If the ICANON flag is set, erases the
preceding character. It will not erase beyond the
start of a line, as delimited by an NL, EOF or EOL
character.
KILL Control-u. If the ICANON flag is set, deletes the
entire line, as delimited by an NL, EOF or EOL
character.
EOF Control-d. If the ICANON flag is set when this
character is received, all the characters waiting to
be read are immediately passed to the program without
waiting for a newline and the EOF is discarded. If
there are no characters waiting, zero characters will
be passed to the program, indicating an end-of-file
condition.
NL ASCII LF. If the ICANON flag is set, this character
is the line delimiter ('\n'). It cannot be changed.
EOL ASCII NUL. If the ICANON flag is set, this character
is an additional line delimiter similar to NL.
SUSP Control-z. If the ISIG flag is set, generates a
SIGTSTP signal which is sent to all processes in the
distinguished process group associated with the
terminal.
STOP Control-s. If IXON or IXOFF flag is set, this
character is used to temporarily suspend output.
Useful on terminals to prevent output from
disappearing before it can be read.
Page 13 May 1989
TERMIOS(7) TERMIOS(7)
START Control-q. If IXON or IXOFF flag is set, this
character is used to resume output that has been
suspended by a STOP character.
SWTCH Control-z. Used by the shell layering facility, shl,
to change the current layer to the control layer.
The START and STOP characters cannot be changed. The values
for INTR, QUIT, ERASE, KILL, EOF, EOL, and SUSP can be
changed using tcsetattr(3P). ERASE, KILL, and EOF
characters may be escaped by preceding the character with a
'\'; in this case, no special function is performed.
cline specifies the line discipline number for the
terminal. The basic line discipline number is zero; this is
currently the only line discipline supported.
Special control characters are defined by the ccc array in
the termios structure. The subscript names and descriptions
are as follows:
VEOF EOF character
VEOL EOL character
VERASE ERASE character
VINTR INTR character
VKILL KILL character
VQUIT QUIT character
VSUSP SUSP character
VMIN MIN character
VTIME TIME character
VSTART START character
VSTOP STOP character
When a modem disconnect is detected by the terminal
interface, a SIGHUP is sent to all processes in the
distinguished process group associated with the terminal.
Unless other arrangements have been made, this signal causes
the processes to terminate. If SIGHUP is ignored or caught,
any subsequent read returns an end-of-file indication until
Page 14 May 1989
TERMIOS(7) TERMIOS(7)
the device is closed. Programs that read a terminal file
and test for end-of-file can terminate appropriately after a
disconnect.
The last process to close a terminal device file shall cause
any output to be sent to the device and any input to be
discarded. If HUPCL is set in the control structure, and
the communications port supports a disconnect function, the
terminal device will perform a disconnect.
The following functions are provided for controlling the
terminal interface:
cfgetispeed(3P)
Return the input baud rate.
cfgetospeed(3P)
Return the output baud rate.
cfsetispeed(3P)
Set the input baud rate.
cfsetospeed(3P)
Set the output baud rate.
tcdrain(3P) Wait until all written data is transmitted.
tcflow(3P) Suspend or restart output or input.
tcflush(3P) Discard data not transmitted.
tcgetattr(3P)
Get terminal attributes.
tcgetpgrp(3P)
Get distinguished process group ID.
tcsendbreak(3P)
Send a break.
Page 15 May 1989
TERMIOS(7) TERMIOS(7)
tcsetattr(3P)
Set terminal attributes.
tcsetpgrp(3P)
Set distinguished process group ID.
FILES
/dev/tty
SEE ALSO
cfgetospeed(3P), fcntl(2), getty(1M), open(2), tcdrain(3P),
tcgetpgrp(3p), tcgetattr(3P), tcsetpgrp(3P).
Page 16 May 1989