TERMIOS(4P)TERMIOS(4P)NAMEtermios - the termios structure and header file
SYNOPSIS
#include <termios.h>
DESCRIPTION
The header <termios.h> contains the definition of the termios structure
and associated constants. The termios structure is passed as an
argument to the tcgetattr, tcsetattr, tcdrain, tcflow, tcflush,
tcsendbreak, cfgetispeed, cfgetospeed, cfsetispeed and cfsetospeed
functions.
The termios Structure
The termios structure contains the following members:
Member Type Description
c_iflag tcflag_t Input modes
c_oflag tcflag_t Output modes
c_cflag tcflag_t Control modes
c_lflag tcflag_t Local modes
c_cc[NCCS] cc_t Control characters
Special Characters
Some characters have special functions on input or output or both.
Some special characters are constants; others are defined in the c_cc
array (indexed by defined constants). The interpretation of these
characters is described in the following subsections. The characters
and their values (as constants or c_cc expressions) are as follows:
CR The carriage-return character: '\r'.
NL The new-line character: '\n'.
EOF The end-of-file character: c_cc[VEOF].
EOL The alternate end-of-line character: c_cc[VEOL].
ERASE The erase character: c_cc[VERASE].
KILL The erase-line character: c_cc[VKILL].
WERASE The erase character: c_cc[VWERASE].
REPRINT The redisplay-input character: c_cc[VREPRINT].
INTR The interrupt character (generates SIGINT): c_cc[VINTR].
QUIT The quit character (generates SIGQUIT): c_cc[VQUIT].
SUSP The suspend character (generates SIGTSTP): c_cc[VSUSP].
DSUSP The delayed-suspend character (generates SIGTSTP):
c_cc[VDSUSP].
STOP The stop-output character: c_cc[VSTOP].
START The start-output character: c_cc[VSTART].
DISCARD The flush-output character: c_cc[VDISCARD].
LNEXT The literal-next character: c_cc[VLNEXT].
QUOTE The quote character: c_cc[VQUOTE].
MIN, TIME MIN and TIME are not special characters, but are nevertheless
stored in the c_cc array. They are, respectively, c_cc[VMIN]
and c_cc[VTIME].
These special characters are only meaningful when specific flags are
set. The NL, EOF, EOL, ERASE, KILL, QUOTE, WERASE, and REPRINT special
characters are enabled when ICANON (in c_lflag) is set. The INTR,
QUIT, SUSP, and DSUSP characters are enabled when ISIG (in c_lflag) is
set. The START and STOP special characters are enabled when IXON or
IXOFF (in c_iflag) is set. LNEXT and DISCARD are enabled by IEXTEN (in
c_lflag).
Input Processing Modes
Each terminal device has associated with it an input queue, into which
incoming data is stored by the system before being read by a process.
Two styles of input processing are available, determined by whether the
terminal device is in canonical mode (ICANON set) or noncanonical mode
(ICANON not set).
In canonical mode input processing, terminal input is processed in
units of lines. A line is delimited by the NL character, the EOF
character, or the EOL character. This means that a read request will
not return until an entire line has been typed (or a signal has been
received). Also, no matter how many bytes 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 bytes, even one, may be
requested in a read without losing information. NL and EOL, when
entered, are considered part of the line. EOF, on the other hand,
terminates a line, but is not passed to the reader. As a consequence,
an EOF received at the beginning of a line marks an empty line, which
causes a read to return zero bytes (the empty line), simulating an end-
of-file condition.
A line can be edited as it is entered, with the ERASE, KILL, and WERASE
characters. Editing is limited to the current line, consisting of
characters in the input queue that have not yet been delimited by NL,
EOF, or EOL. The ERASE character deletes the last character in the
current line, if there is any. The KILL character deletes all
characters in the current line. The WERASE character deletes the last
word in the current line. In addition, the REPRINT character causes
the input queue to be redisplayed.
The QUOTE character followed by the ERASE enters the ERASE character
into the input queue. The sequence QUOTE followed by KILL enters the
KILL character. QUOTE has no special meaning when followed by any
other character (include WERASE). (QUOTE provides compatibility with
older terminal interfaces.)
In noncanonical mode input processing, input bytes are not assembled
into lines, and line editing is not allowed. The values of MIN and
TIME are used to determine how to process the bytes received.
MIN represents the minimum number of bytes that must be entered before
a read will return. The TIME parameter gives the amount of delay, in
1/10-second increments, before a read times out and returns. There are
four different cases to be considered:
MIN > 0 and TIME = 0 TIME is ignored. Data is not made available
to a read request until MIN bytes have been
received. A read can block indefinitely.
MIN > 0 and TIME > 0 TIME acts as an inter-byte timer that is not
set until the first byte is entered and is
reset after each byte. If MIN characters are
received before the timer expires, the data
becomes available and a read will return. It
will return the smaller of MIN and the number
of bytes actually read. Because the timers
does not start until the first byte is
received, a read can block indefinitely.
Moreover, a read will always return at least 1
byte, unless interrupted by a signal.
MIN = 0 and TIME = 0 A read always returns immediately. If data
has already been entered, it is available, and
(up to the number of bytes requested) is
returned.
MIN = 0 and TIME > 0 TIME is a timer activated as soon as the
process reads. Data is made available as soon
as a single byte is entered. It is not
possible for a read to block indefinitely -
after TIME/10 seconds, if no data has been
entered, a read will return 0.
In both canonical and noncanonical modes, other special characters are
available. INTR, QUIT, and SUSP generate signals (SIGINT, SIGQUIT, and
SIGTSTP, respectively) to the current process group. When entered,
DSUSP is placed in the input queue. When it is read by a process,
SIGTSTP is generated and the DSUSP character is not passed to the
process. START and STOP are used for flow control for both input and
output (see IXON and IXOFF below). DISCARD causes further output to the
terminal to be discarded, until another character is entered. LNEXT
followed by any other character (including special characters,
including LNEXT) enters that character into the input queue,
disregarding any special meaning that character may have.
Input Modes
The bit-masks in c_iflag describe basic terminal input control and are
composed of the bitwise inclusive OR of the following masks:
IGNCR A received CR character is ignored (not placed on the input
queue)
ICRNL If IGNCR is not set, then a received CR is translated into
NL.
INLCR A received NL is translated into CR.
INPCK Input parity checking is enabled. The type of parity is
determined by flags in c_cflag.
IGNPAR Characters with parity errors are ignored.
PARMRK If IGNPAR is not set, then a byte with a framing or parity
error is placed in the input queue as the 3-byte sequence:
'\377', '\000', X, where X is the erroneous character.
ISTRIP Valid input characters are first stripped to seven bits
before being placed in the input queue; otherwise, all eight
bits are processed.
IGNBRK A break condition detected on input is ignored (not placed on
the input queue).
BRKINT If IGNBRK is clear, a break causes the input and output
queues to be flushed. A SIGINT signal is sent to the
terminal's process group. If neither IGNBRK nor BRKINT is
set, a break condition is read as a single '\0'.
IXON Start-stop output control is enabled. A received STOP
character suspends output, and a received START character
restarts output. When IXON is set, START and STOP characters
are not read, but merely perform flow control functions.
When IXON is not set, the START and STOP characters are read
but have no special functions.
IXANY When IXANY is set and output is stopped (from receiving the
STOP character), output is be restarted by receiving any
character. That character is processed normally.
IXOFF If IXOFF is set, start-stop input control is enabled. The
system sends one or more STOP characters to cause the
terminal to stop transmitting data, to avoid overflowing the
input buffer. The system also sends one or more START
characters to cause the terminal to restart transmission.
IMAXBEL If IMAXBEL is set and a character is received when the input
queue is full, then a bell character (control-G) is written
to the output.
Output Modes
The bit-masks in c_oflag describe the basic terminal output control and
are composed of the bitwise inclusive OR of the following masks:
OPOST If OPOST is clear, output characters are transmitted
unchanged. If OPOST is set, then output processing is
performed, as dictated by other c_oflag bits. In addition,
if OPOST is set and the device is in canonical mode, then the
ASCII EOT character (control-D) is never transmitted (for
compatibility with older interfaces).
ONLCR If ONLCR is set, an NL character is expanded into CR and NL
on output.
NLDELAY, TBDELAY, ...
The delay flags supported by the tty interface (see tty(4))
are also valid as c_oflag values. Delays, however, are not
supported when outputting 8-bit characters (see CSIZE below).
Control Modes
CLOCAL The modem status lines are ignored (the terminal is assumed
to be connected to the system locally). If CLOCAL is clear,
the modem status lines are monitored.
CREAD Reception of characters is enabled. Otherwise, characters
will not be received.
CSTOPB Two stop bits are sent after each character. Otherwise, only
one is sent.
CSTOPB110 Two stop bits are sent if output speed is 110 baud.
CSIZE The CSIZE bits specify the byte size in bits for both
transmission and reception. Valid values are CS5, CS6, CS7
or CS8 for 5, 6, 7 or 8 bit per byte respectively.
PARENB Parity generation and detection are enabled.
PARODD If PARENB is set, odd parity is generated and expected. If
PARODD is clear and PARENB is set, even parity is generated
and expected.
PAR0 If PARODD is not set, IEXTEN (in c_lflag) is set, and PAR0 is
set, then space (zero) parity is generated on output, and
parity is expected on input but not checked. (PAR0 is meant
to emulate the behavior of the tty(4) interface when neither
EVENP nor ODDP is set.)
PAR1 If PARODD is not set, IEXTEN is set, and PAR1 is set, then
even parity is generated on output, and parity is expect but
unchecked on input. (PAR1 is meant to be equivalent to
setting both EVENP and ODDP through the tty(4) interface.)
The effect of setting both PAR0 and PAR1 is undefined.
HUPCL When the last process that has the terminal file open
terminates or closes the file, the modem control lines will
be lowered and the modem connection is broken.
Local Modes
ECHO Echoing of characters is enabled. Otherwise, characters are
not echoed back to the terminal.
ECHONL A received NL character is echoed even if ECHO is not set.
ECHOCTL If ECHOCTL and ECHO are set, control characters will be
echoed as ^X.
ECHOE In canonical mode, an ERASE character will erase the previous
character from the display, in a way determined by the flags
ECHOCRT and ECHOPRT (see below). If neither ECHOCRT nor
ECHOPRT is set, then a backspace character (`\b') is echoed.
ECHOCRT If ECHOCRT is set, then erasing a deleted character will be
accomplished by sending the sequence “\b \b” (suitable for a
CRT display).
ECHOPRT If ECHOPRT is set, deleted characters will be erased in a way
appropriate for a hard-copy terminal.
ECHOK In canonical mode, a KILL character will cause the terminal
to echo the KILL character followed by a newline (unless
ECHOKE is set).
ECHOKE In canonical mode, a KILL character will cause the terminal
to erase the current line from the display.
ICANON If ICANON is set, the device is in canonical input mode.
Otherwise, the device is in noncanonical input mode.
IEXTEN IEXTEN enables the special characters LNEXT and DISCARD, as
well as certain other features as described.
ISIG If ISIG is set, the characters INTR, QUIT, SUSP, and DSUSP
take on their special meaning.
NOFLSH The input and output queues are not flushed when a signal is
generated due to receipt of an INTR, QUIT, or SUSP character.
If NOFLSH is clear, then generation of such a signal causes
the input and output queues to be flushed.
TOSTOP A SIGTTOU signal is generated for the process group of any
background process that attempts to write to its controlling
terminal. However, if the writing process has arranged to
block or ignore SIGTTOU, then the signal is not generated and
the output is sent. If TOSTOP is not set, then data
transmitted by a write to the controlling terminal from a
background process is put on the output stream.
Compatibility
The features supported by termios are a superset of those implemented
by the older tty(4) interface. The two interfaces can coexist on the
same device. However, mixing uses of both interfaces in the same
program (e.g., using both tcsetattr and ioctl(TIOCSETP)) is not
recommended.
SEE ALSOstty(1), read(2P), sigvec(2), write(2P), cfgetispeed(3P),
cfgetospeed(3P), cfsetispeed(3P), cfsetospeed(3P), tcdrain(3P),
tcflow(3P), tcflush(3P), tcgetattr(3P), tcsetattr(3P), tcsendbreak(3P),
tty(4)4th Berkeley Distribution August 1, 1992 TERMIOS(4P)