TTY(4) Devices TTY(4)
NAME
tty - general terminal interface
SYNOPSIS
#include <sgtty.h>
DESCRIPTION
This file documents the special file .tty and the terminal drivers used
for user-oriented I/O.
Terminals are controlled through calls to the ioctl(2) system call:
#include <sgtty.h>
ioctl(int filedes, unsigned long code, void *arg);
This is a very flexible interface where filedes specifies the terminal
to modify, code indicates an action code, and arg is a pointer to a pa‐
rameter block. The type of variable pointed to by arg and how it is
interpreted depends on the value of code.
Due to the colorful history of UNIX systems, the data structures used
to manipulate terminal modes and settings are separated into five
groups. Future revisions of GNO will implement the POSIX termio inter‐
face, which consolidates these structures into one place.
This manual page first explains the concepts of controlling terminals,
process groups, and terminal modes. It then goes on to explain each
code that can be used with ioctl(2) to control a terminal. Since there
are five data structures used in ioctl calls to control terminals, the
description of the possible codes in this man page is ordered by the
type of the data structure pointed to by arg.
The Controlling Terminal
Every process has associated with it a controlling terminal,
which is the terminal from which the process was invoked. In
some versions of UNIX, the controlling terminal association is
responsible for job control; this is not so under GNO. A
process' controlling terminal is inherited from its parent. By
opening the special file .tty, a process can access its control‐
ling terminal. This is useful where the input and output of a
process was redirected and the process wants to be sure of get‐
ting input from or output to the user at the terminal.
A process can remove the association it has with its controlling
terminal by opening the file .tty and issuing the system call:
ioctl (fd, TIOCNOTTY, NULL);
where fd is the file descriptor associated with .tty. This is
often desirable in server processes.
Process Groups
Every terminal has an associated process group. Any time a sig‐
nal-generating special character is typed at the terminal, the
terminal's process group is sent that signal. UNIX systems set
process groups using ioctl(2) calls, but under GNO a new inter‐
face method is used; process group assignments are controlled
with the JOBCONTROL(2) routines.
Modes There are three modes in which terminal drivers operate. These
modes control how the driver deals with I/O.
cooked This is the default mode of the terminal driver. If an
incoming character is one of the special characters de‐
fined in sgttyb, tchars, or ltchars, the appropriate ac‐
tion is performed (see below). This mode also allows for
input editing, as input is internally buffered line by
line, and data is returned to a reading process only when
CR is entered.
cbreak Input is returned on a per-character basis, instead of
line by line as in cooked mode. If no data is available,
a read will block the calling process. If data is avail‐
able, a number of characters up to but not exceeding the
requested number will be returned. Special characters
such as t_intrc are not handled, but are passed on to the
caller as data.
raw Like cbreak mode, except that no input or output process‐
ing whatsoever is performed.
struct sgttyb
The basic ioctls use the sgttyb structure:
struct sgttyb {
char sg_ispeed;
char sg_ospeed;
char sg_erase;
char sg_kill;
short sg_flags;
};
sg_ispeed and sg_ospeed indicate the baud rates for input and
output according to the following table. Speed changes that do
not apply to a particular piece of hardware are ignored (for in‐
stance, the console driver does not access a serial port so all
baud rate settings are, in effect, impossible). Also, not all
the baud rates supported by a particular device are allowed to
be set from this interface.
These symbolic names for the baud rate settings are defined in
<sgtty.h>.
B0 0 (hang up dataphone)
B50 1 50 baud
B75 2 75 baud
B110 3 110 baud
B134 4 134.5 baud
B150 5 150 baud
B200 6 200 baud
B300 7 300 baud
B600 8 600 baud
B1200 9 1200 baud
B1800 10 1800 baud
B2400 11 2400 baud
B4800 12 4800 baud
B9600 13 9600 baud
B19200 14 19200 baud
EXTA 14 19200 baud
B38400 15 38400 baud
EXTB 15 38400 baud
The sg_erase and sg_kill fields specify the line-editing erase
and kill characters. sg_erase is 0x7F (delete) by default, and
sg_kill is not currently used.
sg_flags is a bitmapped value that indicates various state set‐
tings for the terminal driver (values are in hex).
EVENP 0x80 Use Even parity (serial devices only)
ODDP 0x40 Use Odd parity (serial devices only)
RAW 0x20 Raw mode: wake up on all characters,
8-bit interface
CRMOD 0x10 Map CR into LF; output LF as CR-LF
ECHO 0x08 Echo (full duplex)
CBREAK 0x02 Return each character as soon as typed
TANDEM 0x01 Automatic flow control
RAW and CBREAK modes were described above, in Modes.
If the CRMOD bit is set, a line feed character is appended to
any emitted carriage return.
The ECHO bit controls input echoing; if enabled, any characters
read from the terminal are echoed. This behavior differs
slightly from UNIX, where input characters are echoed as soon as
typed.
TANDEM mode enables automatic software flow control utilizing
the special characters t_startc and t_stopc in tchars (below).
Whenever the input queue is in danger of overflowing, the system
sends t_stopc; when the queue has drained sufficiently, t_startc
is sent. This mode has no effect on the console driver.
Note: t_startc and t_stopc are used for both directions of flow
control; when t_stopc is received from a remote system (or
user), the terminal stops output, and when t_startc is received
output resumes. Certain drivers may also require t_stopc and
t_startc to be the same character, in which case one or the
other setting will be ignored. See the driver's documentation
for details.
The ioctl codes that apply to sgtty are:
TIOCGETP
Fetch the basic parameters associated with the terminal,
and store in the sgttyb structure pointed to by arg.
TIOCSETP
Set the terminal's basic parameters according to the sgt‐
tyb structure pointed to by arg. The input queue is
flushed, and the call waits for the output queue to drain
before the parameters are changed.
TIOCSETN
This is like TIOCSETP, except there is no delay and the
input queue is not flushed.
TIOCEXCL
Set "exclusive-use" mode. The terminal may not be opened
again by any process until all existing references are
closed. arg is ignored and should be the NULL pointer.
TIOCNXCL
Turns off "exclusive-use" mode. arg is ignored and
should be the NULL pointer.
TIOCHPCL
When the last reference to the terminal is closed, the
terminal line is forced to hang up. This applies only to
modem drivers. arg is ignored and should be the NULL
pointer.
TIOCGETD
The current line discipline number is stored in the int
variable pointed to by arg. This value is currently ig‐
nored.
TIOCSETD
The line discipline is set to the value of the int
pointed to by arg.
TIOCFLUSH
The specified queue is flushed. If the value pointed to
by arg is zero, both the input and output queues are
flushed. If the value is FREAD (defined in <sys/fc‐
ntl.h>), the input queue is flushed. If the value is
FWRITE, the output queue is flushed.
TIOCSTI
The character pointed to by arg is placed in the input
queue as if it had been typed on the terminal.
TIOCSBRK
Begins a break sequence on the terminal. arg is ignored
and should be the NULL pointer.
TIOCCBRK
Ends a break sequence. arg is ignored and should be the
NULL pointer.
TIOCSDTR
The DTR line is turned on. arg is ignored and should be
the NULL pointer.
TIOCCDTR
The DTR line is turned off. arg is ignored and should be
the NULL pointer.
TIOCSTOP
Output is stopped as if t_stopc had been typed on the
terminal. arg is ignored and should be the NULL pointer.
TIOCSTART
If output is stopped, it is resumed as if t_startc had
been typed on the terminal. arg is ignored and should be
the NULL pointer.
TIOCOUTQ
The number of characters in the output queue is returned
in the int pointed to by arg.
FIONREAD
The number of characters immediately available for input
from the terminal is returned in the int pointed to by
arg. This is the preferred method of non-blocking I/O
(checking for the presence of characters without waiting
for them).
struct tchars
The second structure associated with a terminal defines special
characters. The structure is defined in <sys/ioctl.h> which is
automatically included by <sgtty.h>:
struct tchars {
char t_intrc; /* interrupt */
char t_quitc; /* quit */
char t_startc; /* start output */
char t_stopc; /* stop output */
char t_eofc; /* end-of-file */
char t_brkc; /* input delimiter (like nl) */
};
The default values for these characters are ^C, ^ ^Q, ^S, ^D and
-1 respectively. A value of -1 for any of the characters means
that the effect of that character is ignored. The stop and
start characters may be the same to produce a 'toggle' effect.
It is not recommended to set any of the other characters to the
same values; the order in which the special characters are
checked is not defined, and the results you get may not be what
was expected.
The ioctl calls that apply to tchars are:
TIOCGETC
Returns the special characters settings in the tchars
structure pointed to by arg.
TIOCSETC
The special characters are set according to tchars struc‐
ture pointed to by arg.
Local Mode
The third "structure" in the terminal interface is a local mode
word; arg points to an int variable, which is broken up into
bitfields. The various bitfields in this word are as follows:
LCRTBS 0x0001 Backspace on erase rather than echoing erase
LPRTERA 0x0002 Printing terminal erase mode
LCRTERA 0x0004 Erase character echoes as backspace-space-backspace
LTILDE 0x0008 Convert ~ to ` on output (for Hazeltine terminals)
LMDMBUF 0x0010 Stop/start output when carrier drops
LLITOUT 0x0020 Suppress output translations
LTOSTOP 0x0040 Send SIGTTOU for background output (not implemented)
LFLUSHO 0x0080 Output is being flushed
LNOHANG 0x0100 Don't send hangup when carrier drops
LPASSOUT 0x0200 Cooked mode with 8-bit output
LCRTKIL 0x0400 BS-space-BS erase entire line on line kill
LPASS8 0x0800 Pass all 8 bits through on input, in any mode
LCTLECH 0x1000 Echo input control chars as ^?
LPENDIN 0x2000 Retype pending input at next read or input character
LDECCTQ 0x4000 Only ^Q restarts output after ^S
LNOFLSH 0x8000 Inhibit flushing of pending I/O when intr char is typed
The ioctl's used to access the local mode follow. In all cases
arg is a pointer to an int.
TIOCLBIS
The bits of the local mode word specified by `1' bits in
the argument are set; this operation is a bit-wise OR.
TIOCLBIC
The bits of the local mode word specified by `1' bits in
the argument are cleared; this operation ANDs the local
mode with the bitwise negation of the argument.
TIOCLSET
Sets the local mode word to the value of the argument.
TIOCLGET
Returns the local mode word in the int pointed to by arg.
struct ltchars
The fourth terminal structure is another set of special charac‐
ters. The structure is named ltchars (for Local Special Charac‐
ters) and is again defined in <ioctl.h>.
struct ltchars {
char t_suspc; /* stop process signal */
char t_dsuspc; /* delayed stop process signal */
char t_rprntc; /* reprint line */
char t_flushc; /* flush output (toggles) */
char t_werasc; /* word erase */
char t_lnextc; /* literal next character */
};
Defaults for these characters are ^Z, ^Y, ^R, ^O, ^W, and ^V.
As with tchars, a value of -1 disables the effect of that char‐
acter. Only t_suspc is currently implemented for the console
driver.
The applicable ioctl functions are:
TIOCSLTC
sets the local characters according to the ltchars struc‐
ture pointed to by arg.
TIOCGLTC
retreives the local characters, storing them in the
ltchars structure pointed to by arg.
struct winsize
The fifth structure associated with terminals is the winsize
struct. Provision is made in the kernel for storage of the cur‐
rent window or terminal size along with the other terminal in‐
formation. This info is recorded in a winsize structure, and is
defined in <ioctl.h>:
struct winsize {
unsigned short ws_row; /* rows, in characters */
unsigned short ws_col; /* columns, in characters */
unsigned short ws_xpixel; /* horizontal size, pixels */
unsigned short ws_ypixel; /* vertical size, pixels */
};
A '0' in a field indicates that the field value is undefined.
'0' is the default when a terminal is first opened. These val‐
ues are not used by the terminal driver itself; rather, they are
for the benefit of applications. The ioctl calls for winsize
are:
TIOCGWINSZ
Returns the window size parameters in the provided win‐
size structure.
TIOCSWINSZ
Sets the window size parameters. If any of the values
differ from the old ones, a SIGWINCH signal is sent to
the terminal's process group.
FILES
.tty
.ttyco (console driver)
.tty* (user-installed drivers)
SEE ALSO
GNO Shell Reference Manual, stty(1), ioctl(2), signal(2)
GNO 15 April 1998 TTY(4)
Man(1) output converted with
man2html