NAME

termio − general terminal interface

SYNOPSIS

#include <termios.h>

#include <termio.h>

DESCRIPTION

All of the asynchronous communications ports and pseudo terminals use the same general interface, no matter what hardware is involved.  This interface is described in tty(4). The remainder of this section discusses the POSIX interface using termios structure and the System V interface using termio structure. 

Users’ programs seldom open terminal files; they are opened by getty(8) and become a user’s standard input, output, and error files.

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 256 characters. 

Normally, terminal input is processed in units of lines.  A line is delimited by a new-line (ASCII LF) character, an end-of-file (by default, control-D) 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.  By default, the character ASCII DEL erases the last character typed, except that it will not erase beyond the beginning of the line.  By default, the character control-U kills (deletes) the entire input line.  Both the erase and kill characters may be entered literally by preceding them with the escape character (\).  In this case the escape character is not read.  The erase and kill characters may be changed. 

Certain characters have special functions on input.  These functions and their default character values are summarized as follows:

INTR (control-C) generates a SIGINT signal which is sent to all processes with the associated control terminal; see tty(4). 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 sigvec(2).

QUIT (Control-\) generates a SIGQUIT signal.  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 (ASCII DEL) erases the preceding character.  It will not erase beyond the start of a line, as delimited by a NL, EOF, or EOL character. 

KILL (control-C) deletes the entire line, as delimited by a NL, EOF, or EOL character. 

EOF (control-D) 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. 

EOL (ASCII NUL) is an additional line delimiter, like NL.  It is not normally used. 

STOP (control-S) 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 (control-Q) 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 escaped. 

SUSP (control-Z) generates a SIGTSTP signal which is used to suspend the current process group. 

DSUSP (control-Y) generates a SIGTSTP signal as control-Z does, but the signal is sent when a program attempts to read the control-Y, rather than when it is typed. 

REPRINT (control-R) retypes the pending input beginning on a new line. 

DISCARD (control-O) causes subsequent output to be flushed until FLUSHO bit in c_lflag is cleared by a program or more input is typed.  This character causes pending input to be retyped if there is any pending input. 

WERASE (control-W) erases the preceding word, but not any spaces before it.  For the purposes of WERASE, a word is defined as a sequence of non-blank characters, with tabs counted as blanks. 

LNEXT (control-V) causes the special meaning of the next character to be ignored. 

The character values for INTR, QUIT, ERASE, KILL, EOF, EOL, START, STOP, SUSP, DSUSP, REPRINT, DISCARD, WERASE, and LNEXT may be changed to suit individual tastes. 

When the carrier signal from the modem drops, a SIGHUP signal is sent to all processes that have this terminal as the control terminal.  Unless other arrangements have been made, this signal causes the processes to terminate.  If the SIGHUP 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 hung up on. 

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. 

Several ioctl(2) system calls apply to terminal files. The primary calls use the following structures, defined in <termios.h> or <termio.h>:

#define NCCS17
typedef unsigned long tcflag_t;
typedef unsigned char cc_t;
 struct termios {
tcflag_tc_iflag;/∗ input modes ∗/
tcflag_tc_oflag;/∗ output modes ∗/
tcflag_tc_cflag;/∗ control modes ∗/
tcflag_tc_lflag;/∗ line discipline modes ∗/
cc_tc_cc[NCCS];/∗ control chars ∗/
};
 #define NCC8
struct termio {
unsigned shortc_iflag;/∗ input modes ∗/
unsigned shortc_oflag;/∗ output modes ∗/
unsigned shortc_cflag;/∗ control modes ∗/
unsigned shortc_lflag;/∗ line discipline modes ∗/
charc_line;/∗ line discipline ∗/
unsigned charc_cc[NCC];/∗ control chars ∗/
};

The special control characters are defined by the array c_cc. The relative positions and initial values for each function are as follows:

0VINTRcontrol-C
1VQUITcontrol-\
2VERASEDEL
3VKILLcontrol-U
4VEOFcontrol-D
5VEOLNUL
6reserved
7reserved
8VSTARTcontrol-Q
9VSTOPcontrol-S
10VSUSPcontrol-Z
11VDSUSPcontrol-Y
12VREPRINTcontrol-R
13VDISCARDcontrol-O
14VWERASEcontrol-W
15VLNEXTcontrol-V

The termio structure allows the first eight characters (before VSTART) for c_cc.

The c_iflag field describes the basic terminal input control:

IGNBRK0000001Ignore break condition.
BRKINT0000002Signal interrupt on break.
IGNPAR0000004Ignore characters with parity errors.
PARMRK0000010Mark parity errors.
INPCK0000020Enable input parity check.
ISTRIP0000040Strip character.
INLCR0000100Map NL to CR on input.
IGNCR0000200Ignore CR.
ICRNL0000400Map CR to NL on input.
IUCLC0001000Map upper-case to lower-case on input.
IXON0002000Enable start/stop output control.
IXANY0004000Enable any character to restart output.
IXOFF0010000Enable start/stop input control.

If IGNBRK is set, the break condition (a character framing error with data all zeros) is ignored, that is, not put on the input queue and therefore not read by any process.  Otherwise if BRKINT is set, the break condition will generate an interrupt signal and flush both the input and output queues.  If IGNPAR is set, characters with other framing and parity errors are ignored. 

If PARMRK is set, a character with a framing or parity error which is not ignored 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 PARMRK is not set, a framing or parity error which is not ignored is read as the character NUL (0). 

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. 

If ISTRIP is set, valid input characters are first stripped to 7-bits, otherwise all 8-bits are processed. 

If INLCR is set, a received NL character is translated into a CR character.  If IGNCR is set, a received CR character is ignored (not read).  Otherwise if ICRNL is set, a received CR character is translated into a NL character. 

If IUCLC is set, a received upper-case alphabetic character is translated into the corresponding lower-case character. 

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.  All start/stop characters are ignored and not read.  If IXANY is set, any input character, will restart output which has been suspended. 

If IXOFF is set, the system will transmit START/STOP characters when the input queue is nearly empty/full. 

The initial input control value is ICRNL. 

The c_oflag field specifies the system treatment of output:

OPOST0000001Postprocess output.
OLCUC0000002Map lower case to upper on output.
ONLCR0000004Map NL to CR-NL on output.
OCRNL0000010Map CR to NL on output.
ONOCR0000020No CR output at column 0.
ONLRET0000040NL performs CR function.
OFILL0000100Use fill characters for delay.
OFDEL0000200Fill is DEL, else NUL.
NLDLY0000400Select new-line delays:
NL00
NL10000400
CRDLY0003000Select carriage-return delays:
CR00
CR10001000
CR20002000
CR30003000
TABDLY0014000Select horizontal-tab delays:
TAB00
TAB10004000
TAB20010000
TAB30014000Expand tabs to spaces.
BSDLY0020000Select backspace delays:
BS00
BS10020000
VTDLY0040000Select vertical-tab delays:
VT00
VT10040000
FFDLY0100000Select form-feed delays:
FF00
FF10100000

If OPOST is set, output characters are post-processed as indicated by the remaining flags, otherwise characters are transmitted without change. 

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. 

If ONLCR is set, the NL character is transmitted as the CR-NL character pair.  If OCRNL is set, the CR character is transmitted as the NL character.  If ONOCR is set, no CR character is transmitted when at column 0 (first position).  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. 

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 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.  If OFDEL is set, the fill character is DEL, otherwise NUL. 

If a form-feed or vertical-tab delay is specified, it lasts for about 2 seconds. 

New-line delay 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. 

Carriage-return delay type 1 is dependent on the current column position, type 2 is about 0.10 seconds, and type 3 is about 0.15 seconds.  If OFILL is set, delay type 1 transmits two fill characters, and type 2, four fill characters. 

Horizontal-tab delay type 1 is dependent on the current column position.  Type 2 is about 0.10 seconds.  Type 3 specifies that tabs are to be expanded into spaces.  If OFILL is set, two fill characters will be transmitted for any delay. 

Backspace delay lasts about 0.05 seconds.  If OFILL is set, one fill character will be transmitted. 

The actual delays depend on line speed and system load. 

The initial output control value is OPOST and ONLCR. 

The c_cflag field describes the hardware control of the terminal:

CBAUD0000017Baud rate:
 B00Hang up
 B50000000150 baud
 B75000000275 baud
 B1100000003110 baud
 B1340000004134.5 baud
 B1500000005150 baud
 B2000000006200 baud
 B3000000007300 baud
 B6000000010600 baud
 B120000000111200 baud
 B180000000121800 baud
 B240000000132400 baud
 B480000000144800 baud
 B960000000159600 baud
 B19200000001619200 baud
 B38400000001738400 baud
 EXTA0000016External A
 EXTB0000017External B
CSIZE0000060Character size:
 CS505 bits
 CS600000206 bits
 CS700000407 bits
 CS800000608 bits
CSTOPB0000100Send two stop bits, else one.
CREAD0000200Enable receiver.
PARENB0000400Parity enable.
PARODD0001000Odd parity, else even.
HUPCL0002000Hang up on last close.
CLOCAL0004000Local line, else dial-up.
CIBAUD03600000Input baud rate.

The CBAUD 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 will not be asserted.  Normally, this will disconnect the line.  For any particular hardware, impossible speed changes are ignored. 

The CSIZE bits specify the character size in bits for both transmission and reception.  This size does not include the parity bit, if any.  If CSTOPB is set, two stop bits are used, otherwise one stop bit.  For example, at 110 baud, two stops bits are required. 

If PARENB is 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. 

If CREAD is set, the receiver is enabled.  Otherwise no characters will be received. 

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. 

If CLOCAL is set, the line is assumed to be a local, direct connection with no modem control.  Otherwise modem control is assumed. 

The initial hardware control value after open is B9600, CS8, CREAD, HUPCL. 

The c_lflag field of the argument structure is used by the line discipline to control terminal functions.  The basic line discipline provides the following:

ISIG0000001Enable signals.
ICANON0000002Canonical input (erase and kill processing).
XCASE0000004Canonical upper/lower presentation.
ECHO0000010Enable echo.
ECHOE0000020Echo erase character as BS-SP-BS.
ECHOK0000040Echo NL after kill character.
ECHONL0000100Echo NL.
NOFLSH0000200Disable flush after interrupt or quit.
TOSTOP0000400Send SIGTTOU for background output.
ECHOCTL0001000Echo input control chars as ^X, delete as ^?.
ECHOPRT0002000Printing terminal erase mode.
ECHOKE0004000BS-SP-BS erase entire line on line kill.
FLUSHO0020000Output is being flushed.
PENDIN0040000Retype pending input at next read or input character.

If ISIG is set, each input character is checked against the special control characters INTR 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 an unlikely or impossible value (e.g., 0377). 

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, and EOL.  If ICANON is not set, read requests are satisfied directly from the input queue. 

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. 

If ECHO is 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 will clear the last character from a CRT screen.  If ECHOK is set, the NL character will be echoed after the kill character to emphasize that the line will be deleted.  Note that an escape character preceding the erase or kill character removes any special function. 

If NOFLSH is set, the normal flush of the input and output queues associated with the intr, quite, and susp characters will not be done. 

If TOSTOP is set, 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 holding or ignoring SIGTTOU signals or which are in the middle of a vfork(2) are excepted and allowed to produce output.

If ECHOCTL is set, non-printing (control) characters are normally echoed as ^X (for some X) rather than being echoed unmodified; delete is echoed as ^?. 

If ECHOPRT is set, characters which are logically erased are then printed out backwards preceded by ‘\’ and followed by ‘/’ in this mode.

If ECHOKE is set, line kill processing uses BS-SP-BS seqences to erase entire line. 

If FLUSHO is set, subsequent output will be flushed until it is cleared by a program or more input is typed. 

If PENDIN is set, pending input will be retyped when the next input character is received. 

The initial line-discipline control value is ISIG, ICANON, and ECHO. 

The POSIX ioctl(2) system calls have the form:

ioctl (fildes, command, arg)
struct termios ∗arg;

The commands using this form are:

TCGETS Get the parameters associated with the terminal and store in the termios structure referenced by arg. 

TCSETS Set the parameters associated with the terminal from the structure referenced by arg.  The change is immediate. 

TCSETSW Wait for the output to drain before setting the new parameters.  This form should be used when changing parameters that will affect output. 

TCSETSF Wait for the output to drain, then flush the input queue and set the new parameters. 

The System V ioctl(2) system calls have the form:

ioctl (fildes, command, arg)
struct termio ∗arg;

The commands using this form are:

TCGETA Get the parameters associated with the terminal and store in the termio structure referenced by arg. 

TCSETA Set the parameters associated with the terminal from the structure referenced by arg.  The change is immediate. 

TCSETAW Wait for the output to drain before setting the new parameters.  This form should be used when changing parameters that will affect output. 

TCSETAF Wait for the output to drain, then flush the input queue and set the new parameters. 

Additional ioctl(2) calls have the form:

ioctl (fildes, command, arg)
int arg;

The commands using this form are:

TCSNDBRK

TCSBRK Wait for the output to drain.  If arg is 0, then send a break (zero bits for 0.25 seconds).  TCSBRK is defined in <termio.h>. 

TCXONC Start/stop control.  If arg is TCOOFF (0), suspend output; if TCOON (1), restart suspended output; if TCIOFF (2), suspend input; if TCION (3), restart suspended input. 

TCFLSH If arg is TCIFLUSH (0), flush the input queue; if TCOFLUSH (1), flush the output queue; if TCIOFLUSH (2), flush both the input and output queues. 

TCDRAIN Wait for the output to drain. 

FILES

/dev/tty∗

SEE ALSO

stty(1V), fork(2), ioctl(2), setpgrp(2), sigvec(2), tty(4). 

BUGS

Some functions of POSIX or System V have not been implemented.  For example, c_cc[VMIN] and c_cc[VTIME] should work when ICANON bit in c_iflag is cleared. 

NEWS-OSRelease 4.1C