NAME
tty, termios - terminals
DESCRIPTION
The tty driver family takes care of all user input and out-
put. It governs the keyboard, the console, the serial
lines, and pseudo ttys. Input on any of these devices
undergoes "input processing", and output undergoes "output
processing" according to the standard termios terminal
interface.
Input processing
Each terminal device has an input queue. This queue is used
to store preprocessed input characters, and to perform the
backspacing and erase functions. Some special characters
like a newline make the contents of the queue available to a
process reading from the terminal. Characters up to and
including the newline, or another so-called "line break",
may be read by a process. The process need not read all
characters at once. An input line may be read byte by byte
if one wants to. A line break just makes characters avail-
able for reading, thats all.
When data is made available depends on whether the tty is in
canonical mode or not. In canonical mode the terminal
processes input line by line. A line ends with a newline
(NL), end-of-file (EOF), or end-of-line (EOL). Characters
that have not been delimited by such a line break may be
erased one by one with the ERASE character or all at once
with the KILL character. Once a line break is typed the
characters become available to a reading process and can no
longer be erased. Once read they are removed from the input
queue. Several lines may be gathered in the input queue if
no reader is present to read them, but a new reader will
only receive one line. Two line breaks are never returned
in one read call. The input queue has a maximum length of
MAX_CANON characters. Any more characters are discarded.
One must use ERASE or KILL to make the terminal functioning
again if the input queue fills up. If nonblocking I/O is
set then -1 is returned with errno set to EAGAIN if the
reader would otherwise be blocked.
In non-canonical mode (raw mode for short) all characters
are immediately available to the reader in principle. One
may however tune the terminal to bursty input with the MIN
and TIME parameters, see the raw I/O parameters section
below. In raw mode no characters are discarded if the input
queue threatens to overflow if the device supports flow con-
trol.
Output processing
Characters written to a terminal device may undergo output
processing, which is usually just inserting a carriage
returns before newlines. A writer may return before all
characters are output if the characters can be stored in the
output buffers. If not then the writer may be blocked until
space is available. If non-blocking I/O is set then only
the count of the number of bytes that can be processed
immediately is returned. If no characters can be written at
all then -1 is returned with errno set to EAGAIN.
Special characters
Some characters have special functions in some of the termi-
nal modes. These characters are as follows, with the MINIX
3 defaults shown in parentheses:
INTR (^?)
Special input character that is recognized if ISIG is
set. (For ISIG and other flags see the various modes
sections below.) It causes a SIGINT signal to be sent
to all processes in the terminal process group. (See
the section on session leaders below.)
QUIT (^\)
Special input character if ISIG is set. Causes a
SIGQUIT signal to be sent to the terminal process
group.
ERASE (^H)
Special input character if ICANON is set. Erases the
last character in the current line.
KILL (^U)
Special input character if ICANON is set. Erases the
entire line.
EOF (^D)
Special input character if ICANON is set. It is a line
break character that is not itself returned to a
reader. If EOF is typed with no input present then the
read returns zero, which normally causes the reader to
assume that end-of-file is reached.
CR (^M)
Special input character if IGNCR or ICRNL is set. It
is a carriage return ('\r'). If IGNCR is set then CR
is discarded. If ICRNL is set and IGNCR is not set
then CR is changed into an NL and has the same function
as NL.
NL (^J)
Special input character if ICANON is set. It is both a
newline ('\n') and a line break.
Special output character if OPOST and ONLCR are set. A
CR NL sequence is output instead of just NL. (MINIX 3
specific, but almost mandatory on any UNIX-like sys-
tem.)
TAB (^I)
Special character on output if OPOST and XTABS are set.
It is transformed into the number of spaces necessary
to reach a column position that is a multiple of eight.
(Only needed for terminals without hardware tabs.)
EOL (undefined)
Special input character if ICANON is set. It is an
additional line break.
SUSP (^Z)
Special input character if job control is implemented
and ISIG is set. It causes a SIGTSTP signal to be send
to the terminal process group. (MINIX 3 does not have
job control.)
STOP (^S)
Special input character if IXON is set. It suspends
terminal output and is then discarded.
START (^Q)
Special output character if IXON is set. It starts
terminal output if suspended and is then discarded. If
IXANY is also set then any other character also starts
terminal output, but they are not discarded.
REPRINT (^R)
Special input character if IEXTEN and ECHO are set.
Reprints the input queue from the last line break
onwards. A reprint also happens automatically if the
echoed input has been messed up by other output and
ERASE is typed.
LNEXT (^V)
Special input character if IEXTEN is set. It is the
"literal next" character that causes the next character
to be input without any special processing.
DISCARD (^O)
Special input character if IEXTEN is set. Causes out-
put to be discarded until it is typed again. (Imple-
mented only under Minix-vmd.)
All of these characters except CR, NL and TAB may be changed
or disabled under MINIX 3. (Changes to START and STOP may
be ignored under other termios implementations.) The
REPRINT and LNEXT characters are MINIX 3 extensions that are
commonly present in other implementations. POSIX is unclear
on whether IEXTEN, IGNCR and ICRNL should be active in non-
canonical mode, but under MINIX 3 they are.
Terminal attributes
The attributes of a terminal, such as whether the mode
should be canonical or non-canonical, are controlled by rou-
tines that use the termios structure as defined in
<termios.h>:
struct termios {
tcflag_t c_iflag; /* input modes */
tcflag_t c_oflag; /* output modes */
tcflag_t c_cflag; /* control modes */
tcflag_t c_lflag; /* local modes */
speed_t c_ispeed; /* input speed */
speed_t c_ospeed; /* output speed */
cc_t c_cc[NCCS]; /* control characters */
};
The types tcflag, speed_t and cc_t are defined in
<termios.h> as unsigned integral types.
Input Modes
The c_iflag field contains the following single bit flags
that control input processing:
ICRNL
Map CR to NL on input.
IGNCR
Ignore CR on input. This flag overrides ICRNL.
INLCR
Map NL to CR on input. This is done after the IGNCR
check.
IXON Enable start/stop output control.
IXOFF
Enable start/stop input control. (Not implemented.)
IXANY
Allow any character to restart output. (MINIX 3
specific.)
ISTRIP
Strip characters to seven bits.
IGNPAR
Ignore characters with parity errors. (Not imple-
mented.)
INPCK
Enable input parity checking. (Not implemented.)
PARMRK
Mark parity errors by preceding the faulty character
with '\377', '\0'. The character '\377' is preceded by
another '\377' to avoid ambiguity. (Not implemented.)
BRKINT
Send the signal SIGINT to the terminal process group
when receiving a break condition. (Not implemented.)
IGNBRK
Ignore break condition. If neither BRKINT or IGNBRK is
set a break is input as a single '\0', or if PARMRK is
set as '\377', '\0', '\0'. (Breaks are always
ignored.)
Output Modes
The c_oflag field contains the following single bit flags
that control output processing:
OPOST
Perform output processing. This flag is the "main
switch" on output processing. All other flags are
MINIX 3 specific.
ONLCR
Transform an NL to a CR NL sequence on output. Note
that a key labeled "RETURN" or "ENTER" usually sends a
CR. In line oriented mode this is normally transformed
into NL by ICRNL. NL is the normal UNIX line delimiter
('\n'). On output an NL is transformed into the CR NL
sequence that is necessary to reach the first column of
the next line. (This is a common output processing
function for UNIX-like systems, but not always
separately switchable by an ONLCR flag.)
XTABS
Transform a TAB into the number of spaces necessary to
reach a column position that is a multiple of eight.
ONOEOT
Discard EOT (^D) characters. (Minix-vmd only.)
Control Modes
The c_cflag field contains the following single bit flags
and bit field for basic hardware control:
CLOCAL
Ignore modem status lines.
CREAD
Enable receiver. (The receiver is always enabled.)
CSIZE
Number of bits per byte. CSIZE masks off the values
CS5, CS6, CS7 and CS8 that indicate that 5, 6, 7 or 8
bits are used.
CSTOPB
Send two stop bits instead of one. Two stop bits are
normally used at 110 baud or less.
PARENB
Enable parity generation.
PARODD
Generate odd parity if parity is generated, otherwise
even parity.
HUPCL
Drop the modem control lines on the last close of the
terminal line. (Not implemented.)
Local Modes
The c_lflag field contains the following single bit flags
that control various functions:
ECHO Enable echoing of input characters. Most input charac-
ters are echoed as they are. Control characters are
echoed as ^X where X is the letter used to say that the
control character is CTRL-X. The CR, NL and TAB char-
acters are echoed with their normal effect unless they
are escaped by LNEXT.
ECHOE
If ICANON and ECHO are set then echo ERASE and KILL as
one or more backspace-space-backspace sequences to wipe
out the last character or the entire line, otherwise
they are echoed as they are.
ECHOK
If ICANON and ECHO are set and ECHOE is not set then
output an NL after the KILL character. (For hardcopy
terminals it is best to unset ECHOE and to set ECHOK.)
ECHONL
Echo NL even if ECHO is not set, but ICANON is set.
ICANON
Canonical input. This enables line oriented input and
erase and kill processing.
IEXTEN
Enable implementation defined input extensions.
ISIG Enable the signal characters INTR, QUIT and SUSP.
NOFLSH
Disable the flushing of the input and output queues
that is normally done if a signal is sent.
TOSTOP
Send a SIGTTOU signal if job control is implemented and
a background process tries to write. (MINIX 3 has no
job control.)
Input and output speed
The input and output speed are encoded into the c_ispeed and
c_ospeed fields. <termios.h> defines the symbols B0, B50,
B75, B110, B134, B150, B200, B300, B600, B1200, B1800,
B2400, B4800, B9600, B19200, B38400, B57600 and B115200 as
values used to indicate the given baud rates. The zero baud
rate, B0, if used for the input speed causes the input speed
to be equal to the output speed. Setting the output speed
to zero hangs up the line. One should use the functions
cfgetispeed(), cfgetospeed(), cfsetispeed() and
cfsetospeed() to get or set a speed, because the c_ispeed
and c_ospeed fields may not be visible under other implemen-
tations. (The c_ispeed and c_ospeed fields and the B57600
and B115200 symbols are MINIX 3 specific.)
Special characters
The c_cc array contains the special characters that can be
modified. The array has length NCCS and is subscripted by
the symbols VEOF, VEOL, VERASE, VINTR, VKILL, VMIN, VQUIT,
VTIME, VSUSP, VSTART, VSTOP, VREPRINT, VLNEXT and VDISCARD.
All these symbols are defined in <termios.h>. Some imple-
mentations may give the same values to the VMIN and VTIME
subscripts and the VEOF and VEOL subscripts respectively,
and may ignore changes to START and STOP. (Under MINIX 3
all special characters have their own c_cc slot and can all
be modified.)
Raw I/O Parameters
The MIN and TIME parameters can be used to adjust a raw con-
nection to bursty input. MIN represents a minimum number of
bytes that must be received before a read call returns.
TIME is a timer of 0.1 second granularity that can be used
to time out a read. Setting either of these parameters to
zero has special meaning, which leads to the following four
possibilities:
MIN > 0, TIME > 0
TIME is an inter-byte timer that is started (and
restarted) when a byte is received. A read succeeds
when either the minimum number of characters is
received or the timer expires. Note that the timer
starts after the first character, so the read returns
at least one byte.
MIN > 0, TIME = 0
Now the timer is disabled, and a reader blocks indefin-
itely until at least MIN characters are received.
MIN = 0, TIME > 0
TIME is now a read timer that is started when a read is
executed. The read will return if the read timer
expires or if at least one byte is input. (Note that a
value of zero may be returned to the reader.)
MIN = 0, TIME = 0
The bytes currently available are returned. Zero is
returned if no bytes are available.
User Level Functions
Termios attributes are set or examined, and special func-
tions can be performed by using the functions described in
termios(3).
Session Leaders and Process Groups
With the use of the setsid() function can a process become a
session leader. A session leader forms a process group with
a process group id equal to the process id of the session
leader. If a session leader opens a terminal device file
then this terminal becomes the controlling tty of the ses-
sion leader. Unless the terminal is already the controlling
tty of another process, or unless the O_NOCTTY flag is used
to prevent the allocation of a controlling tty. The process
group of the session leader is now remembered as the termi-
nal process group for signals sent by the terminal driver.
All the children and grandchildren of the session leader
inherit the controlling terminal and process group until
they themselves use setsid().
The controlling tty becomes inaccessible to the children of
the session leader when the session leader exits, and a
hangup signal is sent to all the members of the process
group. The input and output queues are flushed on the last
close of a terminal and all attributes are reset to the
default state.
A special device /dev/tty is a synonym for the controlling
tty of a process. It allows a process to reach the terminal
even when standard input, output and error are redirected.
Opening this device can also be used as a test to see if a
process has a controlling tty or not.
For MINIX 3 a special write-only device /dev/log exists for
processes that want to write messages to the system console.
Unlike the console this device is still accessible when a
session leader exits.
Minix-vmd also has a /dev/log device, but this device is
read-write. All messages written to the log device or to
the console when X11 is active can be read from /dev/log.
The system tries to preserve the log buffer over a reboot so
that panic messages reappear in the log if the system hap-
pens to crash.
Pseudo Terminals
Pseudo ttys allow a process such as a remote login daemon to
set up a terminal for a remote login session. The login
session uses a device like /dev/ttyp0 for input and output,
and the remote login daemon uses the device /dev/ptyp0 to
supply input to or take output from the login session and
transfer this to or from the originating system. So the
character flow may be: Local user input sent to the remote
system is written to /dev/ptyp0 by the remote login daemon,
undergoes input processing and appears on /dev/ttyp0 as
input to the login session. Output from the login session
to /dev/ttyp0 undergoes output processing, is read from
/dev/ptyp0 by the remote login daemon and is send over to
the local system to be displayed for the user. (So there
are only four data streams to worry about in a pseudo termi-
nal.)
A pseudo terminal can be allocated by trying to open all the
controlling devices /dev/ptynn one by one until it succeeds.
Further opens will fail once a pty is open. The process
should now fork, the child should become session leader,
open the tty side of the pty and start a login session.
If the tty side is eventually closed down then reads from
the pty side will return zero and writes return -1 with
errno set to EIO. If the pty side is closed first then a
SIGHUP signal is sent to the session leader and further
reads from the tty side return zero and writes return -1
with errno set to EIO. (Special note: A line erase may
cause up to three times the size of the tty input queue to
be sent to the pty reader as backspace overstrikes. Some of
this output may get lost if the pty reader cannot accept it
all at once in a single read call.)
Backwards compatibility
The TIOCGETP, TIOCSETP, TIOCGETC and TIOCSETC ioctl func-
tions that are used by the old sgtty terminal interface are
still supported by the terminal driver by emulation. Note
that these old functions cannot control all termios attri-
butes, so the terminal must be in a relatively sane state to
avoid problems.
FILES
The list below shows all devices that MINIX 3 and Minix-vmd
have. Not all of these devices are configured in by
default, as indicated by the numbers (i/j/k, l/m/n) that
tell the minimum, default and maximum possible number of
these devices for MINIX 3 (i/j/k) and Minix-vmd (l/m/n).
/dev/console System console.
/dev/ttyc[1-7] Virtual consoles. (0/1/7, 0/1/7)
/dev/log Console log device.
/dev/tty0[0-3] Serial lines. (0/2/2, 4/4/4)
/dev/tty[p-w][0-f] Pseudo ttys. (0/0/64, 1/32/128)
/dev/pty[p-w][0-f] Associated pseudo tty controllers.
SEE ALSO
stty(1), termios(3), setsid(2), read(2), write(2).
BUGS
A fair number of flags are not implemented under MINIX 3
(yet). Luckily they are very limited utility and only apply
to RS-232, not to the user interface.
AUTHOR
Kees J. Bot (kjb@cs.vu.nl)