NAME

termios −  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:

MemberTypeDescription
c_iflag tcflag_tInput modes
c_oflagtcflag_tOutput modes
c_cflagtcflag_tControl modes
c_lflagtcflag_tLocal modes
c_cc[NCCS]cc_tControl 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:

CRThe carriage-return character: ’\r’. 

NLThe new-line character: ’\n’. 

EOFThe end-of-file character: c_cc[VEOF]. 

EOLThe alternate end-of-line character: c_cc[VEOL]. 

ERASEThe erase character: c_cc[VERASE]. 

KILLThe erase-line character: c_cc[VKILL]. 

WERASEThe erase character: c_cc[VWERASE]. 

REPRINTThe redisplay-input character: c_cc[VREPRINT]. 

INTRThe interrupt character (generates SIGINT): c_cc[VINTR]. 

QUITThe quit character (generates SIGQUIT): c_cc[VQUIT]. 

SUSPThe suspend character (generates SIGTSTP): c_cc[VSUSP]. 

DSUSPThe delayed-suspend character (generates SIGTSTP): c_cc[VDSUSP]. 

STOPThe stop-output character: c_cc[VSTOP]. 

STARTThe start-output character: c_cc[VSTART]. 

DISCARDThe flush-output character: c_cc[VDISCARD]. 

LNEXTThe literal-next character: c_cc[VLNEXT]. 

QUOTEThe 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 = 0TIME 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 > 0TIME 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 = 0A 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 > 0TIME 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:

IGNCRA received CR character is ignored (not placed on the input queue)

ICRNLIf IGNCR is not set, then a received CR is translated into NL. 

INLCRA received NL is translated into CR. 

INPCKInput parity checking is enabled.  The type of parity is determined by flags in c_cflag. 

IGNPARCharacters with parity errors are ignored. 

PARMRKIf 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. 

ISTRIPValid input characters are first stripped to seven bits before being placed in the input queue; otherwise, all eight bits are processed. 

IGNBRKA break condition detected on input is ignored (not placed on the input queue). 

BRKINTIf 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’. 

IXONStart-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. 

IXANYWhen 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. 

IXOFFIf 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. 

IMAXBELIf 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:

OPOSTIf 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). 

ONLCRIf 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

CLOCALThe 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. 

CREADReception of characters is enabled.  Otherwise, characters will not be received. 

CSTOPBTwo stop bits are sent after each character.  Otherwise, only one is sent. 

CSTOPB110
Two stop bits are sent if output speed is 110 baud.

CSIZEThe 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. 

PARENBParity generation and detection are enabled. 

PARODDIf PARENB is set, odd parity is generated and expected.  If PARODD is clear and PARENB is set, even parity is generated and expected. 

PAR0If 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.) 

PAR1If 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. 

HUPCLWhen 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

ECHOEchoing of characters is enabled.  Otherwise, characters are not echoed back to the terminal. 

ECHONLA 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. 

ECHOEIn 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.

ECHOKIn canonical mode, a KILL character will cause the terminal to echo the KILL character followed by a newline (unless ECHOKE is set). 

ECHOKEIn canonical mode, a KILL character will cause the terminal to erase the current line from the display. 

ICANONIf ICANON is set, the device is in canonical input mode.  Otherwise, the device is in noncanonical input mode. 

IEXTENIEXTEN enables the special characters LNEXT and DISCARD, as well as certain other features as described. 

ISIGIf ISIG is set, the characters INTR, QUIT, SUSP, and DSUSP take on their special meaning. 

NOFLSHThe 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. 

TOSTOPA 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 ALSO

stty(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