TERMIO(4,F) AIX Technical Reference TERMIO(4,F)
-------------------------------------------------------------------------------
termio
PURPOSE
Provides the general terminal interface.
SYNOPSIS
#include <sys/hft.h>
#include <sys/termio.h>
#include <sys/tty.h>
DESCRIPTION
All of the asynchronous communications ports use the same general interface,
regardless of the hardware used. This section discusses the common features of
this interface, which is found in all AIX systems.
When a terminal file is opened, it normally causes the process to wait until a
connection is established. In practice, user programs seldom open these files.
They are opened by getty and become standard input, output, and error files for
a user. The first terminal file not already associated with a process group
that is opened by the process group leader becomes the control terminal for
that process group. The control terminal plays a special role in handling
quit, interrupt, and suspend signals as discussed later. During a fork system
call, the child process inherits the control terminal. A process can break the
association to the group using the setpgid system call. The terminal may also
be switched to control a different process group by using the TIOCSPGRP ioctl.
See "BSD Compatibility."
A terminal associated with one of these files ordinarily operates in
full-duplex mode. Characters can be typed at any time, even while output is
occurring. These characters can be lost, however, when the input buffers
become completely full or when the user accumulates the maximum number of input
characters allowed that were not read by a program. Currently, this limit is
256 characters. When the input limit is reached, all the saved characters are
erased from the input buffer without notice. When using the new line
discipline (see "BSD Compatibility") the driver simply refuses to accept any
further input and rings the terminal bell.
Normally, terminal input is processed in units of lines. A line is delimited
by a new-line (ASCII LF) character, an end-of-file (ASCII EOT) character, or an
end-of-line character. This means that a program attempting to read is
suspended until an entire line is typed. Also, no matter how many characters
are requested in the read call, at most one line is returned. It is not,
however, necessary to read a whole line at once. Any number of characters can
be requested in a read without losing information.
Processed November 7, 1990 TERMIO(4,F) 1
TERMIO(4,F) AIX Technical Reference TERMIO(4,F)
During input, erase and kill processing is performed normally. By default, the
Ctrl-H character erases the last character typed, but does not erase beyond the
beginning of the line. By default, the Ctrl-U character kills (deletes) the
entire input line, and optionally outputs a new-line character. Both these
characters operate on a keystroke basis independently of any backspacing or
tabbing that was done. Both the erase and kill characters can be entered
literally by preceding them with the \ (backslash) escape character. In this
case, the escape character is not read. The erase and kill characters can be
changed.
Certain characters have special functions on input. These functions and their
default character values are summarized as follows:
EOF Ctrl-D or ASCII EOT is 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 new-line character, and the
EOF is discarded. Thus, if there are not any characters waiting
(indicating the EOF occurred at the beginning of a line), zero
characters are passed back, which is the standard end-of-file
indication.
EOL ASCII NUL is an additional line delimiter, like NL. It is not normally
used.
ERASE Ctrl-H erases the preceding character. It does not erase beyond the
start of a line, as delimited by an NL, EOF, or EOL character.
INTR Rubout or ASCII DEL (Ctrl-Backspace on the PS/2 console keyboard)
generates a SIGINT (interrupt) signal, which is sent to all processes
with the associated control terminal. Normally, each such process is
forced to terminate, but arrangements can be made either to ignore the
signal or to receive a trap to an agreed-upon location. See "sigaction,
sigvec, signal."
KILL Ctrl-U deletes the entire line, as delimited by an NL, EOF, or EOL
character.
NL ASCII LF is the normal line delimiter. It cannot be changed or escaped.
QUIT Ctrl-V or ACSII SYN generates a quit signal. Its treatment is identical
to the interrupt signal except that, unless a receiving process made
other arrangements, it is not only terminated but a memory file (called
core) is created in the current working directory.
START Ctrl-Q or ASCII DC1 is used to resume output that was 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.
Processed November 7, 1990 TERMIO(4,F) 2
TERMIO(4,F) AIX Technical Reference TERMIO(4,F)
STOP Ctrl-S or ASCII DC3 is used to temporarily suspend output. It is useful
with terminals that have displays to prevent output from disappearing
before it can be read. While output is suspended, STOP characters are
ignored and not read.
SUSP Ctrl-Z or ASCII SUB generates the signal SIGTSTP. If the processes in
the terminal's process group do not specifically handle this signal,
they are suspended. The parent process(es) are notified with a SIGCHLD
signal and can find out about the stopped process using wait3. This is
used for job control in shells such as csh. Unlike the other special
characters listed here, SUSP is set using the TIOCSLTC ioctl. The SUSP
character can only be used with the new line discipline. See "BSD
Compatibility." SUSP characters cannot be escaped with a \.
The character values for INTR, QUIT, ERASE, KILL, EOF, and EOL can be changed
to suit individual preferences. The ERASE, KILL, and EOF characters can be
escaped by a preceding \ (backslash) character, in which case the special
function is not done.
When the carrier signal from the dataset drops, a hangup signal (SIGHUP) is
sent to all processes that have this terminal as the control terminal. Unless
other arrangements were made, this signal causes the process 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 end-of-file can
terminate appropriately.
When one or more characters are written, they are transmitted to the terminal
as soon as previously written characters finish typing. Input characters are
usually echoed by putting them in the output queue as they arrive. If a
process produces characters more rapidly than they can be typed, it is
suspended when its output queue exceeds some limit. When the output decreases
to a determined threshold, the program is resumed.
Several ioctl system calls apply to terminal files. The primary calls use the
following structures defined in the termio.h header file:
#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 */
};
struct tty_page {
char tp_flags;
unsigned char tp_slen;
};
Processed November 7, 1990 TERMIO(4,F) 3
TERMIO(4,F) AIX Technical Reference TERMIO(4,F)
The special control characters are defined by the c_cc array. The relative
positions and initial values for each function are as follows:
+--------+---------+----------------+
|c_cc[VIN|RINTR | Ctrl-Backspace |
| | | (DEL) |
+--------+---------+----------------+
|c_cc[VQU|TQUIT | Ctrl-V (SYN) |
+--------+---------+----------------+
|c_cc[VER|SERASE | Backspace (BS) |
+--------+---------+----------------+
|c_cc[VKI|LKILL | Ctrl-U (NAK) |
+--------+---------+----------------+
|c_cc[VEO|]EOF | Ctrl-D (EOT) |
+--------+---------+----------------+
|c_cc[VEO|]EOL | Ctrl-@ (NUL) |
+--------+---------+----------------+
The c_iflag field describes the basic terminal input control. The initial
input control value is all bits clear. The possible values are:
+-------+----------+----------------------------------------------------------+
|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 new-line character (NL) to carriage return character |
| | | (CR) on input. |
+-------+----------+----------------------------------------------------------+
|IGNCR | 0000200 | Ignore carriage return character. |
+-------+----------+----------------------------------------------------------+
|ICRNL | 0000400 | Map carriage return character to new-line character 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. |
+-------+----------+----------------------------------------------------------+
|ASCEDIT| 0020000 | Enables enhanced editing on ASCII terminals. |
+-------+----------+----------------------------------------------------------+
Processed November 7, 1990 TERMIO(4,F) 4
TERMIO(4,F) AIX Technical Reference TERMIO(4,F)
The values in this field are described as follows:
IGNBRK If set, the break condition (a character framing error with data all
zeros) is ignored. It is not put on the input queue and therefore not
read by any process. Otherwise, if BRKINT is set, the break condition
generates an interrupt signal and flushes both the input and output
queues. If IGNPAR is set, characters with other framing and parity
errors are ignored.
PARMRK If set, a character with a framing or parity error that is not ignored
is read as the 3-character sequence: 0377, 0, x, where x is the data of
the character received in error. If ISTRIP is not set, then a valid
character of 0377 is read as 0377, 0377 to avoid ambiguity. If PARMRK
is not set, a framing or parity error that is not ignored is read as
the character NULL (0).
INPCK If set, input parity checking is enabled. If not set, input parity
checking is disabled. This allows output parity generation without
input parity errors.
ISTRIP If set, valid input characters are first stripped to 7 bits; otherwise
all 8 bits are processed.
INLCR If set, a received new-line character is translated into a
carriage-return character. If IGNCR is set, a received carriage-return
character is ignored (not read). If ICRNL is set, a received
carriage-return character is translated into a new-line character.
IUCLC If set, a received uppercase alphabetic character is translated into
the corresponding lowercase character.
IXON If set, START/STOP output control is enabled. A received STOP
character suspends output and a received START character restarts
output. All START/STOP characters are ignored and not read. If IXANY
is set, any input character restarts output that was suspended.
IXOFF If set, the system transmits START/STOP characters when the input queue
is nearly empty or full.
ASCEDIT If set, ASCII keyboards can be used to enter enhanced edit line
discipline commands.
The c_oflag field specifies how the system treats output. The initial output
control value is all bits clear.
+-------+----------+----------------------------------------------------------+
|OPOST | 0000001 | Postprocess output. |
+-------+----------+----------------------------------------------------------+
|OLCUC | 0000002 | Map lowercase to uppercase on output. |
+-------+----------+----------------------------------------------------------+
Processed November 7, 1990 TERMIO(4,F) 5
TERMIO(4,F) AIX Technical Reference TERMIO(4,F)
+-------+----------+----------------------------------------------------------+
|ONLCR | 0000004 | Map new-line character to CR-NL on output. |
+-------+----------+----------------------------------------------------------+
|OCRNL | 0000010 | Map carriage-return to new-line on output. |
+-------+----------+----------------------------------------------------------+
|ONOCR | 0000020 | No carriage-return character output at column 0. |
+-------+----------+----------------------------------------------------------+
|ONLRET | 0000040 | Perform carriage return function using new-line |
| | | character. |
+-------+----------+----------------------------------------------------------+
|OFILL | 0000100 | Use fill characters for delay. |
+-------+----------+----------------------------------------------------------+
|OFDEL | 0000200 | Fill is DEL or NUL. |
+-------+----------+----------------------------------------------------------+
|NLDLY | 0000400 | Select new-line character 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 | |
+-------+----------+----------------------------------------------------------+
Processed November 7, 1990 TERMIO(4,F) 6
TERMIO(4,F) AIX Technical Reference TERMIO(4,F)
+-------+----------+----------------------------------------------------------+
|FFDLY | 0100000 | Select form-feed delays: |
+-------+----------+----------------------------------------------------------+
|FF0 | 0 | |
+-------+----------+----------------------------------------------------------+
|FF1 | 0100000 | |
+-------+----------+----------------------------------------------------------+
OPOST If set, output characters are post-processed as indicated by the
remaining flags; otherwise characters are transmitted without change.
OLCUC If set, a lowercase alphabetic character is transmitted as the
corresponding uppercase character. This function is often used in
conjunction with IUCLC.
ONLCR If set, the new-line character is transmitted as the carriage-return
new-line character pair.
OCRNL If set, the carriage-return character is transmitted as the new-line
character.
ONOCR If set, no carriage-return character is transmitted when at column 0
(first position).
ONLRET If set, the new-line character is assumed to do the carriage return
function. The column pointer is set to 0 and the delay specified for
carriage return is used. Otherwise the new-line character is assumed to
do just the line feed function; the column pointer remains unchanged.
The column pointer is also set to 0 if the carriage-return character is
actually transmitted.
OFILL If set, fill characters are transmitted for delay instead of a timed
delay. This is useful for high baud rate terminals that need only a
minimal delay.
OFDEL If set, the fill character is DEL, otherwise NUL.
NLDLY, CRDLY, TABDLY, BSDLY, VTDLY, FFDLY
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 ONLRET is
set, the carriage return delays are used instead of the new-line delays.
TAB3 If set, specifies that tabs are to be expanded into spaces.
The c_cflag field describes the hardware control of the terminal:
+-------+----------+----------------------------------------------------------+
|CBAUD | 0000017 | Baud rate |
+-------+----------+----------------------------------------------------------+
|B0 | 0 | Hang up |
+-------+----------+----------------------------------------------------------+
Processed November 7, 1990 TERMIO(4,F) 7
TERMIO(4,F) AIX Technical Reference TERMIO(4,F)
+-------+----------+----------------------------------------------------------+
|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 |
+-------+----------+----------------------------------------------------------+
|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 2 stop bits, else one. |
+-------+----------+----------------------------------------------------------+
|CREAD | 0000200 | Enable receiver. |
+-------+----------+----------------------------------------------------------+
|PARENB | 0000400 | Parity enable. |
+-------+----------+----------------------------------------------------------+
|PARODD | 0001000 | Odd parity, else even. |
+-------+----------+----------------------------------------------------------+
Processed November 7, 1990 TERMIO(4,F) 8
TERMIO(4,F) AIX Technical Reference TERMIO(4,F)
+-------+----------+----------------------------------------------------------+
|HUPCL | 0002000 | Hang up on last close. |
+-------+----------+----------------------------------------------------------+
|CLOCAL | 0004000 | Local line, else dial-up. |
+-------+----------+----------------------------------------------------------+
CBAUD These 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 is dropped. Normally, this disconnects the line. For any
particular hardware, impossible speed changes are ignored.
CSIZE These bits specify the character size in bits for both transmit and
receive. This size does not include the parity bit, if any. If CSTOPB
is set, 2 stop bits are used; otherwise one stop bit is used. For
example, at 110 baud, 2 stop bits are required.
CREAD If set, the receiver is enabled. Otherwise characters are not
received.
PARENB If 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.
The initial hardware control value after open is B300, CS8, CREAD,
HUPCL.
HUPCL If set, the line is disconnected when the last process that has the
line open, either closes it or the process terminates. That is, the
data-terminal-ready signal drops.
CLOCAL If set, the line is assumed to be local, direct connection with no
modem control. Otherwise modem control is assumed.
The c_lflag field of the parameter 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 new-line character after kill character. |
+-------+----------+----------------------------------------------------------+
|ECHONL | 0000100 | Echo new-line character. |
+-------+----------+----------------------------------------------------------+
Processed November 7, 1990 TERMIO(4,F) 9
TERMIO(4,F) AIX Technical Reference TERMIO(4,F)
+-------+----------+----------------------------------------------------------+
|NOFLSH | 0000200 | Disable flushing the queue after interrupt or quit. |
+-------+----------+----------------------------------------------------------+
|XSCAN | 0000400 | Use Scan Code Terminal Processing. |
+-------+----------+----------------------------------------------------------+
ISIG If set, each input character is checked against the special control
characters INTR and QUIT. If a character matches one of these control
characters, the function associated with that character is performed.
If ISIG is not set, checking is not 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 (for example, 0377 octal or 0xFF).
ICANON If set, canonical processing is enabled. Canonical processing 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, then
read requests are satisfied directly from the input queue. In this
case, a read request is not satisfied until either at least MIN
characters have been received, or the timeout value TIME has expired
since the last character was received. This allows bursts of input to
be read, while still allowing single-character input. The MIN and TIME
values are stored in the positions for the EOF and EOL characters,
respectively. The time value represents tenths of seconds.
XCASE If set along with ICANON, an uppercase letter (or the uppercase letter
translated to lowercase by IUCLC) is accepted on input by preceding it
with a \ (backslash) character, and is output preceded by a \
(backslash) character. In this mode, the output generates and the
input accepts the following escape sequences:
For: Use:
"`" "\'"
"|" "\!"
"^" "\^"
"{" "\("
"}" "\)"
"\" "\\"
For example, "A" is input as "\a", "\n" as "\\n", and "\N" as "\\\n".
ECHO If 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 clears the last
character from a cathode-ray-tube screen. If ECHOE is set and ECHO is
not set, the erase character is echoed as ASCII SP BS. If ECHOK is
set, the new-line character is echoed after the kill character to
emphasize that the line is deleted. Note that an escape character
preceding the erase or kill character removes any special function. If
ECHONL is set, the new-line character will be echoed even if ECHO is
not set. This is useful for terminals set to local echo (sometimes
Processed November 7, 1990 TERMIO(4,F) 10
TERMIO(4,F) AIX Technical Reference TERMIO(4,F)
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.
NOFLSH If set, the normal flushing of the input and output queues associated
with the quit and interrupt characters is not done.
XSCAN If set, Scan Code Terminal processing is performed instead of
conventional processing.
SELECT SUPPORT
The asynchronous terminal device driver supports the select system call in the
following manner:
o Read selects are satisfied when input data is available.
o Write selects are always satisfied immediately.
o Exception selects are never satisfied, or hang indefinitely if no timeout
value is specified.
See "select" for more information about this system call.
GETTING AND SETTING TERMINAL ATTRIBUTES
Programs can get and set terminal attributes using the following routines:
#include <termios.h>
int tegetattr(fildes, termios_p)
int fildes;
struct termios * termios_p)
int tesetattr(fildes, optional_actions, termios_p)
int fildes, optional_actions;
struct termios *termios_p;
int length;
These routines get and set all of the supported AIX terminal attributes. AIX
also provides the TCGETA, TCSETA, TIOCGETP and TIOCSETP ioctl options
(described below) as alternative ways of getting and setting terminal
attributes; but no one of these ioctl options supports all of the terminal
attributes, and thus tcgetattr and tcsetattr are the preferred terminal
interface routines.
IOCTL OPERATIONS
The primary ioctl system calls have the format:
Processed November 7, 1990 TERMIO(4,F) 11
TERMIO(4,F) AIX Technical Reference TERMIO(4,F)
ioctl (fildes, command, arg)
int fildes; /* file descriptor */
int command; /* command type */
struct termio *arg;
The commands using this format 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.
Note: TCGETA and TCSETA do not get and set a complete record of the state of
an HFT device. See "hft" for information about high-function terminal
devices.
TCSETAF Waits for the output to empty, then flushes the input queue and
sets the new parameters.
TCSETAW Waits for the output to empty before setting the new parameters.
This form should be used when changing parameters that affect
output.
The terminal paging ioctl calls have the format:
ioctl (fildes, command, arg)
int fildes; /* file descriptor */
int command; /* command type */
struct tty_page *arg;
The commands using this format are:
TCGLEN Gets the current status of the tty_page structure for the terminal
specified as fildes. If paging is enabled, a value 0x1 is set in
tp_flags. The tp_slen value indicates the screen length in lines.
TCSLEN Sets the status of the tty_page structure for this terminal. tp_slen
means the same here as it does in TCGLEN. The tp_flags are:
+----------+-----+------------------------------------------------------------+
|PAGE_SETL | 0x4 | Set page length using the value in tp_slen. |
+----------+-----+------------------------------------------------------------+
|PAGE_MSK | 0x3 | Command mask. |
+----------+-----+------------------------------------------------------------+
|PAGE_ON | 0x1 | Enable paging. |
+----------+-----+------------------------------------------------------------+
|PAGE_OFF | 0x2 | Disable paging. |
+----------+-----+------------------------------------------------------------+
Processed November 7, 1990 TERMIO(4,F) 12
TERMIO(4,F) AIX Technical Reference TERMIO(4,F)
Note that the PAGE_MSK field is interpreted as an encoding, not as separate
flags.
One terminal logging ioctl system call has the following format:
ioctl (fildes, command, (char *)arg)
struct tlog *arg;
The tlog structure is defined in the sys/termio.h header file and contains the
following members:
int tl_flags
int tl_msgqid
The command using this format is:
TCLOG Requests the terminal logging control functions to execute as indicated
by the tlog structure. The tl_flags are:
TCLOG_ON Determines whether terminal logging is turned on or off.
TCLOG_QID Establishes message queue ID.
If TCLOG_QID is set, tl_msgqid contains the message queue ID to be used for
logging from the terminal. The tl_msgqid value must be a message queue
identifier returned from a msgget call.
Additional ioctl system calls formats are:
ioctl (fildes, command, arg)
int fildes; /* file descriptor */
int command; /* command type */
int arg;
The commands using this format are:
TCFLSH If arg is 0, flush the input queue. A value of 1 indicates flush the
output queue. A value of 2 indicates flush both the input and output
queues.
TCSBRK Waits for the output to empty. If arg is 0, then sends a break (zero
bits for 0.25 seconds).
TCXONC Starts or stops control. Suspends output if arg is 0. Restarts
suspended output if arg is a value of 1.
Two query ioctl system calls have the following format:
ioctl (fildes, command, &arg)
int arg; /* returned value */
The commands using this format are:
Processed November 7, 1990 TERMIO(4,F) 13
TERMIO(4,F) AIX Technical Reference TERMIO(4,F)
TIOCNOTTY Causes the tty controlling this process to disassociate from the
process and causes the group ID to clear. Used by background
processes to free them from a controlling tty and process group.
This ioctl should only be used with a file descriptor obtained from
opening /dev/tty.
TIONREAD Gets the summation of the number of characters in the raw and
canonical queues that are immediately available for reading.
Two ioctl system calls specific to the enhanced edit line discipline have the
format:
ioctl (fildes, command, arg)
struct dostmplt *arg;
The dostmplt structure is defined in the sys/termio.h header file, and it
contains the following members:
char *dt_tbuf
int dt_tlen
The commands using this format are:
LDSETDT Sets the template buffer to contain the first dt_tlen characters of
dt_tbuf, if the enhanced edit line discipline has been entered (if
c_line equals 1, for example). At most, DTBISIZE characters are used.
If dt_tlen is -1, the template buffer is not initialized.
LDGETDT Gets the current contents of the template buffer. The characters in
the buffer are written starting at dt_tbuf, and dt_tlen is set to the
number of characters written. At most, DTBSIZE characters will be
returned. The characters will not be null-terminated.
BSD COMPATIBILITY
Several enhancements to the terminal interface described above are provided for
compatibility with the BSD UNIX System. These enhancements ensure that most
applications using the BSD TTY driver will run on the AIX PS/2 Operating System
without any changes.
Line Disciplines
The system provides different line disciplines for controlling communications
lines. There are two such disciplines available:
old The old (Version 7) terminal driver. This is sometimes used when using
the standard shell sh.
new The standard Berkeley terminal driver, with features for job control; this
must be used when using csh.
Line discipline switching is accomplished with the TIOCSETD ioctl:
Processed November 7, 1990 TERMIO(4,F) 14
TERMIO(4,F) AIX Technical Reference TERMIO(4,F)
int ldisc = LDISC;
ioctl(f, TIOCSETD, &ldisc);
where LDISC is OTTYDISC for the standard TTY driver and NTTYDISC for the "new"
driver. The standard (currently old) TTY driver is discipline 0 by convention.
Other disciplines may exist for special purposes, such as use of communications
lines for network connections. The current line discipline can be obtained
with the TIOCGETD ioctl. Pending input is discarded when the line discipline
is changed.
All of the low-speed asynchronous communications ports can use any of the
available line disciplines, no matter what hardware is involved. The remainder
of this section discusses the "old" and "new" disciplines.
The Control Terminal
When a terminal file is opened, it causes the process to wait until a
connection is established. In practice, user programs seldom open these files;
they are opened by getty or rlogind and become a user's standard input and
output file.
If a process which has no control terminal opens a terminal file, then that
terminal file becomes the control terminal for that process. The control
terminal is thereafter inherited by a child process during a fork, even if the
control terminal is closed.
The file /dev/tty is, in each process, a synonym for a control terminal
associated with that process. It is useful for programs that wish to be sure
of writing messages on the terminal no matter how output has been redirected.
It can also be used for programs that demand a file name for output, when typed
output is desired and it is tiresome to find out which terminal is currently in
use.
A process can remove the association it has with its controlling terminal by
opening the file /dev/tty and issuing an
ioctl(f, TIOCNOTTY, 0);
This is often desirable in server processes.
Process groups
Command processors such as csh can arbitrate the terminal between different
jobs by placing related jobs in a single process group and associating this
process group with the terminal. A terminal's associated process group may be
set using the TIOCSPGRP ioctl:
ioctl(fildes, TIOCSPGRP, &pgrp);
or examined using TIOCGPGRP, which returns the current process group in pgrp.
The new terminal driver aids in this arbitration by restricting access to the
Processed November 7, 1990 TERMIO(4,F) 15
TERMIO(4,F) AIX Technical Reference TERMIO(4,F)
terminal by processes which are not in the current process group; see "Job
Access Control."
Modes
The terminal drivers have three major modes, characterized by the amount of
processing on the input and output characters:
cooked The normal mode. In this mode, lines of input are collected and input
editing is done. The edited line is made available when it is completed
by a new-line, or when the t_brkc character (normally undefined) or
t_eofc character (normally an EOT, Ctrl-D) is entered. A carriage
return is usually made synonymous with new-line in this mode, and
replaced with a new-line whenever it is typed. All driver functions
(input editing, interrupt generation, output processing such as delay
generation and tab expansion, and so on) are available in this mode.
CBREAK This mode eliminates the character, word, and line editing input
facilities, making the input character available to the user program as
it is typed. Flow control, literal-next and interrupt processing are
still done in this mode. Output processing is done.
RAW This mode eliminates all input processing and makes all input characters
available as they are typed; no output processing is done either.
The style of input processing can also be very different when the terminal is
put in non-blocking I/O mode; see the description of the O_NONBLOCK flag in
"open, openx, creat" and "fcntl, flock, lockf." In this case, a read from the
control terminal will never block, but rather return an error indication
(EAGAIN) if there is no input available.
A process may also request that a SIGIO signal be sent to it whenever input is
present and also whenever output queues fall below the low-water mark. To
enable this mode, the O_ASYNC flag should be set using fcntl.
Input Editing
An AIX terminal ordinarily operates in full-duplex mode. Characters may be
typed at any time, even while output is occurring, and are only lost when the
system's character input buffers become completely choked, 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. In RAW mode, the terminal driver throws away all input and output
without notice when the limit is reached. In CBREAK or cooked mode, it refuses
to accept any further input and, if in the new-line discipline, rings the
terminal bell.
Input characters are normally accepted in either even or odd parity with the
parity bit being stripped off before the character is given to the program. By
clearing either the EVEN or ODD bit in the flags word, it is possible to have
input characters with that parity discarded (see the "Summary of Modes").
Processed November 7, 1990 TERMIO(4,F) 16
TERMIO(4,F) AIX Technical Reference TERMIO(4,F)
In all of the line disciplines, it is possible to simulate terminal input using
the TIOCSTI ioctl, which takes, as its third argument, the address of a
character. The system pretends that this character was typed on the argument
terminal, which must be the control terminal except for the superuser.
Input characters are normally echoed by putting them in an output queue as they
arrive. This may be disabled by clearing the ECHO bit in the flags word using
the stty call or the TIOCSETN or TIOCSETP ioctls (see the "Summary of Modes").
In cooked mode, terminal input is processed in units of lines. A program
attempting to read will normally be suspended until an entire line has been
received (but see the description of SIGTTIN in "Job Access Control" and of
FIONREAD in "Summary of Modes"). No matter how many characters are requested
in the read call, at most, one line will be returned. 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.
During input, line editing is normally done, with the erase character sg_erase
(by default, DELETE) logically erasing the last character typed and the sg_kill
character (default, Ctrl-U) logically erasing the entire current input line.
These characters never erase beyond the beginning of the current input line or
an EOF. These characters may be entered literally by preceding them with '\';
the '\' will normally be erased when the character is typed.
The drivers normally treat either a carriage return or a new-line character as
terminating an input line, replacing the return with a new-line and echoing a
return and a line feed. If the CRMOD bit is cleared in the local mode word,
then the processing for carriage return is disabled, and it is simply echoed as
a return, and does not terminate cooked mode input.
In the new driver there is a literal-next character (normally undefined) which
can be typed in both cooked and CBREAK mode preceding any character to prevent
its special meaning to the terminal handler. This is to be preferred to the
use of '\' escaping erase and kill characters, but '\' is retained with its old
function in the new-line discipline.
The new terminal driver also provides two other editing characters in normal
mode. The word-erase character, normally Ctrl-W, erases the preceding word,
but not any spaces before it. For the purposes of Ctrl-W, a word is defined as
a sequence of non-blank characters, with tabs counted as blanks. Finally, the
reprint character, normally Ctrl-R, retypes the pending input beginning on a
new line. Retyping occurs automatically in cooked mode if characters which
would normally be erased from the screen are fouled by program output.
Input Echoing and Redisplay
The new terminal driver has several modes for handling the echoing of terminal
input, controlled by bits in a local mode word.
HARDCOPY TERMINALS: When a hardcopy terminal is in use, the LPRTERA bit is
normally set in the local mode word. Characters which are logically erased are
then printed out backwards preceded by '\' and followed by '/' in this mode.
Processed November 7, 1990 TERMIO(4,F) 17
TERMIO(4,F) AIX Technical Reference TERMIO(4,F)
CRT TERMINALS: When a CRT terminal is in use, the LCRTBS bit is normally set
in the local mode word. The terminal driver then echoes the proper number of
erase characters when input is erased; in the normal case where the erase
character is a Ctrl-H, this causes the cursor of the terminal to back up to
where it was before the logically erased character was typed. If the input has
become fouled due to interspersed asynchronous output, the input is
automatically retyped.
ERASING CHARACTERS FROM A CRT: When a CRT terminal is in use, the LCRTERA bit
may be set to cause input to be erased from the screen with a
"backspace-space-backspace" sequence when character or word deleting sequences
are used. A LCRTKIL bit may be set, causing the input to be erased in this
manner on line kill sequences as well.
ECHOING OF CONTROL CHARACTERS: If the LCTLECH bit is set in the local state
word, then non-printing (control) characters are normally echoed as ^X (for
some X) rather than being echoed unmodified; delete is echoed as ^?.
The normal modes for use on CRT terminals are speed-dependent. At speeds less
than 1200 baud, the LCRTERA and LCRTKILL processing is painfully slow, so stty
normally just sets LCRTBS and LCTLECH; at speeds of 1200 baud or greater, all
of these bits are normally set. stty summarizes these option settings and the
use of the new terminal driver as "newcrt."
Output Processing
When one or more characters are written, they are actually transmitted to the
terminal as soon as previously-written characters have finished typing. (As
noted above, input characters are normally echoed by putting them in the output
queue as they arrive.) When 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. Even parity is normally generated on output. The EOT character is
not transmitted in cooked mode to prevent terminals that respond to it from
hanging up; programs using RAW or CBREAK mode should be careful.
The terminal drivers provide necessary processing for cooked and CBREAK mode
output including delay generation for certain special characters and parity
generation. Delays are available after backspaces Ctrl-H, form feeds Ctrl-L,
carriage returns Ctrl-M, tabs Ctrl-I, and new-lines Ctrl-J. The driver will
also optionally expand tabs into spaces, where the tab stops are assumed to be
set every eight columns, and optionally convert new-lines to carriage returns
followed by new-line. These functions are controlled by bits in the tty flags
word; see "Summary of Modes."
The terminal driver provides for mapping between upper and lowercase on
terminals lacking lowercase, and for other special processing on deficient
terminals.
Finally, in the new terminal driver, there is an output flush character,
normally Ctrl-O, which sets the LFLUSHO bit in the local mode word, causing
Processed November 7, 1990 TERMIO(4,F) 18
TERMIO(4,F) AIX Technical Reference TERMIO(4,F)
subsequent output to be flushed until it is cleared by a program or more input
is typed. This character has effect in both cooked and CBREAK modes and causes
pending input to be retyped if there is any pending input. An ioctl to flush
the characters in the input and output queues, TIOCFLUSH, is also available.
Uppercase Terminals and Hazeltines
If the LCASE bit is set in the tty flags, then all uppercase letters are mapped
into the corresponding lowercase letter. The uppercase letter may be generated
by preceding it by '\'. Uppercase letters are preceded by a '\' when output.
In addition, the following escape sequences can be generated on output and
accepted on input:
for ' | ~ { }
use \' \! \^ \( \)
To deal with Hazeltine terminals, which do not understand that ~ has been made
into an ASCII character, the LTILDE bit may be set in the local mode word; in
this case, the character ~ will be replaced with the character ` on output.
Flow Control
There are two characters (the stop character, normally Ctrl-S, and the start
character, normally Ctrl-Q) which cause output to be suspended and resumed
respectively. Extra stop characters typed when output is already stopped have
no effect, unless the start and stop characters are made the same, in which
case output resumes.
A bit in the flags word may be set to put the terminal into TANDEM mode. In
this mode, the system produces a stop character (default Ctrl-S) when the input
queue is in danger of overflowing, and a start character (default Ctrl-Q) when
the input has drained sufficiently. This mode is useful when the terminal is
actually another machine that obeys those conventions.
Line Control and Breaks
There are several ioctl calls available to control the state of the terminal
line. The TIOCSBRK ioctl will set the break bit in the hardware interface
causing a break condition to exist; this can be cleared (usually after a delay
with sleep) by TIOCCBRK. Break conditions in the input are reflected as a null
character in RAW mode or as the interrupt character in cooked or CBREAK mode.
The TIOCCDTR ioctl will clear the data terminal ready condition; it can be set
again by TIOCSDTR.
When the carrier signal from the dataset drops (usually because the user has
hung up his terminal) a SIGHUP hangup signal is sent to the processes in the
distinguished process group of the terminal; this usually causes them to
terminate. The SIGHUP can be suppressed by setting the LNOHANG bit in the
local state word of the driver. Access to the terminal by other processes is
then normally revoked, so any further reads will fail, and programs that read a
terminal and test for end-of-file on their input will terminate appropriately.
Processed November 7, 1990 TERMIO(4,F) 19
TERMIO(4,F) AIX Technical Reference TERMIO(4,F)
It is possible to ask that the phone line be hung up on the last close with the
TIOCHPCL ioctl; this is normally done on the outgoing lines and dialups.
Interrupt Characters
There are several characters that generate interrupts in cooked and CBREAK
mode; all are sent to the processes in the control group of the terminal, as if
a TIOCGPGRP ioctl were done to get the process group and then a killpg system
call were done, except that these characters also flush pending input and
output when typed at a terminal (for example, TIOCFLUSH). The characters shown
here are the defaults; the field names in the structures (given below) are also
shown. The characters may be changed.
Ctrl-Backspace
t_intrc (ASCII DEL) generates a SIGINT signal. This is the normal
way to stop a process which is no longer interesting, or to regain
control in an interactive program.
Ctrl-V t_quitc (ASCII SYN) generates a SIGQUIT signal. This is used to
cause a program to terminate and produce a core image, if possible,
in the file core in the current directory.
Ctrl-Z t_suspc (ASCII SUB) generates a SIGTSTP signal, which is used to
suspend the current process group.
Ctrl-Y t_dsuspc (ASCII EM) generates a SIGSTSTP signal as Ctrl-Z does, but
the signal is sent when a program attempts to read the Ctrl-Y, rather
than when it is typed.
Job Access Control
When using the new terminal driver, if a process which is not in the
distinguished process group of its control terminal attempts to read from that
terminal, its process group is sent a SIGTTIN signal. This signal normally
causes the members of that process group to stop. If, however, the process is
ignoring SIGTTIN or has SIGTTIN blocked, the read will return -1 and set errno
to EIO.
When using the new terminal driver with the LTOSTOP bit set in the local modes,
a process is prohibited from writing on its control terminal if it is not in
the distinguished process group for that terminal. Processes which are
blocking or ignoring SIGTTOU signals are excepted and allowed to produce
output.
TERMINAL/WINDOW SIZES: In order to accommodate terminals and workstations with
variable-sized windows, the terminal driver provides a mechanism for obtaining
and setting the current terminal size. The driver does not use this
information internally, but only stores it and provides a uniform access
mechanism. When the size is changed, a SIGWINCH signal is sent to the
terminal's process group so that knowledgeable programs may detect size
changes. This facility was added in 4.3BSD and is not available in earlier
versions of the system.
Processed November 7, 1990 TERMIO(4,F) 20
TERMIO(4,F) AIX Technical Reference TERMIO(4,F)
Summary of Modes
Unfortunately, due to the evolution of the terminal driver, there are four
different structures which contain various portions of the driver data. The
first of these (sgttyb) contains that part of the information largely common
between version 6 and version 7 UNIX systems. The second contains additional
control characters added in version 7. The third is a word of local state
added in 4BSD, and the fourth is another structure of special characters added
for the new driver. In the future, a single structure may be made available to
programs which need to access all this information; most programs need not
concern themselves with all this state.
BASIC MODES: SGTTY:
The basic ioctls use the structure defined in <sgtty.h>:
struct sgttyb {
char sg_ispeed;
char sg_ospeed;
char sg_erase;
char sg_kill;
short sg_flags;
};
The sg_ispeed and sg_ospeed fields describe the input and output speeds of the
device according to the following table. Impossible speed changes are ignored.
Symbolic values in the table are as 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
EXTA 14 External A
EXTB 15 External B
Code conversion and line control required for IBM 2741's (134.5 baud) must be
implemented by the user's program. The half-duplex line discipline required
for the 202 dataset (1200 baud) is not supplied; full-duplex 212 datasets work
fine.
Processed November 7, 1990 TERMIO(4,F) 21
TERMIO(4,F) AIX Technical Reference TERMIO(4,F)
The sg_erase and sg_kill fields of the argument structure specify the erase and
kill characters respectively. (Defaults are Ctrl-H and Ctrl-U.)
The sg_flags field of the argument structure contains several bits that
determine the system's treatment of the terminal:
ALLDELAY 0177400 Delay algorithm selection
BSDELAY 0100000 Select backspace delays (not implemented):
BS0 0
BS1 0100000
VTDELAY 0040000 Select form-feed and vertical-tab delays:
FF0 0
FF1 0040000
CRDELAY 0030000 Select carriage-return delays:
CR0 0
CR1 0010000
CR2 0020000
CR3 0030000
TBDELAY 0006000 Select tab delays:
TAB0 0
TAB1 0002000
TAB2 0004000
XTABS 0006000
NLDELAY 0001400 Select new-line delays:
NL0 0
NL1 0000400
NL2 0001000
NL3 0001400
EVENP 0000200 Even parity allowed on input
ODDP 0000100 Odd parity allowed on input
RAW 0000040 RAW mode: wake up on all character, 8-bit interface
CRMOD 0000020 Map CR into LF; output LF as CR-LF
ECHO 0000010 Echo (full duplex)
LCASE 0000004 Map uppercase to lower on input and lower to upper on
output
CBREAK 0000002 Return each character as soon as typed
TANDEM 0000001 Automatic flow control
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.
Backspace delays are currently ignored but might be used for Terminet 300's.
If a form-feed/vertical tab delay is specified, it lasts for about two seconds.
Carriage-return delay type 1 lasts about .08 seconds and is suitable for the
Terminet 300. Delay type 2 lasts about .16 seconds and is suitable for the
VT05 and the TI 700. Delay type 3 is suitable for the concept-100 and pads
lines to be at least nine characters at 9600 baud.
Processed November 7, 1990 TERMIO(4,F) 22
TERMIO(4,F) AIX Technical Reference TERMIO(4,F)
New-line delay type 1 is dependent on the current column and is tuned for
Teletype model 37's. Type 2 is useful for the VT05 and is about .10 seconds.
Type 3 is unimplemented and is 0.
Tab delay type 1 is dependent on the amount of movement and is tuned to the
Teletype model 37. Type 3, called XTABS, is not a delay at all but causes tabs
to be replaced by the appropriate number of spaces on output.
The flags for even and odd parity control parity checking on input and
generation on output in cooked and CBREAK mode (unless LPASS8 is enabled, see
below). Even parity is generated on output unless ODDP is set and EVENP is
clear, in which case odd parity is generated. Input characters with the wrong
parity, as determined by EVENP and ODDP, are ignored in cooked and CBREAK mode.
RAW disables all processing save output flushing with LFLUSHO; full 8 bits of
input are given as soon as it is available; all 8 bits are passed on output. A
break condition in the input is reported as a null character. If the input
queue overflows in raw mode, all data in the input and output queues are
discarded; this applies to both new and old drivers.
CRMOD causes input carriage returns to be turned into new-lines, and output and
echoed new-lines to be output as a carriage return followed by a line feed.
CBREAK is a sort of half-cooked (rare?) mode. Programs can read each character
as soon as typed, instead of waiting for a full line; all processing is done
except the input editing: character and word erase and line kill, input
reprint, and the special treatment of \ and EOT are disabled.
TANDEM mode causes the system to produce a stop character (default Ctrl-S)
whenever the input queue is in danger of overflowing, and a start character
(default Ctrl-Q) when the input queue has drained sufficiently. It is useful
for flow control when the "terminal" is really another computer which
understands the conventions.
Note: The same "stop" and "start" characters are used for both directions of
flow control; the t_stopc character is accepted on input as the
character that stops output and is produced on output as the character
to stop input, and the t_startc character is accepted on input as the
character that restarts output and is produced on output as the
character to restart input.
BASIC IOCTLS:
A large number of ioctl calls apply to terminals. Some have the general form:
#include <sgtty.h>
ioctl(fildes, code, arg)
struct sgttyb *arg;
The applicable codes are:
Processed November 7, 1990 TERMIO(4,F) 23
TERMIO(4,F) AIX Technical Reference TERMIO(4,F)
TIOCGETP Fetch the basic parameters associated with the terminal, and store in
the pointed-to sgttyb structure.
TIOCSETP Set the parameters according to the pointed-to sgttyb structure. The
interface delays until output is quiescent, then throws away any
unread characters, before changing the modes.
TIOCSETN Set the parameters like TIOCSETP but do not delay or flush input.
Input is not preserved, however, when changing to or from RAW.
With the following codes arg is ignored.
TIOCEXCL Set "exclusive-use" mode: no further opens are permitted until the
file has been closed.
TIOCNXCL Turn off "exclusive-use" mode.
TIOCHPCL When the file is closed for the last time, hang up the terminal.
This is useful when the line is associated with an ACU used to place
outgoing calls.
With the following codes, arg is a pointer to an int.
TIOCGETD arg is a pointer to an int into which is placed the current line
discipline number.
TIOCSETD arg is a pointer to an int whose value becomes the current line
discipline number.
TIOCFLUSH If the int pointed to by arg has a 0 value, all characters waiting in
input or output queues are flushed. Otherwise, the value of the int
is for the FREAD and FWRITE bits defined in <sys/file.h>; if the
FREAD bit is set, all characters waiting in input queues are flushed,
and if the FWRITE bit is set, all characters waiting in output queues
are flushed.
The remaining calls are not available in standard version 7 UNIX. In cases
where arguments are required, they are described; arg should otherwise be given
as 0.
TIOCSTI The argument points to a character which the system pretends had been
typed on the terminal.
TIOCSBRK The break bit is set in the terminal.
TIOCCBRK The break bit is cleared.
TIOCSDTR Data terminal ready is set.
TIOCCDTR Data terminal ready is cleared.
Processed November 7, 1990 TERMIO(4,F) 24
TERMIO(4,F) AIX Technical Reference TERMIO(4,F)
TIOCSTOP Output is stopped as if the stop character had been typed.
TIOCSTART Output is restarted as if the start character had been typed.
TIOCGPGRP arg is a pointer to an int into which is placed the process group ID
of the process group for which this terminal is the control terminal.
TIOCSPGRP arg is a pointer to an int which is the value to which the process
group ID for this terminal will be set.
TIOCOUTQ Returns in the int pointed to by arg the number of characters queued
for output to the terminal.
FIONREAD Returns in the int pointed to by arg the number of characters
immediately readable from the argument descriptor. This works for
files, pipes, and terminals.
FIONBIO Sets the terminal to be in nonblocking mode. This is equivalent to
setting the O_NONBLOCK file flag using the fcntl or open system call.
TCHARS:
The second structure associated with each terminal specifies characters that
are special in both the old and new terminal interfaces.
The following structure is defined in <sys/ioctl.h>, which is automatically
included in <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 Ctrl-Backspace (DEL), Ctrl-V,
Ctrl-Q, Ctrl-S, Ctrl-D, and 0xff. A character value of 0xff eliminates the
effect of that character. The t_brkc character, by default 0xff, acts like a
new-line in that it terminates a 'line,' is echoed, and is passed to the
program. The 'stop' and 'start' characters may be the same, to produce a
toggle effect. It is probably counterproductive to make other special
characters (including erase and kill) identical.
The applicable ioctl calls are:
TIOCGETC Get the special characters and put them in the specified structure.
TIOCSETC Set the special characters to those given in the structure.
LOCAL MODE:
Processed November 7, 1990 TERMIO(4,F) 25
TERMIO(4,F) AIX Technical Reference TERMIO(4,F)
The third structure associated with each terminal is a local mode word. Except
for the LNOHANG bit, this word is interpreted only when the new driver is in
use. The bits of the local mode word are:
LCRTBS 000001 Backspace on erase rather than echoing erase
LPRTERA 000002 Printing terminal erase mode
LCRTERA 000004 Erase character echoes as backspace-space-backspace
LTILDE 000010 Convert ~ to ` on output (for Hazeltine terminals)
LMDMBUF 000020 Stop/start output when carrier drops.
LLITOUT 000040 Suppress output translations
LTOSTOP 000100 Send SIGTTOU for background output
LFLUSHO 000200 Output is being flushed
LNOHANG 000400 Don't send hangup when carrier drops
LETXACK 001000 Diablo style buffer hacking (unimplemented)
LCRTKIL 002000 BS-space-BS erase entire line on line kill
LPASS8 004000 Pass all 8 bits through on input, in any mode
LCTLECH 010000 Echo input control chars as ^X, delete as ^?
LPENDIN 020000 Retype pending input at next read or input character
LDECCTQ 040000 Only Ctrl-Q restarts output after Ctrl-S
LNOFLSH 100000 Inhibit flushing of pending I/O when an interrupt
character is typed.
The applicable ioctl functions are:
TIOCLBIS arg is a pointer to an int whose value is a mask containing the bits
to be set in the local mode word.
TIOCLBIC arg is a pointer to an int whose value is a mask containing the bits
to be cleared in the local mode word.
TIOCLSET arg is a pointer to an int whose value is stored in the local mode
word.
TIOCLGET arg is a pointer to an int into which the current local mode word is
placed.
LOCAL SPECIAL CHARS:
The final control structure associated with each terminal is the ltchars
structure which defines control characters for the new terminal driver. Its
structure is:
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 */
};
Processed November 7, 1990 TERMIO(4,F) 26
TERMIO(4,F) AIX Technical Reference TERMIO(4,F)
The default values for these characters are Ctrl-Z, Ctrl-Y, Ctrl-R, Ctrl-O,
Ctrl-W, and undefined. A value of 0xff disables the character.
The applicable ioctl functions are:
TIOCSLTC args is a pointer to an ltchars structure which defines the new local
special characters.
TIOCGLTC args is a pointer to an ltchars structure into which is placed the
current set of local special characters.
WINDOW/TERMINAL SIZES: Each terminal has provision for storage of the current
terminal or window size in a winsize structure, with this format:
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 value of 0 in any field is interpreted as "undefined"; the entire structure
is zeroed on final close.
The applicable ioctl functions are:
TIOCGWINSZ
arg is a pointer to a struct winsize into which is placed the current
terminal or window size information.
TIOCSWINSZ
arg is a pointer to a struct winsize which is used to set the current
terminal or window size information. If the new information is
different than the old information, a SIGWINCH signal is sent to the
terminal's process group.
INTERACTION OF AIX AND BSD INTERFACES
The information which describes the state and controls the behavior of the AIX
PS/2 TTY driver is based upon the standard termio structure used in AIX,
supplemented with structures from the 4.3BSD version of UNIX. A collection of
ioctl functions are used to fetch and store these structures. Although the
internal implementation of the TTY driver uses one structure to hold the
current state of control information for each TTY port, this full state cannot
be captured or modified all at once.
However, the termio interface (ioctl commands TCGETA, TCSETA, and so forth)
gives access to most of the TTY driver state. For most applications, this
interface is more than sufficient and using it always produces the expected
results. If a TCGETA is used to save a copy of the control state before
changes are made, a subsequent TCSETA of that saved copy restores the interface
to its original condition for all elements of the state which are accessible
Processed November 7, 1990 TERMIO(4,F) 27
TERMIO(4,F) AIX Technical Reference TERMIO(4,F)
through the termio structure. By contrast, the BSD TIOCGETP and TIOCSETP
ioctls work with sgtty structures that are only mapped onto the termio
structure. Since there is less information in a sgtty structure than in a
termio structure, the interface cannot be completely saved and restored with
these ioctls. Even if you save a copy of the structure returned by TIOCGETP
before you make changes to the TTY control state, you may not be able to
restore the original state with a TIOCSETP using the saved information. This
limitation is a consequence of the fact that the AIX termio interface contains
more function than the BSD sgtty interface.
For source code compatibility the implementation of BSD ioctl support is
usually adequate; problems due to the differences in the termio and sgtty
interfaces are rare. In fact, problems mostly arise when a user has put the
TTY driver in an unusual state, such as when OPOST is off but ICANON is on.
This is because certain sgtty operations, such as setting RAW mode, affect many
termio flags (for example, ICANON, ISIG, MIN, TIME, OPOST). Since little
history is kept in the TTY driver (only enough to ensure that the serial
communication parameters of asynchronous communication ports are maintained)
turning on and off certain sgtty modes, such as RAW mode, effectively resets
the affected termio modes to the default values. This is not a problem if the
termio modes were set to the default values to begin with, but if they were in
an unusual state unexpected results may occur.
The basic input editing control characters accessed with the BSD TIOCGETC and
TIOCSETC ioctls are mapped onto the corresponding termio (c_cc[]) characters.
In addition to the basic ioctls and structures, there are ioctls and structures
used to control certain advanced features of the TTY driver. These include
advanced input editing (from BSD), job control signal-generating characters
(also from BSD), and TTY paging (from earlier versions of AIX). Even though
these features cannot be controlled with the termio (TCGETA and TCSETA) ioctls,
there are still some interactions between the BSD advanced editing features and
certain termio modes, as described below.
The BSD local special characters (struct ltchars) can only be accessed (and can
be completely saved and restored with) the TIOCGLTC and TIOCSLTC ioctls.
The BSD local mode word accessed with the TIOCLGET and TIOCLSET ioctls is a
collection of bits. Setting or resetting some of these bits changes related
termio bits (for example, LCRTERA and ECHOE are related). Some of these bits
control modes which are effected by the state of certain termio modes (for
example, the actions implied by LCRTKIL happen only when ICANON is true), but
the state of these bits cannot be changed by changing termio modes (just as
turning ICANON on and off does not effect the setting of ECHOK). If you intend
to change any bits in the local mode word other than LTILDE, LTOSTOP, LCRTKIL
and LCTLECH, you should use TCGETA and TCSETA to save the termio modes
beforehand and restore them afterwards, as well as saving and restoring the
original value of the local mode word, to ensure consistency. The effect of
setting LPASS8 is to set (in the termio interface) CSIZE to CS8, PARENB to
false, and ISTRIP to false. When LPASS8 is disabled, CSIZE is set to CS7 and
ISTRIP is turned on, PARENB is turned on and PARODD is turned off. The High
Function Terminal is normally in LPASS8 mode.
Processed November 7, 1990 TERMIO(4,F) 28
TERMIO(4,F) AIX Technical Reference TERMIO(4,F)
In order to ensure the consistency of the user's TTY interface, the various
portions of the TTY driver state should be saved and restored in the order
shown below. You are not required to save and restore higher numbered
structures which you do not intend to change, but if you wish to change a
higher numbered structure you must save and restore the lower numbered
structure for complete integrity. Structures and ioctls numbered identically
can be saved and restored independently, in any order. However, if you don't
change TTY paging you need not save and restore it.
1 termio structure, TCGETA
1 TTY paging, TCGLEN
1 local special characters, TIOCGLTC
2 sgtty structure, TIOCGETP (see note below)
2 BSD editing chars, TIOCGETC
3 local mode word, TIOCLGET/TIOCLSET
2 BSD editing chars, TIOCSETC
2 sgtty structure, TIOCSETP
1 local special characters, TIOCSLTC
1 TTY paging, TCSLEN
1 termio structure, TCSETA
Note: Changes to the local mode word may affect the sgtty structure, but if
you do not use the sgtty structure, it is sufficient to save and restore
the local mode word and the termio structure. In general, the sgtty
structure is a subset of the termio structure and they are used in
similar ways by programs that only use one or the other. A program
should not use both. However, if a program is being ported to AIX from
a system which uses sgtty, and the program cannot be modified to use
termio instead of sgtty, a TCGETA to save the termio values before any
sgtty operations are done and a TCSETA to restore those values before
the program exits should be added to the program. If the program is
intended to leave the tty in a different state when it exits then it
should be recoded to use the termio ioctls.
There are several redundant ioctls and/or bits in various control structures.
In general, these can be used interchangeably. For example, TIOCFLUSH is
equivalent to TCFLSH; HUPCL and LNOHANG are inverses. But the rules for
priority of state manipulation given above must be followed for information in
control structures.
FILES
/dev/tty*
/usr/include/sys/ttmap.h
RELATED INFORMATION
In this book: "ioctlx, ioctl, gtty, stty" and "hft."
The csh, getty, and stty commands in AIX Operating System Commands Reference.
Processed November 7, 1990 TERMIO(4,F) 29