TERMIO(7)TERMIO(7)NAME
termio, termios - general terminal interfaces
SYNOPSIS
#include <termios.h>
ioctl (int fildes, int request, struct termios *arg);
ioctl (int fildes, int request, int arg);
#include <termio.h>
ioctl (int fildes, int request, struct termio *arg);
DESCRIPTION
All of the asynchronous communications ports use the same general
interface, no matter what hardware is involved. The user interface to
this functionality is via the ioctl calls described below, or the POSIX
termios interface described in termios(3t). The remainder of this
section discusses the common features of the terminal subsystem which are
relevant to both of these interfaces.
Recent changes
The termio and termios structures have been changed to support bit rates
of greater than 38400 bps. Each of these structures has two new members
c_ospeed and c_ispeed which store the output and input bit rates,
respectively. They replace the CBAUD and CIBAUD fields of the c_cflag
member. CBAUD and CIBAUD should no longer be modified or examined by
applications. (Because no current SGI hardware supports setting input
and output to different rates, c_ispeed is currently unsupported.
Applications should either not modify it, or should set it to the same
value as c_ospeed.)
Unlike CBAUD and CIBAUD, c_ospeed and c_ispeed encode bit rates as plain
integers. To set a bit rate of 38400 bits per second, an application
would set c_ospeed to the integer value 38400. For convenience, macros
such as B38400 have been provided for several common bit rates.
Note that the capabilities of various serial port hardware differ; many
still do not support rates greater than 38400 bps (see serial(7) for more
information on different serial port types.) Applications therefore need
to check the return values of library calls that attempt to set bit rates
(such as ioctl described here) , because the calls may now fail in more
situations than before.
Controlling Terminal
When a terminal file is opened, it normally causes the process to wait
until a connection is established. In practice, users' programs seldom
open terminal files; they are opened by the system and become a user's
standard input, output and error files. The very first terminal file
Page 1
TERMIO(7)TERMIO(7)
opened by the session leader which is not already associated with a
session becomes the controlling terminal for the session.
If a process does not wish to acquire the terminal as a controlling
terminal (as is the case with many daemons that open /dev/console), the
process should add the O_NOCTTY flag into the second argument bitmask to
open(2).
The controlling terminal is inherited by the child process during a
fork(2). A process can break this association by changing its session
using setsid(2). (Currently, this also happens if a process issues a
System V setpgrp() or BSDsetpgrp(mypid, 0). This provides backward
compatibility with SVR3 and BSD4.3).
When a session leader that has a controlling terminal exits, the SIGHUP
signal will be sent to each process in the foreground process group of
the controlling terminal and the controlling terminal will be
disassociated from the current session. This allows the terminal to be
acquired by a new session leader. Subsequent access to the terminal by
other processes in the earlier session will fail, returning the error
code EIO.
Session Management (Job Control)
A controlling terminal will designate one of the process groups in the
session associated with it as the foreground process group. All other
process groups in the session are designated as background process
groups. The foreground process group plays a special role in handling
signal-generating input characters, as discussed below. By default, when
a controlling terminal is allocated, the controlling process's process
group is assigned as the foreground process group.
Background process groups in the controlling process's session are
subject to a job control line discipline when they attempt to access
their controlling terminal. Typically, they will be sent signals that
will cause them to stop, unless they have made other arrangements. An
exception is made for members of orphaned process groups. When a member
of an orphaned process group attempts to access its controlling terminal,
an error is returned since there is no process to continue it should it
stop.
If a member of a background process group attempts to read its
controlling terminal, its process group will be sent a SIGTTIN signal,
which will normally cause the members of that process group to stop. If,
however, the process is ignoring or holding SIGTTIN, or is a member of an
orphaned process group, the read will fail with errno set to EIO, and no
signal will be sent.
If a member of a background process group attempts to write to its
controlling terminal and the TOSTOP bit is set in the c_lflag field (see
below), its process group will be sent a SIGTTOU signal, which will
normally cause the members of that process group to stop. If, however,
the process is ignoring or holding SIGTTOU, the write will succeed. If
Page 2
TERMIO(7)TERMIO(7)
the process is not ignoring or holding SIGTTOU and is a member of an
orphaned process group, the write will fail with errno set to EIO, and no
signal will be sent.
If a member of a background process group attempts to invoke an ioctl()
on its controlling terminal, and that ioctl() will modify terminal
parameters (e.g. TCSETA, TCSETAW, TCSETAF, or TIOCSPGRP), and the TOSTOP
bit is set in the c_lflag field, its process group will be sent a SIGTTOU
signal, which will normally cause the members of that process group to
stop. If, however, the process is ignoring or holding SIGTTOU, the
ioctl() will succeed. If the process is not ignoring or holding SIGTTOU
and is a member of an orphaned process group, the ioctl() will fail with
errno set to EIO, and no signal will be sent.
Input Processing and Reading Characters
A terminal associated with one of these files 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 full (which is rare) or when the user has accumulated
the maximum allowed number of input characters that have not yet been
read by some program. Currently, this limit is {MAX_CANON} characters
(see pathconf(2)). When the input limit is reached, the buffer is
flushed and all the saved characters are thrown away without notice.
Canonical Mode Input Processing
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 will be suspended until an entire line has been typed.
Also, 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, erase and kill processing is normally done. The ERASE
character (Control-H) erases the last character typed. The WERASE
character (Control-W) erases the last ``word'' typed in the current input
line (but not any preceding spaces or tabs). A ``word'' is defined as a
sequence of non-blank characters, with tabs counted as blanks. Neither
ERASE or WERASE will erase beyond the beginning of the line. The KILL
character (Control-U) kills (deletes) the entire input line, and
optionally outputs a new-line character. All these characters operate on
a key-stroke basis, independently of any backspacing or tabbing that may
have been done. The REPRINT character (Control-R) prints a newline
followed by all unread characters. The characters are reprinted as if
they were being echoed; consequently if the ECHO flag is not set (see
below), they are not printed. The ERASE, WERASE, KILL and REPRINT
characters may be changed.
Non-canonical Mode Input Processing
In non-canonical mode input processing, input characters are not
assembled into lines, and erase and kill processing does not occur. The
Page 3
TERMIO(7)TERMIO(7)
MIN and TIME values are used to determine how to process the characters
received.
MIN represents the minimum number of characters that should be received
when the read is satisfied (i.e., when the characters are returned to the
user). TIME is a timer of 0.10-second granularity that is used to
timeout bursty and short-term data transmissions. The four possible
values for MIN and TIME and their interactions are described below.
Case A: MIN > 0, TIME > 0
In this case, TIME serves as an intercharacter timer and is activated
after the first character is received. Since it is an intercharacter
timer, it is reset after a character is received. The interaction
between MIN and TIME is as follows: as soon as one character is
received, the intercharacter timer is started. If MIN characters are
received before the intercharacter timer expires (note that the timer
is reset upon receipt of each character), the read is satisfied. If the
timer expires before MIN characters are received, the characters
received to that point are returned to the user. Note that if TIME
expires, at least one character will be returned because the timer
would not have been enabled unless a character was received. In this
case (MIN > 0, TIME > 0), the read sleeps until the MIN and TIME
mechanisms are activated by the receipt of the first character. If the
number of characters read is less than the number of characters
available, the timer is not reactivated and the subsequent read is
satisfied immediately.
Case B: MIN > 0, TIME = 0
In this case, since the value of TIME is zero, the timer plays no role
and only MIN is significant. A pending read is not satisfied until MIN
characters are received (the pending read sleeps until MIN characters
are received). A program that uses this case to read record based
terminal I/O may block indefinitely in the read operation.
Case C: MIN = 0, TIME > 0
In this case, since MIN = 0, TIME no longer represents an
intercharacter timer: it now serves as a read timer that is activated
as soon as a read is done. A read is satisfied as soon as a single
character is received or the read timer expires. Note that, in this
case, if the timer expires, no character is returned. If the timer
does not expire, the only way the read can be satisfied is if a
character is received. In this case, the read will not block
indefinitely waiting for a character; if no character is received
within TIME*.10 seconds after the read is initiated, the read returns
with zero characters.
Case D: MIN = 0, TIME = 0
In this case, return is immediate. The minimum of either the number of
characters requested or the number of characters currently available is
returned without waiting for more characters to be input.
Page 4
TERMIO(7)TERMIO(7)
Writing Characters
When one or more characters are written, they are transmitted to the
terminal as soon as previously-written characters have finished typing.
Input characters are echoed by putting them in the output queue as they
arrive. If a process produces characters more rapidly than they can be
typed, it will be suspended when its output queue exceeds some limit.
When the queue has drained down to some threshold, the program is
resumed.
Special Characters
Certain characters have special functions on input. These functions and
their default character values are summarized as follows:
INTR (Typically, rubout or ASCII DEL) generates an interrupt
signal SIGINT which is sent to all foreground processes with
the associated controlling terminal. Normally, each such
process is forced to terminate, but arrangements may be made
either to ignore the signal or to receive a trap to an
agreed-upon location; see signal(2).
QUIT (Typically, control-\ or ASCII FS) generates a quit signal
SIGQUIT. Its treatment is identical to the interrupt signal
except that, unless a receiving process has made other
arrangements, it will not only be terminated, but a core
image file (called core) will be created in the current
working directory.
ERASE (Typically, control-H or backspace) erases the preceding
character. It will not erase beyond the start of a line, as
delimited by a NL, EOF, EOL, or EOL2 character.
KILL (Typically, control-U) deletes the entire line, as delimited
by a NL, EOF, EOL, or EOL2 character.
EOF (Typically, control-D or ASCII EOT) may be used to generate
an end-of-file from a terminal. When received, all the
characters waiting to be read are immediately passed to the
program, without waiting for a new-line, and the EOF is
discarded. Thus, if there are no characters waiting, which
is to say the EOF occurred at the beginning of a line, zero
characters will be passed back, which is the standard end-
of-file indication.
NL (ASCII LF) is the normal line delimiter. It can not be
changed or escaped.
EOL (Typically, ASCII NUL) is an additional line delimiter, like
NL. It is not normally used.
EOL2 is another additional line delimiter.
Page 5
TERMIO(7)TERMIO(7)
STOP (Typically, control-S or ASCII DC3) can be used to
temporarily suspend output. It is useful with CRT terminals
to prevent output from disappearing before it can be read.
While output is suspended, STOP characters are ignored and
not read.
START (Typically, control-Q or ASCII DC1) is used to resume output
which has been suspended by a STOP character. While output
is not suspended, START characters are ignored and not read.
The START/STOP characters can not be changed or escaped in
LDISC0 (see ``Termio Structure'' below).
The following characters have special functions on input when the POSIX
termios interface is used or when the System V termio interface is used
and the line discipline is set to the default of LDISC1 (see ``Termio
Structure'' below). These functions and their default character values
are summarized as follows:
SUSP (Control-Z or ASCII SUB) generates a SIGTSTP signal which
stops all processes in the foreground process group for that
terminal.
DSUSP (Control-Y or ASCII EM) generates a SIGTSTP signal as SUSP
does, but the signal is sent when a process in the foreground
process group attempts to read the DSUSP character, rather
than when it is typed.
LNEXT (Control-V or ASCII SYN) causes the next character input to
treated literally.
WERASE (Control-W or ASCII ETB) erases the preceding white space-
delimited word. It will not erase beyond the start of a
line, as delimited by a NL, EOF, EOL, or EOL2 character.
REPRINT (Control-R or ASCII DC2) reprints all characters, preceded by
a newline, that have not been read.
FLUSH (Control-O or ASCII SI) when typed during output causes all
subsequent output to be discarded. Typing any character re-
enables output. This character is also known by the POSIX
name DISCARD
The character values for INTR, QUIT, ERASE, WERASE, KILL, REPRINT, EOF,
EOL, EOL2, SUSP, DSUSP, STOP, START, FLUSH/DISCARD, and LNEXT may be
changed to suit individual tastes (see stty(1)). If the value of a
special control character is CNUL or _POSIX_VDISABLE, the function of
that special control character is disabled. The ERASE, KILL, and EOF
characters may be entered literally in LDISC0 (see ``Termio Structure''
below), by preceding them with the escape character (\), in which case no
special function is done and the escape character is not read. Any of
the special characters may be entered literally in the termios interface
or if the termio interface line discipline is set to LDISC1 (see ``Termio
Page 6
TERMIO(7)TERMIO(7)
Structure'' below), by preceding them with the LNEXT character, in which
case no special function is done and the LNEXT character is not read.
Modem Disconnect
When a modem disconnect is detected, and if CLOCAL is not set in the line
discipline mode (see the discussion of the c_cflag field below), a SIGHUP
signal is sent to the terminal's controlling process. Unless other
arrangements have been made, this signal causes the process to terminate.
If SIGHUP is ignored or caught, any subsequent read returns with an
end-of-file indication until the terminal is closed. Thus, programs that
read a terminal and test for end-of-file can terminate appropriately
after a disconnect. Any subsequent write will return -1 and set errno to
EIO until the device is closed.
If the controlling process is not in the foreground process group of the
terminal, a SIGTSTP is sent to the terminal's foreground process group.
Unless other arrangements have been made, this signal causes the
processes to stop.
Processes in background process groups that attempt to access the
controlling terminal after modem disconnect, while the terminal is still
allocated to the session, will receive appropriate SIGTTOU and SIGTTIN
signals. Unless other arrangements have been made, this signal causes the
processes to stop.
The controlling terminal will remain in this state until it is
reinitialized with a successful open by the controlling process, or
deallocated by the controlling process.
Terminal Parameters
The parameters that control the behavior of devices and modules providing
the termios interface are specified by the termios structure defined by
<termios.h>. Several ioctl(2) system calls that fetch or change these
parameters use this structure, which contains the following members:
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_ospeed; /* output speed */
speed_t c_ispeed; /* input speed; not supported */
cc_t c_cc[NCCS]; /* control chars */
};
The special control characters are defined by the array c_cc. The
symbolic name NCCS is the size of the control-character array and is also
defined by <termios.h>. All space in the array is reserved or used as
described below. The relative positions, subscript names, and normal
default values for each function are as follows:
Page 7
TERMIO(7)TERMIO(7)
0 VINTR CINTR (DEL)
1 VQUIT CQUIT (Control-\)
2 VERASE CERASE (Control-H (Backspace))
3 VKILL CKILL (Control-U)
4 VEOF CEOF (Control-D)
4 VMIN
5 VEOL CEOL (NUL)
5 VTIME
6 VEOL2 CEOL2 (NUL)
7 VSWTCH CNSWTCH (NUL)
8 VSTART CSTART (Control-Q)
9 VSTOP CSTOP (Control-S)
10 VSUSP CNSWTCH (NUL)
11 VDSUSP CNUL (NUL)
12 VREPRINT CRPRNT (Control-R)
13 VFLUSH CFLUSH (Control-O)
14 VWERASE CWERASE (Control-W)
15 VLNEXT CLNEXT (Control-V)
Input Modes
The c_iflag field describes the basic terminal input control. The
values, functions, and symbolic names of the bits in the c_iflag field
are as follows:
IGNBRK 0000001 Ignore break condition.
BRKINT 0000002 Signal interrupt on break.
IGNPAR 0000004 Ignore characters with parity errors.
PARMRK 0000010 Mark parity errors.
INPCK 0000020 Enable input parity check.
ISTRIP 0000040 Strip character.
INLCR 0000100 Map NL to CR on input.
IGNCR 0000200 Ignore CR.
ICRNL 0000400 Map CR to NL on input.
IUCLC 0001000 Map upper-case to lower-case on input.
IXON 0002000 Enable start/stop output control.
IXANY 0004000 Enable any character to restart output.
IXOFF 0010000 Enable start/stop input control.
IMAXBEL 0020000 Echo BEL on input line too long.
IGNBRK If IGNBRK is set, a break condition (a character framing
error with data all zeros) detected on input is ignored, that
is, not put on the input queue and therefore not read by any
process.
BRKINT If IGNBRK is not set and BRKINT is set, the break condition
will flush the input and output queues and if the terminal is
the controlling terminal of a foreground process group, the
break condition will generate a single SIGINT signal to that
foreground process group. If neither IGNBRK nor BRKINT is
set, a break condition is read as a single ASCII NUL
Page 8
TERMIO(7)TERMIO(7)
character, or if PARMRK is set, as: `0377', `0', `0'.
IGNPAR If IGNPAR is set, a byte with framing or parity errors (other
than break) is ignored.
PARMRK If PARMRK is set, and IGNPAR is not set, a character with a
framing or parity error (other than break) is read as the
three-character sequence: `0377', `0', `X', where X is the
data of the character received in error. To avoid ambiguity
in this case, if ISTRIP is not set, a valid character of
`0377' is read as `0377', `0377'. If neither PARMRK nor
IGNPAR is set, a framing or parity error (other than break)
is read as the single ASCII NUL character.
INPCK If INPCK is set, input parity checking is enabled. If INPCK
is not set, input parity checking is disabled. This allows
output parity generation without input parity errors.
ISTRIP If ISTRIP is set, valid input characters are first stripped
to 7-bits, otherwise all 8-bits are processed.
INLCR If INLCR is set, a received NL character is translated into a
CR character.
IGNCR If IGNCR is set, a received CR character is ignored (not
read).
ICRNL If ICRNL is set, a received CR character is translated into a
NL character.
IUCLC If IUCLC is set, a received upper-case alphabetic character
is translated into the corresponding lower-case character.
IXON If IXON is set, start/stop output control is enabled. A
received STOP character will suspend output and a received
START character will restart output. The STOP and START
characters will not be read, but will mearly perform flow
control functions.
IXANY If IXANY is set, any input character will restart output that
has been suspended.
IXOFF If IXOFF is set, the system will transmit START/STOP
characters when the input queue is nearly empty/full.
IMAXBEL If IMAXBEL is set, the ASCII BEL character is echoed if the
input stream overflows. Further input is discarded, but any
input already present in the input stream is preserved.
Output Modes
Page 9
TERMIO(7)TERMIO(7)
The c_oflag field specifies the system treatment of output. The values,
functions, and symbolic names of the bits and subfields in the c_oflag
field are as follows:
OPOST 0000001 Postprocess output.
OLCUC 0000002 Map lower case to upper on output.
ONLCR 0000004 Map NL to CR-NL on output.
OCRNL 0000010 Map CR to NL on output.
ONOCR 0000020 No CR output at column 0.
ONLRET 0000040 NL performs CR function.
OFILL 0000100 Use fill characters for delay.
OFDEL 0000200 Fill is DEL, else NUL.
NLDLY 0000400 Select new-line 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
FFDLY 0100000 Select form-feed delays:
FF0 0
FF1 0100000
OPOST If OPOST is set, output characters are post-processed as
indicated by the remaining flags, otherwise characters are
transmitted without change.
OLCUC If OLCUC is set, a lower-case alphabetic character is
transmitted as the corresponding upper-case character. This
function is often used in conjunction with IUCLC.
ONLCR If ONLCR is set, the NL character is transmitted as the CR-NL
character pair.
OCRNL If OCRNL is set, the CR character is transmitted as the NL
character.
ONOCR If ONOCR is set, no CR character is transmitted when at
column 0 (first position).
Page 10
TERMIO(7)TERMIO(7)
ONLRET If ONLRET is set, the NL character is assumed to do the
carriage-return function; the column pointer will be set to 0
and the delays specified for CR will be used. Otherwise the
NL character is assumed to do just the line-feed function;
the column pointer will remain unchanged. The column pointer
is also set to 0 if the CR character is actually transmitted.
OFILL If OFILL is set, fill characters will be transmitted for
delay instead of a timed delay. This is useful for high baud
rate terminals which need only a minimal delay.
OFDEL If OFDEL is set, the fill character is DEL, otherwise NUL.
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.
The actual delays depend on line speed and system load.
NLDLY Newline delay type 0 (NL0) selects no delay. Newline delay
type 1 (NL1) lasts about 0.10 seconds. If ONLRET is set, the
carriage-return delays are used instead of the new-line
delays. If OFILL is set, two fill characters will be
transmitted.
CRDLY Carriage-return delay type 0 (CR0) selects no delay.
Carriage-return delay type 1 (CR1) is dependent on the
current column position, type 2 (CR2) is about 0.10 seconds,
and type 3 (CR3) is about 0.15 seconds. If OFILL is set,
delay type 1 transmits two fill characters, and type 2, four
fill characters.
TABDLY Horizontal-tab delay type 0 (TAB0) selects no delay.
Horizontal-tab delay type 1 (TAB1) is dependent on the
current column position. Type 2 (TAB2) is about 0.10
seconds. Type 3 (TAB3) specifies that tabs are to be
expanded into spaces. If OFILL is set, two fill characters
will be transmitted for any delay.
BSDLY Backspace delay type 0 (BS0) selects no delay. Backspace
delay type 1 (BS1) lasts about 0.05 seconds. If OFILL is
set, one fill character will be transmitted.
VTDLY Vertical-tab delay type 0 (VT0) selects no delay. Vertical-
tab delay type 1 (VT1) lasts about 2.0 seconds.
FFDLY Form-feed delay type 0 (FF0) selects no delay. Form-feed
delay type 0 (FF0) lasts about 2.0 seconds.
Control Modes
Page 11
TERMIO(7)TERMIO(7)
The c_cflag field describes the hardware control of the terminal. The
values, functions, and symbolic names of the bits and subfields in the
c_cflag field are as follows:
CBAUD 000000017 No longer supported; see "Old termio" below.
CSIZE 000000060 Character size:
CS5 0 5 bits
CS6 000000020 6 bits
CS7 000000040 7 bits
CS8 000000060 8 bits
CSTOPB 000000100 Send two stop bits, else one.
CREAD 000000200 Enable receiver.
PARENB 000000400 Parity enable.
PARODD 000001000 Odd parity, else even.
HUPCL 000002000 Hang up on last close.
CLOCAL 000004000 Local line, else dial-up.
RCV1EN 000010000 Not supported.
XMT1EN 000020000 Not supported.
LOBLK 000040000 Block layer output.
XCLUDE 000100000 Not supported.
CIBAUD 003600000 Not supported.
PAREXT 004000000 Not supported.
CNEW_RTSCTS 010000000 Use RTS/CTS flow control
CSIZE The CSIZE bits specify the character size in bits for both
transmission and reception. This size does not include the
parity bit, if any.
CSTOPB If CSTOPB is set, two stop bits are used, otherwise one
stop bit. For example, at 110 baud, two stops bits are
required.
CREAD If CREAD is set, the receiver is enabled. Otherwise no
characters will be received.
PARENB If PARENB is set, parity generation and detection is
enabled and a parity bit is added to each character.
PARODD If parity is enabled, the PARODD flag specifies odd parity
if set, otherwise even parity is used.
HUPCL If HUPCL is set, the line will be disconnected when the
last process with the line open closes it or terminates.
That is, the data-terminal-ready signal will not be
asserted.
CLOCAL If CLOCAL is set, the line is assumed to be a local, direct
connection with no modem control. Otherwise modem control
is assumed.
Page 12
TERMIO(7)TERMIO(7)
LOBLK If LOBLK is set, the output of a job control layer will be
blocked when it is not the current layer. Otherwise the
output generated by that layer will be multiplexed onto the
current layer.
CNEW_RTSCTS If CNEW_RTSCTS is set, and the communications port supports
it, RTS/CTS handshaking will be used. When the input queue
becomes nearly full, RTS will be dropped. RTS will be
reasserted when the input queue has drained sufficiently.
Output is suspended when CTS is lowered and restarted when
CTS is raised. This flag is automatically set on the ttyf
serial port devices; see serial(7).
Local Modes
The c_lflag field of the argument structure is used by the line
discipline to control terminal functions. The following flags are
currently defined:
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 NL after kill character.
ECHONL 0000100 Echo NL.
NOFLSH 0000200 Disable flush after interrupt or quit.
IEXTEN 0000400 Enable extended functions (not used by IRIX).
ECHOCTL 0001000 Echo control characters as ^char, delete as ^?.
ECHOPRT 0002000 Echo erase character as character erased.
ECHOKE 0004000 BS-SP-BS entire line on line kill.
FLUSHO 0020000 Output being flushed.
PENDIN 0040000 Retype pending input at next read or input char.
TOSTOP 0100000 Send SIGTTOU for background output.
ISIG If ISIG is set, each input character is checked against the
special control characters INTR, SUSP, DSUSP, and QUIT. If an
input character matches one of these control characters, the
function associated with that character is performed. If
ISIG is not set, no checking is done. Thus these special
input functions are possible only if ISIG is set. These
functions may be disabled individually by changing the value
of the control character to CNUL or _POSIX_VDISABLE
ICANON If ICANON is set, canonical processing is enabled. This
enables the erase and kill edit functions, and the assembly
of input characters into lines delimited by NL, EOF, EOLand
EOL2. If ICANON is not set, read requests are satisfied
directly from the input queue. A read will not be satisfied
until at least MIN characters have been received or the
timeout value TIME has expired between characters. This
allows fast bursts of input to be read efficiently while
Page 13
TERMIO(7)TERMIO(7)
still allowing single character input. The MIN and TIME
values are stored in the position for the EOF and EOL
characters, respectively. The time value represents tenths
of seconds.
XCASE If XCASE is set, and if ICANON is set, an upper-case letter
is accepted on input by preceding it with a \ character, and
is output preceded by a \ character. In this mode, the
following escape sequences are generated on output and
accepted on input:
for: use:
` \'
| \!
~ \^
{ \(
} \)
\ \\
For example, ``A'' is input as ``\a'', ``\n'' as ``\\n'', and
``\N'' as ``\\\n''.
ECHO If ECHO is set, characters are echoed as received.
When ICANON is set, the following echo functions are possible.
ECHOE If ECHO and ECHOE are set, and ECHOPRT is not set, the ERASE
and WERASE characters are echoed as one or more ASCII BS SP
BS, which will clear the last character(s) from a CRT screen.
If ECHOE is set and ECHO is not set, the erase character is
echoed as ASCII SP BS.
ECHOK If ECHOK is set, and ECHOKE is not set, the NL character will
be echoed after the kill character to emphasize that the line
will be deleted. Note that an escape character or an LNEXT
character preceding the erase or kill character removes any
special function (see ``Special Characters'' above).
ECHONL If ECHONL is set, the NL character will be echoed even if
ECHO is not set. This is useful for terminals set to local
echo (so-called half duplex). Unless escaped, the EOF
character is not echoed. Because EOT is the default EOF
character, this prevents terminals that respond to EOT from
hanging up.
NOFLSH If NOFLSH is set, the normal flush of the input and output
queues associated with the INTR, QUIT, and SUSP characters
will not be done.
Page 14
TERMIO(7)TERMIO(7)
TOSTOP If TOSTOP is set, the signal SIGTTOU is sent to a process
that tries to write to its controlling terminal if it is not
in the foreground process group for that terminal. This
signal normally stops the process. Otherwise, the output
generated by that process is output to the current output
stream. Processes that are blocking or ignoring SIGTTOU
signals are excepted and allowed to produce output and the
SIGTTOU signal is not sent.
ECHOCTL If ECHOCTL is set, all control characters (characters with
codes between 0 and 37 octal) other than ASCII TAB, ASCII NL,
the START character, the STOP character, ASCII CR, and ASCII
BS are echoed as ^X, where X is the character given by adding
100 octal to the code of the control character (so that the
character with octal code 1 is echoed as ^A), and the ASCII
DEL character, with code 177 octal is echoed as ^?.
ECHOPRT If ECHO and ECHOPRT are set, the first ERASE or WERASE
character in a sequence echoes as a backslash (\), followed
by the characters being erased. Subsequent ERASE or WERASE
characters echo the characters being erased in reverse order.
The next non-erase character causes a slash (/) to be typed
before it is echoed.
ECHOKE If ECHOKE is set, the kill character is echoed by erasing
each character on the line from the screen (using the
mechanism selected by ECHOE and ECHOPRT).
FLUSHO If FLUSHO is set, data written to the terminal is discarded.
This bit is set when the FLUSH/DISCARD character is typed. A
program can cancel the effect of typing the FLUSH/DISCARD
character by clearing FLUSHO.
PENDIN If PENDIN is set, any input that has not yet been read is
reprinted when the next character arrives as input.
Speed
The c_ospeed and c_ispeed fields control the output and input speeds of
the line, respectively, in bits per second (bps). No current SGI devices
support setting output and input speeds to different values, however, so
c_ispeed is not supported.
B0 0 Hang up
B50 50 50 bps
B75 75 75 bps
B110 110 110 bps
B134 134 134 bps
B150 150 150 bps
B200 200 200 bps
B300 300 300 bps
B600 600 600 bps
Page 15
TERMIO(7)TERMIO(7)
B1200 1200 1200 bps
B1800 1800 1800 bps
B2400 2400 2400 bps
B4800 4800 4800 bps
B9600 9600 9600 bps
B19200 19200 19200 bps
B38400 38400 38400 bps
B57600 57600 57600 bps
B76800 76800 76800 bps
B115200 115200 115200 bps
SSPEED B9600 Default baud rate.
The B* names are provided only for convenience; applications may use
plain integer values in c_ospeed and c_ispeed.
Note that capabilities of serial ports vary; not all devices support all
bit rates. Some devices support additional rates.
Termio Structure
The System V termio structure is used by some ioctls; it is defined by
<sys/termio.h> and includes the following members:
struct termio {
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_ospeed; /* output speed */
speed_t c_ispeed; /* input speed; not supported */
char c_line; /* line discipline */
cc_t c_cc[NCCS]; /* control chars */
};
The c_line field defines the line discipline used to interpret control
characters. A line discipline is associated with a family of
interpretations. For example, LDISC0 is the standard System V set of
interpretations, while LDISC1 is similar to the interpretations used in
the 4.3BSD tty driver. In LDISC1,
o additional control characters are available,
o control characters which are not editing characters are echoed as '^'
followed by the equivalent letter,
o backspacing does not back up into the prompt,
o input is re-typed when backspacing encounters a confusion between what
the user and the computer have typed, and
Page 16
TERMIO(7)TERMIO(7)
o job control is available.
The symbolic name NCCS is the size of the control-character array and is
also defined by <termio.h>. The relative positions, subscript names, and
typical default values for each function are as follows:
0 VINTR CINTR (DEL)
1 VQUIT CQUIT (Control-\)
2 VERASE CERASE (Control-H (backspace))
3 VKILL CKILL (Control-U)
4 VEOF CEOF (Control-D (EOT))
4 VMIN
5 VEOL NUL
5 VTIME
6 VEOL2 NUL
If the line discipline (c_line) is set to LDISC1, then additional control
characters are defined:
7 VSWTCH CNSWTCH (NUL)
8 VSTART CSTART (Control-Q)
9 VSTOP CSTOP (Control-S)
10 VSUSP CNSWTCH (NUL)
11 VDSUSP CNUL (NUL)
12 VREPRINT CRPRNT (Control-R)
13 VFLUSH CFLUSH (Control-O)
14 VWERASE CWERASE (Control-W)
15 VLNEXT CLNEXT (Control-V)
Old termio and termios
For compatibility with existing binaries, MIPS ABI programs, and programs
that cannot be ported to use the new termio or termios structures, the
old interfaces are retained. Existing binaries automatically use the old
interfaces. By defining _OLD_TERMIOS at compile time (before including
<termios.h>, <termio.h>, or <sys/ttydev.h>), the old interfaces are in
effect. The old termios structure is defined as follows:
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 */
cc_t c_cc[NCCS]; /* control chars */
};
and the old termio structure is defined as follows:
struct termio {
tcflag_t c_iflag; /* input modes */
tcflag_t c_oflag; /* output modes */
tcflag_t c_cflag; /* control modes */
Page 17
TERMIO(7)TERMIO(7)
tcflag_t c_lflag; /* local modes */
char c_line; /* line discipline */
cc_t c_cc[NCCS]; /* control chars */
};
The members are as described above, except for c_cflag, in which CBAUD
encodes the bit rate:
CBAUD 000000017 Baud rate:
B0 0 Hang up
B50 000000001 50 baud
B75 000000002 75 baud
B110 000000003 110 baud
B134 000000004 134 baud
B150 000000005 150 baud
B200 000000006 200 baud
B300 000000007 300 baud
B600 000000010 600 baud
B1200 000000011 1200 baud
B1800 000000012 1800 baud
B2400 000000013 2400 baud
B4800 000000014 4800 baud
B9600 000000015 9600 baud
B19200 000000016 19200 baud
EXTA 000000016 External A
B38400 000000017 38400 baud
EXTB 000000017 External B
SSPEED B9600 Default baud rate.
Mixing old and new interfaces
If a bit rate is set using the new termio or termios interfaces (or the
POSIX interfaces described in termios(3)) that cannot be represented in
the old CBAUD field, then the old termio, termios, and POSIX interfaces
will return _INVALID_BAUD in the CBAUD field. If the bit rate is set to
_INVALID_BAUD using the old interfaces, the bit rate change will be
ignored, and the actual line speed will remain unchanged. This allows
many programs that do not explicitly manage bit rates to work with the
new interfaces without change. And, it allows some old programs to work
with new, fast bit rates without change. For example, sequences similar
to the following (which are very common) work with either old or new
interfaces, even if the line is currently set to a baud rate than cannot
be represented in the old CBAUD field:
struct termio t;
ioctl(fd, TCGETA, &t);
t.c_cflag |= CREAD;
t.c_lflag &= ~ECHO;
/* t.c_cflag & CBAUD may contain _INVALID_BAUD, but, if so, */
/* this TCSETA will not affect the actual bit rate */
ioctl(fd, TCSETA, &t);
Page 18
TERMIO(7)TERMIO(7)
System Calls
The ioctl()s supported by devices and STREAMS modules providing the
termio and termios interface are listed below.
TCGETA The argument is a pointer to a termio structure. Get the
parameters associated with the terminal and store in the
termio structure referenced by arg.
TCSETA The argument is a pointer to a termio structure. Set the
parameters associated with the terminal from the structure
referenced by arg. The change is immediate.
TCSETAW The argument is a pointer to a termio structure. Wait for
the output to drain before setting the new parameters. This
form should be used when changing parameters that will
affect output.
TCSETAF The argument is a pointer to a termio structure. Wait for
the output to drain, then flush the input queue and set the
new parameters.
TCGETS The argument is a pointer to a termios structure. Get the
parameters associated with the terminal and store in the
termios structure referenced by arg. See tcgetattr(3).
TCSETS The argument is a pointer to a termios structure. Set the
parameters associated with the terminal from the structure
referenced by arg. The change is immediate. See
tcsetattr(3).
TCSETSW The argument is a pointer to a termios structure. Wait for
the output to drain before setting the new parameters. This
form should be used when changing parameters that will
affect output. See tcsetattr(3).
TCSETSF The argument is a pointer to a termios structure. Wait for
the output to drain, then flush the input queue and set the
new parameters. See tcsetattr(3).
TCSBRK The argument is an int value. Wait for the output to drain.
If arg is 0, then send a break (zero bits for 0.25 seconds).
See tcsendbreak(3) and tcdrain(3).
TCXONC Start/stop control. The argument is an int value. If arg
is 0, suspend output; if 1, restart suspended output; if 2,
suspend input; if 3, restart suspended input. See
tcflow(3).
TCFLSH The argument is an int value. If arg is 0, flush the input
queue; if 1, flush the output queue; if 2, flush both the
input and output queues. See tcflush(3).
Page 19
TERMIO(7)TERMIO(7)
TIOCNOTTY Disconnect calling process from terminal and session.
TIOCSTI Simulate terminal input: arg points to a character which the
system pretends has been typed on the terminal.
TIOCSPGRP Set process group of tty: arg is a pointer to a pid_t which
is the value to which the process group ID for this terminal
will be set. See tcsetpgrp(3).
TIOCGPGRP Get process group of tty: arg is a pointer to a pid_t into
which is placed the process group ID of the process group
for which this terminal is the controlling terminal. See
tcgetpgrp(3).
TIOCGSID arg is a pointer to a pid_t into which is placed the session
ID of the terminal.
TIOCFLUSH If the int pointed to by arg has a zero 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.
TIOCMGET The argument is a pointer to an int sized bit field into
which the current state of the modem status lines is stored.
This ioctl() is supported only on special files representing
serial ports. See serial(7). The symbolic names of the
bits returned in arg are defined by <sys/termios.h>:
TIOCM_LE line enable
TIOCM_DTR data terminal ready
TIOCM_RTS request to send
TIOCM_ST secondary transmit
TIOCM_SR secondary receive
TIOCM_CTS clear to send
TIOCM_CAR carrier detect
TIOCM_CD synonym for TIOCM_CAR
TIOCM_RNG ring
TIOCM_RI synonym for TIOCM_RNG
TIOCM_DSR data set ready
Not all of these are necessarily supported by any particular
device.
TIOCMSET The argument is a pointer to an int sized bit field used to
set the state of the modem status lines. If a bit is set, the
coresponding modem status line is turned on. If a bit is
cleared the coresponding modem status line is turned off.
This ioctl() is supported only on special files representing
Page 20
TERMIO(7)TERMIO(7)
serial ports. See serial(7). The symbolic names of the bits
used in arg are the same as for TIOCMGET. Only DTR and RTS
are settable with this ioctl(). Not all of these are
necessarily supported by any particular device.
TIOCGWINSZ Get window size: arg is a pointer to a structure of the
following form: Window size structure:
struct winsize {
unsigned short ws_row; /* rows, in chars */
unsigned short ws_col; /* columns, in chars */
unsigned short ws_xpixel; /* horiz. pixels */
unsigned short ws_ypixel; /* vert. pixels */
};
TIOCSWINSZ Set window size: arg is a pointer to a structure of a winsize
structure.
FIONREAD Return the number of bytes currently available to read. arg
is a pointer to an int.
FIONBIO Enables or disables non-blocking mode, according to the
boolean value of the contents of arg. arg is a pointer to an
int. Enabling this mode has the same effect as the O_NDELAY
flag for open(2).
The following ioctl calls apply only to pseudo terminals; see pty(7M) for
their descriptions:
TIOCPKT, TIOCPKT_DATA, TIOCPKT_FLUSHREAD, TIOCPKT_FLUSHWRITE,
TIOCPKT_STOP, TIOCPKT_START, TIOCPKT_NOSTOP and TIOCPKT_DOSTOP.
NOTES
Of the ioctl commands listed above, all except TCGETA and TCGETS alter
the state of the terminal. For this reason, a background job which
issues any of commands except TCGETA or TCGETS will be suspended. Refer
to csh(1) or ksh(1) for more information about job control.
FILES
/dev/tty*
SEE ALSOstty(1), fork(2), ioctl(2), setsid(2), setpgrp(2), signal(2), tcdrain(3),
tcflow(3), tcflush(3), tcgetattr(3), tcgetpgrp(3), tcsendbreak(3),
tcsetattr(3), tcsetpgrp(3), pty(7M), serial(7), termios(3)
Page 21
